sqlite-executor 4.0.1

package/LICENSE

@@ -0,0 +1,46 @@
+Copyright (c) 2025 Axetroy
+
+"Anti 996" License Version 1.0 (Draft)
+
+Permission is hereby granted to any individual or legal entity
+obtaining a copy of this licensed work (including the source code,
+documentation and/or related items, hereinafter collectively referred
+to as the "licensed work"), free of charge, to deal with the licensed
+work for any purpose, including without limitation, the rights to use,
+reproduce, modify, prepare derivative works of, distribute, publish
+and sublicense the licensed work, subject to the following conditions:
+
+1. The individual or the legal entity must conspicuously display,
+without modification, this License and the notice on each redistributed
+or derivative copy of the Licensed Work.
+
+2. The individual or the legal entity must strictly comply with all
+applicable laws, regulations, rules and standards of the jurisdiction
+relating to labor and employment where the individual is physically
+located or where the individual was born or naturalized; or where the
+legal entity is registered or is operating (whichever is stricter). In
+case that the jurisdiction has no such laws, regulations, rules and
+standards or its laws, regulations, rules and standards are
+unenforceable, the individual or the legal entity are required to
+comply with Core International Labor Standards.
+
+3. The individual or the legal entity shall not induce, suggest or force
+its employee(s), whether full-time or part-time, or its independent
+contractor(s), in any methods, to agree in oral or written form, to
+directly or indirectly restrict, weaken or relinquish his or her
+rights or remedies under such laws, regulations, rules and standards
+relating to labor and employment as mentioned above, no matter whether
+such written or oral agreements are enforceable under the laws of the
+said jurisdiction, nor shall such individual or the legal entity
+limit, in any methods, the rights of its employee(s) or independent
+contractor(s) from reporting or complaining to the copyright holder or
+relevant authorities monitoring the compliance of the license about
+its violation(s) of the said license.
+
+THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN ANY WAY CONNECTION WITH THE
+LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE LICENSED WORK.

package/README.md

