sqlite-executor 4.0.5 → 4.0.7

package/dist/cjs/utils/interpolate.d.cts

@@ -1,3 +1,14 @@
+import type { SQLTemplate } from "./normalize";
+
+/**
+ * 使用预解析的模板替换参数，避免重新扫描 SQL。
+ *
+ * @param template - 由 `normalizeSQLTemplate` 返回的预解析模板
+ * @param params   - 要插值的参数数组
+ * @returns 插值后的完整 SQL 字符串
+ */
+export function interpolateFromTemplate(template: SQLTemplate, params: any[]): string;
+
 /**
  * 替换 SQL 语句中的 `?` 占位符为转义后的参数值。
  *

package/dist/cjs/utils/normalize.d.cts

@@ -5,3 +5,27 @@
  * @returns 规范化后的 SQL 语句
  */
 export function normalizeSQL(sql: string): string;
+
+export interface SQLTemplate {
+	/** 规范化后的完整 SQL 字符串 */
+	normalized: string;
+	/**
+	 * 以 `?` 为分隔符的片段数组。
+	 * - segments[0] 为第一个 `?` 之前的部分
+	 * - segments[n] 为第 n 个 `?` 之后、第 n+1 个 `?` 之前的部分
+	 * - 最后一个元素为最后一个 `?` 之后的部分
+	 * - 无 `?` 时 segments 为 [normalized]
+	 */
+	segments: string[];
+	/** `?` 占位符的数量 */
+	paramCount: number;
+}
+
+/**
+ * 单次扫描同时完成 SQL 规范化和 `?` 占位符追踪。
+ * 避免 `normalizeSQL` + `_parseTemplate` 两次扫描的重复开销。
+ *
+ * @param sql - 原始 SQL 语句
+ * @returns 包含规范化结果和占位符信息的模板对象
+ */
+export function normalizeSQLTemplate(sql: string): SQLTemplate;

package/dist/cjs/utils/timeout.d.cts

@@ -3,9 +3,10 @@ export const DEFAULT_STATEMENT_TIMEOUT: 30000;
 
 /**
  * 创建包含 SQL 上下文的超时错误。
+ * 注意：sql 应已由调用方完成规范化，本函数不再内部调用 normalizeSQL。
  *
  * @param timeout - 超时时间（毫秒）
- * @param sql     - 超时发生时正在执行的 SQL 语句
+ * @param sql     - 超时发生时正在执行的 SQL 语句（已规范化）
  * @returns 包含超时时间和 SQL 信息的 Error 实例
  */
 export function createTimeoutError(timeout: number, sql: string): Error;

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

@@ -0,0 +1,33 @@
+/**
+ * Inflight 任务数组管理器。
+ *
+ * 封装了变长数组 + 头指针的 push/shift 操作和自动压缩逻辑，
+ * PipelineEngine 和 TaskWorker 共享此类，避免重复实现 inflight 管理。
+ *
+ * 设计：
+ * - shift() 出队时将对应槽位置为 null，仅移动头指针
+ * - 头指针超过阈值时通过 slice() 物理回收已消费的前部空间
+ * - 不需使用者关心 #tasks / #head 的内部细节
+ */
+export declare class InflightTracker {
+	/** 当前 inflight 任务数。 */
+	get count(): number;
+
+	/** 第一个（最旧的）inflight 任务，无任务时返回 null。 */
+	get first(): object | null;
+
+	/** 将一个或多个任务追加到队尾。 */
+	push(...items: object[]): void;
+
+	/** 移除并返回第一个 inflight 任务。空时返回 null。 */
+	shift(): object | null;
+
+	/** 清空所有 inflight 任务。 */
+	clear(): void;
+
+	/** 对每个 inflight 任务调用 fn(task)。 */
+	forEach(fn: (task: object) => void): void;
+
+	/** 返回所有 inflight 任务的浅拷贝数组（不含 null 槽位）。 */
+	toArray(): object[];
+}

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

