@zerotal/orm 1.0.0

package/src/model/decorators/hasOneThrough.ts

@@ -0,0 +1,40 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+import type { HasManyThroughOptions } from "./hasManyThrough.ts";
+
+/**
+ * Declare a has-one-through relation: reach a single related record across one
+ * intermediate ("through") model (the one-to-one counterpart of
+ * {@link hasManyThrough}).
+ *
+ * @remarks Not supported by {@link has} / {@link whereHas}; use eager
+ * {@link ModelQueryBuilder.with | with()} to load it.
+ *
+ * @param related - Lazy factory returning the far/related model class.
+ * @param through - Lazy factory returning the intermediate model class.
+ * @param options - First/second key configuration across the two hops.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Country extends BaseModel {
+ *   \@hasOneThrough(() => Post, () => User, { firstKey: 'country_id', secondKey: 'user_id' })
+ *   latestPost!: HasOne<Post>;
+ * }
+ * ```
+ */
+export function hasOneThrough(
+  related: () => unknown,
+  through: () => unknown,
+  options: HasManyThroughOptions,
+) {
+  return makeRelationDecorator(() => ({
+    type: "hasOneThrough" as const,
+    related,
+    through,
+    firstKey: options.firstKey,
+    secondKey: options.secondKey,
+    foreignKey: options.secondKey,
+    localKey: options.localKey ?? "id",
+    throughLocalKey: options.throughLocalKey ?? "id",
+  }));
+}

package/src/model/decorators/manyToMany.ts

@@ -0,0 +1,55 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+/** Options for {@link manyToMany}. */
+export interface ManyToManyOptions {
+  /** Name of the pivot (join) table (e.g. `role_user`). */
+  pivotTable: string;
+  /** Pivot column referencing this (parent) model (e.g. `user_id`). */
+  pivotForeignKey: string;
+  /** Pivot column referencing the related model (e.g. `role_id`). */
+  pivotRelatedKey: string;
+  /** Parent local key the pivot FK references. Defaults to `'id'`. */
+  localKey?: string;
+  /** Related local key the pivot relatedKey references. Defaults to `'id'`. */
+  relatedKey?: string;
+  /** Extra pivot columns to hydrate onto each related model's `pivot` bag. */
+  withPivot?: string[];
+  /** Maintain created_at / updated_at on the pivot table during attach/sync. */
+  withTimestamps?: boolean;
+}
+
+/**
+ * Declare a many-to-many relation through a pivot table (e.g. `User` ↔ `Role`
+ * via `role_user`). The relation property is a {@link ManyToMany} collection that
+ * behaves as an array yet also exposes pivot methods (`attach` / `detach` /
+ * `sync` / `toggle`).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - Pivot table and key configuration.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class User extends BaseModel {
+ *   \@manyToMany(() => Role, {
+ *     pivotTable: 'role_user',
+ *     pivotForeignKey: 'user_id',
+ *     pivotRelatedKey: 'role_id',
+ *   })
+ *   roles!: ManyToMany<Role>;
+ * }
+ * ```
+ */
+export function manyToMany(related: () => unknown, options: ManyToManyOptions) {
+  return makeRelationDecorator(() => ({
+    type: "manyToMany" as const,
+    related,
+    foreignKey: options.pivotForeignKey,
+    localKey: options.localKey ?? "id",
+    pivotTable: options.pivotTable,
+    pivotForeignKey: options.pivotForeignKey,
+    pivotRelatedKey: options.pivotRelatedKey,
+    ...(options.withPivot ? { pivotColumns: options.withPivot } : {}),
+    ...(options.withTimestamps ? { pivotTimestamps: options.withTimestamps } : {}),
+  }));
+}

package/src/model/decorators/morphMany.ts

