@zerotal/orm 1.0.0

package/src/model/Observer.ts

@@ -0,0 +1,73 @@
+import { HookRegistry, type HookName } from "./hooks/HookRegistry.ts";
+
+/**
+ * Observer interface — implement any subset of lifecycle methods to react to a
+ * model's create / update / save / delete / retrieve events in one cohesive class.
+ *
+ * @remarks
+ * Each method name maps to an internal {@link HookName}: `creating`→`beforeCreate`,
+ * `created`→`afterCreate`, `updating`→`beforeUpdate`, `updated`→`afterUpdate`,
+ * `saving`→`beforeSave`, `saved`→`afterSave`, `deleting`→`beforeDelete`,
+ * `deleted`→`afterDelete`, and `retrieved`→`afterFind`. Methods may be async;
+ * a `before*` method that throws aborts the operation.
+ *
+ * @typeParam T - The model type the observer watches.
+ *
+ * @example
+ * export class UserObserver implements ModelObserver<User> {
+ *   creating(user: User) { user.uuid = crypto.randomUUID(); }
+ *   created(user: User)  { Log.info('User created', { id: user.id }); }
+ *   deleting(user: User) { Log.info('Deleting user', { id: user.id }); }
+ * }
+ *
+ * // Register once at boot (in a ServiceProvider)
+ * User.observe(UserObserver);
+ */
+export interface ModelObserver<T = unknown> {
+  creating?(model: T): Promise<void> | void;
+  created?(model: T): Promise<void> | void;
+  updating?(model: T): Promise<void> | void;
+  updated?(model: T): Promise<void> | void;
+  saving?(model: T): Promise<void> | void;
+  saved?(model: T): Promise<void> | void;
+  deleting?(model: T): Promise<void> | void;
+  deleted?(model: T): Promise<void> | void;
+  retrieved?(model: T): Promise<void> | void;
+}
+
+type ObserverClass<T> = new () => ModelObserver<T>;
+
+// Maps observer lifecycle method names to internal HookName
+const _methodToHook: Record<keyof ModelObserver, HookName> = {
+  creating: "beforeCreate",
+  created: "afterCreate",
+  updating: "beforeUpdate",
+  updated: "afterUpdate",
+  saving: "beforeSave",
+  saved: "afterSave",
+  deleting: "beforeDelete",
+  deleted: "afterDelete",
+  retrieved: "afterFind",
+};
+
+/**
+ * Register an observer class for a model: instantiate it once and wire each
+ * implemented lifecycle method to its corresponding hook.
+ *
+ * Called by `BaseModel.observe(ObserverClass)`; app code normally uses that
+ * rather than calling this directly.
+ *
+ * @param ModelClass - The model constructor to observe.
+ * @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 {
+  const instance = new ObserverClass();
+
+  for (const [method, hook] of Object.entries(_methodToHook) as [keyof ModelObserver, HookName][]) {
+    const fn = instance[method] as ((m: T) => Promise<void> | void) | undefined;
+    if (typeof fn === "function") {
+      HookRegistry.register<T>(ModelClass, hook, fn.bind(instance));
+    }
+  }
+}

package/src/model/OrmContext.ts

@@ -0,0 +1,71 @@
+import type { SQLInstance } from "../db/sql-types.ts";
+
+/**
+ * Execution-scoped container for all mutable ORM state that must NOT leak across
+ * requests or tenants — the override/named connections, per-model state-machine
+ * transition callbacks, registered global scopes, and lifecycle hooks.
+ *
+ * Keeping this state on a swappable context (rather than in module globals) lets
+ * each request or tenant boundary run with an isolated ORM view; the app scope
+ * integration below swaps a fresh `OrmContext` in per application scope.
+ *
+ * @example
+ * // Scope connection + registrations to a block, then restore:
+ * const prev = useOrmContext(new OrmContext());
+ * try {
+ *   BaseModel.registerConnection("tenant", tenantConn);
+ *   await doTenantWork();
+ * } finally {
+ *   useOrmContext(prev);
+ * }
+ */
+export class OrmContext {
+  /** Explicit connection override that wins over the resolved default (used by tests / `withDatabase`). */
+  overrideConnection: SQLInstance | null = null;
+  /** 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[]>>();
+  /** Per-model registered global query scopes. */
+  globalScopes = new Map<Function, Map<string, unknown>>();
+  /** Per-model lifecycle hooks. */
+  hooks = new Map<Function, Map<string, unknown[]>>();
+}
+
+let _ctx = new OrmContext();
+
+/** Return the currently active {@link OrmContext}. */
+export function currentOrmContext(): OrmContext {
+  return _ctx;
+}
+
+/**
+ * Install `ctx` (or a fresh {@link OrmContext}) as the active context and return
+ * the previous one, so callers can restore it afterwards.
+ *
+ * @param ctx The context to activate (defaults to a new, empty context).
+ * @returns The context that was active before this call.
+ */
+export function useOrmContext(ctx: OrmContext = new OrmContext()): OrmContext {
+  const prev = _ctx;
+  _ctx = ctx;
+  return prev;
+}
+
+/** Replace the active context with a fresh, empty {@link OrmContext} (test/teardown reset). */
+export function resetOrmContext(): void {
+  _ctx = new OrmContext();
+}
+
+import { registerAppScope } from "@zerotal/core";
+
+let _appScopeRegistered = false;
+if (!_appScopeRegistered) {
+  _appScopeRegistered = true;
+  registerAppScope(() => {
+    const prev = useOrmContext(new OrmContext());
+    return () => {
+      useOrmContext(prev);
+    };
+  });
+}

