日报b

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

使用量

装入模块 :

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

打开或创建数据库文件并像使用 Map

// 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() 将被拒绝。 如果需要, 请使用构造器上的选项参数来打开“ 原谅” 行为 :

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

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

支持自定义对象/值

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

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() 当您不再需要数据库来冲出所有待写并关闭所有文件时:

await db.close();

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

控制文件系统访问

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

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

现有以下选项:

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

与锁定文件相关的选项

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

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

复制和压缩数据库

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() 方法.

await db.compress();

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

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

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

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

跟踪时间戳

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

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

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

导入/导出

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

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

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

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

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) (中文(简体) )

第一次正式发布