deepbase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DeepBase

Overview

概述

DeepBase is a multi-driver persistence system for Node.js that provides a unified API across storage backends (JSON, SQLite, MongoDB, Redis, IndexedDB). It allows switching or combining backends without changing application code.

Use this skill when:

Adding persistence to a Node.js project
Setting up multi-backend storage with automatic failover
Migrating data between storage drivers
Working with nested object paths for data access
Integrating any DeepBase driver package

Do NOT use this skill when:

The project needs a full ORM or relational query builder (use Prisma, Drizzle, etc.)
The project requires SQL queries, joins, or complex aggregations
The task is about browser-only storage without DeepBase (use raw IndexedDB/localStorage)

DeepBase是一款适用于Node.js的多驱动持久化系统，可在多种存储后端（JSON、SQLite、MongoDB、Redis、IndexedDB）间提供统一API。它支持在不修改应用代码的情况下切换或组合不同后端。

在以下场景使用本技能：

为Node.js项目添加持久化功能
配置带自动故障转移的多后端存储
在不同存储驱动间迁移数据
使用嵌套对象路径进行数据访问
集成任意DeepBase驱动包

请勿在以下场景使用本技能：

项目需要完整ORM或关系型查询构建器（请使用Prisma、Drizzle等）
项目需要SQL查询、关联查询或复杂聚合操作
任务仅涉及浏览器端存储且不使用DeepBase（请使用原生IndexedDB/localStorage）

Installation

安装

bash

undefined

bash

undefined

Core package (includes JSON driver by default)

npm install deepbase

Optional drivers — install only what you need

npm install deepbase-sqlite # SQLite (better-sqlite3) npm install deepbase-mongodb # MongoDB npm install deepbase-redis # Redis (vanilla) npm install deepbase-redis-json # Redis Stack (RedisJSON) npm install deepbase-indexeddb # Browser IndexedDB


The core `deepbase` package depends on `deepbase-json` and `nanoid`. No other drivers are required unless explicitly used.


核心`deepbase`包依赖`deepbase-json`和`nanoid`。除非明确使用，否则无需安装其他驱动。

Imports

导入

javascript

// ES Modules (recommended)
import DeepBase from 'deepbase';
import { DeepBase, DeepBaseDriver } from 'deepbase';

// CommonJS
const { DeepBase } = require('deepbase');

// Individual drivers
import { JsonDriver } from 'deepbase-json';
import { MongoDriver } from 'deepbase-mongodb';
import { SqliteDriver } from 'deepbase-sqlite';
import { RedisDriver } from 'deepbase-redis';
import { RedisDriver as RedisJsonDriver } from 'deepbase-redis-json';
import { IndexedDBDriver } from 'deepbase-indexeddb';

javascript

// ES Modules (recommended)
import DeepBase from 'deepbase';
import { DeepBase, DeepBaseDriver } from 'deepbase';

// CommonJS
const { DeepBase } = require('deepbase');

// Individual drivers
import { JsonDriver } from 'deepbase-json';
import { MongoDriver } from 'deepbase-mongodb';
import { SqliteDriver } from 'deepbase-sqlite';
import { RedisDriver } from 'deepbase-redis';
import { RedisDriver as RedisJsonDriver } from 'deepbase-redis-json';
import { IndexedDBDriver } from 'deepbase-indexeddb';

Basic Usage

基础用法

Single driver (JSON — simplest setup)

单驱动（JSON — 最简配置）

javascript

import DeepBase from 'deepbase';

const db = new DeepBase({ path: './data', name: 'app' });
await db.connect();

await db.set('config', 'theme', 'dark');
const theme = await db.get('config', 'theme'); // 'dark'

await db.disconnect();

Lazy connect is enabled by default —

connect()

is called automatically on first operation if omitted.

javascript

import DeepBase from 'deepbase';

const db = new DeepBase({ path: './data', name: 'app' });
await db.connect();

await db.set('config', 'theme', 'dark');
const theme = await db.get('config', 'theme'); // 'dark'

await db.disconnect();

默认启用延迟连接——如果省略

connect()

，会在首次操作时自动调用。

Multi-driver with failover

带故障转移的多驱动

javascript