@@ -0,0 +1,38 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface MorphManyOptions {
+  /**
+   * The morph name — prefix for the `_type` and `_id` columns on the related table.
+   * e.g. `morphName: 'commentable'` → columns `commentable_type`, `commentable_id`.
+   */
+  morphName: string;
+  /** Override the local key. Defaults to 'id'. */
+  localKey?: string;
+}
+
+/**
+ * Declare the "one" side of a polymorphic one-to-many: the parent owns many
+ * related rows that reference it via `{morphName}_id` / `{morphName}_type`
+ * columns (e.g. a `Post` has many `Comment`s through a `commentable` morph).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - The morph name and optional local key.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Post extends BaseModel {
+ *   \@morphMany(() => Comment, { morphName: 'commentable' })
+ *   comments!: MorphMany<Comment>;
+ * }
+ * ```
+ */
+export function morphMany(related: () => unknown, options: MorphManyOptions) {
+  return makeRelationDecorator(() => ({
+    type: "morphMany" as const,
+    related,
+    foreignKey: `${options.morphName}_id`,
+    localKey: options.localKey ?? "id",
+    morphTypeColumn: `${options.morphName}_type`,
+  }));
+}

package/src/model/decorators/morphOne.ts

@@ -0,0 +1,38 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface MorphOneOptions {
+  /**
+   * The morph name — prefix for the `_type` and `_id` columns on the related table.
+   * e.g. `morphName: 'imageable'` → columns `imageable_type`, `imageable_id`.
+   */
+  morphName: string;
+  /** Override the local key. Defaults to 'id'. */
+  localKey?: string;
+}
+
+/**
+ * Declare the "one" side of a polymorphic one-to-one: the parent owns a single
+ * related row that references it via `{morphName}_id` / `{morphName}_type`
+ * columns (e.g. a `User` has one `Image` through an `imageable` morph).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - The morph name and optional local key.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class User extends BaseModel {
+ *   \@morphOne(() => Image, { morphName: 'imageable' })
+ *   avatar!: MorphOne<Image>;
+ * }
+ * ```
+ */
+export function morphOne(related: () => unknown, options: MorphOneOptions) {
+  return makeRelationDecorator(() => ({
+    type: "morphOne" as const,
+    related,
+    foreignKey: `${options.morphName}_id`,
+    localKey: options.localKey ?? "id",
+    morphTypeColumn: `${options.morphName}_type`,
+  }));
+}

package/src/model/decorators/morphTo.ts

