让开源，少一点语言距离。
npm包中文文档

@asamuzakjp/generational-cache

中文文档
3.0.1发布于 2026/06/20MITTypeScriptES Module零依赖近 30 天下载 8570.1万

代相传的缓存,具有严格的入计限制和有效载荷验证.

中文使用文档
中文原文
文档目录19 节
  1. 如何运作
  2. 不使用时
  3. 安装
  4. 使用量
  5. API 密码
  6. new GenerationalCache(max, opt)
  7. 属性
  8. 方法
  9. 业绩
  10. 环境
  11. 1. 小缓存(最大大小=512)
  12. 2. 中缓存(最大大小=2 048)
  13. 3. 大缓存(最大大小=8 192)
  14. 4. 非优先有效载荷(最大尺寸=4 096/严格Validate=为正)
  15. 5. 非优先有效载荷(最大尺寸=4 096/严格Validate=虚假)
  16. 6. 循环访问(最大尺寸=8 192/工作集=5 000)
  17. 7. 循环访问(最大大小=4 096/工作套件=5 000)
  18. 密钥特征
  19. 许可证

代代相传

CI CodeQL npm (scoped)

轻而易举, 世代缓存 严格入站限额和有效载荷验证.

如何运作

GenerationalCache 维持两个内部 Map 对象 : current 财务报告和审定财务报表 old。 。 。 . 它使用内部边界为(马克/2美元),允许两代人保持界限,同时保持世代互换的价格.

  1. 插入验证( V): 新建项目在添加到 current 生成.
  2. 晋升:如果您得到了存在于 old 一代,它被提升到 current 生成以确保它在缓存中停留的时间更长.
  3. 一代拆迁: 一旦 current 生成大小符合或超过边界阈值( max / 2美元) , 启动代交换: 已存在的 old 生成被丢弃 current 世代成为新的 old 生成, 和一个新的空 current 生成.

这种两代方法避免了在每个访问上更新时间戳或链接列表指针的间接费用. 虽然它不是标准液态气流转储点的倒置取而代之,但它优先考虑的是原始吞吐量而不是严格的驱逐令.

不使用时

GenerationalCache 如果:

  • 您需要严格的LRU驱逐命令.
  • 缓存命中率比插入/验证吞吐量更重要.
  • 您已经知道您的工作设置大小, 可以提供足够大的 LRU 缓存 .

安装

npm i @asamuzakjp/generational-cache

使用量

import { GenerationalCache } from '@asamuzakjp/generational-cache';

// Initialize with a max capacity of 1024 items and custom size limits
const cache = new GenerationalCache(1024, {
  maxKeySize: 4096,          // 4 KB limit for keys
  maxValueSize: 1024 * 1024, // 1 MB limit for values
  strictValidate: true       // Enable strict deep validation for objects (default)
});

API 密码

new GenerationalCache(max, opt)

创建一个最大容量为 max 条目.

  • 最大数 (数目):缓存可以持有的最大项目数量. 如果指定值小于4,或者指定了无效值,则使用4的默认值.
  • 选择 (对象,可选)数字 :
    • 缓存功能 (布尔): 如果 true默认为 false。 。 。 .
    • 缓存符号 (布尔): 如果 true默认为 false。 。 。 .
    • 最大键大小 (数目): 最大允许大小 key 以字节表示。 默认为8192 (8 KB).
    • 最大数值 (数目): 最大允许大小 value 以字节表示。 默认为1048576 (1 MB).
    • 严格参数 (布尔): 如果 true默认为 true。 。 。 .

属性

  • 缓存. entryCount (数目,只读): 返回基础总数 entries 目前储存在两代人之间. 说明: 为了最大限度地实现书写吞吐量,此库允许在 current 财务报告和审定财务报表 old (例如,当一个项目同时存在于两代人中时)。 报告数目可能超过 keys,但仍被缓存的内部容量所束缚.
  • 缓存.max (数目): 获取或设置最大项容量. 说明: 动态更新此属性 将清除所有已缓存的项目 (它隐含地引用缓存. clear () 来安全地重新计算边界) .

