@deebeetech/sqleasy-engine 0.0.0

package/dist/mssql/index.d.cts

@@ -0,0 +1,27 @@
+import { DbExecutor, ExplainEstimate } from "../index.cjs";
+import { config } from "mssql";
+//#region src/mssql/index.d.ts
+/** Connection settings — any `mssql` config object, or a raw connection string. */
+type MssqlConfig = config | {
+  connectionString: string;
+};
+/**
+ * Turn the mssql dialect's output into something SHOWPLAN can actually cost.
+ *
+ * It emits `SET NOCOUNT ON; exec sp_executesql N'<select>', N'<decls>'[, @p0 = …];`. SHOWPLAN does
+ * NOT compile dynamic SQL, so explaining the EXEC yields a plan with no cost — the inner statement
+ * must be lifted out. When it has parameters, that inner statement references `@p0`, undeclared
+ * outside sp_executesql, so re-declare them. The assigned VALUES are dropped on purpose: a cost
+ * estimate doesn't need them. Not a wrapped statement ⇒ returned unchanged.
+ */
+declare function toExplainableBatch(sql: string): string;
+/** Parse a SHOWPLAN_XML document into the normalized estimate. Exported for unit tests. */
+declare function parsePlanXml(xml: string): ExplainEstimate;
+/**
+ * A SQL Server executor backed by an `mssql` connection pool. Feed it the self-contained
+ * `sp_executesql` batch a `MssqlQuery` builder emits (its `params` is always `[]`).
+ */
+declare function createMssqlExecutor(config: MssqlConfig): DbExecutor;
+//#endregion
+export { MssqlConfig, createMssqlExecutor, parsePlanXml, toExplainableBatch };
+//# sourceMappingURL=index.d.cts.map

package/dist/mssql/index.d.mts

@@ -0,0 +1,27 @@
+import { DbExecutor, ExplainEstimate } from "../index.mjs";
+import { config } from "mssql";
+//#region src/mssql/index.d.ts
+/** Connection settings — any `mssql` config object, or a raw connection string. */
+type MssqlConfig = config | {
+  connectionString: string;
+};
+/**
+ * Turn the mssql dialect's output into something SHOWPLAN can actually cost.
+ *
+ * It emits `SET NOCOUNT ON; exec sp_executesql N'<select>', N'<decls>'[, @p0 = …];`. SHOWPLAN does
+ * NOT compile dynamic SQL, so explaining the EXEC yields a plan with no cost — the inner statement
+ * must be lifted out. When it has parameters, that inner statement references `@p0`, undeclared
+ * outside sp_executesql, so re-declare them. The assigned VALUES are dropped on purpose: a cost
+ * estimate doesn't need them. Not a wrapped statement ⇒ returned unchanged.
+ */
+declare function toExplainableBatch(sql: string): string;
+/** Parse a SHOWPLAN_XML document into the normalized estimate. Exported for unit tests. */
+declare function parsePlanXml(xml: string): ExplainEstimate;
+/**
+ * A SQL Server executor backed by an `mssql` connection pool. Feed it the self-contained
+ * `sp_executesql` batch a `MssqlQuery` builder emits (its `params` is always `[]`).
+ */
+declare function createMssqlExecutor(config: MssqlConfig): DbExecutor;
+//#endregion
+export { MssqlConfig, createMssqlExecutor, parsePlanXml, toExplainableBatch };
+//# sourceMappingURL=index.d.mts.map

package/dist/mssql/index.mjs

@@ -0,0 +1,129 @@
+import mssql from "mssql";
+//#region src/mssql/index.ts
+const { ConnectionPool, Transaction, Request } = mssql;
+/** Read the T-SQL string literal starting at `from` (just past the opening quote), honouring `''`
+* escapes. Returns the unescaped text and the index just past the closing quote. */
+function readLiteral(sql, from) {
+	let out = "";
+	for (let i = from; i < sql.length; i++) {
+		if (sql[i] !== "'") {
+			out += sql[i];
+			continue;
+		}
+		if (sql[i + 1] === "'") {
+			out += "'";
+			i++;
+			continue;
+		}
+		return {
+			text: out,
+			end: i + 1
+		};
+	}
+}
+/**
+* Turn the mssql dialect's output into something SHOWPLAN can actually cost.
+*
+* It emits `SET NOCOUNT ON; exec sp_executesql N'<select>', N'<decls>'[, @p0 = …];`. SHOWPLAN does
+* NOT compile dynamic SQL, so explaining the EXEC yields a plan with no cost — the inner statement
+* must be lifted out. When it has parameters, that inner statement references `@p0`, undeclared
+* outside sp_executesql, so re-declare them. The assigned VALUES are dropped on purpose: a cost
+* estimate doesn't need them. Not a wrapped statement ⇒ returned unchanged.
+*/
+function toExplainableBatch(sql) {
+	const m = /exec\s+sp_executesql\s+N'/i.exec(sql);
+	if (!m) return sql;
+	const inner = readLiteral(sql, m.index + m[0].length);
+	if (!inner) return sql;
+	const decl = /^\s*,\s*N'/.exec(sql.slice(inner.end));
+	const decls = decl ? readLiteral(sql, inner.end + decl[0].length)?.text.trim() : "";
+	return decls ? `DECLARE ${decls};\n${inner.text}` : inner.text;
+}
+/** Parse a SHOWPLAN_XML document into the normalized estimate. Exported for unit tests. */
+function parsePlanXml(xml) {
+	let best;
+	for (const [tag] of xml.matchAll(/<StmtSimple\b[^>]*>/g)) {
+		const cost = Number(/StatementSubTreeCost="([\d.eE+-]+)"/.exec(tag)?.[1]);
+		if (!Number.isFinite(cost) || best && cost <= best.cost) continue;
+		const rows = Number(/StatementEstRows="([\d.eE+-]+)"/.exec(tag)?.[1]);
+		best = {
+			cost,
+			rows: Number.isFinite(rows) ? rows : void 0
+		};
+	}
+	return {
+		cost: best?.cost,
+		rows: best?.rows,
+		fullScan: /PhysicalOp="(?:Table Scan|Clustered Index Scan|Index Scan)"/.test(xml),
+		plan: xml.slice(0, 500)
+	};
+}
+const toResult = (result) => ({
+	rows: result.recordset ?? [],
+	rowCount: result.recordset ? result.recordset.length : result.rowsAffected?.[0] ?? 0
+});
+const bindParams = (request, params) => {
+	(params ?? []).forEach((value, i) => request.input(`p${i}`, value));
+	return request;
+};
+/**
+* A SQL Server executor backed by an `mssql` connection pool. Feed it the self-contained
+* `sp_executesql` batch a `MssqlQuery` builder emits (its `params` is always `[]`).
+*/
+function createMssqlExecutor(config) {
+	const makePool = () => new ConnectionPool("connectionString" in config ? config.connectionString : config);
+	let pool = makePool();
+	let ready;
+	const ensureReady = () => ready ??= pool.connect().catch((e) => {
+		ready = void 0;
+		const dead = pool;
+		pool = makePool();
+		dead.close().catch(() => {});
+		throw e;
+	});
+	return {
+		async run(prepared) {
+			await ensureReady();
+			const request = bindParams(pool.request(), prepared.params);
+			return toResult(await request.query(prepared.sql));
+		},
+		async transaction(statements) {
+			await ensureReady();
+			const tx = new Transaction(pool);
+			await tx.begin();
+			try {
+				const results = [];
+				for (const s of statements) {
+					const request = bindParams(new Request(tx), s.params);
+					results.push(toResult(await request.query(s.sql)));
+				}
+				await tx.commit();
+				return results;
+			} catch (err) {
+				await tx.rollback().catch(() => {});
+				throw err;
+			}
+		},
+		async explain(prepared) {
+			await ensureReady();
+			const tx = new Transaction(pool);
+			await tx.begin();
+			try {
+				await new Request(tx).batch("SET SHOWPLAN_XML ON");
+				const first = (await new Request(tx).batch(toExplainableBatch(prepared.sql))).recordset?.[0];
+				return parsePlanXml(String(first ? Object.values(first)[0] : ""));
+			} finally {
+				await new Request(tx).batch("SET SHOWPLAN_XML OFF").catch(() => {});
+				await tx.rollback().catch(() => {});
+			}
+		},
+		async close() {
+			await (ready?.catch(() => {}) ?? Promise.resolve());
+			await pool.close();
+		}
+	};
+}
+//#endregion
+export { createMssqlExecutor, parsePlanXml, toExplainableBatch };
+
+//# sourceMappingURL=index.mjs.map