package/src/model/ReactiveProxy.ts

@@ -0,0 +1,53 @@
+import type { BaseModel } from "./BaseModel.ts";
+
+type ProxyTarget = Record<string | symbol, unknown>;
+
+const _proxyCache = new WeakMap<object, object>();
+
+/**
+ * Wrap an object/array `target` in a deeply-reactive `Proxy` so that any nested
+ * mutation marks `model`'s `propertyKey` dirty (via {@link BaseModel.markDirty}),
+ * ensuring in-place edits of `json`/`array` cast columns are persisted on the
+ * next `save()`.
+ *
+ * Non-object values, `null`, and `Date` instances are returned unwrapped.
+ * Nested objects are proxied lazily on access, and proxies are cached per target
+ * (WeakMap) so repeated wrapping is cheap and identity-stable. Used by the
+ * ORM when a model has {@link BaseModel.reactiveCasts} enabled.
+ *
+ * @param model The owning model instance to flag dirty on mutation.
+ * @param propertyKey The column property the target belongs to.
+ * @param target The value to make reactive.
+ * @returns A reactive proxy of `target`, or `target` unchanged if not proxyable.
+ */
+export function makeReactive<T>(model: BaseModel, propertyKey: string, target: T): T {
+  if (typeof target !== "object" || target === null || target instanceof Date) {
+    return target;
+  }
+
+  const cached = _proxyCache.get(target as object) as T | undefined;
+  if (cached) return cached;
+
+  const proxy = new Proxy(target as ProxyTarget, {
+    get(obj, prop, receiver) {
+      const value = Reflect.get(obj, prop, receiver);
+      if (typeof value === "object" && value !== null && !(value instanceof Date)) {
+        return makeReactive(model, propertyKey, value);
+      }
+      return value;
+    },
+    set(obj, prop, value, receiver) {
+      const result = Reflect.set(obj, prop, value, receiver);
+      model.markDirty(propertyKey as keyof BaseModel);
+      return result;
+    },
+    deleteProperty(obj, prop) {
+      const result = Reflect.deleteProperty(obj, prop);
+      model.markDirty(propertyKey as keyof BaseModel);
+      return result;
+    },
+  });
+
+  _proxyCache.set(target as object, proxy);
+  return proxy as unknown as T;
+}

