@deebeetech/sqleasy-engine 0.0.0

package/dist/postgres/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/postgres/index.ts"],"sourcesContent":["import { Pool, type PoolConfig } from 'pg';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\n/** Connection settings — any `pg` `PoolConfig`. Set `statement_timeout` here if you want a\n * per-connection ceiling; the engine imposes none of its own. */\nexport type PostgresConfig = PoolConfig;\n\n/** The root of `EXPLAIN (FORMAT JSON)`: cost/rows sit on the top plan; a `Seq Scan` anywhere in the\n * tree is the full-scan signal. */\ntype PgPlanNode = {\n  'Node Type'?: string;\n  'Total Cost'?: number;\n  'Plan Rows'?: number;\n  Plans?: PgPlanNode[];\n};\n\n/** Parse `EXPLAIN (FORMAT JSON)` result rows into the normalized estimate. Exported for unit tests. */\nexport function parsePgPlan(rows: readonly unknown[]): ExplainEstimate {\n  const root = (rows[0] as { 'QUERY PLAN'?: { Plan?: PgPlanNode }[] } | undefined)?.[\n    'QUERY PLAN'\n  ]?.[0]?.Plan;\n  const seqScan = (n: PgPlanNode | undefined): boolean =>\n    !!n && (n['Node Type'] === 'Seq Scan' || (n.Plans ?? []).some(seqScan));\n  return {\n    cost: root?.['Total Cost'],\n    rows: root?.['Plan Rows'],\n    fullScan: seqScan(root),\n    plan: JSON.stringify(root ?? {}).slice(0, 500),\n  };\n}\n\n// The slice of `pg`'s result the executor reads. `pg`'s QueryResult is structurally assignable.\ntype PgResultLike = { rows: unknown[]; rowCount: number | null };\n\nconst argsOf = (prepared: PreparedSql): unknown[] => (prepared.params ?? []) as unknown[];\n\nconst toResult = <T>(res: PgResultLike): QueryResult<T> => ({\n  rows: res.rows as T[],\n  rowCount: res.rowCount ?? res.rows.length,\n});\n\n/**\n * Build a Postgres executor over an EXISTING pool — bring your own `pg` Pool to share one pool\n * across your app (or hand in a test double). {@link createPostgresExecutor} is the usual entry.\n */\nexport function createPostgresExecutorFromPool(pool: Pool): DbExecutor {\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      return toResult<T>(await pool.query(prepared.sql, argsOf(prepared)));\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      // Postgres's extended protocol runs exactly ONE statement per parameterized query() — so a\n      // batch is NEVER concatenated into one string (its placeholders restart per statement and\n      // would misbind). Each statement runs on its own, inside a single checked-out connection so\n      // BEGIN/COMMIT actually wrap them. ROLLBACK on any error; release the client no matter what.\n      const client = await pool.connect();\n      try {\n        await client.query('BEGIN');\n        const results: QueryResult[] = [];\n        for (const s of statements) {\n          results.push(toResult(await client.query(s.sql, argsOf(s))));\n        }\n        await client.query('COMMIT');\n        return results;\n      } catch (err) {\n        await client.query('ROLLBACK').catch(() => {});\n        throw err;\n      } finally {\n        client.release();\n      }\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      // Plain EXPLAIN never executes the statement (only EXPLAIN ANALYZE does).\n      const res = await pool.query(`EXPLAIN (FORMAT JSON) ${prepared.sql}`, argsOf(prepared));\n      return parsePgPlan(res.rows);\n    },\n\n    async close(): Promise<void> {\n      await pool.end();\n    },\n  };\n}\n\n/**\n * A Postgres executor backed by a `pg` connection pool (placeholders: `$1`, `$2`, …). Feed it the\n * `{ sql, params }` a `PostgresQuery` builder emits.\n */\nexport function createPostgresExecutor(config: PostgresConfig): DbExecutor {\n  return createPostgresExecutorFromPool(new Pool(config));\n}\n"],"mappings":";;;AAiBA,SAAgB,YAAY,MAA2C;CACrE,MAAM,OAAQ,KAAK,EAAE,GACnB,aACD,GAAG,EAAE,EAAE;CACR,MAAM,WAAW,MACf,CAAC,CAAC,MAAM,EAAE,iBAAiB,eAAe,EAAE,SAAS,CAAC,EAAA,CAAG,KAAK,OAAO;CACvE,OAAO;EACL,MAAM,OAAO;EACb,MAAM,OAAO;EACb,UAAU,QAAQ,IAAI;EACtB,MAAM,KAAK,UAAU,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG;CAC/C;AACF;AAKA,MAAM,UAAU,aAAsC,SAAS,UAAU,CAAC;AAE1E,MAAM,YAAe,SAAuC;CAC1D,MAAM,IAAI;CACV,UAAU,IAAI,YAAY,IAAI,KAAK;AACrC;;;;;AAMA,SAAgB,+BAA+B,MAAwB;CACrE,OAAO;EACL,MAAM,IAAa,UAAgD;GACjE,OAAO,SAAY,MAAM,KAAK,MAAM,SAAS,KAAK,OAAO,QAAQ,CAAC,CAAC;EACrE;EAEA,MAAM,YAAY,YAA4D;GAK5E,MAAM,SAAS,MAAM,KAAK,QAAQ;GAClC,IAAI;IACF,MAAM,OAAO,MAAM,OAAO;IAC1B,MAAM,UAAyB,CAAC;IAChC,KAAK,MAAM,KAAK,YACd,QAAQ,KAAK,SAAS,MAAM,OAAO,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7D,MAAM,OAAO,MAAM,QAAQ;IAC3B,OAAO;GACT,SAAS,KAAK;IACZ,MAAM,OAAO,MAAM,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM;GACR,UAAU;IACR,OAAO,QAAQ;GACjB;EACF;EAEA,MAAM,QAAQ,UAAiD;GAG7D,OAAO,aAAY,MADD,KAAK,MAAM,yBAAyB,SAAS,OAAO,OAAO,QAAQ,CAAC,EAAA,CAC/D,IAAI;EAC7B;EAEA,MAAM,QAAuB;GAC3B,MAAM,KAAK,IAAI;EACjB;CACF;AACF;;;;;AAMA,SAAgB,uBAAuB,QAAoC;CACzE,OAAO,+BAA+B,IAAI,KAAK,MAAM,CAAC;AACxD"}