package/dist/mssql/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/mssql/index.ts"],"sourcesContent":["// `mssql` is CommonJS and Node's ESM loader can't see its named exports — import the default and\n// destructure. (pg/mysql2/@libsql expose named exports fine.)\nimport mssql from 'mssql';\nimport type { config as MssqlDriverConfig, IResult } from 'mssql';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\nconst { ConnectionPool, Transaction, Request } = mssql;\n\n/** Connection settings — any `mssql` config object, or a raw connection string. */\nexport type MssqlConfig = MssqlDriverConfig | { connectionString: string };\n\n/** Read the T-SQL string literal starting at `from` (just past the opening quote), honouring `''`\n * escapes. Returns the unescaped text and the index just past the closing quote. */\nfunction readLiteral(sql: string, from: number): { text: string; end: number } | undefined {\n  let out = '';\n  for (let i = from; i < sql.length; i++) {\n    if (sql[i] !== \"'\") {\n      out += sql[i];\n      continue;\n    }\n    if (sql[i + 1] === \"'\") {\n      out += \"'\";\n      i++;\n      continue;\n    }\n    return { text: out, end: i + 1 };\n  }\n  return undefined; // unterminated — caller falls back to the raw batch\n}\n\n/**\n * Turn the mssql dialect's output into something SHOWPLAN can actually cost.\n *\n * It emits `SET NOCOUNT ON; exec sp_executesql N'<select>', N'<decls>'[, @p0 = …];`. SHOWPLAN does\n * NOT compile dynamic SQL, so explaining the EXEC yields a plan with no cost — the inner statement\n * must be lifted out. When it has parameters, that inner statement references `@p0`, undeclared\n * outside sp_executesql, so re-declare them. The assigned VALUES are dropped on purpose: a cost\n * estimate doesn't need them. Not a wrapped statement ⇒ returned unchanged.\n */\nexport function toExplainableBatch(sql: string): string {\n  const m = /exec\\s+sp_executesql\\s+N'/i.exec(sql);\n  if (!m) return sql;\n  const inner = readLiteral(sql, m.index + m[0].length);\n  if (!inner) return sql;\n  const decl = /^\\s*,\\s*N'/.exec(sql.slice(inner.end));\n  const decls = decl ? readLiteral(sql, inner.end + decl[0].length)?.text.trim() : '';\n  return decls ? `DECLARE ${decls};\\n${inner.text}` : inner.text;\n}\n\n/** Parse a SHOWPLAN_XML document into the normalized estimate. Exported for unit tests. */\nexport function parsePlanXml(xml: string): ExplainEstimate {\n  // A batch holds one <StmtSimple> per statement (the injected DECLARE, SET NOCOUNT ON, the SELECT).\n  // Take the most expensive — never blindly the first, which is usually a costless preamble.\n  let best: { cost: number; rows?: number } | undefined;\n  for (const [tag] of xml.matchAll(/<StmtSimple\\b[^>]*>/g)) {\n    const cost = Number(/StatementSubTreeCost=\"([\\d.eE+-]+)\"/.exec(tag)?.[1]);\n    if (!Number.isFinite(cost) || (best && cost <= best.cost)) continue;\n    const rows = Number(/StatementEstRows=\"([\\d.eE+-]+)\"/.exec(tag)?.[1]);\n    best = { cost, rows: Number.isFinite(rows) ? rows : undefined };\n  }\n  return {\n    cost: best?.cost,\n    rows: best?.rows,\n    fullScan: /PhysicalOp=\"(?:Table Scan|Clustered Index Scan|Index Scan)\"/.test(xml),\n    plan: xml.slice(0, 500),\n  };\n}\n\nconst toResult = <T>(result: IResult<unknown>): QueryResult<T> => ({\n  rows: (result.recordset ?? []) as unknown as T[],\n  rowCount: result.recordset ? result.recordset.length : (result.rowsAffected?.[0] ?? 0),\n});\n\n// Bind params (if any) as @p0..@pN. SQLEasy's mssql dialect inlines its values into the\n// sp_executesql batch and passes `params: []`, so nothing binds on that path; a caller passing\n// bound values must reference @p0.. in their SQL (mssql has no positional `?`). No `?`→`@p`\n// rewriting — that scan corrupts a `?` inside a string literal.\ntype BindableRequest = { input(name: string, value: unknown): unknown };\nconst bindParams = <R extends BindableRequest>(request: R, params?: readonly unknown[]): R => {\n  (params ?? []).forEach((value, i) => request.input(`p${i}`, value));\n  return request;\n};\n\n/**\n * A SQL Server executor backed by an `mssql` connection pool. Feed it the self-contained\n * `sp_executesql` batch a `MssqlQuery` builder emits (its `params` is always `[]`).\n */\nexport function createMssqlExecutor(config: MssqlConfig): DbExecutor {\n  const makePool = () =>\n    new ConnectionPool('connectionString' in config ? config.connectionString : config);\n  let pool = makePool();\n\n  // Single-flight connect that RECOVERS. Caching a rejected `pool.connect()` promise would brick the\n  // pool forever (a DB restart / blip): every later query awaits the same settled rejection. So reset\n  // the gate and rebuild the pool on failure, and the next call retries. (pg/mysql self-heal\n  // per-acquire; mssql caches connect, so it alone needs this.)\n  let ready: Promise<unknown> | undefined;\n  const ensureReady = () =>\n    (ready ??= pool.connect().catch((e: unknown) => {\n      ready = undefined;\n      const dead = pool;\n      pool = makePool();\n      void dead.close().catch(() => {});\n      throw e;\n    }));\n\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      await ensureReady();\n      const request = bindParams(pool.request(), prepared.params);\n      return toResult<T>(await request.query(prepared.sql));\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      await ensureReady();\n      const tx = new Transaction(pool);\n      await tx.begin();\n      try {\n        const results: QueryResult[] = [];\n        for (const s of statements) {\n          const request = bindParams(new Request(tx), s.params);\n          results.push(toResult(await request.query(s.sql)));\n        }\n        await tx.commit();\n        return results;\n      } catch (err) {\n        await tx.rollback().catch(() => {});\n        throw err;\n      }\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      await ensureReady();\n      // SQL Server has no EXPLAIN. The estimated plan comes from SET SHOWPLAN_XML, which (a) must be\n      // the ONLY statement in its batch and (b) is SESSION state — so the SET and the query must run\n      // on the SAME connection. A transaction pins one connection for both; the finally block always\n      // clears the flag and releases it, so SHOWPLAN never leaks onto a connection serving reads.\n      const tx = new Transaction(pool);\n      await tx.begin();\n      try {\n        await new Request(tx).batch('SET SHOWPLAN_XML ON');\n        const res = await new Request(tx).batch(toExplainableBatch(prepared.sql));\n        const first = res.recordset?.[0] as Row | undefined;\n        return parsePlanXml(String(first ? Object.values(first)[0] : ''));\n      } finally {\n        await new Request(tx).batch('SET SHOWPLAN_XML OFF').catch(() => {});\n        await tx.rollback().catch(() => {});\n      }\n    },\n\n    async close(): Promise<void> {\n      await (ready?.catch(() => {}) ?? Promise.resolve());\n      await pool.close();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/mysql/index.cjs

