@zerotal/orm 1.0.0

package/src/model/relations/RelationRegistry.ts

@@ -0,0 +1,184 @@
+/** Discriminator for every relation kind the ORM supports. */
+export type RelationType =
+  | "hasMany"
+  | "belongsTo"
+  | "hasOne"
+  | "manyToMany"
+  | "morphTo"
+  | "morphMany"
+  | "morphOne"
+  | "hasManyThrough"
+  | "hasOneThrough"
+  | "morphToMany"
+  | "morphedByMany";
+
+/**
+ * Normalized descriptor for a single relation, produced by a relation decorator
+ * and stored in the {@link relationRegistry}. The {@link ModelQueryBuilder} reads
+ * it to build eager-load, existence and aggregate queries. Which fields are
+ * meaningful depends on {@link RelationMetadata.type | type} (see the per-field
+ * notes below).
+ */
+export interface RelationMetadata {
+  type: RelationType;
+  related: () => unknown;
+  foreignKey: string;
+  localKey: string;
+  /** manyToMany only */
+  pivotTable?: string;
+  /** manyToMany only */
+  pivotForeignKey?: string;
+  /** manyToMany only */
+  pivotRelatedKey?: string;
+  /** morphTo only: maps type discriminator string → model factory */
+  morphMap?: Record<string, () => unknown>;
+  /** morphMany / morphOne / morphTo: the _type column name (e.g. "commentable_type") */
+  morphTypeColumn?: string;
+
+  // ── has*Through ─────────────────────────────────────────────────────────────
+  /** Intermediate ("through") model factory. */
+  through?: () => unknown;
+  /** FK on the through table pointing back to the parent (e.g. country_id on users). */
+  firstKey?: string;
+  /** FK on the related table pointing to the through model (e.g. user_id on posts). */
+  secondKey?: string;
+  /** Local key on the through model the related FK references. Defaults to 'id'. */
+  throughLocalKey?: string;
+
+  // ── manyToMany / morphToMany pivot enrichment ───────────────────────────────
+  /** Extra pivot columns to hydrate onto each related model's `pivot` bag. */
+  pivotColumns?: string[];
+  /** Maintain created_at / updated_at on the pivot table during attach/sync. */
+  pivotTimestamps?: boolean;
+  /** Constant pivot constraints applied to loads and writes: [column, value][]. */
+  pivotWheres?: Array<[string, unknown]>;
+  /** morphToMany / morphedByMany: the pivot _type column name. */
+  pivotMorphType?: string;
+  /** morphToMany / morphedByMany: the _type value stored for this side. */
+  pivotMorphValue?: string;
+
+  // ── belongsTo ───────────────────────────────────────────────────────────────
+  /** belongsTo withDefault: true, an attributes object, or a builder callback. */
+  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void);
+}
+
+/** Alias for RelationMetadata — preferred name going forward. */
+export type RelationDefinition = RelationMetadata;
+
+/**
+ * Global registry of relation metadata, keyed by model constructor then by
+ * relation (property) name. Populated by the relation decorators at class-definition
+ * time and consulted by {@link ModelQueryBuilder} when resolving a relation.
+ */
+export const relationRegistry = new Map<Function, Map<string, RelationMetadata>>();
+
+// ── Pivot collection ─────────────────────────────────────────────────────────
+
+/**
+ * Return type for manyToMany relation properties. Extends Array<T> so every
+ * array operation (map, filter, for-of, spread, destructuring) works without
+ * casting, while adding fully-typed pivot manipulation methods.
+ *
+ * On an unloaded model the pivot methods (attach / detach / sync / toggle)
+ * still function — they hit the DB directly using the parent's primary key.
+ * Array access on an unloaded relation throws RelationNotLoadedError.
+ */
+export interface ManyToMany<T> extends Array<T> {
+  /** Insert pivot rows linking the parent to the given related id(s). Ignores duplicates. */
+  attach(id: number | number[], pivotData?: Record<string, unknown>): Promise<void>;
+  /** Remove pivot rows for the given related id(s), or all rows if omitted. */
+  detach(id?: number | number[]): Promise<void>;
+  /** Replace all pivot rows with exactly the given related ids. */
+  sync(ids: number[]): Promise<void>;
+  /** Attach ids that are missing; detach ids that already exist. */
+  toggle(id: number | number[]): Promise<void>;
+  /** Attach ids without detaching existing ones (no duplicates created). */
+  syncWithoutDetaching(ids: number[]): Promise<void>;
+  /** Update extra pivot columns on an existing pivot row. */
+  updateExistingPivot(id: number, pivotData: Record<string, unknown>): Promise<void>;
+}
+
+// ── Relation marker types (used as property annotations: `posts!: HasMany<Post>`) ─
+
+export declare const __relation__: unique symbol;
+
+/**
+ * Property annotation for a {@link hasMany} relation. A phantom marker: once the
+ * relation is eager-loaded (via `.with()`), {@link WithLoaded} resolves the
+ * property to a concrete `T[]`.
+ */
+export interface HasMany<T> {
+  [__relation__]: "hasMany";
+  __type__: T;
+}
+
+/**
+ * Property annotation for a {@link belongsTo} relation. A phantom marker resolved
+ * by {@link WithLoaded} to `T | null` once eager-loaded.
+ */
+export interface BelongsTo<T> {
+  [__relation__]: "belongsTo";
+  __type__: T;
+}
+
+/**
+ * Property annotation for a {@link hasOne} relation. A phantom marker resolved by
+ * {@link WithLoaded} to `T | null` once eager-loaded.
+ */
+export interface HasOne<T> {
+  [__relation__]: "hasOne";
+  __type__: T;
+}
+
+/**
+ * Property annotation for a {@link morphTo} (inverse polymorphic) relation. A
+ * phantom marker resolved by {@link WithLoaded} to `T | null` once eager-loaded.
+ */
+export interface MorphTo<T> {
+  [__relation__]: "morphTo";
+  __type__: T;
+}
+
+/**
+ * Property annotation for a {@link morphMany} (polymorphic one-to-many) relation.
+ * A phantom marker resolved by {@link WithLoaded} to `T[]` once eager-loaded.
+ */
+export interface MorphMany<T> {
+  [__relation__]: "morphMany";
+  __type__: T;
+}
+
+/**
+ * Property annotation for a {@link morphOne} (polymorphic one-to-one) relation. A
+ * phantom marker resolved by {@link WithLoaded} to `T | null` once eager-loaded.
+ */
+export interface MorphOne<T> {
+  [__relation__]: "morphOne";
+  __type__: T;
+}
+
+// ── WithLoaded ───────────────────────────────────────────────────────────────
+
+/**
+ * Narrows the model type M after calling .with(relation).
+ * ManyToMany<T> is preserved as-is (keeps pivot methods).
+ * Phantom types HasMany/BelongsTo/HasOne are resolved to their concrete forms.
+ * Concrete types (e.g. User, Comment[]) are passed through unchanged.
+ */
+export type WithLoaded<M, R extends keyof M> = Omit<M, R> & {
+  [K in R]: M[K] extends ManyToMany<infer T>
+    ? ManyToMany<T>
+    : M[K] extends HasMany<infer T>
+      ? T[]
+      : M[K] extends BelongsTo<infer T>
+        ? T | null
+        : M[K] extends HasOne<infer T>
+          ? T | null
+          : M[K] extends MorphTo<infer T>
+            ? T | null
+            : M[K] extends MorphMany<infer T>
+              ? T[]
+              : M[K] extends MorphOne<infer T>
+                ? T | null
+                : M[K];
+};