import DeepBase from 'deepbase';
import { JsonDriver } from 'deepbase-json';
import { MongoDriver } from 'deepbase-mongodb';

const db = new DeepBase([
  new MongoDriver({ url: 'mongodb://localhost:27017', database: 'myapp', collection: 'data' }),
  new JsonDriver({ path: './backup', name: 'fallback' })
], {
  writeAll: true,            // Write to all drivers (default: true)
  readFirst: true,           // Read from first available (default: true)
  failOnPrimaryError: false  // Continue if primary fails
});

await db.connect();
// Writes go to both MongoDB and JSON; reads try MongoDB first, fall back to JSON

javascript

import DeepBase from 'deepbase';
import { JsonDriver } from 'deepbase-json';
import { MongoDriver } from 'deepbase-mongodb';

const db = new DeepBase([
  new MongoDriver({ url: 'mongodb://localhost:27017', database: 'myapp', collection: 'data' }),
  new JsonDriver({ path: './backup', name: 'fallback' })
], {
  writeAll: true,            // 写入所有驱动（默认：true）
  readFirst: true,           // 优先从第一个可用驱动读取（默认：true）
  failOnPrimaryError: false  // 主驱动故障时继续执行
});

await db.connect();
// 写入操作会同时同步到MongoDB和JSON；读取操作优先尝试MongoDB，失败则回退到JSON

API Reference

API参考

All methods are async. Path arguments are variadic strings representing nested keys.

所有方法均为异步。路径参数为可变长度字符串，代表嵌套键。

Data operations

数据操作

Method	Signature	Description
`get`	`get(...path)`	Get value at path. Returns `null` if not found.
`set`	`set(...path, value)`	Set value at path. Last argument is the value.
`del`	`del(...path)`	Delete value at path.
`inc`	`inc(...path, amount)`	Increment numeric value.
`dec`	`dec(...path, amount)`	Decrement numeric value.
`add`	`add(...path, value)`	Add item with auto-generated ID. Returns full path array.
`upd`	`upd(...path, fn)`	Atomic update — passes current value to `fn` , stores the return value.

方法	签名	描述
`get`	`get(...path)`	获取指定路径的值。若未找到则返回 `null` 。
`set`	`set(...path, value)`	设置指定路径的值。最后一个参数为要设置的值。
`del`	`del(...path)`	删除指定路径的值。
`inc`	`inc(...path, amount)`	递增数值类型的值。
`dec`	`dec(...path, amount)`	递减数值类型的值。
`add`	`add(...path, value)`	添加带自动生成ID的项。返回完整路径数组。
`upd`	`upd(...path, fn)`	原子更新——将当前值传入 `fn` ，并存储其返回值。

Query operations

查询操作

Method	Signature	Description
`keys`	`keys(...path)`	Get keys at path (array of strings).
`values`	`values(...path)`	Get values at path.
`entries`	`entries(...path)`	Get `[key, value]` pairs at path.
`pop`	`pop(...path)`	Remove and return the last item.
`shift`	`shift(...path)`	Remove and return the first item.

方法	签名	描述
`keys`	`keys(...path)`	获取指定路径下的所有键（字符串数组）。
`values`	`values(...path)`	获取指定路径下的所有值。
`entries`	`entries(...path)`	获取指定路径下的 `[键, 值]` 对。
`pop`	`pop(...path)`	删除并返回最后一项。
`shift`	`shift(...path)`	删除并返回第一项。

Connection

连接管理

Method	Description
`connect()`	Connect all drivers. Returns `{ connected, total }` .
`disconnect()`	Disconnect all drivers.

方法	描述
`connect()`	连接所有驱动。返回 `{ connected, total }` 。
`disconnect()`	断开所有驱动的连接。

Driver access

驱动访问

Method	Description
`getDriver(index)`	Get driver instance by index (default: 0).
`getDrivers()`	Get array of all driver instances.

方法	描述
`getDriver(index)`	通过索引获取驱动实例（默认：0）。
`getDrivers()`	获取所有驱动实例的数组。

Migration

数据迁移

javascript

