metal-orm 1.1.11 → 1.1.16

package/src/schema/table-guards.ts

@@ -1,37 +1,37 @@
-import { ColumnDef } from './column-types.js';
-import type { TableDef } from './table.js';
-
-const isColumnsRecord = (columns: unknown): columns is Record<string, ColumnDef> => {
-    return typeof columns === 'object' && columns !== null;
-};
-
-const isRelationsRecord = (relations: unknown): relations is Record<string, unknown> => {
-    return typeof relations === 'object' && relations !== null;
-};
-
-/**
- * Type guard that checks if a value is a TableDef.
- * 
- * @param value The value to check.
- * @returns True if the value follows the TableDef structure.
- */
-export const isTableDef = (value: unknown): value is TableDef => {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-
-    const candidate = value as Partial<TableDef>;
-    if (typeof candidate.name !== 'string') {
-        return false;
-    }
-
-    if (!isColumnsRecord(candidate.columns)) {
-        return false;
-    }
-
-    if (!isRelationsRecord(candidate.relations)) {
-        return false;
-    }
-
-    return true;
-};
+import { ColumnDef } from './column-types.js';
+import type { TableDef } from './table.js';
+
+const isColumnsRecord = (columns: unknown): columns is Record<string, ColumnDef> => {
+    return typeof columns === 'object' && columns !== null;
+};
+
+const isRelationsRecord = (relations: unknown): relations is Record<string, unknown> => {
+    return typeof relations === 'object' && relations !== null;
+};
+
+/**
+ * Type guard that checks if a value is a TableDef.
+ * 
+ * @param value The value to check.
+ * @returns True if the value follows the TableDef structure.
+ */
+export const isTableDef = (value: unknown): value is TableDef => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+
+    const candidate = value as Partial<TableDef>;
+    if (typeof candidate.name !== 'string') {
+        return false;
+    }
+
+    if (!isColumnsRecord(candidate.columns)) {
+        return false;
+    }
+
+    if (!isRelationsRecord(candidate.relations)) {
+        return false;
+    }
+
+    return true;
+};

package/src/schema/table.ts