@@ -0,0 +1,51 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface MorphToOptions {
+  /** Maps the discriminator string stored in the _type column to the model factory. */
+  morphMap: Record<string, () => unknown>;
+  /**
+   * Override the _type column name. Defaults to `<propertyName>_type`.
+   * e.g. property `commentable` → `commentable_type`.
+   */
+  morphTypeColumn?: string;
+  /**
+   * Override the _id column name. Defaults to `<propertyName>_id`.
+   * e.g. property `commentable` → `commentable_id`.
+   */
+  morphForeignKey?: string;
+}
+
+function _toSnake(s: string): string {
+  return s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
+/**
+ * Declare the inverse side of a polymorphic relation: this model belongs to one
+ * of several possible parent types, resolved at load time from the `_type`
+ * discriminator column via the {@link MorphToOptions.morphMap | morphMap}
+ * (e.g. a `Comment` belongs to a `Post` or `Video` through `commentable`).
+ *
+ * @param options - The type-to-model map plus optional column-name overrides.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Comment extends BaseModel {
+ *   \@morphTo({ morphMap: { Post: () => Post, Video: () => Video } })
+ *   commentable!: MorphTo<Post | Video>;
+ * }
+ * ```
+ */
+export function morphTo(options: MorphToOptions) {
+  return makeRelationDecorator((_ctor, field) => {
+    const snake = _toSnake(field);
+    return {
+      type: "morphTo" as const,
+      related: () => ({}),
+      foreignKey: options.morphForeignKey ?? `${snake}_id`,
+      localKey: "id",
+      morphMap: options.morphMap,
+      morphTypeColumn: options.morphTypeColumn ?? `${snake}_type`,
+    };
+  });
+}

package/src/model/decorators/morphToMany.ts

@@ -0,0 +1,49 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface MorphToManyOptions {
+  /** Morph name — prefix for the pivot `{name}_id` / `{name}_type` columns (e.g. 'taggable'). */
+  morphName: string;
+  /** FK on the pivot table referencing the related model (e.g. 'tag_id'). */
+  relatedPivotKey: string;
+  /** Pivot table name. Defaults to `{morphName}s`. */
+  pivotTable?: string;
+  /** Extra pivot columns to hydrate. */
+  withPivot?: string[];
+  /** Maintain pivot timestamps. */
+  withTimestamps?: boolean;
+}
+
+/**
+ * Declare a polymorphic many-to-many from the "owning" side: several parent types
+ * share one pivot table that carries a `_type` discriminator, linking each to the
+ * related model (e.g. `Post` / `Video` —(taggables)→ `Tag`). The property is a
+ * {@link ManyToMany} collection with pivot methods.
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - Morph name, related pivot key, and optional pivot config.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Post extends BaseModel {
+ *   \@morphToMany(() => Tag, { morphName: 'taggable', relatedPivotKey: 'tag_id' })
+ *   tags!: ManyToMany<Tag>;
+ * }
+ * ```
+ */
+export function morphToMany(related: () => unknown, options: MorphToManyOptions) {
+  const pivotTable = options.pivotTable ?? `${options.morphName}s`;
+  return makeRelationDecorator((ctor) => ({
+    type: "morphToMany" as const,
+    related,
+    pivotTable,
+    pivotForeignKey: `${options.morphName}_id`,
+    pivotRelatedKey: options.relatedPivotKey,
+    pivotMorphType: `${options.morphName}_type`,
+    pivotMorphValue: ctor.name,
+    foreignKey: `${options.morphName}_id`,
+    localKey: "id",
+    ...(options.withPivot ? { pivotColumns: options.withPivot } : {}),
+    ...(options.withTimestamps ? { pivotTimestamps: options.withTimestamps } : {}),
+  }));
+}

package/src/model/decorators/morphedByMany.ts

@@ -0,0 +1,46 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface MorphedByManyOptions {
+  /** Morph name — the pivot `{name}_id` / `{name}_type` columns describe the related side. */
+  morphName: string;
+  /** FK on the pivot referencing the parent model (e.g. 'tag_id'). */
+  parentPivotKey: string;
+  /** Pivot table name. Defaults to `{morphName}s`. */
+  pivotTable?: string;
+  withPivot?: string[];
+  withTimestamps?: boolean;
+}
+
+/**
+ * Declare a polymorphic many-to-many from the "inverse" side: the shared model
+ * reaches back to each of the owning types through the same morph pivot table
+ * (e.g. `Tag` —(taggables)→ `Post` / `Video`). The property is a
+ * {@link ManyToMany} collection with pivot methods.
+ *
+ * @param related - Lazy factory returning the related (owning) model class.
+ * @param options - Morph name, parent pivot key, and optional pivot config.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Tag extends BaseModel {
+ *   \@morphedByMany(() => Post, { morphName: 'taggable', parentPivotKey: 'tag_id' })
+ *   posts!: ManyToMany<Post>;
+ * }
+ * ```
+ */
+export function morphedByMany(related: () => unknown, options: MorphedByManyOptions) {
+  const pivotTable = options.pivotTable ?? `${options.morphName}s`;
+  return makeRelationDecorator(() => ({
+    type: "morphedByMany" as const,
+    related,
+    pivotTable,
+    pivotForeignKey: options.parentPivotKey,
+    pivotRelatedKey: `${options.morphName}_id`,
+    pivotMorphType: `${options.morphName}_type`,
+    foreignKey: options.parentPivotKey,
+    localKey: "id",
+    ...(options.withPivot ? { pivotColumns: options.withPivot } : {}),
+    ...(options.withTimestamps ? { pivotTimestamps: options.withTimestamps } : {}),
+  }));
+}

package/src/model/decorators/table.ts

@@ -0,0 +1,124 @@
+import { drainPendingMembers } from "./_metadata.ts";
+
+/**
+ * Options object accepted as the second argument to `@table()`.
+ * Equivalent to calling the fluent chain methods — choose whichever style you prefer.
+ *
+ * @example
+ * @table("users", { timestamps: true })
+ * export class User extends BaseModel { ... }
+ */
+export interface TableOptions {
+  /** Enable / disable automatic timestamp columns. @default true */
+  timestamps?: boolean;
+  /** Override the primary key column name. @default "id" */
+  primaryKey?: string;
+}
+
+/**
+ * Configuration collected by the fluent builder.
+ * @internal
+ */
+interface TableConfig {
+  tableName: string;
+  timestamps: boolean;
+  primaryKey: string;
+}
+
+/**
+ * A function that acts as a class decorator AND exposes chainable configuration
+ * methods. Every chain method returns the same builder so you can keep chaining
+ * or apply it directly as a decorator.
+ *
+ * @example
+ * // Fluent chain form
+ * @table("users").withoutTimestamps()
+ * export class User extends BaseModel { ... }
+ *
+ * @example
+ * // Options-object form — same result, no parens needed on the decorator
+ * @table("users", { timestamps: true })
+ * export class User extends BaseModel { ... }
+ *
+ * @example
+ * // Non-standard primary key
+ * @table("posts").primaryKey("post_id")
+ * export class Post extends BaseModel { ... }
+ *
+ * Soft deletes are opt-in via the `SoftDeletes` mixin, not `@table`:
+ * `class Post extends BaseModelWith(SoftDeletes) {}` — see /docs/orm/lifecycle.
+ */
+export interface TableDecoratorBuilder {
+  /** Apply the decorator to a class constructor (called automatically by TS). */
+  (target: Function, context?: unknown): void;
+
+  /** Enable automatic `created_at` / `updated_at` management. Default: on. */
+  withTimestamps(): TableDecoratorBuilder;
+  /** Disable automatic timestamp columns. */
+  withoutTimestamps(): TableDecoratorBuilder;
+  /** Override the primary key column name. Default: "id". */
+  primaryKey(key: string): TableDecoratorBuilder;
+}
+
+/**
+ * Fluent class decorator factory for configuring a `BaseModel` subclass.
+ *
+ * Accepts an optional `options` object as a second argument so you don't need to
+ * chain methods if you prefer the inline form. Both styles are fully equivalent.
+ *
+ * ```ts
+ * // Style A — fluent chain
+ * @table("users").withoutTimestamps()
+ * export class User extends BaseModel { ... }
+ *
+ * // Style B — options object
+ * @table("users", { timestamps: true })
+ * export class User extends BaseModel { ... }
+ * ```
+ *
+ * Timestamps are **on by default** — use `.withoutTimestamps()` to opt out. Soft
+ * deletes are **opt-in via the `SoftDeletes` mixin**: `extends BaseModelWith(SoftDeletes)`.
+ *
+ * `@table` is the single, required way to configure a model: besides setting the
+ * table name and options, it anchors the class's `@column`/relation registrations at
+ * definition time (the decorator runs synchronously with the class in hand). Any class
+ * that declares column or relation fields — including a subclass that ADDS fields — must
+ * carry its own `@table`, or those fields won't register.
+ */
+export function table(tableName: string, options: TableOptions = {}): TableDecoratorBuilder {
+  const config: TableConfig = {
+    tableName,
+    timestamps: options.timestamps ?? true,
+    primaryKey: options.primaryKey ?? "id",
+  };
+
+  function apply(target: Function, _context?: unknown): void {
+    // Drain the @column / @relation registrations queued while this class's members were
+    // decorated. @table is the definition-time anchor that owns this — see _metadata.ts.
+    drainPendingMembers(target);
+    const ctor = target as unknown as Record<string, unknown>;
+    ctor.table = config.tableName;
+    ctor.timestamps = config.timestamps;
+    ctor.primaryKey = config.primaryKey;
+    // NOTE: `softDeletes` is intentionally NOT set here — it's owned by the SoftDeletes
+    // mixin (`static softDeletes = true`). Setting it from @table would clobber the
+    // mixin's value back to the default on models that compose it.
+  }
+
+  apply.withTimestamps = (): TableDecoratorBuilder => {
+    config.timestamps = true;
+    return apply as TableDecoratorBuilder;
+  };
+
+  apply.withoutTimestamps = (): TableDecoratorBuilder => {
+    config.timestamps = false;
+    return apply as TableDecoratorBuilder;
+  };
+
+  apply.primaryKey = (key: string): TableDecoratorBuilder => {
+    config.primaryKey = key;
+    return apply as TableDecoratorBuilder;
+  };
+
+  return apply as TableDecoratorBuilder;
+}

package/src/model/hooks/HookRegistry.ts

@@ -0,0 +1,110 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { currentOrmContext } from "../OrmContext.ts";
+
+/**
+ * The set of model lifecycle points a hook can attach to. Each fires once per
+ * persistence operation; `beforeSave`/`afterSave` wrap both inserts and updates,
+ * and `afterFind` fires when a row is hydrated from the database.
+ */
+export type HookName =
+  | "beforeCreate"
+  | "afterCreate"
+  | "beforeSave"
+  | "afterSave"
+  | "beforeUpdate"
+  | "afterUpdate"
+  | "beforeDelete"
+  | "afterDelete"
+  | "afterFind";
+
+type HookFn<T> = (model: T) => Promise<void> | void;
+
+function _registry(): Map<Function, Map<HookName, HookFn<unknown>[]>> {
+  return currentOrmContext().hooks as unknown as Map<Function, Map<HookName, HookFn<unknown>[]>>;
+}
+
+/**
+ * AsyncLocalStorage carrying a boolean that, when `true`, mutes all hook
+ * and observer execution for the duration of the callback.
+ *
+ * Set by `_suppressHooks()` — used by factories to silence observers during
+ * seeding. Opt out by calling `.dispatchEvents()` on the factory.
+ */
+const _suppressCtx = new AsyncLocalStorage<true>();
+
+/**
+ * Run `fn` with all model hooks and observers silenced.
+ * Used internally by Factory when `dispatchEvents()` has NOT been called.
+ */
+export function _suppressHooks<T>(fn: () => Promise<T>): Promise<T> {
+  return _suppressCtx.run(true, fn);
+}
+
+/**
+ * Central store of per-model lifecycle hook callbacks, keyed by model class and
+ * {@link HookName}. Hooks registered on a parent class also run for subclasses
+ * (the prototype chain is walked in base-to-derived order).
+ *
+ * Registration is driven by higher-level APIs (model `beforeCreate()` etc. and the
+ * observer bridge in {@link registerObserver}); most application code never calls
+ * this class directly.
+ *
+ * @internal
+ */
+export class HookRegistry {
+  /**
+   * Optional post-run callback, invoked after a hook's functions run (and only when hooks
+   * are not suppressed). BaseModel sets this to dispatch model events (`dispatchesEvents`).
+   */
+  static onAfterRun: ((ModelClass: Function, hook: HookName, model: unknown) => void) | undefined;
+
+  /**
+   * Append a hook callback for a model class at a given lifecycle point.
+   *
+   * @param ModelClass - The model constructor the hook belongs to.
+   * @param hook - Which lifecycle point to fire on.
+   * @param fn - Callback receiving the model instance; may be async.
+   */
+  static register<T>(ModelClass: Function, hook: HookName, fn: HookFn<T>): void {
+    const registry = _registry();
+    if (!registry.has(ModelClass)) {
+      registry.set(ModelClass, new Map());
+    }
+    const hooks = registry.get(ModelClass)!;
+    if (!hooks.has(hook)) hooks.set(hook, []);
+    hooks.get(hook)!.push(fn as HookFn<unknown>);
+  }
+
+  /**
+   * Run every registered callback for `hook` on `ModelClass`, awaiting each in
+   * turn, walking the prototype chain base-to-derived. No-op while hooks are
+   * suppressed (see {@link _suppressHooks}); otherwise invokes `onAfterRun` afterward.
+   *
+   * @param ModelClass - The model constructor whose hooks (and inherited hooks) to run.
+   * @param hook - Which lifecycle point is firing.
+   * @param model - The model instance passed to each callback.
+   */
+  static async run<T>(ModelClass: Function, hook: HookName, model: T): Promise<void> {
+    if (_suppressCtx.getStore()) return;
+
+    // Walk the prototype chain to collect inherited hooks
+    const chain: Function[] = [];
+    let cur: Function | null = ModelClass;
+    while (cur && cur !== Function.prototype) {
+      chain.unshift(cur);
+      cur = Object.getPrototypeOf(cur) as Function | null;
+    }
+
+    const registry = _registry();
+    for (const cls of chain) {
+      const fns = registry.get(cls)?.get(hook);
+      if (fns) {
+        for (const fn of fns) {
+          await fn(model as unknown);
+        }
+      }
+    }
+
+    HookRegistry.onAfterRun?.(ModelClass, hook, model as unknown);
+  }
+}