@zerotal/orm 1.0.0

package/src/db/ReadWriteRouter.ts

@@ -0,0 +1,96 @@
+import type { SQLInstance } from "./sql-types.ts";
+/**
+ * Transparent read/write routing for Bun SQL connections.
+ *
+ * `createReadWriteRouter()` returns a `SQLInstance`-compatible proxy that:
+ *
+ * - Routes **SELECT / WITH / EXPLAIN / PRAGMA / SHOW / DESCRIBE** → round-robin replica pool.
+ * - Routes **everything else** (INSERT, UPDATE, DELETE, DDL, transactions) → primary.
+ * - Delegates `begin()` (transactions) exclusively to the primary.
+ * - Closes all unique connections on `end()`.
+ *
+ * The returned value is structurally identical to `SQLInstance`, so it is a
+ * drop-in replacement everywhere a connection is expected — `DB.table()`,
+ * `BaseModel`, and `DB.raw()` all route automatically with no code changes.
+ *
+ * @param primary  The writable primary/master connection.
+ * @param replicas One or more read-replica connections. Load-balanced round-robin.
+ *                 When empty, the primary is returned as-is (no overhead).
+ *
+ * @example
+ * const primary = new SQL(env('DATABASE_URL'));
+ * const replica = new SQL(env('REPLICA_URL'));
+ * const router  = createReadWriteRouter(primary, [replica]);
+ *
+ * // Drop-in: pass router wherever you'd pass a SQL connection
+ * DB.table('users')  // SELECT → replica, mutating → primary
+ */
+export function createReadWriteRouter(primary: SQLInstance, replicas: SQLInstance[]): SQLInstance {
+  if (replicas.length === 0) return primary;
+
+  let _rr = 0;
+  const pool = replicas;
+
+  const handler: ProxyHandler<object> = {
+    // Intercepts the tagged-template function call: conn`SELECT ...`
+    apply(_target, _thisArg, args: unknown[]) {
+      const tpl = args[0] as TemplateStringsArray;
+      // Join ALL template fragments — locking clauses (FOR UPDATE / FOR SHARE)
+      // appear at the END of a SELECT, typically after binding placeholders,
+      // so classifying on the first fragment alone would miss them.
+      const sql = Array.isArray(tpl) ? tpl.join(" ") : "";
+      const conn = _isReadQuery(sql) ? pool[_rr++ % pool.length]! : primary;
+      return (conn as unknown as (...a: unknown[]) => unknown)(...args);
+    },
+
+    get(_target, prop: string | symbol) {
+      // Transactions always run on the primary
+      if (prop === "begin") {
+        return (primary as unknown as Record<string | symbol, unknown>)["begin"];
+      }
+
+      // On shutdown, close all unique connections
+      if (prop === "end") {
+        const unique = [...new Set([primary, ...pool])];
+        return () => Promise.all(unique.map((c) => c.end())).then(() => undefined);
+      }
+
+      // Escape hatch used by DB.onPrimary() to extract the underlying primary
+      if (prop === "__primary__") return primary;
+
+      // Delegate all other property access to the primary
+      return (primary as unknown as Record<string | symbol, unknown>)[prop];
+    },
+  };
+
+  // The proxy target must be a function so the `apply` trap fires on calls
+  return new Proxy(primary as unknown as object, handler) as unknown as SQLInstance;
+}
+
+/**
+ * Returns `true` for queries that are safe to run on a read replica.
+ * Strips leading block comments (`/* ... *\/`) and line comments (`-- ...`)
+ * before testing so that annotated SQL is classified correctly.
+ *
+ * Locking reads (`SELECT … FOR UPDATE / FOR SHARE / LOCK IN SHARE MODE`)
+ * are classified as writes — a row lock taken on a replica is useless, so
+ * they must reach the primary even outside a transaction.
+ *
+ * Anything not matched here is treated as a write and routed to the primary.
+ */
+export function _isReadQuery(sql: string): boolean {
+  const stripped = sql
+    .replace(/\/\*[\s\S]*?\*\//g, "") // /* block comments */
+    .replace(/--[^\n]*/g, "") // -- line comments
+    .trimStart();
+  if (!/^(select|with\b|explain\b|pragma\b|show\b|describe\b)/i.test(stripped)) return false;
+  // Pessimistic-lock clauses defeat replication — route to the primary.
+  if (
+    /\bfor\s+(update|share|no\s+key\s+update|key\s+share)\b|\block\s+in\s+share\s+mode\b/i.test(
+      stripped,
+    )
+  ) {
+    return false;
+  }
+  return true;
+}

package/src/db/TransactionContext.ts

@@ -0,0 +1,13 @@
+import type { SQLInstance } from "./sql-types.ts";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * AsyncLocalStorage that carries the active transaction connection through
+ * the call stack. Set by DB.transaction(); read by BaseModel and DB helpers.
+ *
+ * This is the correct propagation mechanism for transactions that originate
+ * outside a request context (console commands, scheduled jobs, seeders).
+ * For request-scoped transactions, ctx._transaction is also set for legacy
+ * callers, but TransactionContext is the authoritative source.
+ */
+export const TransactionContext = new AsyncLocalStorage<SQLInstance>();

package/src/db/dialects/MysqlDialect.ts

@@ -0,0 +1,57 @@
+import type { DatePart, DialectQuery, SqlDialect } from "./types.ts";
+
+/**
+ * MySQL strategy — INFORMATION_SCHEMA introspection, DAY()/MONTH()/YEAR()
+ * date parts, GET_LOCK()/RELEASE_LOCK() named advisory locks.
+ */
+export class MysqlDialect implements SqlDialect {
+  readonly name = "mysql" as const;
+  readonly supportsAdvisoryLocks = true;
+
+  hasTableSql(table: string): DialectQuery {
+    return {
+      sql:
+        `SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES ` +
+        `WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?`,
+      params: [table],
+    };
+  }
+
+  hasColumnSql(table: string, column: string): DialectQuery {
+    return {
+      sql:
+        `SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS ` +
+        `WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
+      params: [table, column],
+    };
+  }
+
+  dateExpr(part: DatePart, column: string): string {
+    switch (part) {
+      case "date":
+        return `DATE(${column})`;
+      case "time":
+        return `TIME(${column})`;
+      case "day":
+        return `DAY(${column})`;
+      case "month":
+        return `MONTH(${column})`;
+      case "year":
+        return `YEAR(${column})`;
+    }
+  }
+
+  // MySQL advisory locks are named — the numeric key maps to a namespaced
+  // string. Timeout -1 blocks until acquired (matching pg_advisory_lock).
+  autoIncrementColumn(column: string): string {
+    return `${column} INT AUTO_INCREMENT PRIMARY KEY`;
+  }
+
+  advisoryLockSql(key: number): DialectQuery {
+    return { sql: `SELECT GET_LOCK(?, -1)`, params: [`zerotal_lock_${key}`] };
+  }
+
+  advisoryUnlockSql(key: number): DialectQuery {
+    return { sql: `SELECT RELEASE_LOCK(?)`, params: [`zerotal_lock_${key}`] };
+  }
+}

package/src/db/dialects/PostgresDialect.ts

@@ -0,0 +1,55 @@
+import type { DatePart, DialectQuery, SqlDialect } from "./types.ts";
+
+/**
+ * PostgreSQL strategy — information_schema introspection, EXTRACT()/casts for
+ * date parts, pg_advisory_lock for advisory locks.
+ */
+export class PostgresDialect implements SqlDialect {
+  readonly name = "postgres" as const;
+  readonly supportsAdvisoryLocks = true;
+
+  hasTableSql(table: string): DialectQuery {
+    return {
+      sql: `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_name = ?`,
+      params: [table],
+    };
+  }
+
+  hasColumnSql(table: string, column: string): DialectQuery {
+    return {
+      sql:
+        `SELECT column_name FROM information_schema.columns ` +
+        `WHERE table_schema = 'public' AND table_name = ? AND column_name = ?`,
+      params: [table, column],
+    };
+  }
+
+  dateExpr(part: DatePart, column: string): string {
+    switch (part) {
+      case "date":
+        return `CAST(${column} AS date)`;
+      case "time":
+        return `CAST(${column} AS time)`;
+      case "day":
+        return `CAST(EXTRACT(DAY FROM ${column}) AS integer)`;
+      case "month":
+        return `CAST(EXTRACT(MONTH FROM ${column}) AS integer)`;
+      case "year":
+        return `CAST(EXTRACT(YEAR FROM ${column}) AS integer)`;
+    }
+  }
+
+  autoIncrementColumn(column: string): string {
+    // GENERATED ALWAYS AS IDENTITY is the SQL-standard form serial has been soft-deprecated
+    // in favour of since PostgreSQL 10.
+    return `${column} INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY`;
+  }
+
+  advisoryLockSql(key: number): DialectQuery {
+    return { sql: `SELECT pg_advisory_lock(?)`, params: [key] };
+  }
+
+  advisoryUnlockSql(key: number): DialectQuery {
+    return { sql: `SELECT pg_advisory_unlock(?)`, params: [key] };
+  }
+}

package/src/db/dialects/SqliteDialect.ts

@@ -0,0 +1,54 @@
+import type { DatePart, DialectQuery, SqlDialect } from "./types.ts";
+
+/**
+ * SQLite strategy — sqlite_master / pragma_table_info introspection,
+ * strftime() date parts, no advisory-lock primitive.
+ */
+export class SqliteDialect implements SqlDialect {
+  readonly name = "sqlite" as const;
+  readonly supportsAdvisoryLocks = false;
+
+  hasTableSql(table: string): DialectQuery {
+    return {
+      sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`,
+      params: [table],
+    };
+  }
+
+  hasColumnSql(table: string, column: string): DialectQuery {
+    // pragma_table_info() is the table-valued form of PRAGMA table_info —
+    // unlike the PRAGMA it accepts bound parameters, so the table name never
+    // needs to be inlined into the SQL.
+    return {
+      sql: `SELECT name FROM pragma_table_info(?) WHERE name = ?`,
+      params: [table, column],
+    };
+  }
+
+  dateExpr(part: DatePart, column: string): string {
+    switch (part) {
+      case "date":
+        return `date(${column})`;
+      case "time":
+        return `time(${column})`;
+      case "day":
+        return `cast(strftime('%d', ${column}) as integer)`;
+      case "month":
+        return `cast(strftime('%m', ${column}) as integer)`;
+      case "year":
+        return `cast(strftime('%Y', ${column}) as integer)`;
+    }
+  }
+
+  autoIncrementColumn(column: string): string {
+    return `${column} INTEGER PRIMARY KEY AUTOINCREMENT`;
+  }
+
+  advisoryLockSql(): DialectQuery | null {
+    return null;
+  }
+
+  advisoryUnlockSql(): DialectQuery | null {
+    return null;
+  }
+}

package/src/db/dialects/index.ts

@@ -0,0 +1,25 @@
+import { SqliteDialect } from "./SqliteDialect.ts";
+import { PostgresDialect } from "./PostgresDialect.ts";
+import { MysqlDialect } from "./MysqlDialect.ts";
+import type { DialectName, SqlDialect } from "./types.ts";
+
+const _dialects: Record<DialectName, SqlDialect> = {
+  sqlite: new SqliteDialect(),
+  postgres: new PostgresDialect(),
+  mysql: new MysqlDialect(),
+};
+
+/**
+ * Resolve the SQL strategy object for a dialect name.
+ *
+ * @example
+ * getDialect(dialectFor(conn)).dateExpr('day', 'created_at')
+ */
+export function getDialect(name: DialectName): SqlDialect {
+  return _dialects[name];
+}
+
+export { SqliteDialect } from "./SqliteDialect.ts";
+export { PostgresDialect } from "./PostgresDialect.ts";
+export { MysqlDialect } from "./MysqlDialect.ts";
+export type { SqlDialect, DialectName, DialectQuery, DatePart } from "./types.ts";

package/src/db/dialects/types.ts

@@ -0,0 +1,67 @@
+// ── Dialect strategy contract ─────────────────────────────────────────────────
+//
+// The ORM is dialect-light, but a handful of SQL constructs genuinely differ
+// across engines: schema introspection (hasTable / hasColumn), date-part
+// extraction (strftime vs EXTRACT vs DAY()/MONTH()/YEAR()) and advisory locks.
+// Each engine implements this interface once; QueryBuilder, Schema and DB
+// consult the active dialect instead of hard-coding SQLite syntax behind the
+// multi-dialect facade.
+
+/** Supported database engines. Mirrors `Dialect` in QueryBuilder.ts. */
+export type DialectName = "sqlite" | "postgres" | "mysql";
+
+/** A parameterised statement: `sql` uses `?` placeholders bound from `params`. */
+export interface DialectQuery {
+  sql: string;
+  params: unknown[];
+}
+
+/** The date component extracted by whereDate/whereTime/whereDay/whereMonth/whereYear. */
+export type DatePart = "date" | "time" | "day" | "month" | "year";
+
+/**
+ * Per-engine SQL strategy.
+ *
+ * @example
+ * const d = getDialect("postgres");
+ * const { sql, params } = d.hasTableSql("users");
+ */
+export interface SqlDialect {
+  readonly name: DialectName;
+
+  /** Introspection query returning at least one row when `table` exists. */
+  hasTableSql(table: string): DialectQuery;
+
+  /** Introspection query returning at least one row when `column` exists on `table`. */
+  hasColumnSql(table: string, column: string): DialectQuery;
+
+  /**
+   * SQL expression extracting a date part from `column`.
+   * The caller must validate `column` as a safe identifier first — the
+   * expression is interpolated verbatim.
+   */
+  dateExpr(part: DatePart, column: string): string;
+
+  /**
+   * The column definition for an auto-incrementing integer primary key.
+   *
+   * Every engine spells this differently and none of them accept SQLite's
+   * `INTEGER PRIMARY KEY AUTOINCREMENT`: PostgreSQL wants a serial/identity type, MySQL
+   * wants `AUTO_INCREMENT`. Hard-coding the SQLite form meant the *first* `migrate` against
+   * PostgreSQL died on a syntax error and MySQL on error 1064 — before any of the
+   * dialect-aware `hasTable`/`ALTER` handling downstream got a chance to matter.
+   *
+   * @param column - Already-validated column name.
+   * @returns The full column fragment, type and constraints included.
+   */
+  autoIncrementColumn(column: string): string;
+
+  /** Whether the engine supports application-level advisory locks. */
+  readonly supportsAdvisoryLocks: boolean;
+
+  /** Statement acquiring an advisory lock (blocking), or null when unsupported. */
+  advisoryLockSql(key: number): DialectQuery | null;
+
+  /** Statement releasing an advisory lock, or null when unsupported. */
+  advisoryUnlockSql(key: number): DialectQuery | null;
+}

package/src/db/resolver.ts

@@ -0,0 +1,30 @@
+import type { SQLInstance } from "./sql-types.ts";
+
+/**
+ * Decouples the ORM from the DI container: a function that returns the active
+ * base connection (or `undefined` if none is registered yet).
+ */
+type ConnectionResolver = () => SQLInstance | undefined;
+
+let _resolver: ConnectionResolver | null = null;
+
+/**
+ * Register the callback used to look up the base connection from the container.
+ * Pass `null` to clear it. Set once by the `DatabaseProvider` at boot.
+ */
+export function setConnectionResolver(fn: ConnectionResolver | null): void {
+  _resolver = fn;
+}
+
+/**
+ * Resolve the container's base connection via the registered resolver, swallowing
+ * any resolver error. Returns `undefined` when no resolver is set or it fails.
+ */
+export function resolveContainerConnection(): SQLInstance | undefined {
+  if (!_resolver) return undefined;
+  try {
+    return _resolver();
+  } catch {
+    return undefined;
+  }
+}

package/src/db/sql-types.ts

@@ -0,0 +1,12 @@
+/**
+ * The shape of a Bun SQL connection as this ORM uses it: a callable tagged-template
+ * that runs a query, plus `begin()` for transactions and `end()` to close.
+ *
+ * Exported (rather than an ambient global) so consumers that pull this package's
+ * source into their type program resolve it through the import graph.
+ */
+export interface SQLInstance {
+  <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}