package/dist/sqlite/index.cjs

@@ -0,0 +1,81 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _libsql_client = require("@libsql/client");
+//#region src/sqlite/index.ts
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** SQLite's "another connection holds the lock" signal — a statement that never ran, safe to retry. */
+const isBusy = (err) => {
+	const msg = err instanceof Error ? err.message : String(err);
+	return msg.includes("SQLITE_BUSY") || msg.includes("database is locked");
+};
+const BUSY_RETRY_DELAYS_MS = [
+	100,
+	200,
+	400,
+	800,
+	1600,
+	3200
+];
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (rs) => {
+	const rows = rs.rows;
+	return {
+		rows,
+		rowCount: rows.length > 0 ? rows.length : rs.rowsAffected
+	};
+};
+/**
+* A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the
+* `{ sql, params }` a `SqliteQuery` builder emits.
+*/
+function createSqliteExecutor(config) {
+	const clientConfig = "file" in config ? { url: `file:${config.file}` } : config;
+	const client = (0, _libsql_client.createClient)(clientConfig);
+	const isLocalFile = typeof clientConfig.url === "string" && clientConfig.url.startsWith("file:");
+	let busyTimeout;
+	const ensureBusyTimeout = () => {
+		if (!isLocalFile) return Promise.resolve();
+		busyTimeout ??= client.execute("PRAGMA busy_timeout = 5000").then(() => {}, () => {});
+		return busyTimeout;
+	};
+	const withBusyRetry = async (op) => {
+		await ensureBusyTimeout();
+		for (let attempt = 0;; attempt++) try {
+			return await op();
+		} catch (err) {
+			if (!isLocalFile || !isBusy(err) || attempt >= BUSY_RETRY_DELAYS_MS.length) throw err;
+			await sleep(BUSY_RETRY_DELAYS_MS[attempt]);
+		}
+	};
+	return {
+		async run(prepared) {
+			const rs = await withBusyRetry(() => client.execute({
+				sql: prepared.sql,
+				args: argsOf(prepared)
+			}));
+			return toResult(rs);
+		},
+		async transaction(statements) {
+			return (await withBusyRetry(() => client.batch(statements.map((s) => ({
+				sql: s.sql,
+				args: argsOf(s)
+			})), "write"))).map((rs) => toResult(rs));
+		},
+		async explain(prepared) {
+			const details = (await withBusyRetry(() => client.execute({
+				sql: `EXPLAIN QUERY PLAN ${prepared.sql}`,
+				args: argsOf(prepared)
+			}))).rows.map((r) => String(r.detail ?? ""));
+			return {
+				fullScan: details.some((d) => d.startsWith("SCAN")),
+				plan: details.join("; ").slice(0, 500)
+			};
+		},
+		async close() {
+			client.close();
+		}
+	};
+}
+//#endregion
+exports.createSqliteExecutor = createSqliteExecutor;
+
+//# sourceMappingURL=index.cjs.map