@@ -0,0 +1,312 @@
+# sqlite-executor
+
+[![Badge](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg?style=flat-square)](https://996.icu/#/en_US)
+[![LICENSE](https://img.shields.io/badge/license-Anti%20996-blue.svg?style=flat-square)](https://github.com/996icu/996.ICU/blob/master/LICENSE)
+![Node](https://img.shields.io/badge/node-%3E=18-blue.svg?style=flat-square)
+[![npm version](https://badge.fury.io/js/sqlite-executor.svg)](https://badge.fury.io/js/sqlite-executor)
+![CI](https://github.com/axetroy/sqlite-wrapper.js/actions/workflows/build.yml/badge.svg)
+
+A lightweight, zero-dependency SQLite wrapper for Node.js that communicates with the `sqlite3` CLI via stdin/stdout — no native addons, no `node-gyp`, no ABI headaches.
+
+## Features
+
+- 🚀 **Zero native dependencies** — pure JavaScript, no compilation needed
+- ⚡ **Long-lived process** — single `sqlite3` process for the entire app lifecycle
+- 🔄 **Promise-based API** — `execute()`, `query()`, `stream()`
+- 📦 **Async Iterator support** — `for await (const row of db.stream(sql))`
+- 🔐 **Transactions** — automatic `BEGIN … COMMIT / ROLLBACK` with concurrent caller serialization
+- 📊 **Read/Write Split** — dedicated reader pool for concurrent read queries
+- ⏱️ **Timeout control** — per-statement timeout with process-level failure recovery
+- 🔁 **Auto-restart** — crashed process restarts automatically
+- 📈 **Runtime metrics** — QPS, avg query time, timeout count, process restarts
+- 📝 **Full TypeScript types** — included
+- 📦 **Dual module** — ESM + CommonJS
+
+## Requirements
+
+- Node.js >= 18
+- `sqlite3` CLI executable available on the system
+
+## Installation
+
+```bash
+npm install sqlite-executor --save
+```
+
+## Quick Start
+
+```js
+import { SQLiteExecutor } from "sqlite-executor";
+
+const db = new SQLiteExecutor({ database: "./app.db" });
+
+await db.execute(`CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT
+)`);
+
+await db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+await db.execute("INSERT INTO users (name) VALUES (?)", ["Bob"]);
+
+const rows = await db.query("SELECT * FROM users ORDER BY id ASC");
+console.log(rows);
+// [ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' } ]
+
+await db.close();
+```
+
+## API Reference
+
+### `SQLiteExecutor`
+
+#### Constructor
+
+```js
+new SQLiteExecutor(options?)
+```
+
+| Option              | Type      | Default        | Description                                              |
+| ------------------- | --------- | -------------- | -------------------------------------------------------- |
+| `binary`            | `string`  | `"sqlite3"`    | Path to the `sqlite3` executable                          |
+| `database`          | `string`  | `":memory:"`   | Database file path                                       |
+| `logger`            | `Logger`  | —              | Optional logger (`log`, `info`, `warn`, `error`, `debug`) |
+| `statementTimeout`  | `number`  | `30000`        | Per-statement timeout in milliseconds                     |
+| `autoRestart`       | `boolean` | `true`         | Auto-restart on process crash                             |
+| `poolSize`          | `number`  | `0`            | Reader pool size (read/write split, file DB only)         |
+| `metrics`           | `Metrics` | auto-created   | Shared metrics instance                                   |
+
+#### `db.execute(sql, params?, options?)`
+
+Executes a SQL statement without returning rows. Use for `CREATE`, `INSERT`, `UPDATE`, `DELETE`.
+
+```js
+await db.execute("CREATE TABLE t (id INTEGER)");
+await db.execute("INSERT INTO t (id) VALUES (?)", [1]);
+await db.execute("UPDATE t SET id = ? WHERE id = ?", [2, 1]);
+```
+
+#### `db.query(sql, params?, options?)`
+
+Executes a query and returns all result rows as an array.
+
+```js
+const rows = await db.query("SELECT * FROM users WHERE id = ?", [1]);
+// [ { id: 1, name: 'Alice' } ]
+```
+
+#### `db.stream(sql, params?, options?)`
+
+Returns an `AsyncIterable` for `for await` consumption.
+
+```js
+for await (const row of db.stream("SELECT * FROM huge_table")) {
+  process(row);
+}
+```
+
+Supports early `break` — the underlying process is not affected.
+
+#### `db.transaction(fn, options?)`
+
+Executes a callback inside a SQLite transaction (`BEGIN` / `COMMIT` / `ROLLBACK`). Concurrent calls are serialized — they never interleave.
+
+```js
+await db.transaction(async (tx) => {
+  await tx.execute("INSERT INTO accounts (id, balance) VALUES (?, ?)", [1, 100]);
+  await tx.execute("INSERT INTO accounts (id, balance) VALUES (?, ?)", [2, 200]);
+}, "IMMEDIATE");
+```
+
+Inside the transaction callback, use the `tx` handle (`execute`, `query`, `stream`) — bare `db.*` calls would break transactional isolation.
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `mode` | `"DEFERRED"` \| `"IMMEDIATE"` \| `"EXCLUSIVE"` | `"DEFERRED"` | SQLite transaction lock mode |
+
+#### `db.close()`
+
+Closes the sqlite3 process and rejects all pending tasks.
+
+```js
+await db.close();
+```
+
+`SQLiteExecutor` also implements `Symbol.asyncDispose` and `Symbol.dispose`:
+
+```js
+// Using explicit resource management (ES2025)
+await using db = new SQLiteExecutor({ database: "./app.db" });
+```
+
+#### `db.pendingStatements`
+
+Returns the total number of pending statements across the writer queue, reader pool, and deferred queue.
+
+#### `db.readerPool`
+
+Returns the `ReaderPool` instance when `poolSize > 0` and the database is a file DB. Returns `null` otherwise.
+
+#### `db.metrics`
+
+Returns the `Metrics` instance. See below.
+
+### `Metrics`
+
+Runtime metrics collector, accessible via `db.metrics`.
+
+```js
+const stats = db.metrics.snapshot();
+console.log(stats);
+// {
+//   tasksTotal: 42,
+//   tasksSuccess: 40,
+//   tasksFailed: 2,
+//   tasksTimeout: 1,
+//   processRestarts: 0,
+//   executeCount: 20,
+//   queryCount: 22,
+//   streamCount: 0,
+//   avgQueryTime: 15.3,   // ms
+//   qps: 8.2,             // queries per second
+//   uptime: 5.1,          // seconds
+// }
+```
+
+| Method / Getter        | Returns        | Description                          |
+| ---------------------- | -------------- | ------------------------------------ |
+| `snapshot()`           | `object`       | All metrics as a plain object         |
+| `tasksTotal`           | `number`       | Total tasks enqueued                  |
+| `tasksSuccess`         | `number`       | Successfully completed tasks          |
+| `tasksFailed`          | `number`       | Failed tasks                          |
+| `tasksTimeout`         | `number`       | Timed-out tasks                       |
+| `processRestarts`      | `number`       | sqlite3 process restarts              |
+| `executeCount`         | `number`       | `execute` calls                       |
+| `queryCount`           | `number`       | `query` calls                         |
+| `streamCount`          | `number`       | `stream` calls                        |
+
+Multiple executors / workers can share the same `Metrics` instance:
+
+```js
+import { SQLiteExecutor, Metrics } from "sqlite-executor";
+
+const metrics = new Metrics();
+
+const db1 = new SQLiteExecutor({ database: "./a.db", metrics });
+const db2 = new SQLiteExecutor({ database: "./b.db", metrics });
+```
+
+### TypeScript Usage
+
+```typescript
+import { SQLiteExecutor } from "sqlite-executor";
+
+interface User {
+  id: number;
+  name: string;
+}
+
+const db = new SQLiteExecutor({ database: "./users.db" });
+
+await db.execute(`CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL
+)`);
+
+const users = await db.query<User>("SELECT * FROM users");
+// users: User[]
+```
+
+## Advanced Usage
+
+### Read/Write Split with Reader Pool
+
+For file-based databases, you can enable a reader pool for concurrent read queries:
+
+```js
+const db = new SQLiteExecutor({
+  database: "./app.db",
+  poolSize: 3,   // 3 reader processes
+});
+```
+
+Writes always go through the main writer process. Reads (`SELECT`, `WITH`, `VALUES`, `EXPLAIN`) are dispatched to a pool of `TaskWorker` instances via round-robin. This prevents long-running reads from blocking writes.
+
+### Parameterized Queries
+
+SQL parameters use `?` placeholders with automatic escaping:
+
+```js
+await db.execute("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@example.com"]);
+const rows = await db.query("SELECT * FROM users WHERE email = ?", ["alice@example.com"]);
+```
+
+Supported parameter types:
+
+| Type                 | SQL Output                              |
+| -------------------- | --------------------------------------- |
+| `string`             | `'value'` (properly escaped)            |
+| `number`             | `123`                                   |
+| `bigint`             | `123`                                   |
+| `boolean`            | `TRUE` / `FALSE`                        |
+| `null` / `undefined` | `NULL`                                  |
+| `Date`               | `'2024-01-15T10:30:00.000Z'` (ISO 8601) |
+
+### Error Handling
+
+SQL errors from sqlite3 are captured and the task promise is rejected:
+
+```js
+try {
+  await db.query("SELECT * FROM nonexistent");
+} catch (err) {
+  console.log(err.message);  // "Parse error near line 1: no such table: nonexistent"
+}
+```
+
+Process crashes are handled automatically — the current task and all queued tasks are rejected, and a new process is spawned (if `autoRestart` is enabled, which is the default).
+
+### Using with Logger
+
+```js
+const db = new SQLiteExecutor({
+  database: "./app.db",
+  logger: {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+  },
+});
+```
+
+### Streaming Large Result Sets
+
+```js
+for await (const row of db.stream("SELECT * FROM logs WHERE created_at > ?", [date])) {
+  sendToClient(row);
+}
+```
+
+## Benchmarks
+
+```bash
+npm run benchmark
+```
+
+See the [benchmark directory](./benchmark/README.md) for details.
+
+## Project Structure
+
+```text
+src/         Source code
+benchmark/   Performance benchmarks
+script/      Utility scripts (e.g. sqlite binary download)
+fixtures/    CJS/ESM fixtures for packaging tests
+bin/         Downloaded sqlite3 binaries
+dist/        Build outputs
+```
+
+## License
+
+The [Anti 996 License](LICENSE)

package/dist/cjs/constants.d.cts

@@ -0,0 +1,2 @@
+/** 标记列名，用于在查询结果末尾标识语句结束 */
+export const TOKEN_COLUMN: "__sqlite_executor_token__";

package/dist/cjs/core/classifier.d.cts

@@ -0,0 +1,13 @@
+/**
+ * 对 SQL 语句进行分类，判断它是只读还是写入操作。
+ *
+ * 分类规则：
+ * - 以 SELECT / WITH / VALUES / EXPLAIN 开头 → `"read"`
+ * - 其余（INSERT、UPDATE、CREATE、DELETE 等）→ `"write"`
+ * - 多语句（以 `;` 分隔）中若包含任意写语句，整体返回 `"write"`
+ * - 空字符串或非字符串输入返回 `"write"`
+ *
+ * @param sql - 要分类的 SQL 语句
+ * @returns `"read"` 或 `"write"`
+ */
+export function classifySQL(sql: string): "read" | "write";

package/dist/cjs/core/executor.d.cts

@@ -0,0 +1,94 @@
+/** 日志接口，可选实现多个级别 */
+export interface Logger {
+	log?(...messages: unknown[]): void;
+	info?(...messages: unknown[]): void;
+	warn?(...messages: unknown[]): void;
+	error?(...messages: unknown[]): void;
+	debug?(...messages: unknown[]): void;
+}
+
+/** SQLiteExecutor 构造选项 */
+export interface SQLiteExecutorOptions {
+	/** sqlite3 可执行文件路径，默认自动查找 */
+	binary?: string;
+	/** 数据库文件路径，默认 ":memory:" */
+	database?: string;
+	/** 日志记录器 */
+	logger?: Logger;
+	/** 单条语句超时时间（毫秒），默认 30000 */
+	statementTimeout?: number;
+	/** 子进程崩溃后是否自动重启，默认 true */
+	autoRestart?: boolean;
+	/**
+	 * 只读 Worker 池大小。
+	 * - 设为 0（默认）：不使用读写分离，所有操作走同一个 writer 进程
+	 * - 设为 >0：启用读写分离，读操作分发到 reader pool
+	 * - `:memory:` 数据库忽略此选项（始终为 0）
+	 */
+	poolSize?: number;
+	/**
+	 * 运行时指标收集器。
+	 * 未指定时自动创建内部实例。
+	 */
+	metrics?: import("./metrics.js").Metrics;
+}
+
+/** 单条语句的执行选项 */
+export interface StatementOptions {
+	/** 覆盖超时时间（毫秒） */
+	timeout?: number;
+}
+
+/** 事务选项 */
+export interface TransactionOptions {
+	/** 事务锁模式 */
+	mode?: "DEFERRED" | "IMMEDIATE" | "EXCLUSIVE";
+}
+
+/** 事务句柄，在事务回调中代替 SQLiteExecutor 执行语句 */
+export interface TransactionHandle {
+	execute(sql: string, params?: any[], options?: StatementOptions): Promise<void>;
+	query<T = any>(sql: string, params?: any[], options?: StatementOptions): Promise<T[]>;
+	stream<T = any>(sql: string, params?: any[], options?: StatementOptions): AsyncIterable<T>;
+}
+
+/**
+ * SQLiteExecutor - 异步 SQLite 执行器。
+ *
+ * 通过衍生 sqlite3 子进程（JSON 模式）执行 SQL 语句。
+ * 支持连接池、自动重启、超时控制、读写分离和流式查询。
+ */
+export declare class SQLiteExecutor implements AsyncDisposable, Disposable {
+	constructor(options?: SQLiteExecutorOptions);
+
+	/** 当前排队等待执行的语句数量 */
+	get pendingStatements(): number;
+
+	/**
+	 * 只读 Worker 池实例。
+	 * - 启用读写分离时（poolSize > 0 且非 :memory:）返回 ReaderPool
+	 * - 否则返回 null
+	 */
+	get readerPool(): import("./readerPool.js").ReaderPool | null;
+
+	/** 运行时指标收集器。 */
+	get metrics(): import("./metrics.js").Metrics;
+
+	/** 执行写操作（INSERT/UPDATE/CREATE 等），返回无行结果 */
+	execute(sql: string, params?: any[], options?: StatementOptions): Promise<void>;
+
+	/** 执行查询并返回所有结果行数组 */
+	query<T = any>(sql: string, params?: any[], options?: StatementOptions): Promise<T[]>;
+
+	/** 流式执行查询，返回 AsyncIterable，可配合 `for await` 逐行消费 */
+	stream<T = any>(sql: string, params?: any[], options?: StatementOptions): AsyncIterable<T>;
+
+	/** 在事务中执行回调，所有操作在同一连接上完成 */
+	transaction<T>(fn: (tx: TransactionHandle) => Promise<T>, options?: TransactionOptions): Promise<T>;
+
+	/** 关闭所有子进程，释放资源 */
+	close(): Promise<void>;
+
+	[Symbol.asyncDispose](): Promise<void>;
+	[Symbol.dispose](): void;
+}

package/dist/cjs/core/lruCache.d.cts

@@ -0,0 +1,16 @@
+/** 基于 Map 插入顺序的 LRU 缓存。 */
+export declare class LRUCache<T> {
+	constructor(options?: { maxSize?: number; maxKeyLength?: number });
+
+	/** 获取缓存值，命中时提升到末尾。未命中或 key 不合法时返回 undefined。 */
+	get(key: string): T | undefined;
+
+	/** 设置缓存值。达到容量上限时淘汰最旧条目。超长 key 不缓存。 */
+	set(key: string, value: T): void;
+
+	/** 当前缓存条目数。 */
+	get size(): number;
+
+	/** 清空缓存。 */
+	clear(): void;
+}

package/dist/cjs/core/metrics.d.cts

@@ -0,0 +1,84 @@
+/** Metrics.snapshot() 返回的快照结构 */
+export interface MetricsSnapshot {
+	/** 总任务数 */
+	tasksTotal: number;
+	/** 成功任务数 */
+	tasksSuccess: number;
+	/** 失败任务数 */
+	tasksFailed: number;
+	/** 超时任务数 */
+	tasksTimeout: number;
+	/** 子进程重启次数 */
+	processRestarts: number;
+	/** execute 操作执行次数 */
+	executeCount: number;
+	/** query 操作执行次数 */
+	queryCount: number;
+	/** stream 操作执行次数 */
+	streamCount: number;
+	/** 平均查询耗时（毫秒） */
+	avgQueryTime: number;
+	/** 每秒查询数 */
+	qps: number;
+	/** 运行时长（秒） */
+	uptime: number;
+}
+
+/**
+ * 运行时指标收集器。
+ *
+ * 追踪 SQL 执行任务的吞吐、耗时、错误、超时和进程重启。
+ * 可通过 `snapshot()` 获取当前快照用于监控和告警。
+ */
+export declare class Metrics {
+	/** 总任务数 */
+	get tasksTotal(): number;
+	/** 成功任务数 */
+	get tasksSuccess(): number;
+	/** 失败任务数 */
+	get tasksFailed(): number;
+	/** 超时任务数 */
+	get tasksTimeout(): number;
+	/** 子进程重启次数 */
+	get processRestarts(): number;
+	/** execute 操作执行次数 */
+	get executeCount(): number;
+	/** query 操作执行次数 */
+	get queryCount(): number;
+	/** stream 操作执行次数 */
+	get streamCount(): number;
+	/** 所有成功任务的总耗时（毫秒） */
+	get totalDuration(): number;
+	/** Metrics 实例的创建时间戳 */
+	get startTime(): number;
+
+	/**
+	 * 增加任务总数计数。
+	 *
+	 * @param kind - 任务类型：execute（写操作）、query（查询）、stream（流式查询）
+	 */
+	incrementTasksTotal(kind: "execute" | "query" | "stream"): void;
+
+	/**
+	 * 增加成功任务计数，并累加耗时。
+	 *
+	 * @param duration - 任务执行耗时（毫秒）
+	 */
+	incrementTasksSuccess(duration: number): void;
+
+	/** 增加失败任务计数。 */
+	incrementTasksFailed(): void;
+
+	/** 增加超时任务计数。 */
+	incrementTasksTimeout(): void;
+
+	/** 增加子进程重启次数计数。 */
+	incrementProcessRestarts(): void;
+
+	/**
+	 * 获取当前运行时指标快照。
+	 *
+	 * @returns 当前所有指标的汇总快照
+	 */
+	snapshot(): MetricsSnapshot;
+}

package/dist/cjs/core/parser.d.cts

@@ -0,0 +1,55 @@
+/** JSON 值流式解析器的状态 */
+export interface JsonValueParser {
+	feed(chunk: string): void;
+	reset(): void;
+	buffer: string;
+	start: number;
+	readPos: number;
+	nesting: number;
+	inString: boolean;
+	escaped: boolean;
+}
+
+/** 行流解析器的状态 */
+export interface RowStreamParser {
+	feed(chunk: string): string;
+	reset(): void;
+	buffer: string;
+	started: boolean;
+	finished: boolean;
+	inString: boolean;
+	escaped: boolean;
+	elementStart: number;
+	elementEnd: number;
+	nesting: number;
+	readPos: number;
+}
+
+/**
+ * 将任意值转为 Error 对象。
+ * 如果值已经是 Error 则直接返回，否则包装为 Error。
+ *
+ * @param value - 可能为 Error、string 或其他类型的值
+ * @returns Error 实例
+ */
+export function toError(value: unknown): Error;
+
+/**
+ * 创建一个 JSON 值流式解析器。
+ * 从 JSON 数组的块式输入中逐个提取完整值，通过回调通知。
+ * 适用于 parse 完整的 JSON 结果。
+ *
+ * @param onValue - 每次解析出一个完整值时的回调
+ * @returns 解析器实例
+ */
+export function createJsonValueParser(onValue: (raw: string) => void): JsonValueParser;
+
+/**
+ * 创建一个行流解析器。
+ * 从 JSON 数组的块式输入中逐行提取原始字符串，通过回调通知。
+ * 适用于流式逐行处理结果而不缓存全部数据。
+ *
+ * @param onRow - 每解析出一行时的回调
+ * @returns 解析器实例
+ */
+export function createRowStreamParser(onRow: (rawRow: string) => void): RowStreamParser;