@@ -1,281 +1,281 @@
-import type { ColumnDef } from './column-types.js';
-import type { RelationDef } from './relation.js';
-
-export interface IndexColumn {
-  column: string;
-  order?: 'ASC' | 'DESC';
-  nulls?: 'FIRST' | 'LAST';
-}
-
-export interface IndexDef {
-  name?: string;
-  columns: (string | IndexColumn)[];
-  unique?: boolean;
-  where?: string;
-}
-
-export interface CheckConstraint {
-  name?: string;
-  expression: string;
-}
-
-export interface TableOptions {
-  schema?: string;
-  primaryKey?: string[];
-  indexes?: IndexDef[];
-  checks?: CheckConstraint[];
-  comment?: string;
-  engine?: string;
-  charset?: string;
-  collation?: string;
-}
-
-export interface TableHooks<TEntity = unknown, TContext = unknown> {
-  beforeInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  beforeUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  beforeDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
-  afterDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
-}
-
-/**
- * Definition of a database table with its columns and relationships
- * @typeParam T - Type of the columns record
- */
-export interface TableDef<
-  T extends Record<string, ColumnDef> = Record<string, ColumnDef>,
-  TEntity = unknown,
-  TContext = unknown
-> {
-  /** Name of the table */
-  name: string;
-  /** Optional schema/catalog name */
-  schema?: string;
-  /** Record of column definitions keyed by column name */
-  columns: T;
-  /** Record of relationship definitions keyed by relation name */
-  relations: Record<string, RelationDef>;
-  /** Optional lifecycle hooks */
-  hooks?: TableHooks<TEntity, TContext>;
-  /** Composite primary key definition (falls back to column.primary flags) */
-  primaryKey?: string[];
-  /** Secondary indexes */
-  indexes?: IndexDef[];
-  /** Table-level check constraints */
-  checks?: CheckConstraint[];
-  /** Table comment/description */
-  comment?: string;
-  /** Dialect-specific options */
-  engine?: string;
-  charset?: string;
-  collation?: string;
-}
-
-/**
- * Creates a table definition with columns and relationships
- * @typeParam T - Type of the columns record
- * @param name - Name of the table
- * @param columns - Record of column definitions
- * @param relations - Record of relationship definitions (optional)
- * @returns Complete table definition with runtime-filled column metadata
- *
- * @example
- * ```typescript
- * const usersTable = defineTable('users', {
- *   id: col.primaryKey(col.int()),
- *   name: col.varchar(255),
- *   email: col.varchar(255)
- * });
- * ```
- */
-export const defineTable = <
-  T extends Record<string, ColumnDef>,
-  TEntity = unknown,
-  TContext = unknown
->(
-  name: string,
-  columns: T,
-  relations: Record<string, RelationDef> = {},
-  hooks?: TableHooks<TEntity, TContext>,
-  options: TableOptions = {}
-): TableDef<T, TEntity, TContext> => {
-  // Runtime mutability to assign names to column definitions for convenience
-  const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
-    const colDef = { ...def, name: key, table: name };
-    (acc as Record<string, unknown>)[key] = colDef;
-    return acc;
-  }, {} as T);
-
-  return {
-    name,
-    schema: options.schema,
-    columns: colsWithNames,
-    relations,
-    hooks,
-    primaryKey: options.primaryKey,
-    indexes: options.indexes,
-    checks: options.checks,
-    comment: options.comment,
-    engine: options.engine,
-    charset: options.charset,
-    collation: options.collation
-  };
-};
-
-/**
- * Assigns relations to a table definition while preserving literal typing.
- */
-export function setRelations<
-  TTable extends TableDef,
-  TRelations extends Record<string, RelationDef>
->(
-  table: TTable,
-  relations: TRelations
-): asserts table is TTable & { relations: TRelations } {
-  table.relations = relations;
-}
-
-/**
- * Adds (or replaces) a single named relation on an existing table definition.
- * Safe to call at any time — before or after queries are built.
- *
- * @param table - The table definition to mutate
- * @param name  - The relation name (property key used in `.include()` / hydration)
- * @param relation - The fully-resolved relation definition
- *
- * @example
- * ```ts
- * addRelation(usersTable, 'comments', hasMany(commentsTable, 'user_id'));
- * ```
- */
-export function addRelation<TTable extends TableDef>(
-  table: TTable,
-  name: string,
-  relation: RelationDef
-): void {
-  table.relations[name] = relation;
-}
-
-type DirectColumnKeys<T extends TableDef> =
-  Exclude<keyof T["columns"] & string, keyof T | "$">;
-
-export type TableRef<T extends TableDef> =
-  T &
-  { [K in DirectColumnKeys<T>]: T["columns"][K] } & {
-    /**
-     * Escape hatch for collisions:
-     * - tref.name  => table name (string)
-     * - tref.$.name => column def for "name"
-     */
-    $: T["columns"];
-  };
-
-const TABLE_REF_CACHE: WeakMap<object, unknown> = new WeakMap();
-
-const withColumnProps = <T extends TableDef>(table: T): TableRef<T> => {
-  const cached = TABLE_REF_CACHE.get(table);
-  if (cached) return cached as TableRef<T>;
-
-  const proxy = new Proxy(table as object, {
-    get(target, prop, receiver) {
-      const t = target as TableDef;
-      if (prop === "$") return t.columns;
-
-      // Prefer real table fields first (prevents collision surprises)
-      if (Reflect.has(target, prop)) return Reflect.get(target, prop, receiver);
-
-      // Fall back to columns bag
-      if (typeof prop === "string" && prop in t.columns) return t.columns[prop];
-
-      return undefined;
-    },
-
-    has(target, prop) {
-      const t = target as TableDef;
-      return (
-        prop === "$" ||
-        Reflect.has(target, prop) ||
-        (typeof prop === "string" && prop in t.columns)
-      );
-    },
-
-    ownKeys(target) {
-      const t = target as TableDef;
-      const base = Reflect.ownKeys(target);
-      const cols = Object.keys(t.columns);
-
-      for (const k of cols) {
-        if (!base.includes(k)) base.push(k);
-      }
-      if (!base.includes("$")) base.push("$");
-      return base;
-    },
-
-    getOwnPropertyDescriptor(target, prop) {
-      if (prop === "$") {
-        return {
-          configurable: true,
-          enumerable: false,
-          get() {
-            return (target as TableDef).columns;
-          },
-        };
-      }
-
-      if (
-        typeof prop === "string" &&
-        prop in (target as TableDef).columns &&
-        !Reflect.has(target, prop)
-      ) {
-        return {
-          configurable: true,
-          enumerable: true,
-          value: (target as TableDef).columns[prop],
-          writable: false,
-        };
-      }
-
-      return Reflect.getOwnPropertyDescriptor(target, prop);
-    },
-  }) as TableRef<T>;
-
-  TABLE_REF_CACHE.set(table, proxy);
-  return proxy;
-};
-
-/**
- * Public API: opt-in ergonomic table reference.
- * Usage:
- *   const t = tableRef(todos);
- *   qb.where(eq(t.done, false)).orderBy(t.id, "ASC");
- * Collisions:
- *   t.name is the table name (real field)
- *   t.$.name is the "name" column (escape hatch)
- */
-export const tableRef = <T extends TableDef>(table: T): TableRef<T> => withColumnProps(table);
-
-/**
- * Public API: dynamic column lookup by string key.
- *
- * Useful when the column name is only known at runtime, or when a column name
- * collides with a real table field (e.g. "name").
- *
- * @example
- * ```ts
- * const t = tableRef(todos);
- * const key = runtimeKey();
- * where(eq(getColumn(t, key), 123));
- * // or: t.$.name (escape hatch)
- * ```
- */
-export function getColumn<T extends TableDef, K extends keyof T['columns'] & string>(table: T, key: K): T['columns'][K];
-export function getColumn<T extends TableDef>(table: T, key: string): ColumnDef;
-export function getColumn<T extends TableDef>(table: T, key: string): ColumnDef {
-  const col = table.columns[key] as ColumnDef | undefined;
-  if (!col) {
-    const tableName = table.name || '<unknown>';
-    throw new Error(`Column '${key}' does not exist on table '${tableName}'`);
-  }
-  return col;
-}
+import type { ColumnDef } from './column-types.js';
+import type { RelationDef } from './relation.js';
+
+export interface IndexColumn {
+  column: string;
+  order?: 'ASC' | 'DESC';
+  nulls?: 'FIRST' | 'LAST';
+}
+
+export interface IndexDef {
+  name?: string;
+  columns: (string | IndexColumn)[];
+  unique?: boolean;
+  where?: string;
+}
+
+export interface CheckConstraint {
+  name?: string;
+  expression: string;
+}
+
+export interface TableOptions {
+  schema?: string;
+  primaryKey?: string[];
+  indexes?: IndexDef[];
+  checks?: CheckConstraint[];
+  comment?: string;
+  engine?: string;
+  charset?: string;
+  collation?: string;
+}
+
+export interface TableHooks<TEntity = unknown, TContext = unknown> {
+  beforeInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterInsert?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterUpdate?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  beforeDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
+  afterDelete?(ctx: TContext, entity: TEntity): Promise<void> | void;
+}
+
+/**
+ * Definition of a database table with its columns and relationships
+ * @typeParam T - Type of the columns record
+ */
+export interface TableDef<
+  T extends Record<string, ColumnDef> = Record<string, ColumnDef>,
+  TEntity = unknown,
+  TContext = unknown
+> {
+  /** Name of the table */
+  name: string;
+  /** Optional schema/catalog name */
+  schema?: string;
+  /** Record of column definitions keyed by column name */
+  columns: T;
+  /** Record of relationship definitions keyed by relation name */
+  relations: Record<string, RelationDef>;
+  /** Optional lifecycle hooks */
+  hooks?: TableHooks<TEntity, TContext>;
+  /** Composite primary key definition (falls back to column.primary flags) */
+  primaryKey?: string[];
+  /** Secondary indexes */
+  indexes?: IndexDef[];
+  /** Table-level check constraints */
+  checks?: CheckConstraint[];
+  /** Table comment/description */
+  comment?: string;
+  /** Dialect-specific options */
+  engine?: string;
+  charset?: string;
+  collation?: string;
+}
+
+/**
+ * Creates a table definition with columns and relationships
+ * @typeParam T - Type of the columns record
+ * @param name - Name of the table
+ * @param columns - Record of column definitions
+ * @param relations - Record of relationship definitions (optional)
+ * @returns Complete table definition with runtime-filled column metadata
+ *
+ * @example
+ * ```typescript
+ * const usersTable = defineTable('users', {
+ *   id: col.primaryKey(col.int()),
+ *   name: col.varchar(255),
+ *   email: col.varchar(255)
+ * });
+ * ```
+ */
+export const defineTable = <
+  T extends Record<string, ColumnDef>,
+  TEntity = unknown,
+  TContext = unknown
+>(
+  name: string,
+  columns: T,
+  relations: Record<string, RelationDef> = {},
+  hooks?: TableHooks<TEntity, TContext>,
+  options: TableOptions = {}
+): TableDef<T, TEntity, TContext> => {
+  // Runtime mutability to assign names to column definitions for convenience
+  const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
+    const colDef = { ...def, name: key, table: name };
+    (acc as Record<string, unknown>)[key] = colDef;
+    return acc;
+  }, {} as T);
+
+  return {
+    name,
+    schema: options.schema,
+    columns: colsWithNames,
+    relations,
+    hooks,
+    primaryKey: options.primaryKey,
+    indexes: options.indexes,
+    checks: options.checks,
+    comment: options.comment,
+    engine: options.engine,
+    charset: options.charset,
+    collation: options.collation
+  };
+};
+
+/**
+ * Assigns relations to a table definition while preserving literal typing.
+ */
+export function setRelations<
+  TTable extends TableDef,
+  TRelations extends Record<string, RelationDef>
+>(
+  table: TTable,
+  relations: TRelations
+): asserts table is TTable & { relations: TRelations } {
+  table.relations = relations;
+}
+
+/**
+ * Adds (or replaces) a single named relation on an existing table definition.
+ * Safe to call at any time — before or after queries are built.
+ *
+ * @param table - The table definition to mutate
+ * @param name  - The relation name (property key used in `.include()` / hydration)
+ * @param relation - The fully-resolved relation definition
+ *
+ * @example
+ * ```ts
+ * addRelation(usersTable, 'comments', hasMany(commentsTable, 'user_id'));
+ * ```
+ */
+export function addRelation<TTable extends TableDef>(
+  table: TTable,
+  name: string,
+  relation: RelationDef
+): void {
+  table.relations[name] = relation;
+}
+
+type DirectColumnKeys<T extends TableDef> =
+  Exclude<keyof T["columns"] & string, keyof T | "$">;
+
+export type TableRef<T extends TableDef> =
+  T &
+  { [K in DirectColumnKeys<T>]: T["columns"][K] } & {
+    /**
+     * Escape hatch for collisions:
+     * - tref.name  => table name (string)
+     * - tref.$.name => column def for "name"
+     */
+    $: T["columns"];
+  };
+
+const TABLE_REF_CACHE: WeakMap<object, unknown> = new WeakMap();
+
+const withColumnProps = <T extends TableDef>(table: T): TableRef<T> => {
+  const cached = TABLE_REF_CACHE.get(table);
+  if (cached) return cached as TableRef<T>;
+
+  const proxy = new Proxy(table as object, {
+    get(target, prop, receiver) {
+      const t = target as TableDef;
+      if (prop === "$") return t.columns;
+
+      // Prefer real table fields first (prevents collision surprises)
+      if (Reflect.has(target, prop)) return Reflect.get(target, prop, receiver);
+
+      // Fall back to columns bag
+      if (typeof prop === "string" && prop in t.columns) return t.columns[prop];
+
+      return undefined;
+    },
+
+    has(target, prop) {
+      const t = target as TableDef;
+      return (
+        prop === "$" ||
+        Reflect.has(target, prop) ||
+        (typeof prop === "string" && prop in t.columns)
+      );
+    },
+
+    ownKeys(target) {
+      const t = target as TableDef;
+      const base = Reflect.ownKeys(target);
+      const cols = Object.keys(t.columns);
+
+      for (const k of cols) {
+        if (!base.includes(k)) base.push(k);
+      }
+      if (!base.includes("$")) base.push("$");
+      return base;
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop === "$") {
+        return {
+          configurable: true,
+          enumerable: false,
+          get() {
+            return (target as TableDef).columns;
+          },
+        };
+      }
+
+      if (
+        typeof prop === "string" &&
+        prop in (target as TableDef).columns &&
+        !Reflect.has(target, prop)
+      ) {
+        return {
+          configurable: true,
+          enumerable: true,
+          value: (target as TableDef).columns[prop],
+          writable: false,
+        };
+      }
+
+      return Reflect.getOwnPropertyDescriptor(target, prop);
+    },
+  }) as TableRef<T>;
+
+  TABLE_REF_CACHE.set(table, proxy);
+  return proxy;
+};
+
+/**
+ * Public API: opt-in ergonomic table reference.
+ * Usage:
+ *   const t = tableRef(todos);
+ *   qb.where(eq(t.done, false)).orderBy(t.id, "ASC");
+ * Collisions:
+ *   t.name is the table name (real field)
+ *   t.$.name is the "name" column (escape hatch)
+ */
+export const tableRef = <T extends TableDef>(table: T): TableRef<T> => withColumnProps(table);
+
+/**
+ * Public API: dynamic column lookup by string key.
+ *
+ * Useful when the column name is only known at runtime, or when a column name
+ * collides with a real table field (e.g. "name").
+ *
+ * @example
+ * ```ts
+ * const t = tableRef(todos);
+ * const key = runtimeKey();
+ * where(eq(getColumn(t, key), 123));
+ * // or: t.$.name (escape hatch)
+ * ```
+ */
+export function getColumn<T extends TableDef, K extends keyof T['columns'] & string>(table: T, key: K): T['columns'][K];
+export function getColumn<T extends TableDef>(table: T, key: string): ColumnDef;
+export function getColumn<T extends TableDef>(table: T, key: string): ColumnDef {
+  const col = table.columns[key] as ColumnDef | undefined;
+  if (!col) {
+    const tableName = table.name || '<unknown>';
+    throw new Error(`Column '${key}' does not exist on table '${tableName}'`);
+  }
+  return col;
+}

package/src/tree/index.ts

@@ -1,13 +1,13 @@
-/**
- * MetalORM Tree Behavior
- * 
- * Provides support for hierarchical data using the Nested Set (MPTT) model.
- * 
- * @module tree
- */
-
-export * from './tree-types.js';
-export * from './nested-set-strategy.js';
-export * from './tree-query.js';
-export * from './tree-manager.js';
-export * from './tree-decorator.js';
+/**
+ * MetalORM Tree Behavior
+ * 
+ * Provides support for hierarchical data using the Nested Set (MPTT) model.
+ * 
+ * @module tree
+ */
+
+export * from './tree-types.js';
+export * from './nested-set-strategy.js';
+export * from './tree-query.js';
+export * from './tree-manager.js';
+export * from './tree-decorator.js';