@zerotal/orm 1.0.0

package/src/model/decorators/_metadata.ts

@@ -0,0 +1,211 @@
+// ── Decorator registration core (Bun 1.3.x standard-decorator workaround) ─────
+//
+// Bun 1.3.x mis-compiles standard TC39 field decorators: deferred work is corrupted
+// and shared across every class defined in the same file. Specifically —
+//   • field initializers and field `addInitializer` callbacks are cross-wired (a class
+//     runs another class's initializers, and names captured in their closures resolve
+//     to the LAST class defined in the file);
+//   • `context.metadata` is a single object shared by every class in the file;
+//   • `Symbol.metadata` is never assigned to the class.
+//
+// The ONE thing Bun compiles correctly is the decorator BODY: it runs synchronously at
+// class-definition time with the correct `context.name`, but without a reference to the
+// class. So each field/relation decorator captures its name+config in the body and
+// ENQUEUES a registration closure. The `@table` class decorator runs synchronously right
+// after a class's members — and it DOES receive the class — so it drains the queue into
+// the concrete class. Result: every model anchors its columns/relations via `@table`.
+
+import { relationRegistry } from "../relations/RelationRegistry.ts";
+import type { RelationMetadata } from "../relations/RelationRegistry.ts";
+import type { ColumnOptions } from "./column.ts";
+
+/**
+ * Per-class OWN column definitions. Readers walk the prototype chain to merge inherited.
+ * @internal
+ */
+export const columnRegistry = new Map<Function, Map<string, ColumnOptions>>();
+
+// ── Definition-time queue ─────────────────────────────────────────────────────
+
+interface PendingMember {
+  /** Field name (captured correctly in the decorator body). */
+  name: string;
+  apply: (ctor: Function) => void;
+}
+let _pending: PendingMember[] = [];
+
+/**
+ * Enqueue a member registration from a decorator body (name captured correctly there).
+ * @internal
+ */
+export function enqueueMember(name: string, apply: (ctor: Function) => void): void {
+  _pending.push({ name, apply });
+}
+
+/**
+ * Drain queued member registrations into `ctor`. Called by the `@table` class decorator,
+ * which runs synchronously immediately after the class's member decorators — so the queue
+ * contains exactly that class's members and nothing else.
+ * @internal
+ */
+export function drainPendingMembers(ctor: Function): void {
+  if (_pending.length === 0) return;
+  const batch = _pending;
+  _pending = [];
+  for (const e of batch) e.apply(ctor);
+  registerModelName(ctor);
+}
+
+// ── Per-class registration (invoked from drained closures) ────────────────────
+
+/**
+ * Record a column definition for `ctor`, and mirror any `cast` onto the class's own
+ * `static casts` map (seeded from the parent so a subclass extends rather than mutates it).
+ * @internal
+ */
+export function registerColumn(ctor: Function, name: string, options: ColumnOptions): void {
+  let m = columnRegistry.get(ctor);
+  if (!m) {
+    m = new Map();
+    columnRegistry.set(ctor, m);
+  }
+  m.set(name, options);
+
+  if (options.cast) {
+    const c = ctor as { casts?: Record<string, ColumnOptions["cast"]> };
+    // Give the class its OWN casts object (seeded from the parent) the first time we add
+    // to it, so a subclass extends rather than mutates the parent's casts.
+    if (!Object.prototype.hasOwnProperty.call(ctor, "casts")) {
+      const parent = (
+        Object.getPrototypeOf(ctor) as { casts?: Record<string, ColumnOptions["cast"]> }
+      )?.casts;
+      c.casts = { ...(parent ?? {}) };
+    }
+    c.casts![name] = options.cast;
+  }
+}
+
+/**
+ * Record relation metadata for `ctor`. Invoked from a drained decorator closure.
+ * @internal
+ */
+export function registerRelation(ctor: Function, name: string, meta: RelationMetadata): void {
+  let m = relationRegistry.get(ctor);
+  if (!m) {
+    m = new Map();
+    relationRegistry.set(ctor, m);
+  }
+  m.set(name, meta);
+}
+
+// ── Convention registration (used by the auto-discovery loader) ───────────────
+
+const _registeredModels = new WeakSet<Function>();
+/**
+ * class name → model class, for observer/policy association by name.
+ * @internal
+ */
+export const modelsByName = new Map<string, Function>();
+
+/**
+ * Look up a model class by its (unqualified) class name.
+ * @internal
+ */
+export function modelByName(name: string): Function | undefined {
+  return modelsByName.get(name);
+}
+
+/** Index a model class under its name. Called by @table's drain and by registerModel(). */
+function registerModelName(ctor: Function): void {
+  const name = (ctor as { name?: string }).name;
+  if (name) modelsByName.set(name, ctor);
+}
+
+/**
+ * Register a model class discovered by convention — the loader calls this for every class
+ * in `app/models/`, so `@table` is not required:
+ *  - drains the class's buffered @column/@relation entries by matching a probe instance's
+ *    own field names (Bun's deferred-decorator bug prevents binding name→class at definition
+ *    without an anchor; the loader IS the anchor, and the probe reveals which buffered
+ *    entries belong to this class — so convention models must use real fields, e.g.
+ *    `@column() name!: string`, not `@column() declare name: string`);
+ *  - indexes it under `modelsByName`.
+ *
+ * The convention table name is applied separately by the loader's models concern (which has
+ * the inflector); explicit `@table("...")` / `static table` always wins. Idempotent and a
+ * safe no-op on already-`@table`'d models.
+ * @internal
+ */
+export function registerModel(ctor: Function): void {
+  if (_registeredModels.has(ctor)) return;
+  _registeredModels.add(ctor);
+
+  if (_pending.length > 0) {
+    let own = new Set<string>();
+    try {
+      own = new Set(Object.keys(new (ctor as new () => object)()));
+    } catch {
+      /* not constructible without args — can't claim columns by probe */
+    }
+    if (own.size) {
+      // A class's field decorators run consecutively at definition, so its buffered
+      // entries form a contiguous run; claim from the first own-matching entry until the
+      // first entry that belongs to another class.
+      const start = _pending.findIndex((e) => own.has(e.name));
+      if (start !== -1) {
+        let end = start;
+        while (end < _pending.length && own.has(_pending[end]!.name)) end++;
+        const claimed = _pending.splice(start, end - start);
+        for (const e of claimed) e.apply(ctor);
+      }
+    }
+  }
+
+  registerModelName(ctor);
+}
+
+// ── Readers (prototype-chain merge; child wins) ───────────────────────────────
+
+/**
+ * Merged column definitions (own + inherited) for a class, or null if none.
+ * @internal
+ */
+export function columnsFor(ctor: Function): Map<string, ColumnOptions> | null {
+  const merged = new Map<string, ColumnOptions>();
+  let cls: Function | null = ctor;
+  while (cls && cls !== Function.prototype) {
+    const c = columnRegistry.get(cls);
+    if (c) for (const [k, v] of c) if (!merged.has(k)) merged.set(k, v);
+    cls = Object.getPrototypeOf(cls) as Function | null;
+  }
+  return merged.size ? merged : null;
+}
+
+/**
+ * Merged relation metadata (imperative mixins + @decorators, own + inherited).
+ * @internal
+ */
+export function relationsFor(ctor: Function): Map<string, RelationMetadata> {
+  const merged = new Map<string, RelationMetadata>();
+  let cls: Function | null = ctor;
+  while (cls && cls !== Function.prototype) {
+    const r = relationRegistry.get(cls);
+    if (r) for (const [k, v] of r) if (!merged.has(k)) merged.set(k, v);
+    cls = Object.getPrototypeOf(cls) as Function | null;
+  }
+  return merged;
+}
+
+/**
+ * Names of reactive (json/array cast) columns for a class (own + inherited).
+ * @internal
+ */
+export function reactiveColumnsFor(ctor: Function): string[] {
+  const cols = columnsFor(ctor);
+  if (!cols) return [];
+  const out: string[] = [];
+  for (const [name, opts] of cols) {
+    if (opts.cast === "json" || opts.cast === "array" || opts.type === "json") out.push(name);
+  }
+  return out;
+}