// Migrate data from driver 0 to driver 1
await db.migrate(0, 1, {
  clear: true,       // Clear target first (default: true)
  batchSize: 100,    // Progress callback interval
  onProgress: ({ migrated, errors, current }) => console.log(`${migrated} items`)
});

// Sync primary (index 0) to all other drivers
await db.syncAll({ clear: true });

javascript

// 将数据从驱动0迁移到驱动1
await db.migrate(0, 1, {
  clear: true,       // 先清空目标驱动（默认：true）
  batchSize: 100,    // 进度回调的间隔
  onProgress: ({ migrated, errors, current }) => console.log(`${migrated} items`)
});

// 将主驱动（索引0）同步到所有其他驱动
await db.syncAll({ clear: true });

Constructor Options

构造函数选项

javascript

new DeepBase(drivers, {
  writeAll: true,              // Write to all drivers
  readFirst: true,             // Read from first available driver in order
  failOnPrimaryError: true,    // Throw if primary driver (index 0) fails
  lazyConnect: true,           // Auto-connect on first operation
  timeout: 0,                  // Global timeout in ms (0 = disabled)
  readTimeout: 0,              // Override for read operations
  writeTimeout: 0,             // Override for write operations
  connectTimeout: 0            // Override for connect
});

javascript

new DeepBase(drivers, {
  writeAll: true,              // 写入所有驱动
  readFirst: true,             // 按顺序从第一个可用驱动读取
  failOnPrimaryError: true,    // 主驱动（索引0）故障时抛出错误
  lazyConnect: true,           // 首次操作时自动连接
  timeout: 0,                  // 全局超时时间（毫秒，0表示禁用）
  readTimeout: 0,              // 覆盖读取操作的超时时间
  writeTimeout: 0,             // 覆盖写入操作的超时时间
  connectTimeout: 0            // 覆盖连接操作的超时时间
});

Driver Configuration

驱动配置

Driver	Key Options
`JsonDriver`	`path` (directory), `name` (filename), `stringify` / `parse` (custom serialization)
`SqliteDriver`	`path` (directory), `name` (database filename)
`MongoDriver`	`url` , `database` , `collection`
`RedisDriver`	`url` , `prefix`
`RedisJsonDriver`	`url` , `prefix` (requires Redis Stack with RedisJSON module)
`IndexedDBDriver`	`name` , `version`

驱动	关键选项
`JsonDriver`	`path` （目录）、 `name` （文件名）、 `stringify` / `parse` （自定义序列化）
`SqliteDriver`	`path` （目录）、 `name` （数据库文件名）
`MongoDriver`	`url` 、 `database` 、 `collection`
`RedisDriver`	`url` 、 `prefix`
`RedisJsonDriver`	`url` 、 `prefix` （需要带RedisJSON模块的Redis Stack）
`IndexedDBDriver`	`name` 、 `version`

Agent Usage Rules

Agent使用规则

Check before installing. Verify
```
package.json
```
for existing
```
deepbase
```
dependency before running
```
npm install
```
.
Use the official API. Never manipulate driver internals or the underlying JSON/SQLite/Mongo storage directly. Always go through
```
db.get()
```
,
```
db.set()
```
, etc.
Prefer lazy connect. Do not call
```
db.connect()
```
explicitly unless you need the
```
{ connected, total }
```
result. Lazy connect handles it automatically.
Always
disconnect()
on shutdown. Especially important for MongoDB and Redis drivers to release connections.
Use
add()
for auto-IDs. Do not manually generate IDs with nanoid/uuid —
```
add()
```
returns the full path array including the generated ID.
Spread the path from
add()
. The return value is an array: use
```
await db.get(...userPath)
```
to retrieve the added item.
Use
upd()
for atomic changes. When modifying existing values based on their current state, use
```
upd()
```
instead of
```
get()
```
+
```
set()
```
to avoid race conditions.
Set
failOnPrimaryError: false
for resilient setups. When using multi-driver for fault tolerance, disable this so operations continue via fallback drivers.
Use environment variables for connection strings. Never hardcode MongoDB URLs or Redis URLs in source code.
Prefer
deepbase-redis-json
over
deepbase-redis
when working with Redis Stack, as it supports native JSON operations.