@@ -1,6 +1,13 @@
 /** 基于 Map 插入顺序的 LRU 缓存。 */
 export declare class LRUCache<T> {
-	constructor(options?: { maxSize?: number; maxKeyLength?: number });
+	/**
+	 * 创建 LRUCache 实例。
+	 * @param options 可选项。
+	 * @param options.maxSize 最大缓存条目数，默认为 100。
+	 * @param options.maxKeyLength 超长 key 的最大长度，默认为 100。超过该长度的 key 不会被缓存。
+	 * @param options.maxValueLength 超长 value 的最大长度，默认为 Infinity。超过该长度的 value 不会被缓存。
+	 */
+	constructor(options?: { maxSize?: number; maxKeyLength?: number, maxValueLength?: number });
 
 	/** 获取缓存值，命中时提升到末尾。未命中或 key 不合法时返回 undefined。 */
 	get(key: string): T | undefined;

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

@@ -16,10 +16,10 @@ export interface MetricsSnapshot {
 	queryCount: number;
 	/** stream 操作执行次数 */
 	streamCount: number;
-	/** 平均查询耗时（毫秒） */
-	avgQueryTime: number;
-	/** 每秒查询数 */
-	qps: number;
+	/** 所有成功任务的平均耗时（毫秒） */
+	avgTaskDuration: number;
+	/** 每秒处理任务数（含 execute/query/stream） */
+	throughput: number;
 	/** 运行时长（秒） */
 	uptime: number;
 }

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

@@ -0,0 +1,196 @@
+import { InflightTracker } from "./inflightTracker.mts";
+import { Metrics } from "./metrics.mts";
+
+// ─── finalizePendingTasks ───
+
+/**
+ * 批量结算 pendingFinalize 集合中的所有任务。
+ * 由 scheduleFinalizeCheck 的 setImmediate 回调调用。
+ *
+ * @param tasks     - pendingFinalizeTasks 集合
+ * @param settle    - 结算回调，形式为 (task, error, value) => void
+ * @param pumpQueue - 泵送回调，结算后触发队列发送
+ */
+export function finalizePendingTasks(
+	tasks: Set<object>,
+	settle: (task: object, error: Error | null, value: any) => void,
+	pumpQueue: () => void,
+): void;
+
+// ─── prepareTaskTimeout ───
+
+/**
+ * 处理单任务超时：防重复结算、清除定时器、更新指标、创建超时错误。
+ *
+ * @param task    - 任务对象
+ * @param metrics - 可选的指标收集器
+ * @returns 已创建的 TimeoutError；若任务已结算则返回 null
+ */
+export function prepareTaskTimeout(
+	task: object,
+	metrics: Metrics | null | undefined,
+): Error | null;
+
+// ─── createSweeper ───
+
+export interface Sweeper {
+	/** 启动 sweep 定时器（如果尚未启动）。 */
+	schedule: () => void;
+	/** 停止 sweep 定时器。 */
+	clear: () => void;
+	/** 获取当前 sweep 定时器引用（测试用）。 */
+	getSweepTimer: () => number | null;
+}
+
+export interface SweeperOptions {
+	/** inflight 任务跟踪器 */
+	inflight: InflightTracker;
+	/** 超时扫描间隔（毫秒） */
+	sweepIntervalMs: number;
+	/** 超时任务处理回调 */
+	handleTaskTimeout: (task: object) => void;
+}
+
+/**
+ * 创建 sweep 定时器管理器。
+ * schedule() 启动定期扫描，检查 inflight 任务是否超时；
+ * clear() 停止定时器。
+ */
+export function createSweeper(options: SweeperOptions): Sweeper;
+
+// ─── createFinalizeScheduler ───
+
+export interface FinalizeSchedulerOptions {
+	/** pendingFinalize 任务集合 */
+	pendingFinalizeTasks: Set<object>;
+	/** 结算回调，形式为 (task, error, value) => void */
+	settleTask: (task: object, error: Error | null, value: any) => void;
+	/** 泵送回调，结算后触发队列发送 */
+	pumpQueue: () => void;
+}
+
+/**
+ * 创建 pendingFinalize 结算调度器。
+ * 通过 setImmediate 延迟一帧执行 finalizePendingTasks，给 stderr chunk 到达的时间窗口。
+ *
+ * @returns 调度函数，调用后将在下一帧执行 finalizePendingTasks
+ */
+export function createFinalizeScheduler(options: FinalizeSchedulerOptions): () => void;
+
+// ─── handleParsedValue ───
+
+export interface ParsedValueCallbacks {
+	/**
+	 * sentinel token 命中后的回调。
+	 * inflight.shift() 已在调用前执行，此处负责后续处理（pendingFinalize 等）。
+	 */
+	afterSentinel: (task: object) => void;
+	/**
+	 * JSON 解析失败时的回调，用于拒绝所有 inflight 任务。
+	 */
+	rejectAll: (error: Error) => void;
+}
+
+/**
+ * 处理一个完整的 JSON 值（来自 sharedValueParser）。
+ * 匹配 sentinel token、收集 query 行数据、触发 stream 回调。
+ * PipelineEngine 和 TaskWorker 共享此逻辑。
+ *
+ * @param raw      - 原始 JSON 文本
+ * @param inflight - inflight 任务跟踪器
+ * @param callbacks - afterSentinel 和 rejectAll 回调
+ */
+export function handleParsedValue(
+	raw: string,
+	inflight: InflightTracker,
+	callbacks: ParsedValueCallbacks,
+): void;
+
+// ─── handleSentinelTask ───
+
+export interface SentinelTaskOptions {
+	/** 结算回调，形式为 (task, error, value) => void */
+	settleTask: (task: object, error: Error | null, value: any) => void;
+	/** pendingFinalize 任务集合 */
+	pendingFinalizeTasks: Set<object>;
+	/** 触发延迟结算的回调 */
+	scheduleFinalizeCheck: () => void;
+	/** 泵送回调 */
+	pumpQueue: () => void;
+}
+
+/**
+ * 处理 sentinel token 命中后的任务结算。
+ * PipelineEngine 和 TaskWorker 共享此逻辑，统一延迟结算策略。
+ *
+ * @param task - 已从 inflight shift 的任务
+ * @param options - 回调集合
+ */
+export function handleSentinelTask(task: object, options: SentinelTaskOptions): void;
+
+// ─── handleStderrChunk ───
+
+export interface StderrChunkOptions {
+	/** inflight 任务跟踪器 */
+	inflight: InflightTracker;
+	/** pendingFinalize 任务集合 */
+	pendingFinalizeTasks: Set<object>;
+	/** 可选的日志记录器 */
+	logger?: { error?: (msg: string) => void };
+}
+
+/**
+ * 处理 sqlite3 的 stderr 输出，将其归因到合适的任务。
+ * PipelineEngine 和 TaskWorker 共享此逻辑。
+ *
+ * @param chunk - stderr 文本块
+ * @param options - 上下文依赖
+ */
+export function handleStderrChunk(chunk: string, options: StderrChunkOptions): void;
+
+// ─── createPumpQueue ───
+
+export interface PumpQueueOptions {
+	/** 待发送的任务队列 */
+	queue: import("./queue.js").Queue;
+	/** inflight 任务跟踪器 */
+	inflight: InflightTracker;
+	/** 子进程管理器（提供 draining 判断、write 写入、onDrained 注册） */
+	processManager: { draining: boolean; write: (data: string) => void; onDrained: (cb: () => void) => void };
+	/** sweep 定时器管理器 */
+	sweeper: Sweeper;
+	/** 批量发送大小 */
+	batchSize: number;
+	/** inflight 上限 */
+	maxInflight: number;
+}
+
+/**
+ * 创建泵送函数，将队列中的任务批量发送给 sqlite3 进程。
+ * PipelineEngine 和 TaskWorker 共享此工厂，消除 #pumpQueue 方法的重复。
+ *
+ * @returns 泵送函数，调用后尝试从队列取出 batch 发送
+ */
+export function createPumpQueue(options: PumpQueueOptions): () => void;
+
+// ─── rejectAllTasks ───
+
+export interface RejectAllOptions {
+	/** inflight 任务跟踪器 */
+	inflight: InflightTracker;
+	/** 待发送的任务队列 */
+	queue: import("./queue.js").Queue;
+	/** pendingFinalize 任务集合 */
+	pendingFinalizeTasks: Set<object>;
+	/** 结算回调，形式为 (task, error, value) => void */
+	settleTask: (task: object, error: Error | null, value: any) => void;
+	/** 拒绝原因 */
+	error: Error;
+}
+
+/**
+ * 拒绝所有待处理任务（inflight、队列、pendingFinalize）。
+ * 提取自 PipelineEngine.rejectAll 和 TaskWorker.#rejectAll，
+ * 消除二者间的逻辑重复。
+ */
+export function rejectAllTasks(options: RejectAllOptions): void;

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

@@ -2,7 +2,7 @@
  * 只读 Worker 连接池。
  *
  * 管理多个 TaskWorker 实例，所有 worker 共享同一数据库文件。
- * 通过轮询（round-robin）分配读任务，实现读操作的水平扩展。
+ * 通过 Least Busy（最小负载）分配读任务，实现读操作的水平扩展。
  *
  * 注意：ReaderPool 中的 worker 不初始化 WAL 模式（`initMode: "none"`），
  * 直接继承数据库文件头中的 journal 模式，避免与 writer 竞争 WAL 初始化锁。
@@ -30,7 +30,7 @@ export class ReaderPool {
 	get pendingStatements(): number;
 
 	/**
-	 * 分发一个读任务到下一个空闲 Worker（轮询）。
+	 * 分发一个读任务到负载最小的 Worker（Least Busy）。
 	 * @param task - 任务配置对象
 	 */
 	enqueue(task: object): void;