metal-orm 1.0.42 → 1.0.44

package/src/query-builder/update-query-state.ts

@@ -14,9 +14,21 @@ import {
 import { JoinNode } from '../core/ast/join.js';
 import { createTableNode } from '../core/ast/builders.js';
 
+/**
+ * Literal values that can be used in UPDATE statements
+ */
 type LiteralValue = string | number | boolean | null;
+
+/**
+ * Values allowed in UPDATE SET clauses
+ */
 type UpdateValue = OperandNode | LiteralValue;
 
+/**
+ * Type guard to check if a value is valid for UPDATE operations
+ * @param value - Value to check
+ * @returns True if value is a valid update value
+ */
 const isUpdateValue = (value: unknown): value is UpdateValue => {
   if (value === null) return true;
   switch (typeof value) {
@@ -36,6 +48,11 @@ export class UpdateQueryState {
   public readonly table: TableDef;
   public readonly ast: UpdateQueryNode;
 
+  /**
+   * Creates a new UpdateQueryState instance
+   * @param table - Table definition for the update
+   * @param ast - Optional existing AST
+   */
   constructor(table: TableDef, ast?: UpdateQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -46,10 +63,20 @@ export class UpdateQueryState {
     };
   }
 
+  /**
+   * Creates a new UpdateQueryState with updated AST
+   * @param nextAst - Updated AST
+   * @returns New UpdateQueryState instance
+   */
   private clone(nextAst: UpdateQueryNode): UpdateQueryState {
     return new UpdateQueryState(this.table, nextAst);
   }
 
+  /**
+   * Sets the columns to update with their new values
+   * @param values - Record of column names to values
+   * @returns New UpdateQueryState with SET clause
+   */
   withSet(values: Record<string, unknown>): UpdateQueryState {
     const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, rawValue]) => {
       if (!isUpdateValue(rawValue)) {
@@ -74,6 +101,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a WHERE condition to the update query
+   * @param expr - WHERE expression
+   * @returns New UpdateQueryState with WHERE clause
+   */
   withWhere(expr: ExpressionNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -81,6 +113,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the update query
+   * @param columns - Columns to return
+   * @returns New UpdateQueryState with RETURNING clause
+   */
   withReturning(columns: ColumnNode[]): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -88,6 +125,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Sets the FROM clause for the update query
+   * @param from - Table source for FROM
+   * @returns New UpdateQueryState with FROM clause
+   */
   withFrom(from: TableSourceNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -95,6 +137,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a JOIN to the update query
+   * @param join - Join node to add
+   * @returns New UpdateQueryState with JOIN
+   */
   withJoin(join: JoinNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -102,6 +149,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Applies an alias to the table being updated
+   * @param alias - Alias for the table
+   * @returns New UpdateQueryState with table alias
+   */
   withTableAlias(alias: string): UpdateQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/update.ts

@@ -2,12 +2,14 @@ import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column.js';
 import { ColumnNode, ExpressionNode } from '../core/ast/expression.js';
 import { JOIN_KINDS, JoinKind } from '../core/sql/sql.js';
-import { CompiledQuery, UpdateCompiler, Dialect } from '../core/dialect/abstract.js';
+import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 import { TableSourceNode, UpdateQueryNode } from '../core/ast/query.js';
 import { UpdateQueryState } from './update-query-state.js';
 import { createJoinNode } from '../core/ast/join-node.js';
 import { buildColumnNode } from '../core/ast/builders.js';
+import { OrmSession } from '../orm/orm-session.js';
+import { QueryResult } from '../core/execution/db-executor.js';
 
 type UpdateDialectInput = Dialect | DialectKey;
 
@@ -18,6 +20,11 @@ export class UpdateQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: UpdateQueryState;
 
+  /**
+   * Creates a new UpdateQueryBuilder instance
+   * @param table - The table definition for the UPDATE query
+   * @param state - Optional initial query state, defaults to a new UpdateQueryState
+   */
   constructor(table: TableDef, state?: UpdateQueryState) {
     this.table = table;
     this.state = state ?? new UpdateQueryState(table);
@@ -27,15 +34,33 @@ export class UpdateQueryBuilder<T> {
     return new UpdateQueryBuilder(this.table, state);
   }
 
+  /**
+   * Sets an alias for the table in the UPDATE query
+   * @param alias - The alias to assign to the table
+   * @returns A new UpdateQueryBuilder with the table alias set
+   */
   as(alias: string): UpdateQueryBuilder<T> {
     return this.clone(this.state.withTableAlias(alias));
   }
 
+  /**
+   * Adds a FROM clause to the UPDATE query
+   * @param source - The table source to use in the FROM clause
+   * @returns A new UpdateQueryBuilder with the FROM clause added
+   */
   from(source: TableDef | TableSourceNode): UpdateQueryBuilder<T> {
     const tableSource = this.resolveTableSource(source);
     return this.clone(this.state.withFrom(tableSource));
   }
 
+  /**
+   * Adds a JOIN clause to the UPDATE query
+   * @param table - The table to join with
+   * @param condition - The join condition expression
+   * @param kind - The type of join (defaults to INNER)
+   * @param relationName - Optional name for the relation
+   * @returns A new UpdateQueryBuilder with the JOIN clause added
+   */
   join(
     table: TableDef | TableSourceNode | string,
     condition: ExpressionNode,
@@ -47,14 +72,29 @@ export class UpdateQueryBuilder<T> {
     return this.clone(this.state.withJoin(joinNode));
   }
 
+  /**
+   * Adds a SET clause to the UPDATE query
+   * @param values - The column-value pairs to update
+   * @returns A new UpdateQueryBuilder with the SET clause added
+   */
   set(values: Record<string, unknown>): UpdateQueryBuilder<T> {
     return this.clone(this.state.withSet(values));
   }
 
+  /**
+   * Adds a WHERE clause to the UPDATE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new UpdateQueryBuilder with the WHERE clause added
+   */
   where(expr: ExpressionNode): UpdateQueryBuilder<T> {
     return this.clone(this.state.withWhere(expr));
   }
 
+  /**
+   * Adds a RETURNING clause to the UPDATE query
+   * @param columns - Columns to return after update
+   * @returns A new UpdateQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): UpdateQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -73,28 +113,39 @@ export class UpdateQueryBuilder<T> {
     return this.resolveTableSource(table);
   }
 
-  // Existing compiler-based compile stays, but we add a new overload.
-
-  // 1) Keep the old behavior (used internally / tests, if any):
-  compile(compiler: UpdateCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
-  compile(dialect: UpdateDialectInput): CompiledQuery;
-
-  compile(arg: UpdateCompiler | UpdateDialectInput): CompiledQuery {
-    if (typeof (arg as any).compileUpdate === 'function') {
-      // UpdateCompiler path – old behavior
-      return (arg as UpdateCompiler).compileUpdate(this.state.ast);
-    }
+  /**
+   * Compiles the UPDATE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect: UpdateDialectInput): CompiledQuery {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileUpdate(this.state.ast);
+  }
 
-    // Dialect | string path – new behavior
-    const dialect = resolveDialectInput(arg as UpdateDialectInput);
-    return dialect.compileUpdate(this.state.ast);
+  /**
+   * Returns the SQL string for the UPDATE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect: UpdateDialectInput): string {
+    return this.compile(dialect).sql;
   }
 
-  toSql(arg: UpdateCompiler | UpdateDialectInput): string {
-    return this.compile(arg as any).sql;
+  /**
+   * Executes the UPDATE query using the provided session
+   * @param session - The ORM session to execute the query with
+   * @returns A promise that resolves to the query results
+   */
+  async execute(session: OrmSession): Promise<QueryResult[]> {
+    const compiled = this.compile(session.dialect);
+    return session.executor.executeSql(compiled.sql, compiled.params);
   }
 
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the UPDATE query
+   */
   getAST(): UpdateQueryNode {
     return this.state.ast;
   }

package/src/schema/column.ts

@@ -100,7 +100,7 @@ export interface ColumnDef<T extends ColumnType = ColumnType, TRuntime = unknown
   /** Column comment/description */
   comment?: string;
   /** Additional arguments for the column type (e.g., VARCHAR length) */
-  args?: any[];
+  args?: unknown[];
   /** Table name this column belongs to (filled at runtime by defineTable) */
   table?: string;
 }
@@ -234,28 +234,28 @@ export const col = {
    * Marks a column as UNIQUE
    */
   unique: <T extends ColumnType>(def: ColumnDef<T>, name?: string): ColumnDef<T> =>
-    ({
-      ...def,
-      unique: name ?? true
-    }),
+  ({
+    ...def,
+    unique: name ?? true
+  }),
 
   /**
    * Sets a default value for the column
    */
   default: <T extends ColumnType>(def: ColumnDef<T>, value: unknown): ColumnDef<T> =>
-    ({
-      ...def,
-      default: value
-    }),
+  ({
+    ...def,
+    default: value
+  }),
 
   /**
    * Sets a raw SQL default value for the column
    */
   defaultRaw: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
-    ({
-      ...def,
-      default: { raw: expression }
-    }),
+  ({
+    ...def,
+    default: { raw: expression }
+  }),
 
   /**
    * Marks a column as auto-increment / identity
@@ -264,27 +264,27 @@ export const col = {
     def: ColumnDef<T>,
     strategy: ColumnDef['generated'] = 'byDefault'
   ): ColumnDef<T> =>
-    ({
-      ...def,
-      autoIncrement: true,
-      generated: strategy
-    }),
+  ({
+    ...def,
+    autoIncrement: true,
+    generated: strategy
+  }),
 
   /**
    * Adds a foreign key reference
    */
   references: <T extends ColumnType>(def: ColumnDef<T>, ref: ForeignKeyReference): ColumnDef<T> =>
-    ({
-      ...def,
-      references: ref
-    }),
+  ({
+    ...def,
+    references: ref
+  }),
 
   /**
    * Adds a check constraint to the column
    */
   check: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
-    ({
-      ...def,
-      check: expression
-    })
+  ({
+    ...def,
+    check: expression
+  })
 };

package/src/schema/table-guards.ts

@@ -0,0 +1,31 @@
+import { ColumnDef } from './column.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;
+};
+
+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

@@ -31,12 +31,12 @@ export interface TableOptions {
 }
 
 export interface TableHooks {
-  beforeInsert?(ctx: unknown, entity: any): Promise<void> | void;
-  afterInsert?(ctx: unknown, entity: any): Promise<void> | void;
-  beforeUpdate?(ctx: unknown, entity: any): Promise<void> | void;
-  afterUpdate?(ctx: unknown, entity: any): Promise<void> | void;
-  beforeDelete?(ctx: unknown, entity: any): Promise<void> | void;
-  afterDelete?(ctx: unknown, entity: any): Promise<void> | void;
+  beforeInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
+  afterInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
+  beforeUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
+  afterUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
+  beforeDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
+  afterDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
 }
 
 /**
@@ -94,7 +94,8 @@ export const defineTable = <T extends Record<string, ColumnDef>>(
 ): TableDef<T> => {
   // Runtime mutability to assign names to column definitions for convenience
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
-    (acc as any)[key] = { ...def, name: key, table: name };
+    const colDef = { ...def, name: key, table: name };
+    (acc as Record<string, unknown>)[key] = colDef;
     return acc;
   }, {} as T);
 
@@ -128,36 +129,39 @@ export type TableRef<T extends TableDef> =
     $: T["columns"];
   };
 
-const TABLE_REF_CACHE: WeakMap<object, any> = new WeakMap();
+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 as any);
+  const cached = TABLE_REF_CACHE.get(table);
   if (cached) return cached as TableRef<T>;
 
-  const proxy = new Proxy(table as any, {
+  const proxy = new Proxy(table as object, {
     get(target, prop, receiver) {
-      if (prop === "$") return target.columns;
+      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 target.columns) return target.columns[prop];
+      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 target.columns)
+        (typeof prop === "string" && prop in t.columns)
       );
     },
 
     ownKeys(target) {
+      const t = target as TableDef;
       const base = Reflect.ownKeys(target);
-      const cols = Object.keys(target.columns);
+      const cols = Object.keys(t.columns);
 
       for (const k of cols) {
         if (!base.includes(k)) base.push(k);
@@ -172,20 +176,20 @@ const withColumnProps = <T extends TableDef>(table: T): TableRef<T> => {
           configurable: true,
           enumerable: false,
           get() {
-            return target.columns;
+            return (target as TableDef).columns;
           },
         };
       }
 
       if (
         typeof prop === "string" &&
-        prop in target.columns &&
+        prop in (target as TableDef).columns &&
         !Reflect.has(target, prop)
       ) {
         return {
           configurable: true,
           enumerable: true,
-          value: target.columns[prop],
+          value: (target as TableDef).columns[prop],
           writable: false,
         };
       }
@@ -194,7 +198,7 @@ const withColumnProps = <T extends TableDef>(table: T): TableRef<T> => {
     },
   }) as TableRef<T>;
 
-  TABLE_REF_CACHE.set(table as any, proxy);
+  TABLE_REF_CACHE.set(table, proxy);
   return proxy;
 };
 
@@ -208,3 +212,28 @@ const withColumnProps = <T extends TableDef>(table: T): TableRef<T> => {
  *   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/schema/types.ts

@@ -23,15 +23,15 @@ export type RelationTargetTable<TRel extends RelationDef> =
  */
 export type ColumnToTs<T extends ColumnDef> =
   [unknown] extends [T['tsType']]
-    ? T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
-      T['type'] extends 'BIGINT' | 'bigint' ? number | bigint :
-      T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number :
-      T['type'] extends 'BOOLEAN' | 'boolean' ? boolean :
-      T['type'] extends 'JSON' | 'json' ? unknown :
-      T['type'] extends 'BLOB' | 'blob' | 'BINARY' | 'binary' | 'VARBINARY' | 'varbinary' | 'BYTEA' | 'bytea' ? Buffer :
-      T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string :
-      string
-    : Exclude<T['tsType'], undefined>;
+  ? T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
+  T['type'] extends 'BIGINT' | 'bigint' ? number | bigint :
+  T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number :
+  T['type'] extends 'BOOLEAN' | 'boolean' ? boolean :
+  T['type'] extends 'JSON' | 'json' ? unknown :
+  T['type'] extends 'BLOB' | 'blob' | 'BINARY' | 'binary' | 'VARBINARY' | 'varbinary' | 'BYTEA' | 'bytea' ? Buffer :
+  T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string :
+  string
+  : Exclude<T['tsType'], undefined>;
 
 /**
  * Infers a row shape from a table definition
@@ -41,10 +41,10 @@ export type InferRow<TTable extends TableDef> = {
 };
 
 type RelationResult<T extends RelationDef> =
-  T extends HasManyRelation<infer TTarget>        ? InferRow<TTarget>[] :
-  T extends HasOneRelation<infer TTarget>         ? InferRow<TTarget> | null :
-  T extends BelongsToRelation<infer TTarget>      ? InferRow<TTarget> | null :
-  T extends BelongsToManyRelation<infer TTarget>  ? (InferRow<TTarget> & { _pivot?: any })[] :
+  T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
+  T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & { _pivot?: unknown })[] :
   never;
 
 /**
@@ -88,15 +88,15 @@ export type EntityInstance<
   TRow = InferRow<TTable>
 > = TRow & {
   [K in keyof RelationMap<TTable>]:
-    TTable['relations'][K] extends HasManyRelation<infer TTarget>
-      ? HasManyCollection<EntityInstance<TTarget>>
-      : TTable['relations'][K] extends HasOneRelation<infer TTarget>
-        ? HasOneReference<EntityInstance<TTarget>>
-        : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
-          ? ManyToManyCollection<EntityInstance<TTarget>>
-          : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
-            ? BelongsToReference<EntityInstance<TTarget>>
-            : never;
+  TTable['relations'][K] extends HasManyRelation<infer TTarget>
+  ? HasManyCollection<EntityInstance<TTarget>>
+  : TTable['relations'][K] extends HasOneRelation<infer TTarget>
+  ? HasOneReference<EntityInstance<TTarget>>
+  : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
+  ? ManyToManyCollection<EntityInstance<TTarget>>
+  : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
+  ? BelongsToReference<EntityInstance<TTarget>>
+  : never;
 } & {
   $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
 };