安装前检查：运行
```
npm install
```
前，先检查
```
package.json
```
中是否已存在
```
deepbase
```
依赖。
使用官方API：切勿直接操作驱动内部或底层的JSON/SQLite/Mongo存储，始终通过
```
db.get()
```
、
```
db.set()
```
等官方方法操作。
优先使用延迟连接：除非需要
```
{ connected, total }
```
结果，否则不要显式调用
```
db.connect()
```
，延迟连接会自动处理。
关闭时务必调用
disconnect()
：对于MongoDB和Redis驱动尤其重要，需释放连接资源。
使用
add()
生成自动ID：不要手动用nanoid/uuid生成ID——
```
add()
```
会返回包含生成ID的完整路径数组。
展开
add()
返回的路径：返回值是数组，需使用
```
await db.get(...userPath)
```
来获取添加的项。
原子更新使用
upd()
：当基于当前值修改现有数据时，使用
```
upd()
```
而非
```
get()
```
+
```
set()
```
，避免竞态条件。
高可用配置设置
failOnPrimaryError: false
：当使用多驱动实现容错时，禁用该选项以便故障时通过备用驱动继续操作。
使用环境变量存储连接字符串：切勿在源代码中硬编码MongoDB或Redis的URL。
使用Redis Stack时优先选
deepbase-redis-json
：它支持原生JSON操作，优于
```
deepbase-redis
```
。

Common Tasks

常见任务

Store and retrieve nested data

存储和获取嵌套数据

javascript

await db.set('users', 'alice', { name: 'Alice', age: 30 });
await db.set('users', 'alice', 'email', 'alice@example.com');
const user = await db.get('users', 'alice');
// { name: 'Alice', age: 30, email: 'alice@example.com' }

javascript

await db.set('users', 'alice', { name: 'Alice', age: 30 });
await db.set('users', 'alice', 'email', 'alice@example.com');
const user = await db.get('users', 'alice');
// { name: 'Alice', age: 30, email: 'alice@example.com' }

Add items with auto-generated IDs

添加带自动生成ID的项

javascript

const userPath = await db.add('users', { name: 'Bob', email: 'bob@example.com' });
// userPath = ['users', 'aB3xK9mL2n']
const user = await db.get(...userPath);

javascript

const userPath = await db.add('users', { name: 'Bob', email: 'bob@example.com' });
// userPath = ['users', 'aB3xK9mL2n']
const user = await db.get(...userPath);

Increment/decrement counters

递增/递减计数器

javascript

await db.set('stats', 'views', 0);
await db.inc('stats', 'views');      // 1
await db.inc('stats', 'views', 10);  // 11
await db.dec('stats', 'views', 5);   // 6

javascript

await db.set('stats', 'views', 0);
await db.inc('stats', 'views');      // 1
await db.inc('stats', 'views', 10);  // 11
await db.dec('stats', 'views', 5);   // 6

Atomic update

原子更新

javascript

await db.upd('user', 'name', name => name.toUpperCase());

javascript

await db.upd('user', 'name', name => name.toUpperCase());

Iterate over collections

遍历集合

javascript

const userKeys = await db.keys('users');
const userList = await db.values('users');
const userEntries = await db.entries('users'); // [[id, data], ...]

javascript

const userKeys = await db.keys('users');
const userList = await db.values('users');
const userEntries = await db.entries('users'); // [[id, data], ...]

Pop/shift from collections

从集合中弹出/移除首项

javascript

const last = await db.pop('queue');    // Remove and return last item
const first = await db.shift('queue'); // Remove and return first item

javascript

const last = await db.pop('queue');    // 删除并返回最后一项
const first = await db.shift('queue'); // 删除并返回第一项

Custom JSON serialization (circular references)

自定义JSON序列化（处理循环引用）

javascript

import { JsonDriver } from 'deepbase-json';
import { stringify, parse } from 'flatted';

const db = new DeepBase(new JsonDriver({
  path: './data',
  name: 'circular',
  stringify,
  parse
}));

javascript

import { JsonDriver } from 'deepbase-json';
import { stringify, parse } from 'flatted';

const db = new DeepBase(new JsonDriver({
  path: './data',
  name: 'circular',
  stringify,
  parse
}));

Three-tier architecture

三层架构配置

javascript

