@zerotal/orm 1.4.0 → 1.5.1

package/src/db/QueryBuilder.ts

@@ -216,6 +216,32 @@ function _getCachedTemplate(strings: string[]): TemplateStringsArray {
   return tpl;
 }
 
+/**
+ * Turn a JS value into something the driver can actually bind.
+ *
+ * Only dates need this, and they need it badly. A `Date` handed to Bun's SQLite
+ * driver as a bind parameter does not land: `update({ read_at: new Date() })`
+ * left the column NULL and **reported no error**, so a "mark all as read"
+ * feature shipped as a latent no-op that read correctly in the source. The
+ * asymmetry made it easy to write, too — `model.save()` applies casts, so the
+ * identical value through a model worked.
+ *
+ * The comparison path already learned this (see `ModelQueryBuilder._bindValue`:
+ * a `Date` in a `where` used to match zero rows). Doing it here covers every
+ * bind on every builder — `DB.table()` writes included — from one place, so the
+ * next path someone adds cannot reintroduce it.
+ *
+ * Dialect-aware because MySQL DATETIME rejects ISO 8601's `T`/`Z`; SQLite and
+ * PostgreSQL take it as-is.
+ */
+function _bindable(value: unknown, dialect: Dialect): unknown {
+  const date = value instanceof Carbon ? value.toDate() : value;
+  if (!(date instanceof Date)) return value;
+  return dialect === "mysql"
+    ? date.toISOString().replace("T", " ").slice(0, 19)
+    : date.toISOString();
+}
+
 /**
  * @internal Execute compiled segments on `conn` with prepared-template
  * interning and QueryExecuted telemetry. Shared by `QueryBuilder._run` and
@@ -230,6 +256,7 @@ export async function _runSegments<T = Record<string, unknown>>(
   const strings: string[] = [];
   const values: unknown[] = [];
   let current = "";
+  const dialect = dialectFor(conn);
 
   for (const seg of segs) {
     if (typeof seg === "string") {
@@ -237,7 +264,7 @@ export async function _runSegments<T = Record<string, unknown>>(
     } else {
       strings.push(current);
       current = "";
-      values.push(seg.val);
+      values.push(_bindable(seg.val, dialect));
     }
   }
   strings.push(current);
@@ -245,14 +272,18 @@ export async function _runSegments<T = Record<string, unknown>>(
   const cacheKey = strings.join("\x00");
   const tpl = _getCachedTemplate(strings);
   const ctx = RequestContext.tryGet();
-  if (trackNPlusOne) trackQuery(ctx, cacheKey);
+  // Bindings go through too: without them the detector groups a six-month
+  // reporting loop — identical SQL, a different `period` each time — with a
+  // genuine per-row lookup, and sends you hunting for a relation to eager-load
+  // that does not exist.
+  if (trackNPlusOne) trackQuery(ctx, cacheKey, values);
 
   const startMs = Date.now();
   const rows = await conn<T>(tpl, ...values);
   const durationMs = Date.now() - startMs;
   FrameworkEvents.emit(
     new QueryExecuted(
-      cacheKey.replace(/\x00/g, "?"),
+      cacheKey.replaceAll("\x00", "?"),
       values,
       startMs,
       durationMs,

package/src/diagnostics/missingRelation.ts

@@ -0,0 +1,187 @@
+/**
+ * "no such table: assets", answered.
+ *
+ * The message is exact and the stack is useless — every frame is inside the SQL
+ * driver, because that is where the failure surfaces, not where it comes from.
+ * The answer is almost always "you have migrations you have not run", and that
+ * lives here, one package away from the error page that needs it.
+ *
+ * The half that earns this feature is refusing to offer the button when it would
+ * not help. There are two situations and they need different answers: a table
+ * missing because a migration is pending, and a table missing because nobody ever
+ * wrote one. Running every pending migration in the second case changes nothing,
+ * leaves the developer where they started, and teaches them not to trust the
+ * panel.
+ */
+import type { ErrorDiagnosis } from "@zerotal/core";
+import { loadMigrations } from "../commands/_loadMigrations.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+
+/** What the database said is missing. */
+export interface MissingRelation {
+  kind: "table" | "column";
+  name: string;
+}
+
+/** Dialect error codes, checked before the message text. */
+const CODES: Record<string, MissingRelation["kind"]> = {
+  // PostgreSQL SQLSTATE
+  "42P01": "table", // undefined_table
+  "42703": "column", // undefined_column
+  // MySQL
+  "1146": "table", // ER_NO_SUCH_TABLE
+  "1054": "column", // ER_BAD_FIELD_ERROR
+  ER_NO_SUCH_TABLE: "table",
+  ER_BAD_FIELD_ERROR: "column",
+};
+
+/**
+ * Message shapes, as a fallback.
+ *
+ * SQLite has no error code worth branching on — everything arrives as
+ * `SQLITE_ERROR` — so its two messages are matched directly. Postgres and MySQL
+ * are matched by code above; their text is included because a driver that wraps
+ * the error can drop the code while keeping the message.
+ */
+const PATTERNS: Array<{ re: RegExp; kind: MissingRelation["kind"] }> = [
+  // Each captures the whole identifier — quotes, schema qualifier and all — and
+  // leaves the tidying to `bareName`. Capturing only the last segment needs a
+  // lazy qualifier prefix, and getting that subtly wrong is how `app.assets`
+  // came back as an empty name.
+  { re: /no such table:\s*([\w".`]+)/i, kind: "table" },
+  { re: /no such column:\s*([\w".`]+)/i, kind: "column" },
+  { re: /relation\s+([\w".]+)\s+does not exist/i, kind: "table" },
+  { re: /column\s+([\w".]+)\s+does not exist/i, kind: "column" },
+  { re: /table\s+'([\w.]+)'\s+doesn'?t exist/i, kind: "table" },
+  { re: /unknown column\s+'([\w.]+)'/i, kind: "column" },
+];
+
+/** Strip a qualifier and quoting: `"public"."assets"` → `assets`. */
+function bareName(raw: string): string {
+  const parts = raw.replace(/["`']/g, "").split(".");
+  return parts[parts.length - 1] ?? raw;
+}
+
+/**
+ * Whether this error is a database complaining about something that is not there.
+ *
+ * Returns `null` for everything else, including every other database error — a
+ * diagnoser that recognises errors it does not own is worse than none.
+ */
+export function detectMissingRelation(error: Error): MissingRelation | null {
+  const message = error.message ?? "";
+
+  // Code first: it is unambiguous where it exists, and message text is localised
+  // on some MySQL builds.
+  const code = (error as { code?: string | number; errno?: number }).code;
+  const errno = (error as { errno?: number }).errno;
+  const kindFromCode = CODES[String(code)] ?? CODES[String(errno)];
+
+  for (const { re, kind } of PATTERNS) {
+    const match = re.exec(message);
+    if (match?.[1]) return { kind: kindFromCode ?? kind, name: bareName(match[1]) };
+  }
+
+  // A recognised code with an unrecognised message still tells us the kind, but
+  // not the name — worth reporting, because "some table is missing" plus the
+  // pending list is still the answer.
+  if (kindFromCode) return { kind: kindFromCode, name: "" };
+  return null;
+}
+
+/** Migrations that exist on disk and have not run. */
+export async function pendingMigrations(): Promise<string[]> {
+  const records = await loadMigrations();
+  if (records.length === 0) return [];
+  const entries: MigrationEntry[] = records.map((r) => ({ name: r.name, migration: r.instance }));
+  const runner = new MigrationRunner({ connection: _getConnection() });
+  const statuses = await runner.status(entries);
+  return statuses.filter((s) => !s.ran).map((s) => s.name);
+}
+
+/**
+ * Does any migration on disk so much as mention this name?
+ *
+ * A weak signal used only to sharpen the message in the nothing-pending case:
+ * "no migration mentions `assets`" is a better sentence than anything generic,
+ * and it is usually right, because a migration that creates a table names it.
+ */
+async function anyMigrationMentions(name: string): Promise<boolean> {
+  if (name === "") return false;
+  const glob = new Bun.Glob("database/migrations/*.ts");
+  for await (const file of glob.scan({ cwd: process.cwd() })) {
+    try {
+      const source = await Bun.file(file).text();
+      if (source.includes(name)) return true;
+    } catch {
+      // Unreadable file — treat as no evidence rather than failing the diagnosis.
+    }
+  }
+  return false;
+}
+
+/**
+ * Build the diagnosis, given a token minter for the action.
+ *
+ * `mintToken` is passed in rather than imported so this stays testable without a
+ * running server, and so the endpoint owns its own token lifetime.
+ */
+export async function diagnoseMissingRelation(
+  error: Error,
+  options: { endpoint: string; mintToken: () => string },
+): Promise<ErrorDiagnosis | null> {
+  const missing = detectMissingRelation(error);
+  if (!missing) return null;
+
+  const subject = missing.name === "" ? `A ${missing.kind}` : `${missing.kind} \`${missing.name}\``;
+
+  let pending: string[];
+  try {
+    pending = await pendingMigrations();
+  } catch {
+    // No connection, no migrations directory, a driver that cannot answer — the
+    // detection still stands, so say what is missing without guessing why.
+    return {
+      title: `${subject} does not exist.`,
+      detail:
+        "The migration state could not be read, so this cannot say whether a pending " +
+        "migration would create it. Run `bun zt migrate:status` to see where things stand.",
+    };
+  }
+
+  if (pending.length > 0) {
+    return {
+      title: `${subject} does not exist, and ${pending.length} migration${
+        pending.length === 1 ? " has" : "s have"
+      } not run.`,
+      detail:
+        "Running them is very likely the fix. This runs the same migrations " +
+        "`bun zt migrate` would, in the same order, against the same connection — " +
+        "and it is available here only because the app is in development.",
+      items: pending,
+      action: {
+        label: `Run ${pending.length} migration${pending.length === 1 ? "" : "s"}`,
+        url: options.endpoint,
+        token: options.mintToken(),
+        pendingLabel: "Migrating…",
+      },
+    };
+  }
+
+  // Nothing pending. Deliberately no button: it would run nothing and change
+  // nothing, and the developer would be back here having been told to try.
+  const mentioned = await anyMigrationMentions(missing.name);
+  return {
+    title: `${subject} does not exist, and every migration has already run.`,
+    detail: mentioned
+      ? `A migration does mention \`${missing.name}\`, so this is more likely a rollback ` +
+        `that left the schema behind, or a migration that did not create what its name ` +
+        `suggests. \`bun zt migrate:status\` shows what ran, and \`migrate:refresh\` ` +
+        `rebuilds from scratch — it will destroy the data in this database.`
+      : `No migration in \`database/migrations\` mentions \`${missing.name}\`, which usually ` +
+        `means the migration that would create it was never written. \`bun zt make:migration\` ` +
+        `scaffolds one.`,
+  };
+}

package/src/diagnostics/runMigrationsEndpoint.ts

@@ -0,0 +1,124 @@
+/**
+ * The endpoint behind the error page's "Run migrations" button.
+ *
+ * This mutates a database in response to a request originating from a page that
+ * was rendered by a GET, which is a shape worth being paranoid about: a dev
+ * server on `localhost:3000` is reachable by any site the developer has open in
+ * another tab, and "run every pending migration" is not something a random page
+ * should be able to trigger.
+ *
+ * So it carries three independent guards, and each is checked here rather than
+ * inferred from the fact that the overlay is dev-only:
+ *
+ * 1. **`devSurfacesEnabled()`**, decided at request time. Note this is not
+ *    `!isProdLike(...)`: `isProdLike("")` is false, so an unset `APP_ENV` would
+ *    have *passed* that check. This one fails closed — only an explicitly
+ *    non-production environment, or a process the dev orchestrator supervises,
+ *    qualifies. It also reads the right thing: `setAppEnv()` overwrites
+ *    `APP_ENV` with a runtime mode before boot, so reading it directly is wrong.
+ * 2. **A single-use token**, minted per error page and spent on first use. This
+ *    is what a cross-origin caller cannot obtain: it would have to read the
+ *    page, and the same-origin policy stops it.
+ * 3. **The origin guard**, the same one the raw Flow endpoints use — because
+ *    this is registered as a raw route and so sits outside the CSRF middleware.
+ *
+ * The route is registered only when dev surfaces are enabled, so in production it
+ * does not exist at all. Guard 1 is the belt to that braces.
+ */
+import { Router, devSurfacesEnabled } from "@zerotal/core";
+import { isAllowedOrigin } from "@zerotal/core/http";
+import { loadMigrations } from "../commands/_loadMigrations.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+
+/** Path the button posts to. */
+export const RUN_MIGRATIONS_PATH = "/__zerotal/run-migrations";
+/** Header carrying the single-use token. */
+const TOKEN_HEADER = "X-Zerotal-Diagnosis-Token";
+
+/**
+ * Outstanding tokens.
+ *
+ * In memory and per process, which is right: a token is only ever handed to the
+ * page this process just rendered, and a restart invalidating them is correct
+ * rather than inconvenient — the page is stale by then anyway.
+ */
+const _tokens = new Set<string>();
+/** Tokens outlive one render but not a session; a bounded set cannot grow without limit. */
+const MAX_TOKENS = 32;
+
+/** Mint a token for one error page. @internal */
+export function _mintDiagnosisToken(): string {
+  // The oldest token is dropped rather than letting a long dev session
+  // accumulate them. Insertion order is iteration order for a Set.
+  if (_tokens.size >= MAX_TOKENS) {
+    const oldest = _tokens.values().next().value;
+    if (oldest !== undefined) _tokens.delete(oldest);
+  }
+  const token = crypto.randomUUID();
+  _tokens.add(token);
+  return token;
+}
+
+/** Spend a token. Returns false when it was never minted, or was already used. @internal */
+export function _spendDiagnosisToken(token: string | null): boolean {
+  if (!token) return false;
+  return _tokens.delete(token);
+}
+
+/** Forget every outstanding token. Tests. @internal */
+export function _resetDiagnosisTokens(): void {
+  _tokens.clear();
+}
+
+/**
+ * Run every pending migration, and report what ran.
+ *
+ * Separated from the route so a test can drive it without a server.
+ */
+export async function _runPendingMigrations(): Promise<string[]> {
+  const records = await loadMigrations();
+  const entries: MigrationEntry[] = records.map((r) => ({ name: r.name, migration: r.instance }));
+  const runner = new MigrationRunner({ connection: _getConnection() });
+  return runner.run(entries);
+}
+
+/**
+ * Register the endpoint, unless this is production.
+ *
+ * Called from `DatabaseProvider.onRegister()`.
+ */
+export function registerRunMigrationsEndpoint(allowedOrigins: () => string[]): void {
+  if (!devSurfacesEnabled()) return;
+
+  Router.raw("POST", RUN_MIGRATIONS_PATH, async (req: Request): Promise<Response> => {
+    // Guard 1 — re-checked at request time, not inherited from registration.
+    if (!devSurfacesEnabled()) {
+      return new Response("Not available.", { status: 404 });
+    }
+
+    // Guard 2 — a raw route bypasses the middleware pipeline, so CSRF protection
+    // does not apply and this is the check standing in for it.
+    if (!isAllowedOrigin(req, allowedOrigins())) {
+      return new Response("Forbidden origin.", { status: 403 });
+    }
+
+    // Guard 3 — single use. A caller that cannot read the error page cannot have
+    // this, and replaying a captured one does not work twice.
+    if (!_spendDiagnosisToken(req.headers.get(TOKEN_HEADER))) {
+      return new Response("Invalid or already-used token.", { status: 403 });
+    }
+
+    try {
+      const ran = await _runPendingMigrations();
+      if (ran.length === 0) return new Response("Nothing to run.", { status: 200 });
+      return new Response(`Ran ${ran.length}: ${ran.join(", ")}`, { status: 200 });
+    } catch (error) {
+      // The migration itself failed — which is a real answer, and more useful
+      // than a generic 500. It goes back as text so the panel can show it.
+      const message = error instanceof Error ? error.message : String(error);
+      return new Response(`Migration failed: ${message}`, { status: 500 });
+    }
+  });
+}

package/src/index.ts

@@ -75,6 +75,9 @@ export { Model, BaseModel } from "./model/BaseModel.ts";
 // Mixin authoring types. Compose them onto a model with the `Model.using(...)` static —
 // `class User extends Model.using(Authenticatable, Roles)`.
 export type { Constructor, Mixin, Compose } from "./model/mixins.ts";
+// The type every metadata registry keys on — a model class rather than an instance.
+// Packages that register columns or relations from outside the ORM take it as a parameter.
+export type { ClassRef } from "./support/classRef.ts";
 // State-machine behaviour is an opt-in mixin — compose with `Model.using(State)`.
 export { State } from "./model/State.ts";
 // Soft deletes are opt-in — compose with `Model.using(SoftDeletes)`.

package/src/model/BaseModel.ts

@@ -46,6 +46,7 @@ import {
 import { TransactionContext } from "../db/TransactionContext.ts";
 import type { InsertPayload, UpdatePayload, FillablePayload } from "./payload.ts";
 import type { WhereOperator, OrderDirection } from "../db/types.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 let _dialect: "sqlite" | "postgres" | "mysql" = "sqlite";
 
@@ -233,13 +234,13 @@ type StringCast =
   | `decimal:${number}`;
 type CastOption = ColumnOptions["cast"];
 
-function getCasts(ctor: Function): Record<string, CastOption> {
+function getCasts(ctor: ClassRef): Record<string, CastOption> {
   const merged: Record<string, CastOption> = {};
-  const chain: Function[] = [];
-  let current: Function | null = ctor;
+  const chain: ClassRef[] = [];
+  let current: ClassRef | null = ctor;
   while (current && current !== Function.prototype) {
     chain.push(current);
-    current = Object.getPrototypeOf(current) as Function | null;
+    current = Object.getPrototypeOf(current) as ClassRef | null;
   }
   chain.reverse();
   // `static encryptable` first, so an explicit cast on the same column still wins —
@@ -426,7 +427,7 @@ type ModelCtor<T extends BaseModel> = typeof BaseModel & { new (): T };
  * (`Roles(Permissions(Base))`), where each relation lives on a different
  * class in the chain.
  */
-function relNames(ctor: Function): Set<string> {
+function relNames(ctor: ClassRef): Set<string> {
   return new Set(relationsFor(ctor).keys());
 }
 
@@ -463,7 +464,7 @@ function* ownDataEntries(
  * (rare edge case: a model with zero @column decorators) so callers can fall back
  * to the old unrestricted behaviour.
  */
-function _allColumnKeys(cls: Function): Set<string> | null {
+function _allColumnKeys(cls: ClassRef): Set<string> | null {
   const cols = columnsFor(cls);
   return cols ? new Set(cols.keys()) : null;
 }
@@ -1524,8 +1525,8 @@ export class BaseModel {
     const ModelClass = this as unknown as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
     const dialect = dialectFor(conn as unknown as object);
-    const casts = getCasts(ModelClass as unknown as Function);
-    const colReg = columnsFor(ModelClass as unknown as Function);
+    const casts = getCasts(ModelClass as unknown as ClassRef);
+    const colReg = columnsFor(ModelClass as unknown as ClassRef);
     const useTs = ModelClass.timestamps;
 
     const rows: Record<string, unknown>[] = _writeDialect.run(dialect, () => {
@@ -1610,8 +1611,8 @@ export class BaseModel {
   ): Promise<void> {
     const conn = _resolveConn(this);
     const dialect = dialectFor(conn as unknown as object);
-    const casts = getCasts(this as unknown as Function);
-    const colReg = columnsFor(this as unknown as Function);
+    const casts = getCasts(this as unknown as ClassRef);
+    const colReg = columnsFor(this as unknown as ClassRef);
 
     const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
       const r: Record<string, unknown> = {};
@@ -1697,8 +1698,8 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
     const dialect = dialectFor(conn as unknown as object);
-    const rels = relNames(ModelClass as unknown as Function);
-    const casts = getCasts(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const casts = getCasts(ModelClass as unknown as ClassRef);
 
     await HookRegistry.run(ModelClass, "beforeSave", this);
 
@@ -1730,8 +1731,8 @@ export class BaseModel {
       }
     }
 
-    const colReg = columnsFor(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const colReg = columnsFor(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
 
     if (!this._exists) {
       // ── INSERT ──
@@ -1995,8 +1996,8 @@ export class BaseModel {
    */
   replicate(except?: string[]): this {
     const ModelClass = this.constructor as typeof BaseModel;
-    const rels = relNames(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
     const skip = new Set<string>([...SYSTEM_KEYS, ...(except ?? [])]);
     const inst = new (this.constructor as new () => this)();
     for (const [k, v] of ownDataEntries(this, skip, rels, colKeys)) {
@@ -2240,7 +2241,7 @@ export class BaseModel {
    * @category Relationships
    */
   associate(relation: string, model: BaseModel): this {
-    const meta = relationsFor(this.constructor).get(relation);
+    const meta = relationsFor(this.constructor as ClassRef).get(relation);
     if (!meta || meta.type !== "belongsTo") {
       throw new Error(
         `associate(): "${relation}" is not a belongsTo relation on ${this.constructor.name}`,
@@ -2267,7 +2268,7 @@ export class BaseModel {
    * @category Relationships
    */
   dissociate(relation: string): this {
-    const meta = relationsFor(this.constructor).get(relation);
+    const meta = relationsFor(this.constructor as ClassRef).get(relation);
     if (!meta || meta.type !== "belongsTo") {
       throw new Error(
         `dissociate(): "${relation}" is not a belongsTo relation on ${this.constructor.name}`,
@@ -2307,8 +2308,8 @@ export class BaseModel {
    */
   $dirty(): Record<string, unknown> {
     const ModelClass = this.constructor as typeof BaseModel;
-    const rels = relNames(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
     const out: Record<string, unknown> = {};
     for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
       if (val !== this._original[key] || this._forcedDirty.has(key)) {
@@ -2499,8 +2500,8 @@ function _createLazyPivotProxy(
 function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
   const self = inst as unknown as Record<string, unknown>;
   const orig: Record<string, unknown> = {};
-  const ctor = inst.constructor;
-  const ModelClass = ctor as typeof BaseModel;
+  const ModelClass = inst.constructor as typeof BaseModel;
+  const ctor: ClassRef = ModelClass;
   const colReg = columnsFor(ctor);
   installReactiveAccessors(inst); // json/array reactiveCasts accessors (registered at decoration)
   const casts = getCasts(ctor);

package/src/model/ModelQueryBuilder.ts

@@ -22,11 +22,12 @@ import type { BaseModel } from "./BaseModel.ts";
 import { type ColumnOptions } from "./decorators/column.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
 import { currentOrmContext } from "./OrmContext.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 type StringCast = "datetime" | "array" | "json" | "date" | "boolean" | "integer" | "float";
 type CastOption = ColumnOptions["cast"];
 
-function _getCasts(ctor: Function): Record<string, CastOption> {
+function _getCasts(ctor: ClassRef): Record<string, CastOption> {
   const merged: Record<string, CastOption> = {};
   const colReg = columnsFor(ctor);
   // Mirrors getCasts() in BaseModel: `static encryptable` resolves to casts, and an
@@ -274,9 +275,9 @@ function _createPivotCollection<T extends BaseModel>(
 // BaseModel as a type only — no cycle.
 
 export type GlobalScopeCallback = (qb: ModelQueryBuilder<BaseModel>) => void;
-export function _globalScopeRegistry(): Map<Function, Map<string, GlobalScopeCallback>> {
+export function _globalScopeRegistry(): Map<ClassRef, Map<string, GlobalScopeCallback>> {
   return currentOrmContext().globalScopes as unknown as Map<
-    Function,
+    ClassRef,
     Map<string, GlobalScopeCallback>
   >;
 }
@@ -1142,15 +1143,14 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   withScopes(callback: (scopes: any) => void): this {
     const ModelClass = this._ModelClass;
-    const self = this;
     const proxy = new Proxy({} as Record<string, (...args: unknown[]) => void>, {
-      get(_target, prop: string | symbol) {
+      get: (_target, prop: string | symbol) => {
         return (...args: unknown[]) => {
           const fn = (ModelClass as unknown as Record<string | symbol, unknown>)[prop];
           if (typeof fn !== "function") return;
           const result = fn(...args) as { apply?: (q: unknown) => void } | null | undefined;
           if (result != null && typeof result.apply === "function") {
-            result.apply(self);
+            result.apply(this);
           }
         };
       },
@@ -1249,8 +1249,8 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
 
     const rawKey = column.split(".").pop() ?? column;
     const camelKey = rawKey.includes("_") ? _toCamel(rawKey) : rawKey;
-    const casts = _getCasts(this._ModelClass as unknown as Function);
-    const colMeta = columnsFor(this._ModelClass as unknown as Function)?.get(camelKey);
+    const casts = _getCasts(this._ModelClass as unknown as ClassRef);
+    const colMeta = columnsFor(this._ModelClass as unknown as ClassRef)?.get(camelKey);
     const castOpt = casts[rawKey] ?? casts[camelKey] ?? colMeta?.cast;
     const colType = colMeta?.type;
 
@@ -1324,9 +1324,9 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
       if (spec.children.length > 0 && related.length > 0) {
         if (meta.type === "morphTo") {
           // Mixed related classes — group by constructor and recurse per group.
-          const groups = new Map<Function, BaseModel[]>();
+          const groups = new Map<ClassRef, BaseModel[]>();
           for (const r of related) {
-            const ctor = r.constructor as Function;
+            const ctor = r.constructor as ClassRef;
             if (!groups.has(ctor)) groups.set(ctor, []);
             groups.get(ctor)!.push(r);
           }

package/src/model/Observer.ts

@@ -1,4 +1,5 @@
 import { HookRegistry, type HookName } from "./hooks/HookRegistry.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 /**
  * Observer interface — implement any subset of lifecycle methods to react to a
@@ -61,7 +62,7 @@ const _methodToHook: Record<keyof ModelObserver, HookName> = {
  * @param ObserverClass - An observer class (zero-arg constructor) implementing any subset of {@link ModelObserver}.
  * @internal
  */
-export function registerObserver<T>(ModelClass: Function, ObserverClass: ObserverClass<T>): void {
+export function registerObserver<T>(ModelClass: ClassRef, ObserverClass: ObserverClass<T>): void {
   const instance = new ObserverClass();
 
   for (const [method, hook] of Object.entries(_methodToHook) as [keyof ModelObserver, HookName][]) {

package/src/model/OrmContext.ts

@@ -25,11 +25,11 @@ export class OrmContext {
   /** Connections registered by name, selectable via `static connection`. */
   namedConnections = new Map<string, SQLInstance>();
   /** Per-model `onTransition` callbacks, keyed by target state (see the `State` mixin). */
-  transitionCallbacks = new Map<Function, Map<string, unknown[]>>();
+  transitionCallbacks = new Map<ClassRef, Map<string, unknown[]>>();
   /** Per-model registered global query scopes. */
-  globalScopes = new Map<Function, Map<string, unknown>>();
+  globalScopes = new Map<ClassRef, Map<string, unknown>>();
   /** Per-model lifecycle hooks. */
-  hooks = new Map<Function, Map<string, unknown[]>>();
+  hooks = new Map<ClassRef, Map<string, unknown[]>>();
 }
 
 let _ctx = new OrmContext();
@@ -58,6 +58,7 @@ export function resetOrmContext(): void {
 }
 
 import { registerAppScope } from "@zerotal/core";
+import type { ClassRef } from "../support/classRef.ts";
 
 let _appScopeRegistered = false;
 if (!_appScopeRegistered) {

package/src/model/State.ts

@@ -22,6 +22,7 @@
 import { StateError } from "../errors/index.ts";
 import { currentOrmContext } from "./OrmContext.ts";
 import type { Constructor } from "./mixins.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -87,7 +88,7 @@ export type TransitionCallback<T> = (
 // ── Callback registry (execution-scoped on the OrmContext) ────────────────────
 
 /** @internal Register or retrieve transition callbacks for a model class. */
-function _getCallbacks(ModelClass: Function, state: string): TransitionCallback<unknown>[] {
+function _getCallbacks(ModelClass: ClassRef, state: string): TransitionCallback<unknown>[] {
   const reg = currentOrmContext().transitionCallbacks;
   if (!reg.has(ModelClass)) reg.set(ModelClass, new Map());
   const map = reg.get(ModelClass)!;
@@ -169,7 +170,7 @@ export function State<TBase extends Constructor>(Base: TBase) {
       toState: string,
       callback: TransitionCallback<T>,
     ): void {
-      _getCallbacks(this as unknown as Function, toState).push(
+      _getCallbacks(this as unknown as ClassRef, toState).push(
         callback as TransitionCallback<unknown>,
       );
     }
@@ -260,7 +261,7 @@ export function State<TBase extends Constructor>(Base: TBase) {
       await (this as unknown as { save(): Promise<unknown> }).save();
 
       // Fire registered transition callbacks.
-      const map = currentOrmContext().transitionCallbacks.get(this.constructor as Function);
+      const map = currentOrmContext().transitionCallbacks.get(this.constructor as ClassRef);
       const meta = { from: currentState, to: newState };
       const toFns = (map?.get(newState) ?? []) as TransitionCallback<unknown>[];
       const anyFns = (map?.get("*") ?? []) as TransitionCallback<unknown>[];