package/dist/sqlite/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/sqlite/index.ts"],"sourcesContent":["import { createClient, type Config, type InArgs, type ResultSet } from '@libsql/client';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\n/**\n * How to reach the database. Either a full `@libsql/client` {@link Config} (a Turso/libSQL `url` +\n * `authToken`, an in-memory `':memory:'`, …) or the shorthand `{ file }` for a local SQLite file.\n */\nexport type SqliteConfig = Config | { file: string };\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/** SQLite's \"another connection holds the lock\" signal — a statement that never ran, safe to retry. */\nconst isBusy = (err: unknown): boolean => {\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('SQLITE_BUSY') || msg.includes('database is locked');\n};\n\n// Up to ~6.3s of extra waiting beyond the busy timeout, then give up and surface the error.\nconst BUSY_RETRY_DELAYS_MS = [100, 200, 400, 800, 1600, 3200];\n\nconst argsOf = (prepared: PreparedSql): InArgs => (prepared.params ?? []) as InArgs;\n\nconst toResult = <T>(rs: ResultSet): QueryResult<T> => {\n  const rows = rs.rows as unknown as T[];\n  // SELECT → row count; write → affected count (rows is empty).\n  return { rows, rowCount: rows.length > 0 ? rows.length : rs.rowsAffected };\n};\n\n/**\n * A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the\n * `{ sql, params }` a `SqliteQuery` builder emits.\n */\nexport function createSqliteExecutor(config: SqliteConfig): DbExecutor {\n  const clientConfig: Config = 'file' in config ? { url: `file:${config.file}` } : config;\n  const client = createClient(clientConfig);\n\n  // A local SQLite FILE can be open in more than one connection at once (SQLite allows one writer),\n  // so two defenses, only for file URLs — remote libSQL/Turso has no such lock:\n  //   1. a busy timeout, so a briefly-held lock is waited out instead of throwing on the spot;\n  //   2. a bounded retry, because under sustained reader pressure the timeout can still lapse. A\n  //      SQLITE_BUSY means the statement did not run, so retrying — read OR write — repeats nothing;\n  //      a transaction batch rolls back fully before it surfaces, so retrying it is equally safe.\n  const isLocalFile = typeof clientConfig.url === 'string' && clientConfig.url.startsWith('file:');\n\n  let busyTimeout: Promise<void> | undefined;\n  const ensureBusyTimeout = (): Promise<void> => {\n    if (!isLocalFile) return Promise.resolve();\n    // Cached and best-effort: a driver that rejects the pragma must not break the executor.\n    busyTimeout ??= client.execute('PRAGMA busy_timeout = 5000').then(\n      () => {},\n      () => {},\n    );\n    return busyTimeout;\n  };\n\n  const withBusyRetry = async <R>(op: () => Promise<R>): Promise<R> => {\n    await ensureBusyTimeout();\n    for (let attempt = 0; ; attempt++) {\n      try {\n        return await op();\n      } catch (err) {\n        if (!isLocalFile || !isBusy(err) || attempt >= BUSY_RETRY_DELAYS_MS.length) throw err;\n        await sleep(BUSY_RETRY_DELAYS_MS[attempt]!);\n      }\n    }\n  };\n\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      const rs = await withBusyRetry(() =>\n        client.execute({ sql: prepared.sql, args: argsOf(prepared) }),\n      );\n      return toResult<T>(rs);\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      // `batch` runs every statement in ONE transaction and rolls back on any error — exactly the\n      // multi-builder contract, and each statement stays its own prepared statement.\n      const results = await withBusyRetry(() =>\n        client.batch(\n          statements.map((s) => ({ sql: s.sql, args: argsOf(s) })),\n          'write',\n        ),\n      );\n      return results.map((rs) => toResult(rs));\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      // SQLite's planner exposes no cost or row estimate — only the plan SHAPE. `SCAN` means a full\n      // table scan, `SEARCH` an index seek, so `fullScan` is the only signal this dialect gives.\n      const rs = await withBusyRetry(() =>\n        client.execute({ sql: `EXPLAIN QUERY PLAN ${prepared.sql}`, args: argsOf(prepared) }),\n      );\n      const details = rs.rows.map((r) =>\n        String((r as unknown as { detail?: string }).detail ?? ''),\n      );\n      return {\n        fullScan: details.some((d) => d.startsWith('SCAN')),\n        plan: details.join('; ').slice(0, 500),\n      };\n    },\n\n    async close(): Promise<void> {\n      client.close();\n    },\n  };\n}\n"],"mappings":";;;AASA,MAAM,SAAS,OAA8B,IAAI,SAAS,MAAM,WAAW,GAAG,EAAE,CAAC;;AAGjF,MAAM,UAAU,QAA0B;CACxC,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;CAC3D,OAAO,IAAI,SAAS,aAAa,KAAK,IAAI,SAAS,oBAAoB;AACzE;AAGA,MAAM,uBAAuB;CAAC;CAAK;CAAK;CAAK;CAAK;CAAM;AAAI;AAE5D,MAAM,UAAU,aAAmC,SAAS,UAAU,CAAC;AAEvE,MAAM,YAAe,OAAkC;CACrD,MAAM,OAAO,GAAG;CAEhB,OAAO;EAAE;EAAM,UAAU,KAAK,SAAS,IAAI,KAAK,SAAS,GAAG;CAAa;AAC3E;;;;;AAMA,SAAgB,qBAAqB,QAAkC;CACrE,MAAM,eAAuB,UAAU,SAAS,EAAE,KAAK,QAAQ,OAAO,OAAO,IAAI;CACjF,MAAM,UAAA,GAAA,eAAA,aAAA,CAAsB,YAAY;CAQxC,MAAM,cAAc,OAAO,aAAa,QAAQ,YAAY,aAAa,IAAI,WAAW,OAAO;CAE/F,IAAI;CACJ,MAAM,0BAAyC;EAC7C,IAAI,CAAC,aAAa,OAAO,QAAQ,QAAQ;EAEzC,gBAAgB,OAAO,QAAQ,4BAA4B,CAAC,CAAC,WACrD,CAAC,SACD,CAAC,CACT;EACA,OAAO;CACT;CAEA,MAAM,gBAAgB,OAAU,OAAqC;EACnE,MAAM,kBAAkB;EACxB,KAAK,IAAI,UAAU,IAAK,WACtB,IAAI;GACF,OAAO,MAAM,GAAG;EAClB,SAAS,KAAK;GACZ,IAAI,CAAC,eAAe,CAAC,OAAO,GAAG,KAAK,WAAW,qBAAqB,QAAQ,MAAM;GAClF,MAAM,MAAM,qBAAqB,QAAS;EAC5C;CAEJ;CAEA,OAAO;EACL,MAAM,IAAa,UAAgD;GACjE,MAAM,KAAK,MAAM,oBACf,OAAO,QAAQ;IAAE,KAAK,SAAS;IAAK,MAAM,OAAO,QAAQ;GAAE,CAAC,CAC9D;GACA,OAAO,SAAY,EAAE;EACvB;EAEA,MAAM,YAAY,YAA4D;GAS5E,QAAO,MANe,oBACpB,OAAO,MACL,WAAW,KAAK,OAAO;IAAE,KAAK,EAAE;IAAK,MAAM,OAAO,CAAC;GAAE,EAAE,GACvD,OACF,CACF,EAAA,CACe,KAAK,OAAO,SAAS,EAAE,CAAC;EACzC;EAEA,MAAM,QAAQ,UAAiD;GAM7D,MAAM,WAAU,MAHC,oBACf,OAAO,QAAQ;IAAE,KAAK,sBAAsB,SAAS;IAAO,MAAM,OAAO,QAAQ;GAAE,CAAC,CACtF,EAAA,CACmB,KAAK,KAAK,MAC3B,OAAQ,EAAqC,UAAU,EAAE,CAC3D;GACA,OAAO;IACL,UAAU,QAAQ,MAAM,MAAM,EAAE,WAAW,MAAM,CAAC;IAClD,MAAM,QAAQ,KAAK,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;GACvC;EACF;EAEA,MAAM,QAAuB;GAC3B,OAAO,MAAM;EACf;CACF;AACF"}