package/src/model/SoftDeletes.ts

@@ -0,0 +1,108 @@
+// ── SoftDeletes mixin ─────────────────────────────────────────────────────────
+//
+// Opt-in soft deletes. Compose it so only models that want them carry the API —
+// `deletedAt`, `forceDelete()`, `restore()`, `trashed()`, and the `withTrashed()` /
+// `onlyTrashed()` query scopes. A hard-delete model has none of these.
+//
+//   import { BaseModelWith, SoftDeletes } from "@zerotal/orm";
+//
+//   @table("posts")
+//   class Post extends BaseModelWith(SoftDeletes) {
+//     @column() title!: string;
+//   }
+//
+//   await post.delete();        // sets deleted_at; row hidden from default queries
+//   await Post.withTrashed().get();
+//   await post.restore();       // deleted_at = NULL
+//   await post.forceDelete();   // permanent
+//
+// Setting `static softDeletes = true` is what the query engine and schema sync read
+// (every query scopes `WHERE deleted_at IS NULL`, and the migrator provisions the
+// `deleted_at` column) — the mixin flips it for you.
+
+import { _resolveConn, type BaseModel } from "./BaseModel.ts";
+import { ModelQueryBuilder } from "./ModelQueryBuilder.ts";
+import { QueryBuilder } from "../db/QueryBuilder.ts";
+import type { Constructor } from "./mixins.ts";
+
+// Structural view of the concrete model class used by the static scopes.
+interface SoftDeleteModelClass<T extends BaseModel> {
+  table: string;
+  primaryKey: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  new (...args: any[]): T;
+}
+
+/**
+ * Mixin that adds opt-in soft deletes to a model. Compose it so only models that
+ * want them carry the API — `deletedAt`, {@link SoftDeletes.forceDelete},
+ * {@link SoftDeletes.restore}, {@link SoftDeletes.trashed}, and the
+ * {@link SoftDeletes.withTrashed} / {@link SoftDeletes.onlyTrashed} query scopes.
+ *
+ * The mixin flips `static softDeletes = true`, which is what the query engine and
+ * schema sync read: every default query scopes `WHERE deleted_at IS NULL`, the
+ * migrator provisions a `deleted_at` column, and `delete()` sets `deleted_at`
+ * instead of removing the row.
+ *
+ * @example
+ * ```ts
+ * @table("posts")
+ * class Post extends BaseModelWith(SoftDeletes) {
+ *   @column() title!: string;
+ * }
+ *
+ * await post.delete();               // sets deleted_at; hidden from default queries
+ * await Post.withTrashed().get();     // includes soft-deleted rows
+ * await Post.onlyTrashed().get();     // only soft-deleted rows
+ * await post.restore();               // deleted_at = NULL
+ * await post.forceDelete();           // permanent DELETE
+ * ```
+ */
+export function SoftDeletes<TBase extends Constructor>(Base: TBase) {
+  class SoftDeletes extends Base {
+    /** Engine switch — query scoping + schema `deleted_at` provisioning read this. */
+    static softDeletes = true;
+
+    /** When the row was soft-deleted, or null/undefined when live. */
+    declare deletedAt?: Date | null;
+
+    /** A query that INCLUDES soft-deleted rows (bypasses the default scope). */
+    static withTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T> {
+      return new ModelQueryBuilder<T>(this.table, _resolveConn(this as never), this as never);
+    }
+
+    /** A query that returns ONLY soft-deleted rows. */
+    static onlyTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T> {
+      const qb = new ModelQueryBuilder<T>(this.table, _resolveConn(this as never), this as never);
+      qb.whereNotNull("deleted_at");
+      return qb;
+    }
+
+    /** True when this record is currently soft-deleted. */
+    trashed(): boolean {
+      return (this as { deletedAt?: unknown }).deletedAt != null;
+    }
+
+    /** Permanently delete the row, bypassing soft delete. */
+    async forceDelete(): Promise<void> {
+      const M = this.constructor as unknown as { table: string; primaryKey: string };
+      await new QueryBuilder(M.table, _resolveConn(this.constructor as never))
+        .where(M.primaryKey, (this as { id?: unknown }).id)
+        .delete();
+    }
+
+    /**
+     * Restore a soft-deleted record by setting `deleted_at` back to NULL, so it
+     * reappears in normal queries.
+     */
+    async restore(): Promise<void> {
+      const M = this.constructor as unknown as { table: string; primaryKey: string };
+      await new QueryBuilder(M.table, _resolveConn(this.constructor as never))
+        .where(M.primaryKey, (this as { id?: unknown }).id)
+        .update({ deleted_at: null });
+      (this as { deletedAt?: unknown }).deletedAt = null;
+    }
+  }
+
+  return SoftDeletes;
+}