const db = new DeepBase([
  new MongoDriver({ url: process.env.MONGO_URL, database: 'app' }),
  new JsonDriver({ path: './backup' }),
  new RedisDriver({ url: process.env.REDIS_URL })
], { writeAll: true, failOnPrimaryError: false });

javascript

const db = new DeepBase([
  new MongoDriver({ url: process.env.MONGO_URL, database: 'app' }),
  new JsonDriver({ path: './backup' }),
  new RedisDriver({ url: process.env.REDIS_URL })
], { writeAll: true, failOnPrimaryError: false });

Extend with a custom driver

扩展自定义驱动

javascript

import { DeepBaseDriver } from 'deepbase';

class MyDriver extends DeepBaseDriver {
  async connect() { /* ... */ this._connected = true; }
  async disconnect() { /* ... */ }
  async get(...args) { /* ... */ }
  async set(...args) { /* ... */ }
  async del(...args) { /* ... */ }
  async inc(...args) { /* ... */ }
  async dec(...args) { /* ... */ }
  async add(...args) { /* ... */ }
  async upd(...args) { /* ... */ }
}

All methods listed in

DeepBaseDriver

must be implemented.

keys()

values()

entries()

have default implementations that call

get()

javascript

import { DeepBaseDriver } from 'deepbase';

class MyDriver extends DeepBaseDriver {
  async connect() { /* ... */ this._connected = true; }
  async disconnect() { /* ... */ }
  async get(...args) { /* ... */ }
  async set(...args) { /* ... */ }
  async del(...args) { /* ... */ }
  async inc(...args) { /* ... */ }
  async dec(...args) { /* ... */ }
  async add(...args) { /* ... */ }
  async upd(...args) { /* ... */ }
}

必须实现

DeepBaseDriver

中列出的所有方法。

keys()

、

values()

、

entries()

有默认实现，会调用

get()

。

Troubleshooting

故障排除

All drivers must extend DeepBaseDriver
— Ensure all drivers in the array are proper driver instances, not plain objects.
Operation timed out — Increase
```
timeout
```
,
```
readTimeout
```
, or
```
writeTimeout
```
in the constructor options.
MongoDB/Redis connection fails silently — Set
```
failOnPrimaryError: true
```
(default) to surface connection errors, or check
```
connect()
```
return value for
```
{ connected, total }
```
.
Data not synced across drivers — Ensure
```
writeAll: true
```
(default). For existing data, use
```
db.migrate()
```
or
```
db.syncAll()
```
.
Stale reads after failover — The fallback driver may have older data. Use
```
db.syncAll()
```
after the primary recovers.

All drivers must extend DeepBaseDriver
— 确保数组中的所有驱动都是正确的驱动实例，而非普通对象。
Operation timed out — 在构造函数选项中增大
```
timeout
```
、
```
readTimeout
```
或
```
writeTimeout
```
的值。
MongoDB/Redis连接静默失败 — 设置
```
failOnPrimaryError: true
```
（默认值）以暴露连接错误，或检查
```
connect()
```
返回的
```
{ connected, total }
```
结果。
数据未在驱动间同步 — 确保
```
writeAll: true
```
（默认值）。对于已有数据，使用
```
db.migrate()
```
或
```
db.syncAll()
```
同步。
故障转移后读取到旧数据 — 备用驱动可能存储的是旧数据。主驱动恢复后使用
```
db.syncAll()
```
同步数据。

References

参考资料

Repository: https://github.com/clasen/DeepBase
npm: https://www.npmjs.com/package/deepbase
Examples:
```
examples/
```
directory in the repository (01 through 12)

Monorepo packages:

packages/core

packages/driver-json

packages/driver-sqlite

packages/driver-mongodb

packages/driver-redis

packages/driver-redis-json

packages/driver-indexeddb

仓库地址：https://github.com/clasen/DeepBase
npm地址：https://www.npmjs.com/package/deepbase
示例：仓库中的
```
examples/
```
目录（01至12）

单仓库包：

packages/core

、

packages/driver-json

、

packages/driver-sqlite

、

packages/driver-mongodb

、

packages/driver-redis

、

packages/driver-redis-json

、

packages/driver-indexeddb