package/dist/sqlite/index.d.cts

@@ -0,0 +1,18 @@
+import { DbExecutor } from "../index.cjs";
+import { Config } from "@libsql/client";
+//#region src/sqlite/index.d.ts
+/**
+ * How to reach the database. Either a full `@libsql/client` {@link Config} (a Turso/libSQL `url` +
+ * `authToken`, an in-memory `':memory:'`, …) or the shorthand `{ file }` for a local SQLite file.
+ */
+type SqliteConfig = Config | {
+  file: string;
+};
+/**
+ * A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the
+ * `{ sql, params }` a `SqliteQuery` builder emits.
+ */
+declare function createSqliteExecutor(config: SqliteConfig): DbExecutor;
+//#endregion
+export { SqliteConfig, createSqliteExecutor };
+//# sourceMappingURL=index.d.cts.map

package/dist/sqlite/index.d.mts

@@ -0,0 +1,18 @@
+import { DbExecutor } from "../index.mjs";
+import { Config } from "@libsql/client";
+//#region src/sqlite/index.d.ts
+/**
+ * How to reach the database. Either a full `@libsql/client` {@link Config} (a Turso/libSQL `url` +
+ * `authToken`, an in-memory `':memory:'`, …) or the shorthand `{ file }` for a local SQLite file.
+ */
+type SqliteConfig = Config | {
+  file: string;
+};
+/**
+ * A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the
+ * `{ sql, params }` a `SqliteQuery` builder emits.
+ */
+declare function createSqliteExecutor(config: SqliteConfig): DbExecutor;
+//#endregion
+export { SqliteConfig, createSqliteExecutor };
+//# sourceMappingURL=index.d.mts.map

