# @e280/kv 中文文档

规范地址：https://npmcn.com/package/%40e280/kv/

版本：0\.2\.6
npm 元数据更新时间：2026-11-03T00:27:45.720Z
中文译文更新时间：2026-11-13T03:11:52.205Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40e280/kv
原文对照：https://npmcn.com/package/%40e280/kv/?lang=original
项目主页：https://github.com/e280/kv#readme
源码仓库：https://github.com/e280/kv

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

- 包体积（解压后）：116 kB，123 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-04-22T23:54:50.308Z
- 最新版本发布：2026-11-03T00:27:45.339Z
- 近 30 天下载量：2409（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 20 个）

## 中文简介

微小运行中任意键值数据库

## 安装

```sh
npm install @e280/kv
```

也可以使用：`pnpm add @e280/kv`、`yarn add @e280/kv`、`bun add @e280/kv`

## README

![](https://i.imgur.com/SfYyhtx.png)

# 时间轴 :

**微小的密钥值存储库 .**  
键入脚本。节点或网络。 内存,平分db,地盘存储,或索引eddb. 范围命名空间和原子写入批次。 将测距和输入的 kv 实例传递到您的应用组件中, 他们不需要担心数据的实际存在.

```bash
npm install @e280/kv
```

```ts
import {Kv} from "@e280/kv"
```

## kv很简单.

-   **让你的kv.**
    
    ```ts
    const kv = new Kv()
    ```
    
-   **准备和得到的东西.**
    
    ```ts
    await kv.set("penguins", 123)
      // setting undefined is the same as delete
    ```
    
    ```ts
    await kv.get("penguins")
      // 123
    ```
    
-   **键是字符串。 值可以是任何结构化数据.**
    
    ```ts
    await kv.set("hello", {alpha: 123, bravo: ["bingus"]})
    ```
    
-   **从解剖学角度来说, 执行了一系列行动.**
    
    ```ts
    await kv.commit([
      kv.op.set("pangolins", 100),
      kv.op.delete("bingus"),
    ])
    ```
    

## 插上你最喜欢的kv杂志.

-   **记忆- 马加锡 _(违约),_** 麻黄入内贮.
    
    > _记忆杂志是缓慢和非原子的。 用来测试的._
    
    ```ts
    import {Kv, MemoryMagazine} from "@e280/kv"
    
    const kv = new Kv(new MemoryMagazine())
    ```
    
-   **马加锡级,** 磁盘上的节点 [职等db](https://github.com/google/leveldb)。 。 。 .
    
    ```ts
    import {Level} from "level"
    import {Kv, LevelMagazine} from "@e280/kv"
    
    const level = new Level("./kv")
    const kv = new Kv(new LevelMagazine(level))
    ```
    
-   **Idb Magazine, (意大利语),** 内浏览器索引 DB 存储.
    
    ```ts
    import {Kv, IdbMagazine, idbOpen} from "@e280/kv"
    
    const idb = await idbOpen("kv")
    const kv = new Kv(new IdbMagazine(idb))
    ```
    
-   **储存马加锡,** 正在浏览的本地Storage/会话Storage.
    
    > _存储杂志是缓慢和非原子的。 它意味着少量的数据._
    
    ```ts
    import {Kv, StorageMagazine} from "@e280/kv"
    
    const kv = new Kv(new StorageMagazine(localStorage))
    ```
    
-   **写自己的杂志,** 你不会相信它是多么容易.
    
    ```ts
    import {Magazine, Op, Scan, Value} from "@e280/kv"
    
    // three methods and you're done!
    export class MyMagazine implements Magazine {
      async commit(ops: Op<Value>[]): Promise<void> {/*...*/}
      async getMany(keys: string[]): Promise<(unknown | undefined)[]> {/*...*/}
      async* entries(scan?: Scan): AsyncIterable<[key: string, value: unknown]> {/*...*/}
    }
    ```
    
    见 [杂志/杂志](https://npmcn.com/package/%40e280/kv/s/magazines/memory.ts) 给灵感.

## kv瞄准镜.

-   **`scope` 使 Kv 实例具有命名空间.**
    
    ```ts
    const users = kv.scope("users")
    const messages = kv.scope("messages")
    ```
    
    ```ts
    await users.set("111", "chase")
    await messages.set("222", ["111", "yo"])
    ```
    
    ```ts
    await kv.get("111") // undefined
      // 👮 parent is blind to child entries
    
    await users.get("222") // undefined
      // 👮 child is blind to sibling and parent entries
    ```
    
-   **瞄准镜是可嵌入的,** 它的龟 一路下.
    
    ```ts
    kv.scope("animals").scope("turtles")
    
    // 🥸 equivalent
    kv.scope("animals", "turtles")
    
    // 🙅 illegal: empty strings, reserved characters "." and ":"
    kv.scope("", "e280.org", "e280:org")
    ```
    
-   **所有kv操作都被隔离到自己的范围.**
    
    > _root kv 是一个和任何其他区域相同的范围._
    
    ```ts
    const animals = kv.scope("animals")
    const turtles = animals.scope("turtles")
    const squirrels = animals.scope("squirrels")
    ```
    
    ```ts
    await animals.clear()
      // 👮 turtles and squirrels are safe
    ```
    
    ```ts
    await squirrels.clear()
      // 👮 turtles are safe
    ```
    
-   ☣️ **`subtree` 很危险,** 它允许父母范围伤害孩子.
    
    > _它返回一个特殊 `Subtree` 实例 `count` 财务报告和审定财务报表 `clear` 方法。 。 ._
    
    ```ts
    await animals.subtree.count()
      // count includes animals, turtles, and squirrels
    ```
    
    ```ts
    await animals.subtree.clear()
      // 💀 wipes out all animals, turtles, and squirrels. i'm sorry.
    ```
    
-   **别忘了你可以设置严格的类型,** kV和瞄准镜上都有.
    
    ```ts
    const kv = new Kv<unknown>()
    const users = kv.scope<string>("users")
    const messages = kv.scope<[author: string, text: string]>("messages")
    ```
    
-   🍋‍🟩 **承诺可以跨范围,** 不要错过这个!
    
    ```ts
    await kv.commit([
      users.op.set("345", "bingus"),
      messages.op.set("456", ["345", "don't let the raccoons know"]),
    ])
    ```
    

## 更多kv方法.

-   **`delete` 一对按键.**
    
    ```ts
    await kv.delete("hello")
    ```
    
    也可以通过多键.
    
    ```ts
    await kv.delete("123", "234", "345")
    ```
    
-   **`has` 检查密钥是否存在 .**
    
    ```ts
    await kv.has("hello")
      // true
    ```
    
-   **`setMany` 立即设置许多密钥值对.**
    
    ```ts
    await kv.setMany([["1", "alpha"], ["2", "bravo"]])
    ```
    
-   **`getMany` 一次获取许多值.**
    
    ```ts
    const values = await kv.getMany(["alpha", "bravo"])
      // [123, undefined]
    ```
    
-   **`need` 获取一个值,** 如果值缺失/ 无效, 则丢出 .
    
    ```ts
    const value = await kv.need("hello")
      // "world" (or throws error)
    ```
    
-   **`needMany` 获取许多值,** 或丢入缺失/无效值.
    
    ```ts
    const values = await kv.needMany(["alpha", "bravo"])
      // [123, 234] (or throws error)
    ```
    
-   **`entries` 绕过密钥值对.**
    
    ```ts
    for await (const [key, value] of kv.entries())
      console.log(key, value)
    ```
    
    它的别名是 `Symbol.asyncIterator`,所以你可以做到这一点:
    
    ```ts
    for await (const [key, value] of kv)
      console.log(key, value)
    ```
    
    页:1 `entries` 方法接受扫描选项.
    
    ```ts
    for await (const [key, value] of kv.entries({
        limit: 100,
        reverse: false,
        start: "alpha", // inclusive
        end: "omega", // exclusive
      }))
      console.log(key, value)
    ```
    
    {\\fn华文楷体\\fs16\\1che0e0e0}你可以使用 `collect` 助手从 `@e280/stz` 以数组形式获取条目/键/值:
    
    ```ts
    import {collect} from "@e280/stz"
    
    const entries = await collect(kv)
      // [["123", "alpha"], ["234", "bravo"]]
    
    const keys = await collect(kv.keys())
      // ["123", "234"]
    ```
    
-   **`keys` 财务报告和审定财务报表 `values`。 。 。 .** _(接受扫描选项)_
    
    ```ts
    for await (const key of kv.keys()) console.log(key)
    for await (const value of kv.values()) console.log(value)
    ```
    
-   **`count` 条目数** 在这个范围. _(接受扫描选项)_
    
    ```ts
    await kv.count()
      // 123
    ```
    
-   **`clear` 删除全部** 在这个范围. _(接受扫描选项)_
    
    ```ts
    await kv.clear()
    ```
    
-   **`cell` 做一个小熊,** 用于存储单个值.
    
    > _(执行) `@e280/stz`是因为 `Cubby` 类型)_
    
    ```ts
    const muffins = kv.cell<number>("muffins")
    ```
    
    ```ts
    await muffins.set(99)
    ```
    
    ```ts
    await muffins.has() // true or false
    await muffins.get() // number or undefined
    await muffins.need() // number or throws error
    ```
    
    ```ts
    await muffins.delete()
    ```
    
    您可以通过键入 `Cell<X>` 您的应用程序周围的所有实例 .
    
    ```ts
    import {Cell} from "@e280/kv"
    
    class MuffinCaptain {
      constructor(public muffins: Cell<number>) {}
    }
    ```
    

  
  

_[https://e280.org/ (中文(简体) )](https://e280.org/)_

## 常见问题

### @e280/kv 是什么？

微小运行中任意键值数据库

### 如何安装 @e280/kv？

在项目目录运行 npm install @e280/kv，或使用 pnpm add / yarn add / bun add。

### @e280/kv 支持 TypeScript 吗？

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

### @e280/kv 支持 ESM 还是 CommonJS？

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

### @e280/kv 可以商用吗？

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

### @e280/kv 的下载量有多少？

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

### @e280/kv 还在维护吗？

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