sqlite-executor 4.0.4 → 4.0.6

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/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/pipelineEngine.d.mts

@@ -16,6 +16,8 @@ export interface PipelineEngineOptions {
 	maxInflight?: number;
 	/** 任务超时时的回调 */
 	onTaskTimeout?: (task: any) => void;
+	/** 任务超时检查的时间间隔，默认 100ms */
+	sweepInterval?: number;
 }
 
 /**

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;