package/dist/sqlite/index.mjs

@@ -0,0 +1,80 @@
+import { createClient } from "@libsql/client";
+//#region src/sqlite/index.ts
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** SQLite's "another connection holds the lock" signal — a statement that never ran, safe to retry. */
+const isBusy = (err) => {
+	const msg = err instanceof Error ? err.message : String(err);
+	return msg.includes("SQLITE_BUSY") || msg.includes("database is locked");
+};
+const BUSY_RETRY_DELAYS_MS = [
+	100,
+	200,
+	400,
+	800,
+	1600,
+	3200
+];
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (rs) => {
+	const rows = rs.rows;
+	return {
+		rows,
+		rowCount: rows.length > 0 ? rows.length : rs.rowsAffected
+	};
+};
+/**
+* A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the
+* `{ sql, params }` a `SqliteQuery` builder emits.
+*/
+function createSqliteExecutor(config) {
+	const clientConfig = "file" in config ? { url: `file:${config.file}` } : config;
+	const client = createClient(clientConfig);
+	const isLocalFile = typeof clientConfig.url === "string" && clientConfig.url.startsWith("file:");
+	let busyTimeout;
+	const ensureBusyTimeout = () => {
+		if (!isLocalFile) return Promise.resolve();
+		busyTimeout ??= client.execute("PRAGMA busy_timeout = 5000").then(() => {}, () => {});
+		return busyTimeout;
+	};
+	const withBusyRetry = async (op) => {
+		await ensureBusyTimeout();
+		for (let attempt = 0;; attempt++) try {
+			return await op();
+		} catch (err) {
+			if (!isLocalFile || !isBusy(err) || attempt >= BUSY_RETRY_DELAYS_MS.length) throw err;
+			await sleep(BUSY_RETRY_DELAYS_MS[attempt]);
+		}
+	};
+	return {
+		async run(prepared) {
+			const rs = await withBusyRetry(() => client.execute({
+				sql: prepared.sql,
+				args: argsOf(prepared)
+			}));
+			return toResult(rs);
+		},
+		async transaction(statements) {
+			return (await withBusyRetry(() => client.batch(statements.map((s) => ({
+				sql: s.sql,
+				args: argsOf(s)
+			})), "write"))).map((rs) => toResult(rs));
+		},
+		async explain(prepared) {
+			const details = (await withBusyRetry(() => client.execute({
+				sql: `EXPLAIN QUERY PLAN ${prepared.sql}`,
+				args: argsOf(prepared)
+			}))).rows.map((r) => String(r.detail ?? ""));
+			return {
+				fullScan: details.some((d) => d.startsWith("SCAN")),
+				plan: details.join("; ").slice(0, 500)
+			};
+		},
+		async close() {
+			client.close();
+		}
+	};
+}
+//#endregion
+export { createSqliteExecutor };
+
+//# sourceMappingURL=index.mjs.map