package/src/observability.ts

@@ -0,0 +1,210 @@
+/**
+ * ORM → observer bridges. The ORM emits its own framework events (query, N+1,
+ * transaction, migration, model-change) on the core `FrameworkEvents` bus; this
+ * module forwards them to whichever observer packages are installed.
+ *
+ * Each observer's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, so the ORM depends on none of the
+ * observer packages — installing or removing an observer requires no change here.
+ * When an observer is not installed its binding is absent and its wiring is skipped.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import {
+  QueryExecuted,
+  NPlusOneDetected,
+  ModelChanged,
+  TransactionCommitted,
+  TransactionRolledBack,
+  MigrationRan,
+} from "./events.ts";
+
+/** The subset of the telemetry tracer this bridge calls (bound as `telemetry`). */
+interface TelemetrySink {
+  recordCompleted(
+    name: string,
+    durationMs: number,
+    options?: {
+      kind?: "internal" | "server" | "client" | "producer" | "consumer";
+      attributes?: Record<string, string | number | boolean>;
+      status?: "ok" | "error";
+      errorMessage?: string;
+    },
+  ): unknown;
+}
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordQuery(q: { sql: string; ms: number }): void;
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+  bufferQuery(ctx: object, q: { ms: number; sql: string }): void;
+  markNPlus(ctx: object): void;
+}
+
+/** The subset of the devtools trace sink this bridge calls (bound as `devtools.trace`). */
+interface DevtoolsSink {
+  bufferQuery(
+    ctx: object,
+    q: { sql: string; bindings: unknown[]; startMs: number; durationMs: number; rowCount: number },
+  ): void;
+  bufferWarning(ctx: object, w: { sql: string; count: number }): void;
+}
+
+/** The subset of the logger this bridge calls (bound as `log`). */
+interface LogSink {
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+}
+
+/** Matched-route template (else raw path) from an HttpContext, for event routes. */
+function _ctxPath(ctx: object): string {
+  const c = ctx as { _routeDef?: { pattern?: string }; url?: { pathname?: string } };
+  return c._routeDef?.pattern ?? c.url?.pathname ?? "/";
+}
+
+/**
+ * Subscribe the ORM's events to every installed observer. Returns a disposer that
+ * removes every subscription; call it from the ORM provider's `onStopping()`.
+ */
+export function installOrmObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+
+  const tracer = app.container.tryMake("telemetry" as never) as TelemetrySink | undefined;
+  if (tracer) {
+    unsubs.push(
+      FrameworkEvents.on(QueryExecuted, (e) => {
+        void tracer.recordCompleted("db.query", e.durationMs, {
+          kind: "client",
+          attributes: { "db.statement": e.sql, "db.rows": e.rowCount },
+        });
+      }),
+    );
+  }
+
+  const store = app.container.tryMake("monitor.store" as never) as MonitorSink | undefined;
+  if (store) {
+    unsubs.push(
+      // Slow-query aggregates + the per-request query buffer, correlated by ctx.
+      FrameworkEvents.on(QueryExecuted, (e) => {
+        store.recordQuery({ sql: e.sql, ms: e.durationMs });
+        if (e.ctx) store.bufferQuery(e.ctx, { ms: Math.round(e.durationMs), sql: e.sql });
+      }),
+      FrameworkEvents.on(NPlusOneDetected, (e) => {
+        if (e.ctx) store.markNPlus(e.ctx);
+        store.recordEvent({
+          kind: "nplus",
+          label: e.fingerprint.replace(/\x00/g, "?"),
+          status: "warn",
+          route: e.ctx ? _ctxPath(e.ctx) : null,
+          data: { count: e.count },
+        });
+      }),
+      FrameworkEvents.on(ModelChanged, (e) =>
+        store.recordEvent({
+          kind: "model",
+          label: e.model,
+          status: "info",
+          route: e.operation,
+          data: { table: e.table, op: e.operation },
+        }),
+      ),
+      FrameworkEvents.on(TransactionCommitted, (e) =>
+        store.recordEvent({
+          kind: "tx",
+          label: "committed",
+          status: "ok",
+          route: null,
+          data: { ms: e.durationMs },
+        }),
+      ),
+      FrameworkEvents.on(TransactionRolledBack, (e) =>
+        store.recordEvent({
+          kind: "tx",
+          label: "rolledback",
+          status: "warn",
+          route: null,
+          data: { ms: e.durationMs, detail: e.reason ?? "" },
+        }),
+      ),
+      FrameworkEvents.on(MigrationRan, (e) =>
+        store.recordEvent({
+          kind: "migration",
+          label: e.name,
+          status: e.ok ? "ok" : "bad",
+          route: e.direction,
+          data: { direction: e.direction, ms: e.durationMs, detail: e.error ?? "" },
+        }),
+      ),
+    );
+  }
+
+  const trace = app.container.tryMake("devtools.trace" as never) as DevtoolsSink | undefined;
+  if (trace) {
+    unsubs.push(
+      // Buffer each query/warning against its request context for the request trace.
+      FrameworkEvents.on(QueryExecuted, (e) => {
+        if (!e.ctx) return;
+        trace.bufferQuery(e.ctx, {
+          sql: e.sql,
+          bindings: e.bindings,
+          startMs: e.startMs,
+          durationMs: e.durationMs,
+          rowCount: e.rowCount,
+        });
+      }),
+      FrameworkEvents.on(NPlusOneDetected, (e) => {
+        if (!e.ctx) return;
+        trace.bufferWarning(e.ctx, { sql: e.fingerprint.replace(/\x00/g, "?"), count: e.count });
+      }),
+    );
+  }
+
+  const log = app.container.tryMake("log" as never) as LogSink | undefined;
+  if (log) {
+    const cfg = app.container.tryMake("config");
+    const slowMs = cfg?.get<number>("logging.slowQueryMs") ?? 1000;
+    unsubs.push(
+      FrameworkEvents.on(QueryExecuted, (e) => {
+        if (e.durationMs >= slowMs) {
+          log.warn("Slow query", { sql: e.sql, durationMs: e.durationMs, rowCount: e.rowCount });
+        }
+      }),
+      FrameworkEvents.on(NPlusOneDetected, (e) =>
+        log.warn("N+1 query detected", { fingerprint: e.fingerprint, count: e.count }),
+      ),
+      FrameworkEvents.on(TransactionRolledBack, (e) =>
+        log.warn("Transaction rolled back", {
+          txId: e.txId,
+          durationMs: e.durationMs,
+          reason: e.reason,
+        }),
+      ),
+      FrameworkEvents.on(MigrationRan, (e) => {
+        if (e.ok) {
+          log.info("Migration ran", {
+            name: e.name,
+            direction: e.direction,
+            durationMs: e.durationMs,
+          });
+        } else {
+          log.error(
+            "Migration failed",
+            { name: e.name, direction: e.direction, durationMs: e.durationMs },
+            new Error(e.error),
+          );
+        }
+      }),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/provider/DatabaseProvider.ts

@@ -0,0 +1,266 @@
+import type { SQLInstance } from "../db/sql-types.ts";
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { SQL } from "bun";
+import { DB, _getConnection } from "../db/DB.ts";
+import { preventNPlusOne } from "../db/NPlusOneDetector.ts";
+import {
+  _setBaseModelConnection,
+  _setBaseModelDialect,
+  _setModelEventDispatcher,
+} from "../model/BaseModel.ts";
+import { setConnectionResolver } from "../db/resolver.ts";
+import { createReadWriteRouter } from "../db/ReadWriteRouter.ts";
+import { ormConcerns } from "../conventions.ts";
+import { validateDatabaseConfig } from "../config.ts";
+import { autoMigrateConcern } from "../schema/autoMigrate.ts";
+import { registerImplicitBinding } from "../implicitBinding.ts";
+import { installOrmObservability } from "../observability.ts";
+
+// Extend the core container registry so 'db' is a typed binding.
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    db: SQLInstance;
+  }
+}
+
+/**
+ * Service provider that wires the ORM into a Zerotal application.
+ *
+ * @remarks
+ * Register this provider to get: the `db` container binding (a `Bun.sql`
+ * connection, optionally wrapped in a read/write router when `database.replicas`
+ * is set), convention auto-discovery of `app/models` and `app/observers`,
+ * auto-migration, implicit route-model binding, N+1 detection outside production,
+ * validator `unique`/`exists` rule wiring, and the `migrate` / `make:*` / `db:seed`
+ * CLI commands. The connection URL, pool, replicas, and dialect are read from the
+ * `database` config namespace (see {@link DatabaseConfig}).
+ *
+ * @example
+ * ```ts
+ * // config/app.ts
+ * providers: [DatabaseProvider]
+ * ```
+ */
+export class DatabaseProvider extends ServiceProvider {
+  static override provides = ["db"] as const;
+  // Use an explicit mutable array type to satisfy ServiceProvider's static property constraint.
+  static override environments: AppEnvironment[] = ["web", "console", "test", "repl"];
+
+  private _disposeObservability: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    // Convention-based auto-discovery: app/models, app/observers, and auto-migrate.
+    // Optional-chained so bare-container unit tests with a minimal app stub still pass.
+    for (const concern of ormConcerns) this.app.registerConcern?.(concern);
+    this.app.registerConcern?.(autoMigrateConcern);
+
+    // Refuse a production boot on a driver/URL mismatch; warn on in-memory
+    // stores and no-op synchronize flags. Runs in the boot-time config pass.
+    this.app.registerConfigValidator?.("database", validateDatabaseConfig);
+
+    // Implicit route-model binding: `:user` -> User.findOrFail(value), for every registered
+    // model (opt out per model with `static implicitBinding = false`). Resolves lazily at
+    // route-compile time, so model registration order doesn't matter.
+    registerImplicitBinding();
+
+    setConnectionResolver(() => {
+      try {
+        return this.app.container.makeSync("db") as SQLInstance;
+      } catch {
+        return undefined;
+      }
+    });
+
+    this.app.container.singleton("db", async () => {
+      const config = (await this.app.container.make("config")) as ConfigManager;
+      const rawUrl = config.get<string>("database.url", ":memory:");
+      const pool = config.get<{ max?: number; idleTimeout?: number } | undefined>("database.pool");
+      const replicaUrls = config.get<string[]>("database.replicas", []);
+
+      const url = _normaliseSqliteUrl(rawUrl);
+      const sqlArg =
+        pool?.max !== undefined || pool?.idleTimeout !== undefined ? { url, ...pool } : url;
+      const primary = new SQL(sqlArg as unknown as string);
+
+      if (replicaUrls.length === 0) return primary;
+
+      // Build read replicas and wrap in a transparent read/write router.
+      // SELECT / WITH / EXPLAIN → round-robin replica pool.
+      // INSERT / UPDATE / DELETE / DDL / transactions → primary.
+      const replicas = replicaUrls.map((ru) => {
+        const replicaUrl = _normaliseSqliteUrl(ru);
+        const replicaSqlArg =
+          pool?.max !== undefined || pool?.idleTimeout !== undefined
+            ? { url: replicaUrl, ...pool }
+            : replicaUrl;
+        return new SQL(replicaSqlArg as unknown as string);
+      });
+
+      return createReadWriteRouter(primary, replicas);
+    });
+  }
+
+  override async onBooting(): Promise<void> {
+    const config = (await this.app.container.make("config")) as ConfigManager;
+    const rawUrl = config.get<string>("database.url", ":memory:");
+    _setBaseModelDialect(_detectDialect(rawUrl));
+
+    const sql = (await this.app.container.make("db")) as SQLInstance;
+    _setBaseModelConnection(sql);
+    await sql`SELECT 1`;
+
+    // Bridge model `dispatchesEvents` to the app event bus (no-op if no emitter).
+    _setModelEventDispatcher((event) => {
+      void this.app.container.tryMake("events")?.emit(event as object);
+    });
+
+    // Wire unique()/exists() validation rules to query through this connection.
+    // Lazy-import so @zerotal/validator is an optional peer — apps that don't use
+    // the validator still boot without errors.
+    try {
+      const { registerDbRuleRunner } = await import("@zerotal/validator");
+      registerDbRuleRunner(async (rule, table, column, value, options) => {
+        const conn = _getConnection();
+
+        if (rule === "unique") {
+          const ignoreId = options.ignoreId;
+          let rows: unknown[];
+          if (ignoreId !== undefined) {
+            const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` AND id != `, ` LIMIT 1`];
+            rows = await conn(
+              Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
+              value,
+              ignoreId,
+            );
+          } else {
+            const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` LIMIT 1`];
+            rows = await conn(
+              Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
+              value,
+            );
+          }
+          return rows.length === 0; // true = unique (no duplicate found)
+        }
+
+        // exists
+        const strs = [`SELECT 1 FROM ${table} WHERE ${column} = `, ` LIMIT 1`];
+        const rows = await conn(
+          Object.assign(strs, { raw: strs }) as unknown as TemplateStringsArray,
+          value,
+        );
+        return rows.length > 0; // true = exists (row found)
+      });
+    } catch {
+      // @zerotal/validator not installed — unique()/exists() rules won't work
+    }
+  }
+
+  override replContext(): Record<string, unknown> {
+    return { DB };
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeObservability?.();
+    this._disposeObservability = undefined;
+    try {
+      const sql = this.app.container.makeSync("db") as SQLInstance;
+      _setBaseModelConnection(null);
+      setConnectionResolver(null);
+      await sql.end();
+    } catch {
+      // DB was never initialised — nothing to close
+    }
+  }
+
+  override async onBooted(): Promise<void> {
+    // Forward the ORM's framework events to whatever observers are installed.
+    this._disposeObservability = installOrmObservability(this.app);
+
+    // N+1 query detection — enabled outside production. Previously activated by
+    // the devtools provider; owned here so devtools needs no ORM import.
+    const env = Bun.env.APP_ENV ?? "";
+    if (env !== "production" && env !== "prod") {
+      preventNPlusOne({ threshold: 5, mode: "warn" });
+    }
+
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+
+    runner.registerLazy(
+      "migrate",
+      () => import("../commands/MigrateCommand.ts").then((m) => m.MigrateCommand),
+      ["db:migrate"],
+    );
+    runner.registerLazy("migrate:rollback", () =>
+      import("../commands/MigrateRollbackCommand.ts").then((m) => m.MigrateRollbackCommand),
+    );
+    runner.registerLazy("migrate:fresh", () =>
+      import("../commands/MigrateFreshCommand.ts").then((m) => m.MigrateFreshCommand),
+    );
+    runner.registerLazy("migrate:status", () =>
+      import("../commands/MigrateStatusCommand.ts").then((m) => m.MigrateStatusCommand),
+    );
+    runner.registerLazy("make:migration", () =>
+      import("../commands/MakeMigrationCommand.ts").then((m) => m.MakeMigrationCommand),
+    );
+    runner.registerLazy(
+      "make:model",
+      () => import("../commands/MakeModelCommand.ts").then((m) => m.MakeModelCommand),
+      ["make:m"],
+    );
+    runner.registerLazy("db:seed", () =>
+      import("../commands/DbSeedCommand.ts").then((m) => m.DbSeedCommand),
+    );
+    runner.registerLazy("make:seeder", () =>
+      import("../commands/MakeSeederCommand.ts").then((m) => m.MakeSeederCommand),
+    );
+    runner.registerLazy("make:factory", () =>
+      import("../commands/MakeFactoryCommand.ts").then((m) => m.MakeFactoryCommand),
+    );
+    runner.registerLazy("migrate:generate", () =>
+      import("../commands/MigrateGenerateCommand.ts").then((m) => m.MigrateGenerateCommand),
+    );
+  }
+}
+
+/**
+ * Normalise a database URL for Bun.sql.
+ *
+ * Bun v1.3.x on Windows only recognises SQLite when the URL begins with
+ * 'sqlite:' or is exactly ':memory:'. Bare file paths are silently treated
+ * as PostgreSQL connection strings, so we add the scheme explicitly.
+ *
+ * Mapping:
+ *   :memory:            → :memory:        (Bun accepts it directly)
+ *   sqlite://…          → sqlite:…        (collapse double-slash)
+ *   sqlite:…            → sqlite:…        (keep)
+ *   file:…              → sqlite:…        (rewrite scheme)
+ *   postgres(ql)://…    → unchanged       (PostgreSQL pass-through)
+ *   mysql(2)://…        → unchanged       (MySQL pass-through)
+ *   ./path or path      → sqlite:./path   (add scheme)
+ *
+ * @internal
+ */
+export function _normaliseSqliteUrl(raw: string): string {
+  if (!raw || raw === ":memory:") return raw;
+  if (raw.startsWith("postgres://")) return raw;
+  if (raw.startsWith("postgresql://")) return raw;
+  if (raw.startsWith("mysql2://")) return raw;
+  if (raw.startsWith("mysql://")) return raw;
+  if (raw.startsWith("sqlite://")) return raw.replace("sqlite://", "sqlite:");
+  if (raw.startsWith("sqlite:")) return raw;
+  if (raw.startsWith("file:")) return "sqlite:" + raw.slice("file:".length);
+  return "sqlite:" + raw;
+}
+
+/**
+ * Infer the ORM dialect from a raw database URL.
+ * @internal
+ */
+function _detectDialect(raw: string): "sqlite" | "postgres" | "mysql" {
+  if (raw.startsWith("postgres://") || raw.startsWith("postgresql://")) return "postgres";
+  if (raw.startsWith("mysql://") || raw.startsWith("mysql2://")) return "mysql";
+  return "sqlite";
+}