sqlite-executor 4.0.1

package/dist/esm/core/lruCache.d.mts

@@ -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/esm/core/metrics.d.mts

@@ -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/esm/core/parser.d.mts

@@ -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;

package/dist/esm/core/pipelineEngine.d.mts

@@ -0,0 +1,91 @@
+import { ProcessManager } from "./process.mts";
+import { Metrics } from "./metrics.mts";
+import { Queue } from "./queue.mts";
+
+/** PipelineEngine 的构造选项 */
+export interface PipelineEngineOptions {
+	/** 运行时指标收集器 */
+	metrics: Metrics;
+	/** 单条语句超时时间（毫秒） */
+	statementTimeout: number;
+	/** 日志记录器（仅使用 error 级别） */
+	logger?: { error?: (...args: any[]) => void };
+	/** 管线化批量大小，控制一次 stdin.write 合并几条语句，默认 10 */
+	batchSize?: number;
+	/** 任务超时时的回调 */
+	onTaskTimeout?: (task: any) => void;
+}
+
+/**
+ * 管线化引擎。
+ *
+ * 核心调度组件，管理子进程的输入输出：
+ * - 将任务的 SQL payload 批量写入子进程 stdin（管线化）
+ * - 从 stdout 读取结果并路由到对应任务的 resolve/reject
+ * - 处理超时、错误、进程输出分割与解析
+ *
+ * 内部维护 mainQueue（待发送队列）和 inflight 计数器。
+ */
+export declare class PipelineEngine {
+	constructor(processManager: ProcessManager, options: PipelineEngineOptions);
+
+	/** 主任务队列（待发送到子进程的任务列表） */
+	get mainQueue(): Queue;
+
+	/** 当前排队等待和正在执行的总语句数 */
+	get pendingStatements(): number;
+
+	/**
+	 * 向引擎的缓冲区追加原始数据。
+	 * 数据通常来自子进程的 stdout/stderr。
+	 *
+	 * @param raw - 原始数据块
+	 */
+	feed(raw: string): void;
+
+	/**
+	 * 泵送逻辑：将 mainQueue 中的任务批量写入子进程 stdin。
+	 * 受 inflight 上限和 batchSize 控制，不会无限发送。
+	 */
+	pump(): void;
+
+	/** 激活引擎，开始处理队列中的任务。 */
+	activate(): void;
+
+	/** 停用引擎，暂停处理新任务。 */
+	deactivate(): void;
+
+	/**
+	 * 将任务加入主队列并触发泵送。
+	 *
+	 * @param task - 任务配置对象（包含 kind、sql、timeout、resolve、reject 等）
+	 */
+	enqueue(task: any): void;
+
+	/**
+	 * 处理子进程 stdout 数据块。
+	 * 分割数据、解析 JSON 行、匹配 sentinel token 完成任务。
+	 *
+	 * @param chunk - stdout 数据块
+	 */
+	handleStdoutChunk(chunk: string): void;
+
+	/**
+	 * 处理子进程 stderr 数据块。
+	 * 通常用于日志和调试信息。
+	 *
+	 * @param chunk - stderr 数据块
+	 */
+	handleStderrChunk(chunk: string): void;
+
+	/**
+	 * 拒绝所有尚未完成的任务。
+	 * 通常在进程崩溃或主动关闭时调用。
+	 *
+	 * @param error - 拒绝原因
+	 */
+	rejectAll(error: Error): void;
+
+	/** 销毁引擎，释放所有资源。 */
+	kill(): void;
+}

package/dist/esm/core/process.d.mts

@@ -0,0 +1,38 @@
+import { ChildProcess } from "node:child_process";
+
+/**
+ * sqlite3 子进程管理器。
+ * 封装 spawn、stdin 写入和进程销毁，提供统一的进程生命周期管理。
+ */
+export declare class ProcessManager {
+	/**
+	 * @param options.binary   sqlite3 可执行文件路径
+	 * @param options.database 数据库文件路径，不传则不打开数据库
+	 * @param options.initMode 初始化模式
+	 *   - `"wal"` （默认）：启动时通过 `-cmd` 设置 WAL 模式 + busy_timeout
+	 *   - `"none"`：不添加任何初始化参数（适用于 reader，直接继承数据库已有 WAL 模式）
+	 */
+	constructor(options?: { binary?: string; database?: string; initMode?: "wal" | "none" });
+
+	/** 当前使用的 sqlite3 可执行文件路径 */
+	get binary(): string;
+
+	/** 底层子进程实例，未启动时为 null */
+	get process(): ChildProcess | null;
+
+	/**
+	 * 启动子进程（json 模式），返回 ChildProcess 实例。
+	 * @throws {Error} 如果 binary 路径为空或文件不存在
+	 */
+	start(): ChildProcess;
+
+	/** 向子进程的 stdin 写入数据 */
+	write(data: string): void;
+
+	/**
+	 * 终止子进程。
+	 * 先尝试 SIGTERM，3 秒后未退出则 SIGKILL。
+	 * 返回被终止的 ChildProcess 或 null。
+	 */
+	kill(): ChildProcess | null;
+}