package/src/model/decorators/_registerRelation.ts

@@ -0,0 +1,20 @@
+import type { RelationMetadata } from "../relations/RelationRegistry.ts";
+import { enqueueMember, registerRelation } from "./_metadata.ts";
+
+/**
+ * The single plumbing for every relation field decorator (standard TC39 decorators).
+ *
+ * Registration is captured in the decorator BODY (which runs at definition time with the
+ * correct `context.name`) and ENQUEUED — we can't use a field initializer/addInitializer,
+ * which Bun 1.3.x cross-wires across classes in a file. The `@table` class decorator
+ * drains the queue into the concrete class, invoking the relation FACTORY (`metaFor`)
+ * with that class so morph/through values depending on the class name resolve correctly.
+ */
+export function makeRelationDecorator(
+  metaFor: (ctor: Function, field: string) => RelationMetadata,
+) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext): void {
+    const name = String(context.name);
+    enqueueMember(name, (ctor) => registerRelation(ctor, name, metaFor(ctor, name)));
+  };
+}

package/src/model/decorators/belongsTo.ts

@@ -0,0 +1,38 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+/** Options for {@link belongsTo}. */
+export interface BelongsToOptions {
+  /** FK column on this (child) model pointing to the related row (e.g. `user_id`). */
+  foreignKey: string;
+  /** Key on the related model the FK references. Defaults to `'id'`. */
+  localKey?: string;
+  /** Return a default (unsaved) related model instead of null when absent. */
+  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void);
+}
+
+/**
+ * Declare the inverse of a one-to-many / one-to-one: this model belongs to a
+ * single related row referenced by a foreign key on this model's table (e.g. a
+ * `Post` belongs to a `User`).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - Foreign/local key configuration, plus optional `withDefault`.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class Post extends BaseModel {
+ *   \@belongsTo(() => User, { foreignKey: 'user_id' })
+ *   author!: BelongsTo<User>;
+ * }
+ * ```
+ */
+export function belongsTo(related: () => unknown, options: BelongsToOptions) {
+  return makeRelationDecorator(() => ({
+    type: "belongsTo" as const,
+    related,
+    foreignKey: options.foreignKey,
+    localKey: options.localKey ?? "id",
+    ...(options.withDefault !== undefined ? { withDefault: options.withDefault } : {}),
+  }));
+}

