# @alcalzone/jsonl-db 中文文档

规范地址：https://npmcn.com/package/%40alcalzone/jsonl-db/

版本：4\.0\.2
npm 元数据更新时间：2025-10-15T09:04:17.888Z
中文译文更新时间：2026-11-05T18:05:19.562Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：179 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2020-04-25T09:28:08.231Z
- 最新版本发布：2025-10-15T09:04:17.489Z
- 近 30 天下载量：106830（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 0 个）

## 中文简介

简单的基于 JSONL 的密钥值商店

## 安装

```sh
npm install @alcalzone/jsonl-db
```

也可以使用：`pnpm add @alcalzone/jsonl-db`、`yarn add @alcalzone/jsonl-db`、`bun add @alcalzone/jsonl-db`

## README

# 日报b

简单的基于JSONL的密钥价值商店. 使用附件文件存储数据。 支持数据库堆放并压缩db文件.

![Build Status](https://action-badges.now.sh/AlCalzone/jsonl-db)

 [![node](https://img.shields.io/node/v/@alcalzone/jsonl-db.svg) ![npm](https://img.shields.io/npm/v/@alcalzone/jsonl-db.svg)](https://www.npmjs.com/package/@alcalzone/jsonl-db)

## 使用量

装入模块 :

```ts
import { DB } from "@alcalzone/jsonl-db";
```

打开或创建数据库文件并像使用 [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)

```ts
// Open
const db = new DB("/path/to/file");
await db.open();
// db.isOpen is now true

// and use it
db.set("key", value);
db.delete("key");
db.clear();
if (db.has("key")) {
    result = db.get("key");
}
// ...forEach, keys(), entries(), values(), ...
```

### 处理无效的数据

如果打开 DB 时遇到损坏的数据, 调用到 `open()` 将被拒绝。 如果需要, 请使用构造器上的选项参数来打开“ 原谅” 行为 :

```ts
const db = new DB("/path/to/file", { ignoreReadErrors: true });
await db.open();
```

**警告:** 这可能导致数据不一致,因为无效行会被默默地忽略.

### 支持自定义对象/值

您可以通过传回函数来可选地转换解析值 。 如果可以转换为JSON(例如通过覆盖 `toJSON` 页:1 要控制转换值在保存到数据库之前,使用序列器函数. 这是必需的 `Map`s, (中文(简体) ), `Set`s, (中文(简体) ), `WeakMap`s 和 `WeakSet`编号.

```ts
function reviver(key: string, serializedValue: any) {
    // MUST return a value. If you don't want to transform `serializedValue`, return it.
}

function serializer(key: string, value: any) {
    // MUST return a value. If you don't want to transform `value`, return it.
}

const db = new DB("/path/to/file", { reviver, serializer });
await db.open();
```

### 关闭数据库

编写给数据库的数据是同步的。 一定要打电话 `close()` 当您不再需要数据库来冲出所有待写并关闭所有文件时:

```ts
await db.close();
```

现在, `db.isOpen` 实值 `false`。当 db 不打开时,任何访问数据的呼叫都会出错.

### 控制文件系统访问

默认情况下,数据库会立即写入数据库文件. 您可以使用 `throttleFS` 构造器选项 。 注意缓冲数据会丢失,以防进程崩溃.

```ts
const db = new DB("/path/to/file", { throttleFS: { /* throttle options */ } });
```

现有以下选项:

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `intervalMs` | `0` | 写入数据库文件的时间不超过每个 `intervalMs` 毫秒长. |
| `maxBufferedCommands` | `+Infinity` | 强制写入后面 `maxBufferedCommands` 已经缓冲。 这降低了发生相撞时的内存消耗和数据损失. |

在 `/path/to/file.dump`,使用 `dump()` 方法。 如果在垃圾堆中将任何数据写入db,则该数据附于垃圾堆后,但最有可能压缩.

### 与锁定文件相关的选项

一个锁文件用于避免同时访问 DB 文件. 存在多个选项来控制此锁文件创建地点和如何访问 :

```ts
const db = new DB("/path/to/file", { lockfile: { /* lockfile options */ } });
```

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `directory` | \- 说吧 | 更改创建锁文件的地方, 例如将锁文件放入 `tmpfs`。默认情况下,锁文件与 DB 文件在同一目录中创建。 如果目录不存在,将在打开 DB 时创建. |
| `staleMs` | `10000` | 锁被停止的时间。 最小值 : `2000` |
| `updateMs` | `staleMs/2` | 锁文件的间隔 `mtime` 将更新。 范围 : `1000 ... staleMs/2` |
| `retries` | `0` | 在放弃之前,如何经常重试获得锁. 复试用指数式后退策略逐渐等更久. |
| `retryMinTimeoutMs` | `updateMs/2` 或者说 `1000` | 用于重试的起始间隔 。 最小值 : `100` |

### 复制和压缩数据库

```ts
await db.dump(); // To use the default dump filename `/path/to/file.dump`
await db.dump("/somewhere/else.jsonl"); // To use a different filename
```

一段时间后,主 db 文件可能包含不必要的条目. 使用 `uncompressedSize` 属性。 要删除不必要的条目,请使用 `compress()` 方法.

```ts
await db.compress();
```

**说明:** 在此期间, `/path/to/file.dump` 被覆盖,然后被重新命名, `/path/to/file.bak` 已覆盖并删除。 所以要确保这些文件中没有任何重要数据.

数据库在某些条件下可以自动压缩数据库文件. 要做到这一点,使用 `autoCompress` 构造器选项的参数 :

```ts
const db = new DB("/path/to/file", { autoCompress: { /* auto compress options */ }});
```

以下选项(均为可选选项)存在,可以合并:

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `sizeFactor` | `+Infinity` | 压缩时 `uncompressedSize >= size * sizeFactor` |
| `sizeFactorMinimumSize` | 0 个 | 根据大小配置自动压缩所需的最小大小 |
| `intervalMs` | `+Infinity` | 一段时间后压缩 |
| `intervalMinChanges` | 1个 | 配置基于时间的自动压缩最小变化数 |
| `onClose` | `false` | 关闭 DB 时压缩 |
| `onOpen` | `false` | 打开 DB 后压缩 |

### 跟踪时间戳

DB可以自动跟踪上次键被写入的时间. 为此,设置 `enableTimestamps` 选项到 `true`每一个 `set` 调用后将更新一个值的时间戳,该值可以使用 `getTimestamp(key)`为个人写作选择不这样做,通过 `false` 作为第三个参数 `set`。 。 。 .

```ts
db.set("key", "value", false); // Don't update the timestamp
```

> **说明** 记录时间戳将 DB 吞吐量减少 ~ 10%... 30%, 取决于其使用方式 .

### 导入/导出

以下列方式将结构化数据导入数据库:

```ts
// pass the object directly, the import will be synchronous
db.importJSON({key: "value"});
```

DB中的现有条目不会被删除,但如果存在,则会被覆盖.

也可以将数据导出为 JSON 对象 :

```ts
const json = db.toJSON();
```

## 更改日志

### 4.0.2 (2025-10-15) (中文(简体) )

-   固定普通JS导入

### 4.0.1 (2025-10-14) (中文(简体) )

-   如果自定义序列器在自动压缩过程中抛出错误, 则会解决应用程序可能耗尽内存的问题

### 4.0.0 (2025-10-07) (中文(简体) )

-   放弃对比 v20 年长的节点.js 版本的支持
-   拆开 `exportJson` 方法为 `toJSON`
-   重命名为 `importJson` 方法 `importJSON`。不再支持从文件中导入。 如果您需要此功能, 请自己读取文件 .
-   现在使用本地文件系统访问 `fs.promises` 改为 `fs-extra`
-   该套装现在是混合无害环境管理/CJS套装

### 3.1.1 (2024-01-25) (中文(简体) )

-   闲置时降低CPU负载(# 475)

### 3.1.0 (2023-03-15) (中文(简体) )

-   支持退出更新单个调用的时间戳(# 415)

### 3.0.0 (2023-03-09) (中文(简体) )

-   支持记录每个值的时间戳(# 413)
-   放弃对 Node.js 12 (# 414) 的支持

### 2.5.3 (2022-09-06) (中文(简体) )

-   将未来的锁文件视为陈旧(# 371)

### 2.5.2 (2022-05-02) (中文(简体) )

-   依赖性更新

### 2.5.1 (2022-02-13) (中文(简体) )

-   允许设置最小重试超时
-   正确的锁定文件已暂停的最小值

### 2.5.0 (2022-02-13) (中文(简体) )

-   添加控制锁文件 stale/ update 超时并重试获取锁的能力

### 2.4.3 (2022-02-09) (中文(简体) )

-   自动压缩 DB 时出错

### 2.4.2 (2022-02-09) (中文(简体) )

-   从备份或垃圾堆中自动恢复 DB 时出错现已被捕获
-   简化并解除了持久性代码. 单个命令如 `dump` 财务报告和审定财务报表 `compress` 现在已适当排序,不应再相冲突.
-   原始条目吞吐量增加~2x

### 2.4.1 (2021-12-30) (中文(简体) )

-   个人写作现在被收集成一个字符串并同时被写出,对较大条目的吞吐量增加~10x.

### 2.4.0 (2021-12-27) (中文(简体) )

-   将单行线固定在懒惰的状态下,只有在实际需要时,才能使吞吐量增加30.50x.

### 2.3.0 (2021-12-19) (中文(简体) )

-   添加将数据库倾倒到不同位置的能力

### 2.2.0 (2021-10-15) (中文(简体) )

-   添加指定锁文件创建地点的能力

### 2.1.0 (2021-06-22) (中文(简体) )

-   打开 DB 时, 在压缩 DB 时从发生的碰撞中恢复
-   确保关闭或重命名文件时将 DB 文件冲入磁盘
-   测试现在与真实文件系统相对应 `mock-fs`,在节点中断开 `16.3+`
-   现代化类型Script 构建输出

### 2.0.0 (2021-06-19) (中文(简体) )

更新Node.js 10 的依赖性和减少支持

### 1.2.5 (2021-05-29) (中文(简体) )

防止在多个 DB 实例中使用锁文件打开一个 DB 文件

### 1.2.4 (2021-02-15) (中文(简体) )

打开 DB 时减少工作

### 1.2.3 (2021-01-02) (中文(简体) )

在压缩 DB 时修复一个崩溃 `.bak` 文件已存在

### 1.2.2(2020-10-16)

当不使用此库时 `skipLibCheck`, (中文(简体) ), `@types/fs-extra` 不再需要

### 1.2.1 (2020-08-20) (中文(简体) )

更新依赖关系

### 1.2.0 (2020-05-25) (中文(简体) )

在写入 DB 文件前添加了可选的序列器函数来转换非主对象

### 1.1.2 (2020-05-11) (中文(简体) )

固定了超时漏出,防止节点出站

### 1.1.1 (2020-05-07) (中文(简体) )

如果主目录不存在, 则创建了主目录

### 1.1.0 (2020-05-02) (中文(简体) )

添加到节流器写入访问器中的功能

### 1.0.1(2020-04-29) (中文(简体) )

导出 `JsonlDBOptions` 从主要切入点

### 1.0.0 (2020-04-29) (中文(简体) )

添加自动压缩功能

### 0.5.1 (2020-04-28) (中文(简体) )

修补 : 主要出口不再出口 `JsonlDB` 作为 `DB`。 。 。 .

### 0.5.0 (2020-04-27) (中文(简体) )

在装入 DB 时添加了可选的复活器函数来转换非主对象

### 0.4.0 (2020-04-27) (中文(简体) )

-   重命名为 `DB` 类改为 `JsonlDB`
-   `open()` 现在跳过空行
-   `open()` 遇到无效行时,随行号抛出错误。 使用新的构建器选项参数可以忽略这些错误 .

### 0.3.0 (2020-04-26) (中文(简体) )

-   已添加 `importJson` 财务报告和审定财务报表 `exportJson` 方法

### 0.2.0 (2020-04-25) (中文(简体) )

-   已添加 `isOpen` 属性

### 0.1.3 (2020-04-25) (中文(简体) )

-   写出发生时 `compress()` 替换文件已持续

### 0.1.2 (2020-04-25) (中文(简体) )

-   `compress()` dB 关闭时不再覆盖主文件

### 0.1 (2020-04-25) (中文(简体) )

-   修补了一些种族条件

### 0.1.0 (2020-04-25) (中文(简体) )

第一次正式发布

## 常见问题

### @alcalzone/jsonl-db 是什么？

简单的基于 JSONL 的密钥值商店

### 如何安装 @alcalzone/jsonl-db？

在项目目录运行 npm install @alcalzone/jsonl-db，或使用 pnpm add / yarn add / bun add。

### @alcalzone/jsonl-db 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/alcalzone\_\_jsonl-db 是否存在。

### @alcalzone/jsonl-db 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @alcalzone/jsonl-db 需要什么版本的 Node\.js？

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

### @alcalzone/jsonl-db 可以商用吗？

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

### @alcalzone/jsonl-db 的下载量有多少？

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

### @alcalzone/jsonl-db 还在维护吗？

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