package/dist/esm/core/protocol.d.mts

@@ -0,0 +1,23 @@
+/** 标记列名，用于在查询结果中插入结束标记行 */
+export const TOKEN_COLUMN: "__sqlite_executor_token__";
+
+/**
+ * 构造发送给子进程的 payload 字符串。
+ * 将 SQL 语句和 token 包装为 sqlite3 能够执行的格式，
+ * 使结果末尾包含一个标记行用于判断查询是否结束。
+ *
+ * @param sql   - 原始 SQL 语句
+ * @param token - 唯一标记值
+ * @returns 组装后的 payload 字符串
+ */
+export function buildPayload(sql: string, token: string): string;
+
+/**
+ * 判断一个值是否为结束标记行。
+ * 用于在解析查询结果时识别语句执行完毕的信号。
+ *
+ * @param value - 待判断的值（通常为对象行）
+ * @param token - 期望的标记值
+ * @returns 如果是标记行则返回 true
+ */
+export function isSentinelRow(value: unknown, token: string): boolean;

package/dist/esm/core/queue.d.mts

@@ -0,0 +1,40 @@
+/**
+ * 双端队列，基于双向链表实现。
+ * 支持 O(1) 的首尾入队/出队操作，以及查找、删除、迭代等功能。
+ */
+export declare class Queue<T = any> {
+	/** 将值加入队尾 */
+	enqueue(value: T): void;
+
+	/** 移除并返回队首元素；队列为空时返回 null */
+	dequeue(): T | null;
+
+	/** 返回队首元素但不移除；队列为空时返回 null */
+	peek(): T | null;
+
+	/** 移除队列中第一个匹配的值，返回是否成功移除 */
+	remove(value: T): boolean;
+
+	/** 查找第一个满足条件的元素，未找到时返回 null */
+	find(predicate: (value: T) => boolean): T | null;
+
+	/** 清空队列 */
+	clear(): void;
+
+	/** 将队列转为数组（从队首到队尾） */
+	toArray(): T[];
+
+	/** 遍历队列元素 */
+	values(): Generator<T, void, unknown>;
+
+	/** 将另一个队列的所有元素追加到当前队尾 */
+	prependAll(other: Queue<T>): void;
+
+	/** 队列是否为空 */
+	isEmpty(): boolean;
+
+	/** 队列中的元素数量 */
+	get size(): number;
+
+	[Symbol.iterator](): Generator<T, void, unknown>;
+}

package/dist/esm/core/readerPool.d.mts

@@ -0,0 +1,40 @@
+/**
+ * 只读 Worker 连接池。
+ *
+ * 管理多个 TaskWorker 实例，所有 worker 共享同一数据库文件。
+ * 通过轮询（round-robin）分配读任务，实现读操作的水平扩展。
+ *
+ * 注意：ReaderPool 中的 worker 不初始化 WAL 模式（`initMode: "none"`），
+ * 直接继承数据库文件头中的 journal 模式，避免与 writer 竞争 WAL 初始化锁。
+ */
+export class ReaderPool {
+	/**
+	 * @param options.binary            sqlite3 可执行文件路径
+	 * @param options.database          数据库文件路径
+	 * @param options.poolSize          Worker 数量
+	 * @param options.statementTimeout  单条语句超时（毫秒）
+	 * @param options.logger            日志记录器
+	 */
+	constructor(options: {
+		binary: string;
+		database: string;
+		poolSize: number;
+		statementTimeout: number;
+		logger?: import("./executor.js").Logger;
+	});
+
+	/** 池中 Worker 数量 */
+	get size(): number;
+
+	/** 所有 Worker 排队中的语句总数 */
+	get pendingStatements(): number;
+
+	/**
+	 * 分发一个读任务到下一个空闲 Worker（轮询）。
+	 * @param task - 任务配置对象
+	 */
+	enqueue(task: object): void;
+
+	/** 终止所有 Worker */
+	kill(): void;
+}