@@ -0,0 +1,90 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let mysql2_promise = require("mysql2/promise");
+//#region src/mysql/index.ts
+/** Every `table` node in the plan, however deeply the operation wrappers nest it. */
+function tablesOf(block) {
+	if (!block) return [];
+	return [
+		...block.table ? [block.table] : [],
+		...(block.nested_loop ?? []).flatMap(tablesOf),
+		...tablesOf(block.ordering_operation),
+		...tablesOf(block.grouping_operation),
+		...tablesOf(block.duplicates_removal)
+	];
+}
+/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */
+function parseMysqlPlan(raw) {
+	let plan = {};
+	try {
+		plan = JSON.parse(raw || "{}");
+	} catch {}
+	const cost = Number(plan.query_block?.cost_info?.query_cost);
+	const tables = tablesOf(plan.query_block);
+	return {
+		cost: Number.isFinite(cost) ? cost : void 0,
+		rows: tables[0]?.rows_examined_per_scan,
+		fullScan: tables.some((t) => t.access_type === "ALL"),
+		plan: (raw ?? "").slice(0, 500)
+	};
+}
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (result) => {
+	if (Array.isArray(result)) return {
+		rows: result,
+		rowCount: result.length
+	};
+	return {
+		rows: [],
+		rowCount: result.affectedRows ?? 0
+	};
+};
+/**
+* Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across
+* your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.
+*/
+function createMysqlExecutorFromPool(pool) {
+	return {
+		async run(prepared) {
+			const [result] = await pool.query(prepared.sql, argsOf(prepared));
+			return toResult(result);
+		},
+		async transaction(statements) {
+			const conn = await pool.getConnection();
+			try {
+				await conn.beginTransaction();
+				const results = [];
+				for (const s of statements) {
+					const [result] = await conn.query(s.sql, argsOf(s));
+					results.push(toResult(result));
+				}
+				await conn.commit();
+				return results;
+			} catch (err) {
+				await conn.rollback().catch(() => {});
+				throw err;
+			} finally {
+				conn.release();
+			}
+		},
+		async explain(prepared) {
+			const [rows] = await pool.query(`EXPLAIN FORMAT=JSON ${prepared.sql}`, argsOf(prepared));
+			return parseMysqlPlan((Array.isArray(rows) ? rows[0]?.EXPLAIN : "") ?? "");
+		},
+		async close() {
+			await pool.end();
+		}
+	};
+}
+/**
+* A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the
+* `{ sql, params }` a `MysqlQuery` builder emits.
+*/
+function createMysqlExecutor(config) {
+	return createMysqlExecutorFromPool((0, mysql2_promise.createPool)(config));
+}
+//#endregion
+exports.createMysqlExecutor = createMysqlExecutor;
+exports.createMysqlExecutorFromPool = createMysqlExecutorFromPool;
+exports.parseMysqlPlan = parseMysqlPlan;
+
+//# sourceMappingURL=index.cjs.map