package/src/model/State.ts

@@ -0,0 +1,290 @@
+// ── State machine mixin ───────────────────────────────────────────────────────
+//
+// Finite-state-machine behaviour as an opt-in mixin, so only models that declare a
+// workflow carry the API — `transitionTo` / `forceState` / `onTransition` / the
+// `states` + `stateField` statics never appear on models that don't use them.
+//
+//   import { BaseModelWith } from "@zerotal/orm";
+//
+//   const States = {
+//     pending: { canTransitionTo: ["active", "cancelled"] as const },
+//     active:  { canTransitionTo: ["expired"] as const,
+//                guard: (s: Subscription) => { if (!s.stripeId) throw new StateError(...); } },
+//     expired: { canTransitionTo: [] as const },
+//     cancelled: { canTransitionTo: [] as const },
+//   } as const;
+//
+//   class Subscription extends BaseModelWith(State) {
+//     static states = States;
+//     @column() status!: keyof typeof States;
+//   }
+
+import { StateError } from "../errors/index.ts";
+import { currentOrmContext } from "./OrmContext.ts";
+import type { Constructor } from "./mixins.ts";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Reject the in-flight transition with a human-readable reason. Throws a {@link StateError}
+ * pre-populated with the model name and the from/to states, so a guard doesn't have to
+ * construct the error itself:
+ *
+ *   guard: async (order, reject) => {
+ *     if (!order.paid) reject("Can't ship an unpaid order.");
+ *   }
+ */
+export type RejectTransition = (reason: string) => never;
+
+/** Context a guard receives alongside the model: the reject helper and the from/to states. */
+export interface TransitionContext {
+  /** Reject the transition with a reason — throws a StateError carrying the model + from/to. */
+  reject: RejectTransition;
+  /** The state being transitioned **from**. */
+  current: string;
+  /** The state being transitioned **to**. */
+  intended: string;
+}
+
+/**
+ * A guard that runs before a transition is committed. It may:
+ *  - allow it (return `true`/`undefined`),
+ *  - block it (return `false` — yields a generic StateError), or
+ *  - reject it with a reason via `ctx.reject(reason)` (a StateError carrying that reason).
+ */
+export type StateGuard<T> = (
+  model: T,
+  ctx: TransitionContext,
+) => boolean | void | Promise<boolean | void>;
+
+/**
+ * Result of {@link State.transitionTo}: `[true]` on success, or `[false, StateError]` when the
+ * transition is illegal or a guard blocks it. Destructure and check — TypeScript narrows the
+ * error to `StateError` in the `!ok` branch:
+ *
+ *   const [ok, err] = await order.transitionTo("shipped");
+ *   if (!ok) return json({ error: err.message }, 422);
+ */
+export type TransitionResult = [ok: true] | [ok: false, error: StateError];
+
+/** One state's definition within a state machine. */
+export interface StateDefinition<States extends string, T = unknown> {
+  canTransitionTo: readonly States[];
+  guard?: StateGuard<T>;
+}
+
+/** Full state schema — a plain object with `as const`. */
+export type StateMachine<States extends string, T = unknown> = {
+  [K in States]: StateDefinition<States, T>;
+};
+
+/** Callback fired after a successful transition (from → to). */
+export type TransitionCallback<T> = (
+  model: T,
+  meta: { from: string; to: string },
+) => Promise<void> | void;
+
+// ── 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>[] {
+  const reg = currentOrmContext().transitionCallbacks;
+  if (!reg.has(ModelClass)) reg.set(ModelClass, new Map());
+  const map = reg.get(ModelClass)!;
+  if (!map.has(state)) map.set(state, []);
+  return map.get(state)! as TransitionCallback<unknown>[];
+}
+
+/** @internal Clear all transition callbacks — used in tests. Prefer resetOrmContext(). */
+export function _clearTransitionCallbacks(): void {
+  currentOrmContext().transitionCallbacks.clear();
+}
+
+// ── The mixin ─────────────────────────────────────────────────────────────────
+
+interface StateModelClass {
+  // `any` (not `unknown`) for the model type so a subclass can type its guards with its own
+  // concrete model — `guard: (order: Order, reject) => …` — without a variance conflict.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  states?: Record<string, StateDefinition<string, any>>;
+  stateField: string;
+  name: string;
+}
+
+/**
+ * Mixin that adds finite-state-machine behaviour to a model. Compose it so only
+ * models that declare a workflow carry the API — `transitionTo` / `forceState` /
+ * `onTransition` and the `states` + `stateField` statics never appear on models
+ * that don't use them.
+ *
+ * Declare the machine in `static states` (use `as const` for exact state typing)
+ * and, optionally, override `static stateField` when the state column isn't
+ * `status`. Each transition validates that the move is allowed, runs the target
+ * state's guard, persists via `save()`, then fires `onTransition` callbacks.
+ *
+ * @example
+ * ```ts
+ * const States = {
+ *   pending:   { canTransitionTo: ["active", "cancelled"] as const },
+ *   active:    { canTransitionTo: ["expired"] as const,
+ *                guard: (s: Subscription) => { if (!s.stripeId) throw new StateError(...); } },
+ *   expired:   { canTransitionTo: [] as const },
+ *   cancelled: { canTransitionTo: [] as const },
+ * } as const;
+ *
+ * class Subscription extends BaseModelWith(State) {
+ *   static states = States;
+ *   @column() status!: keyof typeof States;
+ * }
+ *
+ * const [ok, err] = await sub.transitionTo("active");
+ * if (!ok) return json({ error: err.message }, 422);
+ * ```
+ */
+export function State<TBase extends Constructor>(Base: TBase) {
+  class State extends Base {
+    /** Column name that holds the state value. Override when it isn't `status`. */
+    static stateField = "status";
+
+    /**
+     * Finite-state-machine definition. Each key is a valid state; `canTransitionTo`
+     * lists the states reachable from it, and an optional `guard` runs before the
+     * target is entered (call `reject(reason)`, throw `StateError`, or return `false`
+     * to block). Use `as const` so TypeScript infers the exact state union.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see StateModelClass note
+    static states?: Record<string, StateDefinition<string, any>>;
+
+    /**
+     * Register a callback that fires after a successful `transitionTo()`. Pass `'*'`
+     * to listen on every transition.
+     *
+     * @example
+     * Subscription.onTransition("active", async (sub, { from }) => { ... });
+     * Subscription.onTransition("*", (sub, { from, to }) => { ... });
+     */
+    static onTransition<T>(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      this: { new (...args: any[]): T },
+      toState: string,
+      callback: TransitionCallback<T>,
+    ): void {
+      _getCallbacks(this as unknown as Function, toState).push(
+        callback as TransitionCallback<unknown>,
+      );
+    }
+
+    /**
+     * Transition the model to a new state, enforcing the rules in `static states`:
+     * validates the transition is allowed, runs the target state's guard, updates
+     * the state column and `save()`s, then fires `onTransition` callbacks.
+     *
+     * Returns a result tuple — `[true]` on success, or `[false, StateError]` when the
+     * transition is illegal or a guard blocks it — so callers can branch without a
+     * try/catch. Unexpected errors (a failing `save()`, a throwing `onTransition`
+     * callback, or a non-StateError thrown by a guard) still propagate.
+     *
+     * @example
+     * const [ok, err] = await ticket.transitionTo("resolved");
+     * if (!ok) return json({ error: err.message }, 422);
+     */
+    async transitionTo(newState: string): Promise<TransitionResult> {
+      const ModelClass = this.constructor as unknown as StateModelClass;
+      const schema = ModelClass.states;
+      const self = this as unknown as Record<string, unknown>;
+      const field = ModelClass.stateField;
+      const currentState = String(self[field] ?? "");
+      const modelName = ModelClass.name;
+
+      if (!schema) {
+        return [
+          false,
+          new StateError(
+            modelName,
+            currentState,
+            newState,
+            `State machine not configured on ${modelName}. Add \`static states = { ... }\`.`,
+          ),
+        ];
+      }
+
+      const currentDef = schema[currentState];
+      if (!currentDef) {
+        return [
+          false,
+          new StateError(
+            modelName,
+            currentState,
+            newState,
+            `Unknown current state '${currentState}' on ${modelName}.`,
+          ),
+        ];
+      }
+
+      if (!(currentDef.canTransitionTo as readonly string[]).includes(newState)) {
+        return [false, new StateError(modelName, currentState, newState)];
+      }
+
+      // Run the target state's guard before touching the DB. A guard blocks the transition by
+      // returning `false` or calling `ctx.reject(reason)` (which throws a StateError we catch
+      // and surface in the tuple). Any *other* thrown error is a real fault and propagates.
+      const targetDef = schema[newState];
+      if (targetDef?.guard) {
+        const reject: RejectTransition = (reason: string): never => {
+          throw new StateError(modelName, currentState, newState, reason);
+        };
+        try {
+          const allowed = await (targetDef.guard as StateGuard<this>)(this, {
+            reject,
+            current: currentState,
+            intended: newState,
+          });
+          if (allowed === false) {
+            return [
+              false,
+              new StateError(
+                modelName,
+                currentState,
+                newState,
+                `Guard rejected transition from '${currentState}' to '${newState}' on ${modelName}.`,
+              ),
+            ];
+          }
+        } catch (error) {
+          if (error instanceof StateError) return [false, error];
+          throw error;
+        }
+      }
+
+      self[field] = newState;
+      await (this as unknown as { save(): Promise<unknown> }).save();
+
+      // Fire registered transition callbacks.
+      const map = currentOrmContext().transitionCallbacks.get(this.constructor as Function);
+      const meta = { from: currentState, to: newState };
+      const toFns = (map?.get(newState) ?? []) as TransitionCallback<unknown>[];
+      const anyFns = (map?.get("*") ?? []) as TransitionCallback<unknown>[];
+      for (const fn of [...toFns, ...anyFns]) await fn(this as unknown, meta);
+
+      return [true];
+    }
+
+    /**
+     * Forcefully set the state column to any value, bypassing guards and
+     * `onTransition` callbacks. For **test factories** and **seeders** only —
+     * throws when `APP_ENV` is `production`.
+     *
+     * @throws {Error} when called with `APP_ENV=production`.
+     */
+    async forceState(state: string): Promise<this> {
+      if (Bun.env["APP_ENV"] === "production") {
+        throw new Error("forceState() cannot be called in production (APP_ENV=production).");
+      }
+      const field = (this.constructor as unknown as StateModelClass).stateField;
+      (this as unknown as Record<string, unknown>)[field] = state;
+      return (this as unknown as { save(): Promise<unknown> }).save() as Promise<this>;
+    }
+  }
+
+  return State;
+}