package/dist/esm/core/settleUtils.d.mts

@@ -0,0 +1,36 @@
+/**
+ * 将解析结果收集到任务的 rows 数组中。
+ * 用于非流式查询，将子进程返回的 JSON 行追加到 task.rows。
+ *
+ * @param task   - 任务对象，需包含 rows 数组
+ * @param parsed - 解析出的单行数据
+ */
+export function collectQueryRows(task: { rows: any[] }, parsed: any): void;
+
+/**
+ * 将解析结果通过任务的 onRow 回调逐行推送给消费者。
+ * 用于流式查询，不缓存全部结果。
+ * 如果 task.consumerError 已设置，则跳过后续推送。
+ *
+ * @param task   - 任务对象，需包含 onRow 回调和可选的 consumerError
+ * @param parsed - 解析出的单行数据
+ */
+export function processStreamRows(task: { onRow: Function; consumerError?: Error | null }, parsed: any): void;
+
+/**
+ * 完成一个任务：调用 resolve 或 reject，并更新指标。
+ * 任务可以是 query、execute 或 stream 类型。
+ *
+ * @param task    - 待完成的任务对象
+ * @param error   - 错误对象（为 null 表示成功）
+ * @param value   - 成功时的结果值
+ * @param metrics - 可选的指标收集器，用于统计任务耗时和结果
+ * @param options - 可选的附加选项，如 resetRowParser 是否重置行解析器
+ */
+export function settleTask(
+	task: any,
+	error: Error | null,
+	value: any,
+	metrics?: import("./metrics.js").Metrics | null,
+	options?: { resetRowParser?: boolean },
+): void;

package/dist/esm/core/taskWorker.d.mts

@@ -0,0 +1,50 @@
+/**
+ * 单个 sqlite3 进程 Worker，支持管线化（pipelining）。
+ *
+ * 内部维护 pending 和 inflight 两个队列：
+ * - pending：等待写入 stdin 的任务
+ * - inflight：已写入 stdin、等待 stdout 返回的任务
+ *
+ * 当 pending 中有任务且 inflight 未满时，自动将多个任务的 SQL payload
+ * 合并为一次 stdin.write() 发送（管线化），由 sqlite3 顺序执行后，
+ * 在 stdout 解析时按 FIFO 顺序匹配 sentinel token 逐一完成。
+ */
+export class TaskWorker {
+	/**
+	 * @param options.binary            sqlite3 可执行文件路径
+	 * @param options.database          数据库文件路径
+	 * @param options.statementTimeout  单条语句超时（毫秒）
+	 * @param options.logger            日志记录器
+	 * @param options.name              Worker 名称，用于日志和调试
+	 * @param options.initMode          子进程初始化模式（参考 ProcessManager）
+	 * @param options.batchSize         管线化批量大小，默认 10
+	 */
+	constructor(options: {
+		binary: string;
+		database: string;
+		statementTimeout: number;
+		logger?: import("./executor.js").Logger;
+		name?: string;
+		initMode?: "wal" | "none";
+		batchSize?: number;
+	});
+
+	/** Worker 名称 */
+	get name(): string;
+
+	/** 当前是否空闲（无 pending 也无 inflight 任务） */
+	get idle(): boolean;
+
+	/** 当前排队（pending + inflight）的语句数量 */
+	get pendingStatements(): number;
+
+	/**
+	 * 加入一个任务到待发送队列。
+	 * 内部会触发泵送逻辑，可能立即与队列中其他任务合批发送。
+	 * @param config - 任务配置对象，包含 kind、sql、timeout、token、resolve、reject、onRow 等
+	 */
+	enqueue(config: object): void;
+
+	/** 立即终止子进程，丢弃所有待处理和已发送的任务 */
+	kill(): void;
+}

package/dist/esm/core/transactionScope.d.mts