package/dist/mysql/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/mysql/index.ts"],"sourcesContent":["import { createPool, type Pool, type PoolOptions, type ResultSetHeader } from 'mysql2/promise';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\n/** Connection settings — any `mysql2` `PoolOptions`. */\nexport type MysqlConfig = PoolOptions;\n\n/** `EXPLAIN FORMAT=JSON` shape — only the bits we read. A `table` node is not always a direct child\n * of `query_block`: a JOIN nests it under `nested_loop[]`, ORDER BY under `ordering_operation`, etc. */\ntype MysqlTable = { access_type?: string; rows_examined_per_scan?: number };\ntype MysqlBlock = {\n  cost_info?: { query_cost?: string };\n  table?: MysqlTable;\n  nested_loop?: MysqlBlock[];\n  ordering_operation?: MysqlBlock;\n  grouping_operation?: MysqlBlock;\n  duplicates_removal?: MysqlBlock;\n};\ntype MysqlPlan = { query_block?: MysqlBlock };\n\n/** Every `table` node in the plan, however deeply the operation wrappers nest it. */\nfunction tablesOf(block: MysqlBlock | undefined): MysqlTable[] {\n  if (!block) return [];\n  return [\n    ...(block.table ? [block.table] : []),\n    ...(block.nested_loop ?? []).flatMap(tablesOf),\n    ...tablesOf(block.ordering_operation),\n    ...tablesOf(block.grouping_operation),\n    ...tablesOf(block.duplicates_removal),\n  ];\n}\n\n/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */\nexport function parseMysqlPlan(raw: string): ExplainEstimate {\n  let plan: MysqlPlan = {};\n  try {\n    plan = JSON.parse(raw || '{}') as MysqlPlan;\n  } catch {\n    // Unparseable plan — an empty estimate beats throwing.\n  }\n  const cost = Number(plan.query_block?.cost_info?.query_cost);\n  const tables = tablesOf(plan.query_block);\n  return {\n    cost: Number.isFinite(cost) ? cost : undefined,\n    // The driving (first) table's scanned rows.\n    rows: tables[0]?.rows_examined_per_scan,\n    // `ALL` is MySQL's full-table-scan access type — a scan ANYWHERE in the plan counts.\n    fullScan: tables.some((t) => t.access_type === 'ALL'),\n    plan: (raw ?? '').slice(0, 500),\n  };\n}\n\nconst argsOf = (prepared: PreparedSql): unknown[] => (prepared.params ?? []) as unknown[];\n\n// mysql2's query() resolves to `[rows | ResultSetHeader, fields]`. SELECT → an array of rows; a\n// write → a ResultSetHeader carrying affectedRows.\nconst toResult = <T>(result: unknown): QueryResult<T> => {\n  if (Array.isArray(result)) return { rows: result as T[], rowCount: result.length };\n  return { rows: [], rowCount: (result as ResultSetHeader).affectedRows ?? 0 };\n};\n\n/**\n * Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across\n * your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.\n */\nexport function createMysqlExecutorFromPool(pool: Pool): DbExecutor {\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      const [result] = await pool.query(prepared.sql, argsOf(prepared));\n      return toResult<T>(result);\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      // Driver-level transaction on a single pinned connection — beginTransaction/commit/rollback\n      // speak the protocol correctly (no `multipleStatements`, no concatenation). Each statement\n      // runs on its own; ROLLBACK on any error; release the connection no matter what.\n      const conn = await pool.getConnection();\n      try {\n        await conn.beginTransaction();\n        const results: QueryResult[] = [];\n        for (const s of statements) {\n          const [result] = await conn.query(s.sql, argsOf(s));\n          results.push(toResult(result));\n        }\n        await conn.commit();\n        return results;\n      } catch (err) {\n        await conn.rollback().catch(() => {});\n        throw err;\n      } finally {\n        conn.release();\n      }\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      // EXPLAIN never executes the statement; FORMAT=JSON is the only form carrying a cost estimate.\n      const [rows] = await pool.query(`EXPLAIN FORMAT=JSON ${prepared.sql}`, argsOf(prepared));\n      const raw = Array.isArray(rows) ? (rows[0] as { EXPLAIN?: string } | undefined)?.EXPLAIN : '';\n      return parseMysqlPlan(raw ?? '');\n    },\n\n    async close(): Promise<void> {\n      await pool.end();\n    },\n  };\n}\n\n/**\n * A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the\n * `{ sql, params }` a `MysqlQuery` builder emits.\n */\nexport function createMysqlExecutor(config: MysqlConfig): DbExecutor {\n  return createMysqlExecutorFromPool(createPool(config));\n}\n"],"mappings":";;;;AAoBA,SAAS,SAAS,OAA6C;CAC7D,IAAI,CAAC,OAAO,OAAO,CAAC;CACpB,OAAO;EACL,GAAI,MAAM,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;EACnC,IAAI,MAAM,eAAe,CAAC,EAAA,CAAG,QAAQ,QAAQ;EAC7C,GAAG,SAAS,MAAM,kBAAkB;EACpC,GAAG,SAAS,MAAM,kBAAkB;EACpC,GAAG,SAAS,MAAM,kBAAkB;CACtC;AACF;;AAGA,SAAgB,eAAe,KAA8B;CAC3D,IAAI,OAAkB,CAAC;CACvB,IAAI;EACF,OAAO,KAAK,MAAM,OAAO,IAAI;CAC/B,QAAQ,CAER;CACA,MAAM,OAAO,OAAO,KAAK,aAAa,WAAW,UAAU;CAC3D,MAAM,SAAS,SAAS,KAAK,WAAW;CACxC,OAAO;EACL,MAAM,OAAO,SAAS,IAAI,IAAI,OAAO,KAAA;EAErC,MAAM,OAAO,EAAE,EAAE;EAEjB,UAAU,OAAO,MAAM,MAAM,EAAE,gBAAgB,KAAK;EACpD,OAAO,OAAO,GAAA,CAAI,MAAM,GAAG,GAAG;CAChC;AACF;AAEA,MAAM,UAAU,aAAsC,SAAS,UAAU,CAAC;AAI1E,MAAM,YAAe,WAAoC;CACvD,IAAI,MAAM,QAAQ,MAAM,GAAG,OAAO;EAAE,MAAM;EAAe,UAAU,OAAO;CAAO;CACjF,OAAO;EAAE,MAAM,CAAC;EAAG,UAAW,OAA2B,gBAAgB;CAAE;AAC7E;;;;;AAMA,SAAgB,4BAA4B,MAAwB;CAClE,OAAO;EACL,MAAM,IAAa,UAAgD;GACjE,MAAM,CAAC,UAAU,MAAM,KAAK,MAAM,SAAS,KAAK,OAAO,QAAQ,CAAC;GAChE,OAAO,SAAY,MAAM;EAC3B;EAEA,MAAM,YAAY,YAA4D;GAI5E,MAAM,OAAO,MAAM,KAAK,cAAc;GACtC,IAAI;IACF,MAAM,KAAK,iBAAiB;IAC5B,MAAM,UAAyB,CAAC;IAChC,KAAK,MAAM,KAAK,YAAY;KAC1B,MAAM,CAAC,UAAU,MAAM,KAAK,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC;KAClD,QAAQ,KAAK,SAAS,MAAM,CAAC;IAC/B;IACA,MAAM,KAAK,OAAO;IAClB,OAAO;GACT,SAAS,KAAK;IACZ,MAAM,KAAK,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;IACpC,MAAM;GACR,UAAU;IACR,KAAK,QAAQ;GACf;EACF;EAEA,MAAM,QAAQ,UAAiD;GAE7D,MAAM,CAAC,QAAQ,MAAM,KAAK,MAAM,uBAAuB,SAAS,OAAO,OAAO,QAAQ,CAAC;GAEvF,OAAO,gBADK,MAAM,QAAQ,IAAI,IAAK,KAAK,EAAE,EAAuC,UAAU,OAC9D,EAAE;EACjC;EAEA,MAAM,QAAuB;GAC3B,MAAM,KAAK,IAAI;EACjB;CACF;AACF;;;;;AAMA,SAAgB,oBAAoB,QAAiC;CACnE,OAAO,6BAAA,GAAA,eAAA,WAAA,CAAuC,MAAM,CAAC;AACvD"}

package/dist/mysql/index.d.cts

@@ -0,0 +1,20 @@
+import { DbExecutor, ExplainEstimate } from "../index.cjs";
+import { Pool, PoolOptions } from "mysql2/promise";
+//#region src/mysql/index.d.ts
+/** Connection settings — any `mysql2` `PoolOptions`. */
+type MysqlConfig = PoolOptions;
+/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */
+declare function parseMysqlPlan(raw: string): ExplainEstimate;
+/**
+ * Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across
+ * your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.
+ */
+declare function createMysqlExecutorFromPool(pool: Pool): DbExecutor;
+/**
+ * A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the
+ * `{ sql, params }` a `MysqlQuery` builder emits.
+ */
+declare function createMysqlExecutor(config: MysqlConfig): DbExecutor;
+//#endregion
+export { MysqlConfig, createMysqlExecutor, createMysqlExecutorFromPool, parseMysqlPlan };
+//# sourceMappingURL=index.d.cts.map

package/dist/mysql/index.d.mts

@@ -0,0 +1,20 @@
+import { DbExecutor, ExplainEstimate } from "../index.mjs";
+import { Pool, PoolOptions } from "mysql2/promise";
+//#region src/mysql/index.d.ts
+/** Connection settings — any `mysql2` `PoolOptions`. */
+type MysqlConfig = PoolOptions;
+/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */
+declare function parseMysqlPlan(raw: string): ExplainEstimate;
+/**
+ * Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across
+ * your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.
+ */
+declare function createMysqlExecutorFromPool(pool: Pool): DbExecutor;
+/**
+ * A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the
+ * `{ sql, params }` a `MysqlQuery` builder emits.
+ */
+declare function createMysqlExecutor(config: MysqlConfig): DbExecutor;
+//#endregion
+export { MysqlConfig, createMysqlExecutor, createMysqlExecutorFromPool, parseMysqlPlan };
+//# sourceMappingURL=index.d.mts.map

package/dist/mysql/index.mjs

@@ -0,0 +1,87 @@
+import { createPool } from "mysql2/promise";
+//#region src/mysql/index.ts
+/** Every `table` node in the plan, however deeply the operation wrappers nest it. */
+function tablesOf(block) {
+	if (!block) return [];
+	return [
+		...block.table ? [block.table] : [],
+		...(block.nested_loop ?? []).flatMap(tablesOf),
+		...tablesOf(block.ordering_operation),
+		...tablesOf(block.grouping_operation),
+		...tablesOf(block.duplicates_removal)
+	];
+}
+/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */
+function parseMysqlPlan(raw) {
+	let plan = {};
+	try {
+		plan = JSON.parse(raw || "{}");
+	} catch {}
+	const cost = Number(plan.query_block?.cost_info?.query_cost);
+	const tables = tablesOf(plan.query_block);
+	return {
+		cost: Number.isFinite(cost) ? cost : void 0,
+		rows: tables[0]?.rows_examined_per_scan,
+		fullScan: tables.some((t) => t.access_type === "ALL"),
+		plan: (raw ?? "").slice(0, 500)
+	};
+}
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (result) => {
+	if (Array.isArray(result)) return {
+		rows: result,
+		rowCount: result.length
+	};
+	return {
+		rows: [],
+		rowCount: result.affectedRows ?? 0
+	};
+};
+/**
+* Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across
+* your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.
+*/
+function createMysqlExecutorFromPool(pool) {
+	return {
+		async run(prepared) {
+			const [result] = await pool.query(prepared.sql, argsOf(prepared));
+			return toResult(result);
+		},
+		async transaction(statements) {
+			const conn = await pool.getConnection();
+			try {
+				await conn.beginTransaction();
+				const results = [];
+				for (const s of statements) {
+					const [result] = await conn.query(s.sql, argsOf(s));
+					results.push(toResult(result));
+				}
+				await conn.commit();
+				return results;
+			} catch (err) {
+				await conn.rollback().catch(() => {});
+				throw err;
+			} finally {
+				conn.release();
+			}
+		},
+		async explain(prepared) {
+			const [rows] = await pool.query(`EXPLAIN FORMAT=JSON ${prepared.sql}`, argsOf(prepared));
+			return parseMysqlPlan((Array.isArray(rows) ? rows[0]?.EXPLAIN : "") ?? "");
+		},
+		async close() {
+			await pool.end();
+		}
+	};
+}
+/**
+* A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the
+* `{ sql, params }` a `MysqlQuery` builder emits.
+*/
+function createMysqlExecutor(config) {
+	return createMysqlExecutorFromPool(createPool(config));
+}
+//#endregion
+export { createMysqlExecutor, createMysqlExecutorFromPool, parseMysqlPlan };
+
+//# sourceMappingURL=index.mjs.map

package/dist/mysql/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/mysql/index.ts"],"sourcesContent":["import { createPool, type Pool, type PoolOptions, type ResultSetHeader } from 'mysql2/promise';\nimport type { DbExecutor, ExplainEstimate, PreparedSql, QueryResult, Row } from '../index';\n\n/** Connection settings — any `mysql2` `PoolOptions`. */\nexport type MysqlConfig = PoolOptions;\n\n/** `EXPLAIN FORMAT=JSON` shape — only the bits we read. A `table` node is not always a direct child\n * of `query_block`: a JOIN nests it under `nested_loop[]`, ORDER BY under `ordering_operation`, etc. */\ntype MysqlTable = { access_type?: string; rows_examined_per_scan?: number };\ntype MysqlBlock = {\n  cost_info?: { query_cost?: string };\n  table?: MysqlTable;\n  nested_loop?: MysqlBlock[];\n  ordering_operation?: MysqlBlock;\n  grouping_operation?: MysqlBlock;\n  duplicates_removal?: MysqlBlock;\n};\ntype MysqlPlan = { query_block?: MysqlBlock };\n\n/** Every `table` node in the plan, however deeply the operation wrappers nest it. */\nfunction tablesOf(block: MysqlBlock | undefined): MysqlTable[] {\n  if (!block) return [];\n  return [\n    ...(block.table ? [block.table] : []),\n    ...(block.nested_loop ?? []).flatMap(tablesOf),\n    ...tablesOf(block.ordering_operation),\n    ...tablesOf(block.grouping_operation),\n    ...tablesOf(block.duplicates_removal),\n  ];\n}\n\n/** Parse `EXPLAIN FORMAT=JSON` output into the normalized estimate. Exported for unit tests. */\nexport function parseMysqlPlan(raw: string): ExplainEstimate {\n  let plan: MysqlPlan = {};\n  try {\n    plan = JSON.parse(raw || '{}') as MysqlPlan;\n  } catch {\n    // Unparseable plan — an empty estimate beats throwing.\n  }\n  const cost = Number(plan.query_block?.cost_info?.query_cost);\n  const tables = tablesOf(plan.query_block);\n  return {\n    cost: Number.isFinite(cost) ? cost : undefined,\n    // The driving (first) table's scanned rows.\n    rows: tables[0]?.rows_examined_per_scan,\n    // `ALL` is MySQL's full-table-scan access type — a scan ANYWHERE in the plan counts.\n    fullScan: tables.some((t) => t.access_type === 'ALL'),\n    plan: (raw ?? '').slice(0, 500),\n  };\n}\n\nconst argsOf = (prepared: PreparedSql): unknown[] => (prepared.params ?? []) as unknown[];\n\n// mysql2's query() resolves to `[rows | ResultSetHeader, fields]`. SELECT → an array of rows; a\n// write → a ResultSetHeader carrying affectedRows.\nconst toResult = <T>(result: unknown): QueryResult<T> => {\n  if (Array.isArray(result)) return { rows: result as T[], rowCount: result.length };\n  return { rows: [], rowCount: (result as ResultSetHeader).affectedRows ?? 0 };\n};\n\n/**\n * Build a MySQL executor over an EXISTING pool — bring your own `mysql2` Pool to share one across\n * your app (or hand in a test double). {@link createMysqlExecutor} is the usual entry.\n */\nexport function createMysqlExecutorFromPool(pool: Pool): DbExecutor {\n  return {\n    async run<T = Row>(prepared: PreparedSql): Promise<QueryResult<T>> {\n      const [result] = await pool.query(prepared.sql, argsOf(prepared));\n      return toResult<T>(result);\n    },\n\n    async transaction(statements: readonly PreparedSql[]): Promise<QueryResult[]> {\n      // Driver-level transaction on a single pinned connection — beginTransaction/commit/rollback\n      // speak the protocol correctly (no `multipleStatements`, no concatenation). Each statement\n      // runs on its own; ROLLBACK on any error; release the connection no matter what.\n      const conn = await pool.getConnection();\n      try {\n        await conn.beginTransaction();\n        const results: QueryResult[] = [];\n        for (const s of statements) {\n          const [result] = await conn.query(s.sql, argsOf(s));\n          results.push(toResult(result));\n        }\n        await conn.commit();\n        return results;\n      } catch (err) {\n        await conn.rollback().catch(() => {});\n        throw err;\n      } finally {\n        conn.release();\n      }\n    },\n\n    async explain(prepared: PreparedSql): Promise<ExplainEstimate> {\n      // EXPLAIN never executes the statement; FORMAT=JSON is the only form carrying a cost estimate.\n      const [rows] = await pool.query(`EXPLAIN FORMAT=JSON ${prepared.sql}`, argsOf(prepared));\n      const raw = Array.isArray(rows) ? (rows[0] as { EXPLAIN?: string } | undefined)?.EXPLAIN : '';\n      return parseMysqlPlan(raw ?? '');\n    },\n\n    async close(): Promise<void> {\n      await pool.end();\n    },\n  };\n}\n\n/**\n * A MySQL / MariaDB executor backed by a `mysql2` connection pool (placeholders: `?`). Feed it the\n * `{ sql, params }` a `MysqlQuery` builder emits.\n */\nexport function createMysqlExecutor(config: MysqlConfig): DbExecutor {\n  return createMysqlExecutorFromPool(createPool(config));\n}\n"],"mappings":";;;AAoBA,SAAS,SAAS,OAA6C;CAC7D,IAAI,CAAC,OAAO,OAAO,CAAC;CACpB,OAAO;EACL,GAAI,MAAM,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;EACnC,IAAI,MAAM,eAAe,CAAC,EAAA,CAAG,QAAQ,QAAQ;EAC7C,GAAG,SAAS,MAAM,kBAAkB;EACpC,GAAG,SAAS,MAAM,kBAAkB;EACpC,GAAG,SAAS,MAAM,kBAAkB;CACtC;AACF;;AAGA,SAAgB,eAAe,KAA8B;CAC3D,IAAI,OAAkB,CAAC;CACvB,IAAI;EACF,OAAO,KAAK,MAAM,OAAO,IAAI;CAC/B,QAAQ,CAER;CACA,MAAM,OAAO,OAAO,KAAK,aAAa,WAAW,UAAU;CAC3D,MAAM,SAAS,SAAS,KAAK,WAAW;CACxC,OAAO;EACL,MAAM,OAAO,SAAS,IAAI,IAAI,OAAO,KAAA;EAErC,MAAM,OAAO,EAAE,EAAE;EAEjB,UAAU,OAAO,MAAM,MAAM,EAAE,gBAAgB,KAAK;EACpD,OAAO,OAAO,GAAA,CAAI,MAAM,GAAG,GAAG;CAChC;AACF;AAEA,MAAM,UAAU,aAAsC,SAAS,UAAU,CAAC;AAI1E,MAAM,YAAe,WAAoC;CACvD,IAAI,MAAM,QAAQ,MAAM,GAAG,OAAO;EAAE,MAAM;EAAe,UAAU,OAAO;CAAO;CACjF,OAAO;EAAE,MAAM,CAAC;EAAG,UAAW,OAA2B,gBAAgB;CAAE;AAC7E;;;;;AAMA,SAAgB,4BAA4B,MAAwB;CAClE,OAAO;EACL,MAAM,IAAa,UAAgD;GACjE,MAAM,CAAC,UAAU,MAAM,KAAK,MAAM,SAAS,KAAK,OAAO,QAAQ,CAAC;GAChE,OAAO,SAAY,MAAM;EAC3B;EAEA,MAAM,YAAY,YAA4D;GAI5E,MAAM,OAAO,MAAM,KAAK,cAAc;GACtC,IAAI;IACF,MAAM,KAAK,iBAAiB;IAC5B,MAAM,UAAyB,CAAC;IAChC,KAAK,MAAM,KAAK,YAAY;KAC1B,MAAM,CAAC,UAAU,MAAM,KAAK,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC;KAClD,QAAQ,KAAK,SAAS,MAAM,CAAC;IAC/B;IACA,MAAM,KAAK,OAAO;IAClB,OAAO;GACT,SAAS,KAAK;IACZ,MAAM,KAAK,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;IACpC,MAAM;GACR,UAAU;IACR,KAAK,QAAQ;GACf;EACF;EAEA,MAAM,QAAQ,UAAiD;GAE7D,MAAM,CAAC,QAAQ,MAAM,KAAK,MAAM,uBAAuB,SAAS,OAAO,OAAO,QAAQ,CAAC;GAEvF,OAAO,gBADK,MAAM,QAAQ,IAAI,IAAK,KAAK,EAAE,EAAuC,UAAU,OAC9D,EAAE;EACjC;EAEA,MAAM,QAAuB;GAC3B,MAAM,KAAK,IAAI;EACjB;CACF;AACF;;;;;AAMA,SAAgB,oBAAoB,QAAiC;CACnE,OAAO,4BAA4B,WAAW,MAAM,CAAC;AACvD"}

package/dist/postgres/index.cjs

@@ -0,0 +1,64 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let pg = require("pg");
+//#region src/postgres/index.ts
+/** Parse `EXPLAIN (FORMAT JSON)` result rows into the normalized estimate. Exported for unit tests. */
+function parsePgPlan(rows) {
+	const root = rows[0]?.["QUERY PLAN"]?.[0]?.Plan;
+	const seqScan = (n) => !!n && (n["Node Type"] === "Seq Scan" || (n.Plans ?? []).some(seqScan));
+	return {
+		cost: root?.["Total Cost"],
+		rows: root?.["Plan Rows"],
+		fullScan: seqScan(root),
+		plan: JSON.stringify(root ?? {}).slice(0, 500)
+	};
+}
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (res) => ({
+	rows: res.rows,
+	rowCount: res.rowCount ?? res.rows.length
+});
+/**
+* Build a Postgres executor over an EXISTING pool — bring your own `pg` Pool to share one pool
+* across your app (or hand in a test double). {@link createPostgresExecutor} is the usual entry.
+*/
+function createPostgresExecutorFromPool(pool) {
+	return {
+		async run(prepared) {
+			return toResult(await pool.query(prepared.sql, argsOf(prepared)));
+		},
+		async transaction(statements) {
+			const client = await pool.connect();
+			try {
+				await client.query("BEGIN");
+				const results = [];
+				for (const s of statements) results.push(toResult(await client.query(s.sql, argsOf(s))));
+				await client.query("COMMIT");
+				return results;
+			} catch (err) {
+				await client.query("ROLLBACK").catch(() => {});
+				throw err;
+			} finally {
+				client.release();
+			}
+		},
+		async explain(prepared) {
+			return parsePgPlan((await pool.query(`EXPLAIN (FORMAT JSON) ${prepared.sql}`, argsOf(prepared))).rows);
+		},
+		async close() {
+			await pool.end();
+		}
+	};
+}
+/**
+* A Postgres executor backed by a `pg` connection pool (placeholders: `$1`, `$2`, …). Feed it the
+* `{ sql, params }` a `PostgresQuery` builder emits.
+*/
+function createPostgresExecutor(config) {
+	return createPostgresExecutorFromPool(new pg.Pool(config));
+}
+//#endregion
+exports.createPostgresExecutor = createPostgresExecutor;
+exports.createPostgresExecutorFromPool = createPostgresExecutorFromPool;
+exports.parsePgPlan = parsePgPlan;
+
+//# sourceMappingURL=index.cjs.map

package/dist/postgres/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["Pool"],"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,IAAIA,GAAAA,KAAK,MAAM,CAAC;AACxD"}

package/dist/postgres/index.d.cts

@@ -0,0 +1,21 @@
+import { DbExecutor, ExplainEstimate } from "../index.cjs";
+import { Pool, PoolConfig } from "pg";
+//#region src/postgres/index.d.ts
+/** Connection settings — any `pg` `PoolConfig`. Set `statement_timeout` here if you want a
+ * per-connection ceiling; the engine imposes none of its own. */
+type PostgresConfig = PoolConfig;
+/** Parse `EXPLAIN (FORMAT JSON)` result rows into the normalized estimate. Exported for unit tests. */
+declare function parsePgPlan(rows: readonly unknown[]): ExplainEstimate;
+/**
+ * Build a Postgres executor over an EXISTING pool — bring your own `pg` Pool to share one pool
+ * across your app (or hand in a test double). {@link createPostgresExecutor} is the usual entry.
+ */
+declare function createPostgresExecutorFromPool(pool: Pool): DbExecutor;
+/**
+ * A Postgres executor backed by a `pg` connection pool (placeholders: `$1`, `$2`, …). Feed it the
+ * `{ sql, params }` a `PostgresQuery` builder emits.
+ */
+declare function createPostgresExecutor(config: PostgresConfig): DbExecutor;
+//#endregion
+export { PostgresConfig, createPostgresExecutor, createPostgresExecutorFromPool, parsePgPlan };
+//# sourceMappingURL=index.d.cts.map

package/dist/postgres/index.d.mts

@@ -0,0 +1,21 @@
+import { DbExecutor, ExplainEstimate } from "../index.mjs";
+import { Pool, PoolConfig } from "pg";
+//#region src/postgres/index.d.ts
+/** Connection settings — any `pg` `PoolConfig`. Set `statement_timeout` here if you want a
+ * per-connection ceiling; the engine imposes none of its own. */
+type PostgresConfig = PoolConfig;
+/** Parse `EXPLAIN (FORMAT JSON)` result rows into the normalized estimate. Exported for unit tests. */
+declare function parsePgPlan(rows: readonly unknown[]): ExplainEstimate;
+/**
+ * Build a Postgres executor over an EXISTING pool — bring your own `pg` Pool to share one pool
+ * across your app (or hand in a test double). {@link createPostgresExecutor} is the usual entry.
+ */
+declare function createPostgresExecutorFromPool(pool: Pool): DbExecutor;
+/**
+ * A Postgres executor backed by a `pg` connection pool (placeholders: `$1`, `$2`, …). Feed it the
+ * `{ sql, params }` a `PostgresQuery` builder emits.
+ */
+declare function createPostgresExecutor(config: PostgresConfig): DbExecutor;
+//#endregion
+export { PostgresConfig, createPostgresExecutor, createPostgresExecutorFromPool, parsePgPlan };
+//# sourceMappingURL=index.d.mts.map

package/dist/postgres/index.mjs

@@ -0,0 +1,61 @@
+import { Pool } from "pg";
+//#region src/postgres/index.ts
+/** Parse `EXPLAIN (FORMAT JSON)` result rows into the normalized estimate. Exported for unit tests. */
+function parsePgPlan(rows) {
+	const root = rows[0]?.["QUERY PLAN"]?.[0]?.Plan;
+	const seqScan = (n) => !!n && (n["Node Type"] === "Seq Scan" || (n.Plans ?? []).some(seqScan));
+	return {
+		cost: root?.["Total Cost"],
+		rows: root?.["Plan Rows"],
+		fullScan: seqScan(root),
+		plan: JSON.stringify(root ?? {}).slice(0, 500)
+	};
+}
+const argsOf = (prepared) => prepared.params ?? [];
+const toResult = (res) => ({
+	rows: res.rows,
+	rowCount: res.rowCount ?? res.rows.length
+});
+/**
+* Build a Postgres executor over an EXISTING pool — bring your own `pg` Pool to share one pool
+* across your app (or hand in a test double). {@link createPostgresExecutor} is the usual entry.
+*/
+function createPostgresExecutorFromPool(pool) {
+	return {
+		async run(prepared) {
+			return toResult(await pool.query(prepared.sql, argsOf(prepared)));
+		},
+		async transaction(statements) {
+			const client = await pool.connect();
+			try {
+				await client.query("BEGIN");
+				const results = [];
+				for (const s of statements) results.push(toResult(await client.query(s.sql, argsOf(s))));
+				await client.query("COMMIT");
+				return results;
+			} catch (err) {
+				await client.query("ROLLBACK").catch(() => {});
+				throw err;
+			} finally {
+				client.release();
+			}
+		},
+		async explain(prepared) {
+			return parsePgPlan((await pool.query(`EXPLAIN (FORMAT JSON) ${prepared.sql}`, argsOf(prepared))).rows);
+		},
+		async close() {
+			await pool.end();
+		}
+	};
+}
+/**
+* A Postgres executor backed by a `pg` connection pool (placeholders: `$1`, `$2`, …). Feed it the
+* `{ sql, params }` a `PostgresQuery` builder emits.
+*/
+function createPostgresExecutor(config) {
+	return createPostgresExecutorFromPool(new Pool(config));
+}
+//#endregion
+export { createPostgresExecutor, createPostgresExecutorFromPool, parsePgPlan };
+
+//# sourceMappingURL=index.mjs.map