@mandujs/core 0.53.3 → 0.54.0

package/src/db/index.ts

@@ -115,7 +115,7 @@ export interface DbConfig {
  * returns the full result array. The attached methods support one-shot
  * reads, transactions, and shutdown.
  */
-export interface Db {
+export interface Db {
   /**
    * Tagged-template query. Values are bound as parameters, never
    * interpolated as SQL text.
@@ -158,17 +158,17 @@ export interface Db {
    * Closes the connection pool. Subsequent queries reject with a clear
    * "pool closed" error. Calling `close()` twice is a no-op (idempotent).
    */
-  close(options?: DbCloseOptions): Promise<void>;
-}
-
-/** Options forwarded to Bun.SQL pool shutdown. */
-export interface DbCloseOptions {
-  /**
-   * Maximum seconds to wait for in-flight queries before closing the pool.
-   * `0` asks Bun.SQL to close immediately.
-   */
-  timeout?: number;
-}
+  close(options?: DbCloseOptions): Promise<void>;
+}
+
+/** Options forwarded to Bun.SQL pool shutdown. */
+export interface DbCloseOptions {
+  /**
+   * Maximum seconds to wait for in-flight queries before closing the pool.
+   * `0` asks Bun.SQL to close immediately.
+   */
+  timeout?: number;
+}
 
 // ─── Bun runtime surface (structural; no `any`) ─────────────────────────────
 
@@ -190,14 +190,14 @@ interface BunSqlOptions {
  * A Bun.SQL instance — itself a callable tagged-template function with
  * methods attached. We only model the subset we actually use.
  */
-interface BunSqlInstance {
-  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<
-    T[] & { count?: number; command?: string }
-  >;
-  begin<R>(fn: (tx: BunSqlInstance) => Promise<R>): Promise<R>;
-  close(options?: DbCloseOptions): Promise<void>;
-  readonly options?: BunSqlOptions;
-}
+interface BunSqlInstance {
+  <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<
+    T[] & { count?: number; command?: string }
+  >;
+  begin<R>(fn: (tx: BunSqlInstance) => Promise<R>): Promise<R>;
+  close(options?: DbCloseOptions): Promise<void>;
+  readonly options?: BunSqlOptions;
+}
 
 /**
  * Constructor surface — `Bun.SQL` is a class; we only need the `new`
@@ -259,35 +259,35 @@ function getBunSqlCtor(): BunSqlCtor {
 
 // ─── Error helpers ──────────────────────────────────────────────────────────
 
-const POOL_CLOSED_MESSAGE =
-  "[@mandujs/core/db] pool closed — query issued after Db.close().";
-
-const PIN_DB_HANDLE = Symbol.for("@mandujs/core/db/pin-handle");
-
-interface DbHandlePin {
-  [PIN_DB_HANDLE]?: <R>(fn: () => Promise<R>) => Promise<R>;
-}
-
-/**
- * Internal helper for code paths that must keep a MySQL session alive across
- * transaction boundaries, such as named advisory locks. Public Db callers do
- * not need this; normal MySQL transactions recycle the handle afterwards.
- *
- * @internal
- */
-export async function withPinnedDbHandle<R>(
-  db: Db,
-  fn: () => Promise<R>,
-): Promise<R> {
-  const pin = (db as DbHandlePin)[PIN_DB_HANDLE];
-  if (!pin) return await fn();
-  return await pin(fn);
-}
-
-/**
- * Structural check for "connection/pool closed" errors that Bun.SQL raises
- * after `.close()`. Bun surfaces these as `SQLiteError` / `PostgresError` /
- * `MySQLError` with a `code` ending in `CLOSED`.
+const POOL_CLOSED_MESSAGE =
+  "[@mandujs/core/db] pool closed — query issued after Db.close().";
+
+const PIN_DB_HANDLE = Symbol.for("@mandujs/core/db/pin-handle");
+
+interface DbHandlePin {
+  [PIN_DB_HANDLE]?: <R>(fn: () => Promise<R>) => Promise<R>;
+}
+
+/**
+ * Internal helper for code paths that must keep a MySQL session alive across
+ * transaction boundaries, such as named advisory locks. Public Db callers do
+ * not need this; normal MySQL transactions recycle the handle afterwards.
+ *
+ * @internal
+ */
+export async function withPinnedDbHandle<R>(
+  db: Db,
+  fn: () => Promise<R>,
+): Promise<R> {
+  const pin = (db as DbHandlePin)[PIN_DB_HANDLE];
+  if (!pin) return await fn();
+  return await pin(fn);
+}
+
+/**
+ * Structural check for "connection/pool closed" errors that Bun.SQL raises
+ * after `.close()`. Bun surfaces these as `SQLiteError` / `PostgresError` /
+ * `MySQLError` with a `code` ending in `CLOSED`.
  */
 function isPoolClosedError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
@@ -458,14 +458,14 @@ function buildDbHandle(bunSql: BunSqlInstance, provider: SqlProvider): Db {
       });
     };
 