方法

  • 缓存. get( 键) 获取一个项目。 如果在 old 将自动提升到 current 用于防止在下次互换时被拆迁.
    • 回返 (任何未定义的): 与 key,或 undefined 若为 key 无法找到.
  • 缓存. set( 键, 值) 添加或更新一个项目。 它在插入前验证键和值(如果是字符串)的字节大小。 如果操作导致 current 生成的大小以达到或超过边界阈值,启动一代互换.
    • 说明: 储存 undefined 作为值 不支持,作为缓存.get(key治疗 undefined 作为缓存错过.
    • 回返:缓存实例本身( allows 链式).
  • 缓存. has( 键) 检查是否 key 存在于缓存中(在两代中).
    • 回返情况: true 如果密钥存在, 否则 false。 。 。 .
  • 缓存. delete( 键) 从缓存中删除项目.
    • 回返情况: true 如果物品存在并被移除,否则 false。 。 。 .
  • 缓存。 clear () 启动缓存中的所有项目 .

业绩

基准分为两个州来模拟现实世界的条件:

  • 冷 国:用有侵略性的内部垃圾收集来测量,在全V8涡轮箱优化前观察性能.
  • 温暖状态:在足够热量后测量,在最佳联合信息技术数据库汇编下,代表持续的吞吐量.

以下结果反映每秒(ops/sec)的持续运行,从平均延迟(ns/iter)计算. 较高的数值表明业绩较好.

环境

1. 小缓存(最大大小=512)

假设状态生成缓存路加锡快递气象学家
设定凉了15,137,754项行动/sec4 265 484项行动/sec13 800 718项行动/sec17 844 397项行动/sec
温暖18 993 352项行动/秒15 299 878项行动/sec18,132,366项行动/sec19 007 793项行动/sec
获取凉了16 028 210项行动/秒7 566 013项行动/秒13 881 177项行动/sec30 030 030 行动/秒
温暖17 917 936项行动/sec23 523 877起行动/sec16 458 196项行动/sec39,416,634 行动/sec
选举凉了16 236 402项行动/秒7 372 457项行动/sec14,547,571项行动/sec5 407 451项行动/秒
温暖20 479 214项行动/秒8 993 615项行动/sec17,123,288项行动/sec7 668 712项行动/sec

2. 中缓存(最大大小=2 048)

假设状态生成缓存路加锡快递气象学家
设定凉了15 024 038项行动/秒4 537 617项行动/sec11 818 934项行动/秒15,110,305项行动/秒
温暖17 126 220项行动/秒13 299 641项行动/秒15 309 247项行动/sec17 070 673项行动/秒
获取凉了13 976 240项行动/sec8 134 711项行动/秒11 784 115项业务/秒26 315 789项行动/秒
温暖16 015 375项行动/秒19,425,019 行动/sec13 599 891项行动/秒35,663,338项行动/sec
选举凉了14 858 841项行动/sec6 439 979项行动/sec12 425 447项行动/秒5,252,929项行动/sec
温暖19,805,902项行动/sec7 981 483项行动/秒16,108,247 行动/sec7 295 010 行动/sec

3. 大缓存(最大大小=8 192)

假设状态生成缓存路加锡快递气象学家
设定凉了13 292 569项行动/sec3,637,686项行动/sec7 970 033项行动/秒11 318 619项行动/sec
温暖17 652 251项行动/秒11 709 602项行动/秒12 781 186项行动/sec15 225 335项行动/秒
获取凉了13 840 830项行动/秒5,746,136项行动/sec11 021 713项行动/秒17 155 601项行动/sec
温暖19,116,804项行动/sec17 885 888 行动/sec15 664 160项行动/sec28 344 671项行动/秒
选举凉了14 025 245项行动/sec5 358 770项行动/sec9 882 399项行动/sec4 185 501项行动/秒
温暖19 249 278项行动/sec7 029 383项行动/秒13 646 288项行动/sec6 086 798起行动/事件

4. 非优先有效载荷(最大尺寸=4 096/严格Validate=为正)

假设状态生成缓存路加锡快递气象学家
设定凉了602,410 行动/sec3 003 725项行动/秒9 948 269项行动/sec10,231,226项行动/秒
温暖757 576 行动/sec10 964 912项行动/秒14,697,237项行动/sec16 572 754项行动/秒
获取凉了13,180,440项行动/sec7 043 742项行动/sec11 037 528项行动/秒17 580 872项行动/秒
温暖16 170 763项行动/秒19 007 793项行动/sec14,363,689项行动/sec28 719 127项行动/秒
选举凉了617 284 行动/sec5 356 186项行动/sec12,072,920项行动/秒2 607 222项行动/sec
温暖775 194项行动/sec7,504,127项行动/sec14 981 273项行动/秒6,208,481项行动/秒

5. 非优先有效载荷(最大尺寸=4 096/严格Validate=虚假)

假设状态生成缓存路加锡快递气象学家
设定凉了12 315 271项行动/秒2 650 060次行动/秒10 233 320项行动/秒10 884 946项行动/sec
温暖16 100 467项行动/sec10 561 893项行动/秒14,624,159项行动/sec16 672 224项行动/秒
获取凉了13 835 086项行动/秒7 248 478项行动/sec10 714 668项行动/sec19 015 022项行动/秒
温暖16 012 810项行动/秒18 744 142项行动/sec14,106,362项行动/秒32 927 231项行动/sec
选举凉了10 424 268项行动/sec5 473 753项行动/秒11 983 223项行动/秒2,544,853项行动/sec
温暖16 291 952项行动/秒6,972,996项行动/秒13 417 416项行动/sec5 798 782项行动/秒

6. 循环访问(最大尺寸=8 192/工作集=5 000)

度量衡生成缓存路加锡快递气象学家
点击率78.30%100.0% (单位:千美元)100.0% (单位:千美元)100.0% (单位:千美元)
吞吐量8 783 487项行动/sec37,778,617项行动/sec38 550 501 行动/sec44,742,729项行动/sec

7. 循环访问(最大大小=4 096/工作套件=5 000)

度量衡生成缓存路加锡快递气象学家
点击率0.00 % (单位:千美元)0.00 % (单位:千美元)78.30%0.00 % (单位:千美元)
吞吐量9 931 472项行动/秒6 396 724项行动/sec8 509 189项行动/sec6 078 288项行动/sec

密钥特征

  • 高排出效率数字 : GenerationalCache 与大规模驱逐情况下的标准路由和转机设计相比,在高转机工作量期间显示强劲的吞吐量.
  • 可预测的可伸缩性: 虽然其他图书馆可能因缓存大小增加而出现性能退化, GenerationalCache 由于其世代互换机制,维持了一致的吞吐量.
  • 平衡读取/写入:它在所有基本业务中提供稳定和有竞争力的业绩(get, (中文(简体) ), set),使得它既适合读重又适合写重的环境.
  • 严格校验切换: 默认情况下,非原生有效载荷进行深度验证,以防止超大小物体的内存耗尽,从而会影响写入吞吐量. 残疾 strictValidate 恢复写入性能,前提是有效载荷大小由外部管理(见4和5).
  • 权衡: 在工作集大于 max / 2 不过小于 max, (中文(简体) ), GenerationalCache 将经常发生世代互换和缓存缺失。 最大限度地提高业绩效益 GenerationalCache通常最好还是保持 max 面积小到可以进行一些驱逐,而不是试图适应整个工作组(见6和7).

许可证

麻省理工学院

版本与发布记录

@asamuzakjp/generational-cache 共发布 10 个版本，首次发布于 2026/04/12；过去 12 个月发布了 10 个版本。

版本发布日期距今
3.0.1latest2026/06/204 个月前
3.0.02026/06/164 个月前
2.0.42026/06/114 个月前
2.0.32026/06/114 个月前
2.0.22026/05/155 个月前
2.0.12026/05/026 个月前

其他发布通道：next → 0.1.0。

关于 @asamuzakjp/generational-cache 的常见问题

@asamuzakjp/generational-cache 是什么？

代相传的缓存,具有严格的入计限制和有效载荷验证.

如何安装 @asamuzakjp/generational-cache？

在项目目录运行 npm install @asamuzakjp/generational-cache，或使用 pnpm add / yarn add / bun add。

@asamuzakjp/generational-cache 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@asamuzakjp/generational-cache 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@asamuzakjp/generational-cache 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^22.13.0 || >=24.0.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@asamuzakjp/generational-cache 可以商用吗？

@asamuzakjp/generational-cache 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@asamuzakjp/generational-cache 的下载量有多少？

根据 npm 官方下载统计，@asamuzakjp/generational-cache 在 2026/10/07 – 2026/11/05 这 30 天内被下载 85,701,131 次，日均约 2,856,704 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@asamuzakjp/generational-cache 还在维护吗？

最新版本 3.0.1 发布于 2026/06/20（4 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/04/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。