package/src/model/decorators/column.ts

@@ -0,0 +1,278 @@
+import { makeReactive } from "../ReactiveProxy.ts";
+import type { CastContract } from "../../casts/Cast.ts";
+import {
+  enqueueMember,
+  registerColumn,
+  columnRegistry,
+  columnsFor,
+  reactiveColumnsFor,
+} from "./_metadata.ts";
+
+// Re-exported here for the public API — populated at class-definition time via @table.
+export { columnRegistry };
+
+// ── Column type definitions ───────────────────────────────────────────────────
+
+/**
+ * String shorthand accepted by `@column("...")`.
+ * Each value maps to a fully-resolved `ColumnOptions` object.
+ *
+ * | Shorthand   | Equivalent options                              |
+ * |-------------|--------------------------------------------------|
+ * | `"string"`  | `{ type: "string" }`                            |
+ * | `"text"`    | `{ type: "string" }` (large text, alias)        |
+ * | `"integer"` | `{ type: "number", cast: "integer" }`           |
+ * | `"number"`  | `{ type: "number" }`                            |
+ * | `"float"`   | `{ type: "number", cast: "float" }`             |
+ * | `"boolean"` | `{ type: "boolean", cast: "boolean" }`          |
+ * | `"datetime"`| `{ type: "datetime", cast: "datetime" }`        |
+ * | `"date"`    | `{ type: "datetime", cast: "date" }`            |
+ * | `"json"`    | `{ type: "json", cast: "json" }`                |
+ * | `"array"`   | `{ type: "json", cast: "array" }`               |
+ */
+export type ColumnShorthand =
+  | "string"
+  | "text"
+  | "integer"
+  | "number"
+  | "float"
+  | "boolean"
+  | "datetime"
+  | "date"
+  | "json"
+  | "array";
+
+/**
+ * Full option object accepted by `@column({ ... })`.
+ *
+ * Every string shorthand ({@link ColumnShorthand}) resolves to one of these; use
+ * the object form directly when you need `nullable`, `default`, a custom `cast`,
+ * or to mark a `primary` key.
+ *
+ * @remarks
+ * The registered `type` drives schema generation / auto-migration, while `cast`
+ * drives runtime serialization of the attribute value (see the field docs below).
+ * A `cast` is also mirrored onto the model class's `static casts` map at
+ * registration time.
+ *
+ * @example
+ * ```ts
+ * @column({ type: "string", nullable: true, default: "guest" })
+ * nickname?: string | null;
+ *
+ * @column({ type: "json", cast: "array", default: [] })
+ * tags!: string[];
+ *
+ * @column({ cast: new MoneyCast() })
+ * price!: number;
+ * ```
+ */
+export interface ColumnOptions {
+  /** Logical storage type; drives schema generation and auto-migration. @default "string" */
+  type?: "string" | "number" | "boolean" | "datetime" | "json";
+  /** Mark this column as the table's primary key. */
+  primary?: boolean;
+  /** Allow SQL `NULL` for this column. */
+  nullable?: boolean;
+  /** Default value applied when none is provided. */
+  default?: unknown;
+  /**
+   * Shorthand cast types automatically serialize/deserialize the column value.
+   * Can also be a custom object with `get`/`set` functions for full control.
+   *
+   * - 'datetime'       — Carbon on read, ISO string on write (recommended for dates)
+   * - 'date'           — native Date on read, ISO string on write
+   * - 'array' / 'json' — JSON.parse on read, JSON.stringify on write
+   * - 'boolean'        — coerces 0/1 integers; writes 0 or 1
+   * - 'integer'        — parseInt on both read and write
+   * - 'float'          — parseFloat on both read and write
+   * - 'enum'           — pass-through; pairs with `enumValues` for TS enum columns
+   */
+  cast?:
+    | "datetime"
+    | "array"
+    | "json"
+    | "date"
+    | "boolean"
+    | "integer"
+    | "float"
+    | "enum"
+    | "immutable_datetime"
+    | `decimal:${number}`
+    | {
+        get?: (dbValue: unknown) => unknown;
+        set?: (jsValue: unknown) => unknown;
+      }
+    | CastContract<unknown>;
+  /** Enum object (e.g. the imported TS enum) used alongside cast: 'enum'. */
+  enumValues?: Record<string, string | number>;
+}
+
+/**
+ * Map each ColumnShorthand to its resolved ColumnOptions.
+ */
+const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
+  string: { type: "string" },
+  text: { type: "string" },
+  integer: { type: "number", cast: "integer" },
+  number: { type: "number" },
+  float: { type: "number", cast: "float" },
+  boolean: { type: "boolean", cast: "boolean" },
+  datetime: { type: "datetime", cast: "datetime" },
+  date: { type: "datetime", cast: "date" },
+  json: { type: "json", cast: "json" },
+  array: { type: "json", cast: "array" },
+};
+
+function resolveOptions(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
+  if (arg === undefined) return { type: "string" };
+  if (typeof arg === "string") {
+    const a = arg as string;
+    if (a.startsWith("decimal:"))
+      return { type: "number", cast: a as ColumnOptions["cast"] } as ColumnOptions;
+    if (a === "immutable_datetime")
+      return {
+        type: "datetime",
+        cast: "immutable_datetime" as ColumnOptions["cast"],
+      } as ColumnOptions;
+    return SHORTHAND_MAP[a as ColumnShorthand] ?? { type: "string" };
+  }
+  return arg;
+}
+
+// ── Reactivity ────────────────────────────────────────────────────────────────
+
+function shouldReactive(options: ColumnOptions): boolean {
+  return options.cast === "json" || options.cast === "array" || options.type === "json";
+}
+
+function wrapReactive(
+  instance: unknown,
+  key: string,
+  options: ColumnOptions,
+  value: unknown,
+): unknown {
+  if (!shouldReactive(options)) return value;
+  const ctor = (instance as { constructor?: { reactiveCasts?: boolean } }).constructor;
+  if (!ctor || !ctor.reactiveCasts) return value;
+  return makeReactive(instance as any, key, value);
+}
+
+function defineReactiveProperty(
+  instance: unknown,
+  key: string,
+  options: ColumnOptions,
+  initialValue?: unknown,
+): void {
+  if (!shouldReactive(options)) return;
+
+  const privateKey = `_zerotal_${key}`;
+  const self = instance as Record<string, unknown>;
+  const seed = initialValue !== undefined ? initialValue : self[key];
+  self[privateKey] = wrapReactive(instance, key, options, seed);
+
+  Object.defineProperty(instance, key, {
+    get() {
+      return (this as Record<string, unknown>)[privateKey];
+    },
+    set(value: unknown) {
+      const next = wrapReactive(this, key, options, value);
+      (this as Record<string, unknown>)[privateKey] = next;
+      if ((this as { _exists?: boolean })._exists) {
+        (this as { markDirty: (k: string) => void }).markDirty(key);
+      }
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}
+
+// ── @column() overloads ───────────────────────────────────────────────────────
+
+/** Standard TC39 class-field decorator returned by {@link column}. */
+type ColumnDecorator = (value: undefined, context: ClassFieldDecoratorContext) => void;
+
+/**
+ * Map a model property to a database column.
+ *
+ * @remarks
+ * Applied to a field of a `BaseModel` subclass, `@column` registers that property
+ * in the ORM's column metadata (`columnRegistry`), so it participates in
+ * hydration, dirty-tracking, persistence, and schema generation / auto-migration.
+ *
+ * The argument may be omitted (defaults to a `"string"` column), given as a
+ * {@link ColumnShorthand} string, or given as a full {@link ColumnOptions} object.
+ * Options control the storage `type`, `primary` key, `nullable`, `default`, and —
+ * most importantly — the `cast` that serializes the value between DB and model
+ * (`json`/`array`, `datetime`/`date`, `boolean`, `integer`/`float`, `decimal:n`,
+ * `enum`, or a custom `{ get, set }` / {@link CastContract}). A declared `cast` is
+ * also mirrored onto the class's `static casts` map.
+ *
+ * Timestamp and primary-key conventions themselves are configured on the class via
+ * `@table` (see {@link table}); `@column` only maps individual fields.
+ *
+ * Registration is anchored at class-definition time by the `@table` decorator (a
+ * Bun 1.3.x standard-decorator workaround), so a model that declares columns must
+ * also carry `@table` — or be auto-discovered from `app/models/`.
+ *
+ * @param arg - A {@link ColumnShorthand} string, a {@link ColumnOptions} object, or nothing (defaults to `"string"`).
+ * @returns A class-field decorator that registers the property as a column.
+ *
+ * @example
+ * ```ts
+ * @table("users")
+ * export class User extends BaseModel {
+ *   @column({ primary: true }) id!: number;
+ *
+ *   // No args — defaults to a string column
+ *   @column() name!: string;
+ *
+ *   // String shorthand
+ *   @column("integer") age!: number;
+ *   @column("datetime") createdAt!: Carbon;
+ *
+ *   // Cast a JSON column to/from an array (reactive when `static reactiveCasts`)
+ *   @column({ type: "json", cast: "array", default: [] }) roles!: string[];
+ *
+ *   // Nullable with a custom cast object
+ *   @column({ nullable: true, cast: { get: (v) => v && new URL(String(v)), set: (u) => u?.href } })
+ *   website?: URL | null;
+ * }
+ * ```
+ */
+export function column(): ColumnDecorator;
+export function column(type: ColumnShorthand): ColumnDecorator;
+export function column(options: ColumnOptions): ColumnDecorator;
+export function column(arg?: ColumnShorthand | ColumnOptions): ColumnDecorator {
+  const options = resolveOptions(arg);
+  // The decorator BODY runs synchronously at definition time with the correct
+  // `context.name` (the only thing Bun 1.3.x compiles reliably for field decorators).
+  // We can't defer to a field initializer or addInitializer — Bun cross-wires those
+  // across classes. Instead capture name+options here and enqueue the registration; the
+  // `@table` class decorator drains the queue into the concrete class (see _metadata.ts).
+  return function (_value: undefined, context: ClassFieldDecoratorContext): void {
+    const name = String(context.name);
+    enqueueMember(name, (ctor) => registerColumn(ctor, name, options));
+  };
+}
+
+/**
+ * Install reactive accessors (json/array `reactiveCasts` columns) on a fresh instance.
+ * Called from the model's fill()/hydrate paths — registration now happens at decoration
+ * time, so the per-instance reactive setup is done here rather than in a field initializer.
+ * Idempotent.
+ *
+ * @param instance - The freshly constructed / hydrated model instance to wire.
+ * @internal
+ */
+export function installReactiveAccessors(instance: object): void {
+  const reactive = reactiveColumnsFor(instance.constructor as Function);
+  if (!reactive.length) return;
+  const cols = columnsFor(instance.constructor as Function);
+  for (const name of reactive) {
+    const desc = Object.getOwnPropertyDescriptor(instance, name);
+    if (desc && typeof desc.get === "function") continue; // already installed
+    const opts = cols?.get(name);
+    if (opts) defineReactiveProperty(instance, name, opts);
+  }
+}

package/src/model/decorators/hasMany.ts

@@ -0,0 +1,34 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+/** Options for {@link hasMany}. */
+export interface HasManyOptions {
+  /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
+  foreignKey: string;
+  /** Parent local key the FK references. Defaults to `'id'`. */
+  localKey?: string;
+}
+
+/**
+ * Declare a one-to-many relation: the parent owns many related rows, matched by a
+ * foreign key on the related table (e.g. a `User` has many `Post`s).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - Foreign/local key configuration.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class User extends BaseModel {
+ *   \@hasMany(() => Post, { foreignKey: 'user_id' })
+ *   posts!: HasMany<Post>;
+ * }
+ * ```
+ */
+export function hasMany(related: () => unknown, options: HasManyOptions) {
+  return makeRelationDecorator(() => ({
+    type: "hasMany" as const,
+    related,
+    foreignKey: options.foreignKey,
+    localKey: options.localKey ?? "id",
+  }));
+}

package/src/model/decorators/hasManyThrough.ts

@@ -0,0 +1,50 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+export interface HasManyThroughOptions {
+  /** FK on the through table referencing the parent (e.g. 'country_id' on users). */
+  firstKey: string;
+  /** FK on the related table referencing the through model (e.g. 'user_id' on posts). */
+  secondKey: string;
+  /** Parent local key the firstKey references. Default 'id'. */
+  localKey?: string;
+  /** Through local key the secondKey references. Default 'id'. */
+  throughLocalKey?: string;
+}
+
+/**
+ * Declare a has-many-through relation: reach the related rows across one
+ * intermediate ("through") model — e.g. `Country` —(users.country_id)→ `User`
+ * —(posts.user_id)→ `Post`, so a country has many posts through its users.
+ *
+ * @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 {
+ *   \@hasManyThrough(() => Post, () => User, { firstKey: 'country_id', secondKey: 'user_id' })
+ *   posts!: HasMany<Post>;
+ * }
+ * ```
+ */
+export function hasManyThrough(
+  related: () => unknown,
+  through: () => unknown,
+  options: HasManyThroughOptions,
+) {
+  return makeRelationDecorator(() => ({
+    type: "hasManyThrough" 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/hasOne.ts

@@ -0,0 +1,34 @@
+import { makeRelationDecorator } from "./_registerRelation.ts";
+
+/** Options for {@link hasOne}. */
+export interface HasOneOptions {
+  /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
+  foreignKey: string;
+  /** Parent local key the FK references. Defaults to `'id'`. */
+  localKey?: string;
+}
+
+/**
+ * Declare a one-to-one relation: the parent owns a single related row, matched by
+ * a foreign key on the related table (e.g. a `User` has one `Profile`).
+ *
+ * @param related - Lazy factory returning the related model class.
+ * @param options - Foreign/local key configuration.
+ * @category Relationships
+ *
+ * @example
+ * ```ts
+ * class User extends BaseModel {
+ *   \@hasOne(() => Profile, { foreignKey: 'user_id' })
+ *   profile!: HasOne<Profile>;
+ * }
+ * ```
+ */
+export function hasOne(related: () => unknown, options: HasOneOptions) {
+  return makeRelationDecorator(() => ({
+    type: "hasOne" as const,
+    related,
+    foreignKey: options.foreignKey,
+    localKey: options.localKey ?? "id",
+  }));
+}