-  (db as { close: Db["close"] }).close = async function close(
-    options?: DbCloseOptions,
-  ): Promise<void> {
-    if (closed) return; // idempotent
-    closed = true;
-    try {
-      await bunSql.close(options);
-    } catch (err) {
+  (db as { close: Db["close"] }).close = async function close(
+    options?: DbCloseOptions,
+  ): Promise<void> {
+    if (closed) return; // idempotent
+    closed = true;
+    try {
+      await bunSql.close(options);
+    } catch (err) {
       // Bun.SQL can throw if already-closed under the hood (mostly from a
       // racing concurrent close). We already flipped our flag so subsequent
       // queries reject cleanly — swallow this one.
@@ -484,7 +484,7 @@ function buildDbHandle(bunSql: BunSqlInstance, provider: SqlProvider): Db {
  *
  * @throws {TypeError} when `config.url` is missing or empty.
  */
-export function createDb(config: DbConfig): Db {
+export function createDb(config: DbConfig): Db {
   // Up-front config validation. We check `url` here (not only in
   // `_createDbWith`) so the error fires at construction time — matches
   // the TypeError contract the public API documents.
@@ -502,43 +502,43 @@ export function createDb(config: DbConfig): Db {
   // fires on the first real call, with a version-specific message.
   //
   // We still need to *return* a Db now, so call through a forwarding
-  // function that probes on demand.
-  let real: Db | null = null;
-  let closed = false;
-  let pinDepth = 0;
-  let pendingMysqlRecycle = false;
-  function materialize(): Db {
-    if (closed) {
-      throw new Error(POOL_CLOSED_MESSAGE);
-    }
-    if (real) return real;
-    real = _createDbWith(getBunSqlCtor(), config);
-    return real;
-  }
-
-  async function flushPendingMysqlRecycle(): Promise<void> {
-    if (provider !== "mysql" || pinDepth > 0 || !pendingMysqlRecycle) return;
-    pendingMysqlRecycle = false;
-    if (closed || !real) return;
-    const db = real;
-    real = null;
-    await db.close({ timeout: 0 });
-  }
-
-  async function recycleMysqlHandle(db: Db): Promise<void> {
-    if (provider !== "mysql" || real !== db || closed) return;
-    if (pinDepth > 0) {
-      pendingMysqlRecycle = true;
-      return;
-    }
-    real = null;
-    await db.close({ timeout: 0 });
-  }
-
-  const forward = async function forwardCall<T extends Row = Row>(
-    strings: TemplateStringsArray,
-    ...values: unknown[]
-  ): Promise<T[]> {
+  // function that probes on demand.
+  let real: Db | null = null;
+  let closed = false;
+  let pinDepth = 0;
+  let pendingMysqlRecycle = false;
+  function materialize(): Db {
+    if (closed) {
+      throw new Error(POOL_CLOSED_MESSAGE);
+    }
+    if (real) return real;
+    real = _createDbWith(getBunSqlCtor(), config);
+    return real;
+  }
+
+  async function flushPendingMysqlRecycle(): Promise<void> {
+    if (provider !== "mysql" || pinDepth > 0 || !pendingMysqlRecycle) return;
+    pendingMysqlRecycle = false;
+    if (closed || !real) return;
+    const db = real;
+    real = null;
+    await db.close({ timeout: 0 });
+  }
+
+  async function recycleMysqlHandle(db: Db): Promise<void> {
+    if (provider !== "mysql" || real !== db || closed) return;
+    if (pinDepth > 0) {
+      pendingMysqlRecycle = true;
+      return;
+    }
+    real = null;
+    await db.close({ timeout: 0 });
+  }
+
+  const forward = async function forwardCall<T extends Row = Row>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]> {
     return await materialize()<T>(strings, ...values);
   } as unknown as Db;
 
@@ -555,46 +555,46 @@ export function createDb(config: DbConfig): Db {
     ...values: unknown[]
   ): Promise<T | null> {
     return await materialize().one<T>(strings, ...values);
-  };
-  (forward as { transaction: Db["transaction"] }).transaction =
-    async function transaction<R>(fn: (tx: Db) => Promise<R>): Promise<R> {
-      const hadMaterializedHandle = real !== null;
-      let db = materialize();
-      if (provider === "mysql" && hadMaterializedHandle) {
-        await recycleMysqlHandle(db);
-        db = materialize();
-      }
-      try {
-        return await db.transaction(fn);
-      } finally {
-        await recycleMysqlHandle(db);
-      }
-    };
-  (forward as { close: Db["close"] }).close = async function close(
-    options?: DbCloseOptions,
-  ): Promise<void> {
-    if (closed) return;
-    closed = true;
-    // If no query ever ran, materialize() was never called — nothing to close.
-    if (!real) return;
-    const db = real;
-    real = null;
-    await db.close(options);
-  };
-  Object.defineProperty(forward, PIN_DB_HANDLE, {
-    value: async function withPinnedHandle<R>(fn: () => Promise<R>): Promise<R> {
-      pinDepth += 1;
-      try {
-        return await fn();
-      } finally {
-        pinDepth -= 1;
-        await flushPendingMysqlRecycle();
-      }
-    },
-    enumerable: false,
-    writable: false,
-    configurable: false,
-  });
-
-  return forward;
-}
+  };
+  (forward as { transaction: Db["transaction"] }).transaction =
+    async function transaction<R>(fn: (tx: Db) => Promise<R>): Promise<R> {
+      const hadMaterializedHandle = real !== null;
+      let db = materialize();
+      if (provider === "mysql" && hadMaterializedHandle) {
+        await recycleMysqlHandle(db);
+        db = materialize();
+      }
+      try {
+        return await db.transaction(fn);
+      } finally {
+        await recycleMysqlHandle(db);
+      }
+    };
+  (forward as { close: Db["close"] }).close = async function close(
+    options?: DbCloseOptions,
+  ): Promise<void> {
+    if (closed) return;
+    closed = true;
+    // If no query ever ran, materialize() was never called — nothing to close.
+    if (!real) return;
+    const db = real;
+    real = null;
+    await db.close(options);
+  };
+  Object.defineProperty(forward, PIN_DB_HANDLE, {
+    value: async function withPinnedHandle<R>(fn: () => Promise<R>): Promise<R> {
+      pinDepth += 1;
+      try {
+        return await fn();
+      } finally {
+        pinDepth -= 1;
+        await flushPendingMysqlRecycle();
+      }
+    },
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+
+  return forward;
+}