@@ -0,0 +1,83 @@
+import { Queue } from "./queue.mts";
+
+/**
+ * 事务作用域的进入结果。
+ * - scopeId：唯一作用域标识符
+ * - release：释放作用域锁定的回调
+ */
+export interface TransactionScopeResult {
+	/** 事务作用域的唯一标识符号 */
+	scopeId: symbol;
+	/** 释放事务作用域锁，允许后续任务继续执行 */
+	release: () => void;
+}
+
+/**
+ * 事务作用域管理器。
+ *
+ * 确保事务内的所有 SQL 操作绑定到同一个子进程（通过 scopeId），
+ * 避免在读写分离模式下事务内的读操作被分发到其他进程。
+ *
+ * 实现原理：
+ * - 事务开始前调用 `enter()` 获取 scopeId，后续所有语句携带该 scopeId
+ * - 事务外的语句不携带 scopeId（scopeId 为 null），可由任务调度器自由分发
+ * - 事务内的语句暂存（defer）到独立的队列，事务结束后恢复（restoreDeferred）
+ */
+export class TransactionScope {
+	/** 当前作用域标识，无活跃事务时为 null */
+	get scopeId(): symbol | null;
+
+	/** 是否有活跃的事务正在执行 */
+	get active(): boolean;
+
+	/** 事务队列中等待执行的语句数量 */
+	get pendingStatements(): number;
+
+	/**
+	 * 判断给定的 scopeId 是否与当前事务作用域匹配。
+	 * scopeId 为 null 表示不在事务中，返回 true。
+	 *
+	 * @param scopeId - 待判断的作用域标识
+	 * @returns 如果匹配或传入 null 则返回 true
+	 */
+	isDeferred(scopeId: symbol | null): boolean;
+
+	/**
+	 * 将任务暂存到事务延迟队列。
+	 * 事务提交前不会实际执行这些任务。
+	 *
+	 * @param task - 待暂存的任务对象
+	 */
+	defer(task: any): void;
+
+	/**
+	 * 进入事务作用域。
+	 * 锁定一个 scopeId，后续所有语句将被关联到该作用域。
+	 * 同时暂停主队列的正常分发，将新语句转入 defer 队列。
+	 *
+	 * @returns 包含 scopeId 和 release 回调的结果对象
+	 */
+	enter(): Promise<TransactionScopeResult>;
+
+	/**
+	 * 退出事务作用域。
+	 * 将 defer 队列中的任务恢复到目标队列，然后清空作用域。
+	 */
+	exit(): void;
+
+	/**
+	 * 恢复之前暂存（defer）的所有任务到目标队列。
+	 * 通常在事务提交后调用。
+	 *
+	 * @param targetQueue - 接收暂存任务的目标队列
+	 */
+	restoreDeferred(targetQueue: Queue): void;
+
+	/**
+	 * 拒绝事务作用域内所有暂存的任务。
+	 * 通常在事务回滚或发生错误时调用。
+	 *
+	 * @param error - 拒绝原因
+	 */
+	rejectAll(error: Error): void;
+}

package/dist/esm/index.d.mts

@@ -0,0 +1,28 @@
+/// <reference lib="esnext" />
+
+/**
+ * 主控制器，管理 sqlite3 子进程，提供 execute/query/stream/transaction 等 API。
+ * 当 `database` 为文件路径且 `poolSize > 0` 时，自动启用读写分离：
+ * - 读操作（SELECT/WITH/VALUES/EXPLAIN）路由到 ReaderPool 中的空闲 worker
+ * - 写操作（其余语句）始终由主 writer 进程执行
+ */
+export { SQLiteExecutor } from "./core/executor.mts";
+export type { Logger, SQLiteExecutorOptions, StatementOptions, TransactionOptions, TransactionHandle } from "./core/executor.mts";
+
+/**
+ * 运行时指标收集器。
+ * 追踪 SQL 执行任务的吞吐、耗时、错误、超时和进程重启。
+ */
+export { Metrics } from "./core/metrics.mts";
+export type { MetricsSnapshot } from "./core/metrics.mts";
+
+/**
+ * 有效的事务隔离级别列表。
+ */
+export { VALID_TRANSACTION_MODES } from "./transaction/transaction.mts";
+
+/**
+ * 默认语句超时时间（30 秒）。
+ * `createTimeoutError` 用于构造带 SQL 上下文的超时错误。
+ */
+export { DEFAULT_STATEMENT_TIMEOUT, createTimeoutError } from "./utils/timeout.mts";