@mandujs/core 0.53.0 → 0.53.2

package/src/content/loaders/glob.ts

@@ -12,9 +12,9 @@
 
 import type { Loader, GlobLoaderOptions, ParsedMarkdown } from "./types";
 import type { LoaderContext, DataEntry } from "../types";
-import { LoaderError, ParseError } from "../types";
+import { ParseError } from "../types";
 import { generateFileDigest, combineDigests } from "../digest";
-import { inferParser, MARKDOWN_EXTENSIONS } from "./types";
+import { inferParser } from "./types";
 import * as fs from "fs";
 import * as path from "path";
 
@@ -108,7 +108,7 @@ export function glob(options: GlobLoaderOptions): Loader {
     name: "glob",
 
     async load(context: LoaderContext): Promise<void> {
-      const { store, config, logger, parseData, renderMarkdown, watcher } = context;
+      const { store, config, logger, parseData: _parseData, renderMarkdown: _renderMarkdown, watcher } = context;
 
       // 기본 디렉토리
       const baseDir = base
@@ -181,7 +181,7 @@ async function processFile(
   context: LoaderContext,
   filePath: string,
   id: string,
-  baseDir: string
+  _baseDir: string
 ): Promise<void> {
   const { store, parseData, renderMarkdown, logger } = context;
 

package/src/content/loaders/types.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ZodSchema } from "zod";
-import type { LoaderContext, DataEntry, RenderedContent } from "../types";
+import type { LoaderContext, RenderedContent } from "../types";
 
 /**
  * 로더 인터페이스

package/src/content/meta-store.ts

@@ -102,7 +102,7 @@ export class ContentMetaStore {
    */
   private autoSave(): void {
     if (this.options.autoSave && this.options.filePath) {
-      this.save();
+      void this.save();
     }
   }
 

package/src/content/types.ts

@@ -110,7 +110,7 @@ export interface LoaderContext {
 /**
  * parseData 옵션
  */
-export interface ParseDataOptions<T> {
+export interface ParseDataOptions<_T> {
   /** 엔트리 ID */
   id: string;
   /** 원본 데이터 */

package/src/contract/define.ts

@@ -27,16 +27,15 @@
  * ```
  */
 
-import { z, type ZodType, type ZodObject, type ZodRawShape } from 'zod';
-import {
-  getZodTypeName,
-  getZodInnerType,
-  getZodArrayElementType,
-  getZodObjectShape,
-  getZodEnumValues,
-  getZodChecks,
-  isZodRequired,
-} from './zod-utils';
+import type { ZodType } from 'zod';
+import {
+  getZodTypeName,
+  getZodInnerType,
+  getZodArrayElementType,
+  getZodObjectShape,
+  getZodEnumValues,
+  isZodRequired,
+} from './zod-utils';
 
 // ============================================================================
 // Types
@@ -167,7 +166,7 @@ export function generateApiHandler<T extends ContractDefinition>(
     throw new Error(`Endpoint "${String(endpointName)}" not found in contract`);
   }
 
-  const { method, path, input, output, description } = endpoint;
+  const { method, path, input, description } = endpoint;
 
   return `
 import { Mandu } from '@mandujs/core';
@@ -345,7 +344,7 @@ export function generateOpenAPISpec<T extends ContractDefinition>(
   const paths: Record<string, Record<string, unknown>> = {};
 
   for (const [name, endpoint] of Object.entries(contract.__endpoints)) {
-    const { method, path, input, output, description, tags, errors } = endpoint;
+    const { method, path, input, description, tags, errors } = endpoint;
 
     if (!paths[path]) {
       paths[path] = {};

package/src/contract/index.ts

@@ -37,10 +37,10 @@ export {
   type RpcWireError,
 } from "./rpc";
 
-import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
-import type { ContractHandlers, RouteDefinition } from "./handler";
+import type { ContractDefinition, ContractInstance } from "./schema";
+
 import { defineHandler, defineRoute } from "./handler";
-import { createClient, contractFetch, type ClientOptions } from "./client";
+import { createClient, contractFetch } from "./client";
 import { createClientContract } from "./client-safe";
 
 /**

package/src/contract/protection.ts

@@ -102,7 +102,7 @@ export function extractProtectedFields(
       }
       // 민감 필드도 보호 대상
       else if (isSensitiveField(value)) {
-        const meta = getMetadata(value, SENSITIVE_FIELD) as SensitiveFieldMetadata | undefined;
+        const _meta = getMetadata(value, SENSITIVE_FIELD) as SensitiveFieldMetadata | undefined;
         fields.push({
           path: currentPath,
           reason: "Sensitive field - redacted in logs",
@@ -187,7 +187,7 @@ export function extractContractProtectedFields(
 /**
  * 객체에서 경로로 값 가져오기
  */
-function getValueByPath(obj: unknown, path: string): unknown {
+function _getValueByPath(obj: unknown, path: string): unknown {
   const parts = path.split(".");
   let current: unknown = obj;
 

package/src/contract/types.ts

@@ -14,7 +14,7 @@ import type {
 /**
  * Extract inferred type from Zod schema
  */
-type InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+type _InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
 
 /**
  * Extract inferred type from response schema (supports ResponseSchemaWithExamples)

package/src/contract/validator.ts

@@ -19,7 +19,6 @@ import type {
   ContractValidationError,
   ContractValidationIssue,
   MethodRequestSchema,
-  ContractNormalizeMode,
   ResponseSchemaWithExamples,
 } from "./schema";
 import {

package/src/db/__tests__/db.test.ts

@@ -107,13 +107,10 @@ function createFakeCtor(): { Ctor: BunSqlCtor; state: FakeState } {
     return Object.assign(call, methods);
   }
 
-  class FakeBunSql {
-    constructor(config: Record<string, unknown>) {
-      state.ctorCalls.push(config);
-      // Return the callable instance — NOT a class instance. Returning a
-      // non-this value from a constructor replaces the default return.
-      return makeFakeSqlInstance(false) as FakeBunSql;
-    }
+  function FakeBunSql(config: Record<string, unknown>) {
+    state.ctorCalls.push(config);
+    // Return the callable instance — NOT the default constructed object.
+    return makeFakeSqlInstance(false);
   }
 
   return {

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,8 +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(): Promise<void>;
-}
+  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`) ─────────────────────────────
 
@@ -181,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(): 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`
@@ -250,13 +259,35 @@ function getBunSqlCtor(): BunSqlCtor {
 
 // ─── Error helpers ──────────────────────────────────────────────────────────
 
-const POOL_CLOSED_MESSAGE =
-  "[@mandujs/core/db] pool closed — query issued after Db.close().";
-
-/**
- * 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;
@@ -427,12 +458,14 @@ function buildDbHandle(bunSql: BunSqlInstance, provider: SqlProvider): Db {
       });
     };
 
-  (db as { close: Db["close"] }).close = async function close(): Promise<void> {
-    if (closed) return; // idempotent
-    closed = true;
-    try {
-      await bunSql.close();
-    } 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.
@@ -451,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.
@@ -469,18 +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;
-  function materialize(): Db {
-    if (real) return real;
-    real = _createDbWith(getBunSqlCtor(), config);
-    return real;
-  }
-
-  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;
 
@@ -497,17 +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> {
-      return await materialize().transaction(fn);
-    };
-  (forward as { close: Db["close"] }).close = async function close(): Promise<void> {
-    // If no query ever ran, materialize() was never called — nothing to
-    // close. Only materialize + close if a real handle exists.
-    if (!real) return;
-    await real.close();
-  };
-
-  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;
+}

package/src/db/migrations/index.ts

@@ -0,0 +1,3 @@
+export * from "./history-table";
+export * from "./lock";
+export * from "./runner";

package/src/db/migrations/lock.ts

@@ -102,11 +102,11 @@ async function acquirePgAdvisoryLock(
   // hash-function reproduction.
   await db`SELECT pg_advisory_lock(hashtext(${lockId})::bigint)`;
 
-  let released = false;
+  let _released = false;
   return {
     async release(): Promise<void> {
-      if (released) return;
-      released = true;
+      if (_released) return;
+      _released = true;
       try {
         await db`SELECT pg_advisory_unlock(hashtext(${lockId})::bigint)`;
       } catch (err) {
@@ -126,6 +126,7 @@ async function acquireMysqlLock(
   db: Db,
   lockId: string,
 ): Promise<MigrationLock> {
+  const processLock = await acquireMysqlProcessMutex(lockId);
   // `GET_LOCK` returns:
   //   1 — lock granted
   //   0 — timeout (still blocked after the timeout)
@@ -133,25 +134,30 @@ async function acquireMysqlLock(
   //
   // Bun.SQL returns the single row as `[{ acquired: 1 }]`; we destructure
   // defensively to handle any driver-side aliasing.
-  const timeoutSec = MYSQL_LOCK_TIMEOUT_SECONDS;
-  const rows = await db<{ acquired: number | bigint | null }>`
-    SELECT GET_LOCK(${lockId}, ${timeoutSec}) AS acquired
-  `;
-  const first = rows[0];
-  const value = first ? Number(first.acquired) : NaN;
-  if (value !== 1) {
-    throw new Error(
-      `[@mandujs/core/db/migrations] GET_LOCK(${JSON.stringify(lockId)}, ${timeoutSec}) ` +
-        `returned ${value === 0 ? "0 (timeout)" : "NULL (error)"}; ` +
-        `another migration runner may be holding the lock.`,
-    );
+  try {
+    const timeoutSec = MYSQL_LOCK_TIMEOUT_SECONDS;
+    const rows = await db<{ acquired: number | bigint | null }>`
+      SELECT GET_LOCK(${lockId}, ${timeoutSec}) AS acquired
+    `;
+    const first = rows[0];
+    const value = first ? Number(first.acquired) : NaN;
+    if (value !== 1) {
+      throw new Error(
+        `[@mandujs/core/db/migrations] GET_LOCK(${JSON.stringify(lockId)}, ${timeoutSec}) ` +
+          `returned ${value === 0 ? "0 (timeout)" : "NULL (error)"}; ` +
+          `another migration runner may be holding the lock.`,
+      );
+    }
+  } catch (err) {
+    await processLock.release();
+    throw err;
   }
 
-  let released = false;
+  let _released = false;
   return {
     async release(): Promise<void> {
-      if (released) return;
-      released = true;
+      if (_released) return;
+      _released = true;
       try {
         await db`SELECT RELEASE_LOCK(${lockId})`;
       } catch (err) {
@@ -159,6 +165,55 @@ async function acquireMysqlLock(
         console.warn(
           `[@mandujs/core/db/migrations] RELEASE_LOCK failed: ${msg}`,
         );
+      } finally {
+        await processLock.release();
+      }
+    },
+  };
+}
+
+/**
+ * Same-process MySQL runners are serialised before hitting GET_LOCK.
+ * Cross-process safety still comes from MySQL's named lock; this mutex only
+ * avoids concurrent GET_LOCK calls from separate Bun.SQL pools in one runtime.
+ */
+const MYSQL_LOCK_REGISTRY_SYMBOL = Symbol.for(
+  "@mandujs/core/db/migrations/mysql-locks",
+);
+interface MysqlLockRegistry {
+  chains: Map<string, Promise<void>>;
+}
+function getMysqlLockRegistry(): MysqlLockRegistry {
+  const g = globalThis as unknown as Record<symbol, unknown>;
+  let reg = g[MYSQL_LOCK_REGISTRY_SYMBOL] as MysqlLockRegistry | undefined;
+  if (!reg) {
+    reg = { chains: new Map() };
+    g[MYSQL_LOCK_REGISTRY_SYMBOL] = reg;
+  }
+  return reg;
+}
+
+async function acquireMysqlProcessMutex(lockId: string): Promise<MigrationLock> {
+  const registry = getMysqlLockRegistry();
+  const previous = registry.chains.get(lockId) ?? Promise.resolve();
+
+  let release!: () => void;
+  const nextPromise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const tail = previous.then(() => nextPromise);
+  registry.chains.set(lockId, tail);
+
+  await previous;
+
+  let _released = false;
+  return {
+    async release(): Promise<void> {
+      if (_released) return;
+      _released = true;
+      release();
+      if (registry.chains.get(lockId) === tail) {
+        registry.chains.delete(lockId);
       }
     },
   };
@@ -229,11 +284,11 @@ async function acquireSqliteImmediate(
   // Wait for the previous holder to release.
   await previous;
 
-  let released = false;
+  let _released = false;
   return {
     async release(): Promise<void> {
-      if (released) return;
-      released = true;
+      if (_released) return;
+      _released = true;
       release();
       // If no one queued behind us, drop the entry so the registry
       // doesn't grow unbounded across many apply() cycles.
@@ -245,10 +300,10 @@ async function acquireSqliteImmediate(
 }
 
 function makeNoopLock(): MigrationLock {
-  let released = false;
+  let _released = false;
   return {
     async release(): Promise<void> {
-      released = true;
+      _released = true;
     },
   };
 }