# @asamuzakjp/generational-cache 中文文档

规范地址：https://npmcn.com/package/%40asamuzakjp/generational-cache/

版本：3\.0\.1
npm 元数据更新时间：2026-06-20T00:01:39.191Z
中文译文更新时间：2026-11-06T22:07:45.247Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40asamuzakjp/generational-cache
原文对照：https://npmcn.com/package/%40asamuzakjp/generational-cache/?lang=original
项目主页：https://github.com/asamuzaK/generationalCache
源码仓库：https://github.com/asamuzaK/generationalCache

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：27 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.13\.0 \|\| \>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-04-12T13:37:15.356Z
- 最新版本发布：2026-06-20T00:01:39.085Z
- 近 30 天下载量：85701131（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

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

## 安装

```sh
npm install @asamuzakjp/generational-cache
```

也可以使用：`pnpm add @asamuzakjp/generational-cache`、`yarn add @asamuzakjp/generational-cache`、`bun add @asamuzakjp/generational-cache`

## README

# 代代相传

[![CI](https://github.com/asamuzaK/generationalCache/actions/workflows/ci.yaml/badge.svg)](https://github.com/asamuzaK/generationalCache/actions/workflows/ci.yaml) [![CodeQL](https://github.com/asamuzaK/generationalCache/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/asamuzaK/generationalCache/actions/workflows/github-code-scanning/codeql) [![npm (scoped)](https://img.shields.io/npm/v/@asamuzakjp/generational-cache)](https://www.npmjs.com/package/@asamuzakjp/generational-cache)

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

## 如何运作

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

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

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

## 不使用时

`GenerationalCache` 如果:

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

## 安装

```console
npm i @asamuzakjp/generational-cache
```

## 使用量

```javascript
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)计算. 较高的数值表明业绩较好._

### 环境

-   **引擎 :** 节点.js v24.x (V8)
-   **测量:** [米塔塔语](https://github.com/evanwashere/mitata)。 。 。 .
-   **比较 :** [路加锡](https://www.npmjs.com/package/lru-cache) 页:1, [快递](https://www.npmjs.com/package/quick-lru) (v7.x), (中文(简体) ), [气象学家](https://www.npmjs.com/package/mnemonist) (v0.40.x) (中文(简体) )

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

| 假设 | 状态 | 生成缓存 | 路加锡 | 快递 | 气象学家 |
| :-- | :-- | :-- | :-- | :-- | :-- |
| **设定** | 凉了 | 15,137,754项行动/sec | 4 265 484项行动/sec | 13 800 718项行动/sec | **17 844 397项行动/sec** |
|  | 温暖 | **18 993 352项行动/秒** | 15 299 878项行动/sec | **18,132,366项行动/sec** | **19 007 793项行动/sec** |
| **获取** | 凉了 | 16 028 210项行动/秒 | 7 566 013项行动/秒 | 13 881 177项行动/sec | **30 030 030 行动/秒** |
|  | 温暖 | 17 917 936项行动/sec | 23 523 877起行动/sec | 16 458 196项行动/sec | **39,416,634 行动/sec** |
| **选举** | 凉了 | **16 236 402项行动/秒** | 7 372 457项行动/sec | 14,547,571项行动/sec | 5 407 451项行动/秒 |
|  | 温暖 | **20 479 214项行动/秒** | 8 993 615项行动/sec | 17,123,288项行动/sec | 7 668 712项行动/sec |

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

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

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

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

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

| 假设 | 状态 | 生成缓存 | 路加锡 | 快递 | 气象学家 |
| :-- | :-- | :-- | :-- | :-- | :-- |
| **设定** | 凉了 | 602,410 行动/sec | 3 003 725项行动/秒 | 9 948 269项行动/sec | **10,231,226项行动/秒** |
|  | 温暖 | 757 576 行动/sec | 10 964 912项行动/秒 | 14,697,237项行动/sec | **16 572 754项行动/秒** |
| **获取** | 凉了 | 13,180,440项行动/sec | 7 043 742项行动/sec | 11 037 528项行动/秒 | **17 580 872项行动/秒** |
|  | 温暖 | 16 170 763项行动/秒 | 19 007 793项行动/sec | 14,363,689项行动/sec | **28 719 127项行动/秒** |
| **选举** | 凉了 | 617 284 行动/sec | 5 356 186项行动/sec | **12,072,920项行动/秒** | 2 607 222项行动/sec |
|  | 温暖 | 775 194项行动/sec | 7,504,127项行动/sec | **14 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项行动/sec** | 10 561 893项行动/秒 | 14,624,159项行动/sec | **16 672 224项行动/秒** |
| **获取** | 凉了 | 13 835 086项行动/秒 | 7 248 478项行动/sec | 10 714 668项行动/sec | **19 015 022项行动/秒** |
|  | 温暖 | 16 012 810项行动/秒 | 18 744 142项行动/sec | 14,106,362项行动/秒 | **32 927 231项行动/sec** |
| **选举** | 凉了 | 10 424 268项行动/sec | 5 473 753项行动/秒 | **11 983 223项行动/秒** | 2,544,853项行动/sec |
|  | 温暖 | **16 291 952项行动/秒** | 6,972,996项行动/秒 | 13 417 416项行动/sec | 5 798 782项行动/秒 |

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

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

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

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

## 密钥特征

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

## 许可证

麻省理工学院

## 常见问题

### @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 和提交记录判断。