package/dist/sqlite/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/sqlite/index.ts"],"sourcesContent":["import { createClient, type Config, type InArgs, type ResultSet } from '@libsql/client';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\n/**\n * How to reach the database. Either a full `@libsql/client` {@link Config} (a Turso/libSQL `url` +\n * `authToken`, an in-memory `':memory:'`, …) or the shorthand `{ file }` for a local SQLite file.\n */\nexport type SqliteConfig = Config | { file: string };\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/** SQLite's \"another connection holds the lock\" signal — a statement that never ran, safe to retry. */\nconst isBusy = (err: unknown): boolean => {\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('SQLITE_BUSY') || msg.includes('database is locked');\n};\n\n// Up to ~6.3s of extra waiting beyond the busy timeout, then give up and surface the error.\nconst BUSY_RETRY_DELAYS_MS = [100, 200, 400, 800, 1600, 3200];\n\nconst argsOf = (prepared: PreparedSql): InArgs => (prepared.params ?? []) as InArgs;\n\nconst toResult = <T>(rs: ResultSet): QueryResult<T> => {\n  const rows = rs.rows as unknown as T[];\n  // SELECT → row count; write → affected count (rows is empty).\n  return { rows, rowCount: rows.length > 0 ? rows.length : rs.rowsAffected };\n};\n\n/**\n * A SQLite / libSQL / Turso executor backed by `@libsql/client` (placeholders: `?`). Feed it the\n * `{ sql, params }` a `SqliteQuery` builder emits.\n */\nexport function createSqliteExecutor(config: SqliteConfig): DbExecutor {\n  const clientConfig: Config = 'file' in config ? { url: `file:${config.file}` } : config;\n  const client = createClient(clientConfig);\n\n  // A local SQLite FILE can be open in more than one connection at once (SQLite allows one writer),\n  // so two defenses, only for file URLs — remote libSQL/Turso has no such lock:\n  //   1. a busy timeout, so a briefly-held lock is waited out instead of throwing on the spot;\n  //   2. a bounded retry, because under sustained reader pressure the timeout can still lapse. A\n  //      SQLITE_BUSY means the statement did not run, so retrying — read OR write — repeats nothing;\n  //      a transaction batch rolls back fully before it surfaces, so retrying it is equally safe.\n  const isLocalFile = typeof clientConfig.url === 'string' && clientConfig.url.startsWith('file:');\n\n  let busyTimeout: Promise<void> | undefined;\n  const ensureBusyTimeout = (): Promise<void> => {\n    if (!isLocalFile) return Promise.resolve();\n    // Cached and best-effort: a driver that rejects the pragma must not break the executor.\n    busyTimeout ??= client.execute('PRAGMA busy_timeout = 5000').then(\n      () => {},\n      () => {},\n    );\n    return busyTimeout;\n  };\n\n  const withBusyRetry = async <R>(op: () => Promise<R>): Promise<R> => {\n    await ensureBusyTimeout();\n    for (let attempt = 0; ; attempt++) {\n      try {\n        return await op();\n      } catch (err) {\n        if (!isLocalFile || !isBusy(err) || attempt >= BUSY_RETRY_DELAYS_MS.length) throw err;\n        await sleep(BUSY_RETRY_DELAYS_MS[attempt]!);\n      }\n    }\n  };\n\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      const rs = await withBusyRetry(() =>\n        client.execute({ sql: prepared.sql, args: argsOf(prepared) }),\n      );\n      return toResult<T>(rs);\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      // `batch` runs every statement in ONE transaction and rolls back on any error — exactly the\n      // multi-builder contract, and each statement stays its own prepared statement.\n      const results = await withBusyRetry(() =>\n        client.batch(\n          statements.map((s) => ({ sql: s.sql, args: argsOf(s) })),\n          'write',\n        ),\n      );\n      return results.map((rs) => toResult(rs));\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      // SQLite's planner exposes no cost or row estimate — only the plan SHAPE. `SCAN` means a full\n      // table scan, `SEARCH` an index seek, so `fullScan` is the only signal this dialect gives.\n      const rs = await withBusyRetry(() =>\n        client.execute({ sql: `EXPLAIN QUERY PLAN ${prepared.sql}`, args: argsOf(prepared) }),\n      );\n      const details = rs.rows.map((r) =>\n        String((r as unknown as { detail?: string }).detail ?? ''),\n      );\n      return {\n        fullScan: details.some((d) => d.startsWith('SCAN')),\n        plan: details.join('; ').slice(0, 500),\n      };\n    },\n\n    async close(): Promise<void> {\n      client.close();\n    },\n  };\n}\n"],"mappings":";;AASA,MAAM,SAAS,OAA8B,IAAI,SAAS,MAAM,WAAW,GAAG,EAAE,CAAC;;AAGjF,MAAM,UAAU,QAA0B;CACxC,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;CAC3D,OAAO,IAAI,SAAS,aAAa,KAAK,IAAI,SAAS,oBAAoB;AACzE;AAGA,MAAM,uBAAuB;CAAC;CAAK;CAAK;CAAK;CAAK;CAAM;AAAI;AAE5D,MAAM,UAAU,aAAmC,SAAS,UAAU,CAAC;AAEvE,MAAM,YAAe,OAAkC;CACrD,MAAM,OAAO,GAAG;CAEhB,OAAO;EAAE;EAAM,UAAU,KAAK,SAAS,IAAI,KAAK,SAAS,GAAG;CAAa;AAC3E;;;;;AAMA,SAAgB,qBAAqB,QAAkC;CACrE,MAAM,eAAuB,UAAU,SAAS,EAAE,KAAK,QAAQ,OAAO,OAAO,IAAI;CACjF,MAAM,SAAS,aAAa,YAAY;CAQxC,MAAM,cAAc,OAAO,aAAa,QAAQ,YAAY,aAAa,IAAI,WAAW,OAAO;CAE/F,IAAI;CACJ,MAAM,0BAAyC;EAC7C,IAAI,CAAC,aAAa,OAAO,QAAQ,QAAQ;EAEzC,gBAAgB,OAAO,QAAQ,4BAA4B,CAAC,CAAC,WACrD,CAAC,SACD,CAAC,CACT;EACA,OAAO;CACT;CAEA,MAAM,gBAAgB,OAAU,OAAqC;EACnE,MAAM,kBAAkB;EACxB,KAAK,IAAI,UAAU,IAAK,WACtB,IAAI;GACF,OAAO,MAAM,GAAG;EAClB,SAAS,KAAK;GACZ,IAAI,CAAC,eAAe,CAAC,OAAO,GAAG,KAAK,WAAW,qBAAqB,QAAQ,MAAM;GAClF,MAAM,MAAM,qBAAqB,QAAS;EAC5C;CAEJ;CAEA,OAAO;EACL,MAAM,IAAa,UAAgD;GACjE,MAAM,KAAK,MAAM,oBACf,OAAO,QAAQ;IAAE,KAAK,SAAS;IAAK,MAAM,OAAO,QAAQ;GAAE,CAAC,CAC9D;GACA,OAAO,SAAY,EAAE;EACvB;EAEA,MAAM,YAAY,YAA4D;GAS5E,QAAO,MANe,oBACpB,OAAO,MACL,WAAW,KAAK,OAAO;IAAE,KAAK,EAAE;IAAK,MAAM,OAAO,CAAC;GAAE,EAAE,GACvD,OACF,CACF,EAAA,CACe,KAAK,OAAO,SAAS,EAAE,CAAC;EACzC;EAEA,MAAM,QAAQ,UAAiD;GAM7D,MAAM,WAAU,MAHC,oBACf,OAAO,QAAQ;IAAE,KAAK,sBAAsB,SAAS;IAAO,MAAM,OAAO,QAAQ;GAAE,CAAC,CACtF,EAAA,CACmB,KAAK,KAAK,MAC3B,OAAQ,EAAqC,UAAU,EAAE,CAC3D;GACA,OAAO;IACL,UAAU,QAAQ,MAAM,MAAM,EAAE,WAAW,MAAM,CAAC;IAClD,MAAM,QAAQ,KAAK,IAAI,CAAC,CAAC,MAAM,GAAG,GAAG;GACvC;EACF;EAEA,MAAM,QAAuB;GAC3B,OAAO,MAAM;EACf;CACF;AACF"}

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "@deebeetech/sqleasy-engine",
+  "version": "0.0.0",
+  "description": "A thin, opt-in executor for @deebeetech/sqleasy: runs its prepared SQL and transactions on Postgres, MySQL, SQL Server, and SQLite — loading only the driver you import.",
+  "keywords": [
+    "sql",
+    "sql-executor",
+    "query-runner",
+    "postgres",
+    "mysql",
+    "mssql",
+    "sqlite",
+    "libsql",
+    "transactions",
+    "sqleasy",
+    "typescript",
+    "database"
+  ],
+  "homepage": "https://github.com/deebee-tech/sqleasy-engine",
+  "license": "MIT",
+  "private": false,
+  "author": {
+    "name": "Sandy Weatherby",
+    "email": "unicornbeachdiaries@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deebee-tech/sqleasy-engine"
+  },
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite/index.d.mts",
+      "import": "./dist/sqlite/index.mjs",
+      "require": "./dist/sqlite/index.cjs"
+    },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.mts",
+      "import": "./dist/postgres/index.mjs",
+      "require": "./dist/postgres/index.cjs"
+    },
+    "./mysql": {
+      "types": "./dist/mysql/index.d.mts",
+      "import": "./dist/mysql/index.mjs",
+      "require": "./dist/mysql/index.cjs"
+    },
+    "./mssql": {
+      "types": "./dist/mssql/index.d.mts",
+      "import": "./dist/mssql/index.mjs",
+      "require": "./dist/mssql/index.cjs"
+    },
+    "./introspection": {
+      "types": "./dist/introspection/index.d.mts",
+      "import": "./dist/introspection/index.mjs",
+      "require": "./dist/introspection/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "packageManager": "pnpm@11.13.0",
+  "peerDependencies": {
+    "@libsql/client": "*",
+    "mssql": "*",
+    "mysql2": "*",
+    "pg": "*"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@libsql/client": "^0.17.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/mssql": "^12.3.0",
+    "@types/node": "^26.1.1",
+    "@types/pg": "^8.20.0",
+    "conventional-changelog-conventionalcommits": "^10.2.1",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "mssql": "^12.7.0",
+    "mysql2": "^3.22.6",
+    "pg": "^8.22.0",
+    "prettier": "^3.9.5",
+    "semantic-release": "^25.0.7",
+    "tsdown": "^0.22.7",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^4.1.10"
+  }
+}