metal-orm 1.0.42 → 1.0.44

package/src/core/functions/text.ts

@@ -6,7 +6,7 @@ import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
 
 type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
 
-const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
 
 const toOperand = (input: OperandInput): OperandNode => {
   if (isOperandNode(input)) return input;
@@ -23,22 +23,30 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
 });
 
 /**
- * Helper: LOWER(str)
+ * Converts a string to lowercase.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LOWER SQL function.
  */
 export const lower = (value: OperandInput): FunctionNode => fn('LOWER', [value]);
 
 /**
- * Helper: UPPER(str)
+ * Converts a string to uppercase.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the UPPER SQL function.
  */
 export const upper = (value: OperandInput): FunctionNode => fn('UPPER', [value]);
 
 /**
- * Helper: ASCII(str)
+ * Returns the ASCII code of the first character of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the ASCII SQL function.
  */
 export const ascii = (value: OperandInput): FunctionNode => fn('ASCII', [value]);
 
 /**
- * Helper: CHAR(code[, code...])
+ * Returns a string from one or more ASCII codes.
+ * @param codes - The ASCII codes.
+ * @returns A FunctionNode representing the CHAR SQL function.
  */
 export const char = (...codes: OperandInput[]): FunctionNode => {
   if (codes.length === 0) throw new Error('char() expects at least 1 argument');
@@ -46,33 +54,46 @@ export const char = (...codes: OperandInput[]): FunctionNode => {
 };
 
 /**
- * Helper: CHAR_LENGTH(str)
+ * Returns the number of characters in a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
  */
 export const charLength = (value: OperandInput): FunctionNode => fn('CHAR_LENGTH', [value]);
 
 /**
- * Helper: LENGTH(str)
+ * Returns the length of a string in bytes or characters.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LENGTH SQL function.
  */
 export const length = (value: OperandInput): FunctionNode => fn('LENGTH', [value]);
 
 /**
- * Helper: TRIM([chars FROM] str)
+ * Removes leading and trailing whitespace or specified characters from a string.
+ * @param value - The string value.
+ * @param chars - The characters to trim (optional).
+ * @returns A FunctionNode representing the TRIM SQL function.
  */
 export const trim = (value: OperandInput, chars?: OperandInput): FunctionNode =>
   chars === undefined ? fn('TRIM', [value]) : fn('TRIM', [value, chars]);
 
 /**
- * Helper: LTRIM(str)
+ * Removes leading whitespace from a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the LTRIM SQL function.
  */
 export const ltrim = (value: OperandInput): FunctionNode => fn('LTRIM', [value]);
 
 /**
- * Helper: RTRIM(str)
+ * Removes trailing whitespace from a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the RTRIM SQL function.
  */
 export const rtrim = (value: OperandInput): FunctionNode => fn('RTRIM', [value]);
 
 /**
- * Helper: CONCAT(arg1, arg2, ...)
+ * Concatenates two or more strings.
+ * @param args - The strings to concatenate.
+ * @returns A FunctionNode representing the CONCAT SQL function.
  */
 export const concat = (...args: OperandInput[]): FunctionNode => {
   if (args.length < 2) throw new Error('concat() expects at least 2 arguments');
@@ -80,7 +101,10 @@ export const concat = (...args: OperandInput[]): FunctionNode => {
 };
 
 /**
- * Helper: CONCAT_WS(separator, arg1, arg2, ...)
+ * Concatenates strings with a separator.
+ * @param separator - The separator string.
+ * @param args - The strings to concatenate.
+ * @returns A FunctionNode representing the CONCAT_WS SQL function.
  */
 export const concatWs = (separator: OperandInput, ...args: OperandInput[]): FunctionNode => {
   if (args.length < 1) throw new Error('concatWs() expects at least 2 arguments including the separator');
@@ -88,61 +112,98 @@ export const concatWs = (separator: OperandInput, ...args: OperandInput[]): Func
 };
 
 /**
- * Helper: SUBSTR(str, start[, length])
+ * Extracts a substring from a string.
+ * @param value - The string value.
+ * @param start - The starting position.
+ * @param length - The length of the substring (optional).
+ * @returns A FunctionNode representing the SUBSTR SQL function.
  */
 export const substr = (value: OperandInput, start: OperandInput, length?: OperandInput): FunctionNode =>
   length === undefined ? fn('SUBSTR', [value, start]) : fn('SUBSTR', [value, start, length]);
 
 /**
- * Helper: LEFT(str, length)
+ * Returns the leftmost characters of a string.
+ * @param value - The string value.
+ * @param len - The number of characters to return.
+ * @returns A FunctionNode representing the LEFT SQL function.
  */
 export const left = (value: OperandInput, len: OperandInput): FunctionNode => fn('LEFT', [value, len]);
 
 /**
- * Helper: RIGHT(str, length)
+ * Returns the rightmost characters of a string.
+ * @param value - The string value.
+ * @param len - The number of characters to return.
+ * @returns A FunctionNode representing the RIGHT SQL function.
  */
 export const right = (value: OperandInput, len: OperandInput): FunctionNode => fn('RIGHT', [value, len]);
 
 /**
- * Helper: POSITION(substring IN string)
+ * Returns the position of a substring in a string.
+ * @param substring - The substring to search for.
+ * @param value - The string to search in.
+ * @returns A FunctionNode representing the POSITION SQL function.
  */
 export const position = (substring: OperandInput, value: OperandInput): FunctionNode => fn('POSITION', [substring, value]);
 
 /**
- * Helper: INSTR(string, substring)
+ * Returns the position of a substring in a string.
+ * @param value - The string to search in.
+ * @param substring - The substring to search for.
+ * @returns A FunctionNode representing the INSTR SQL function.
  */
 export const instr = (value: OperandInput, substring: OperandInput): FunctionNode => fn('INSTR', [value, substring]);
 
 /**
- * Helper: LOCATE(substring, string[, start])
+ * Returns the position of a substring in a string, optionally starting from a position.
+ * @param substring - The substring to search for.
+ * @param value - The string to search in.
+ * @param start - The starting position (optional).
+ * @returns A FunctionNode representing the LOCATE SQL function.
  */
 export const locate = (substring: OperandInput, value: OperandInput, start?: OperandInput): FunctionNode =>
   start === undefined ? fn('LOCATE', [substring, value]) : fn('LOCATE', [substring, value, start]);
 
 /**
- * Helper: REPLACE(string, search, replace)
+ * Replaces occurrences of a substring in a string.
+ * @param value - The string to search in.
+ * @param search - The substring to replace.
+ * @param replacement - The replacement string.
+ * @returns A FunctionNode representing the REPLACE SQL function.
  */
 export const replace = (value: OperandInput, search: OperandInput, replacement: OperandInput): FunctionNode =>
   fn('REPLACE', [value, search, replacement]);
 
 /**
- * Helper: REPEAT(string, count)
+ * Repeats a string a specified number of times.
+ * @param value - The string to repeat.
+ * @param count - The number of times to repeat.
+ * @returns A FunctionNode representing the REPEAT SQL function.
  */
 export const repeat = (value: OperandInput, count: OperandInput): FunctionNode => fn('REPEAT', [value, count]);
 
 /**
- * Helper: LPAD(string, length, padstr)
+ * Left-pads a string to a certain length with another string.
+ * @param value - The string to pad.
+ * @param len - The length to pad to.
+ * @param pad - The padding string.
+ * @returns A FunctionNode representing the LPAD SQL function.
  */
 export const lpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
   fn('LPAD', [value, len, pad]);
 
 /**
- * Helper: RPAD(string, length, padstr)
+ * Right-pads a string to a certain length with another string.
+ * @param value - The string to pad.
+ * @param len - The length to pad to.
+ * @param pad - The padding string.
+ * @returns A FunctionNode representing the RPAD SQL function.
  */
 export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
   fn('RPAD', [value, len, pad]);
 
 /**
- * Helper: SPACE(count)
+ * Returns a string consisting of a specified number of spaces.
+ * @param count - The number of spaces.
+ * @returns A FunctionNode representing the SPACE SQL function.
  */
 export const space = (count: OperandInput): FunctionNode => fn('SPACE', [count]);

package/src/core/functions/types.ts

@@ -1,18 +1,33 @@
-import { FunctionNode, OperandNode } from '../ast/expression.js';
-
-export interface FunctionRenderContext {
-    node: FunctionNode;
-    compiledArgs: string[];
-    /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
-    compileOperand: (operand: OperandNode) => string;
-}
+import { FunctionNode, OperandNode } from '../ast/expression.js';
 
+/**
+ * Context provided to function renderers.
+ */
+export interface FunctionRenderContext {
+    /** The function node being rendered. */
+    node: FunctionNode;
+    /** The compiled arguments for the function. */
+    compiledArgs: string[];
+    /** Helper to compile additional operands (e.g., separators or ORDER BY columns). */
+    compileOperand: (operand: OperandNode) => string;
+}
+
+/**
+ * A function that renders a SQL function call.
+ * @param ctx - The rendering context.
+ * @returns The rendered SQL string.
+ */
 export type FunctionRenderer = (ctx: FunctionRenderContext) => string;
 
+/**
+ * Strategy for rendering SQL functions in a specific dialect.
+ */
 export interface FunctionStrategy {
     /**
      * Returns a renderer for a specific function name (e.g. "DATE_ADD").
      * Returns undefined if this dialect doesn't support the function.
+     * @param functionName - The name of the function.
+     * @returns The renderer function or undefined.
      */
     getRenderer(functionName: string): FunctionRenderer | undefined;
 }

package/src/decorators/bootstrap.ts

@@ -8,6 +8,7 @@ import {
   type RelationDef
 } from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
+import { isTableDef } from '../schema/table-guards.js';
 import {
   buildTableDef,
   EntityConstructor,
@@ -18,11 +19,10 @@ import {
   RelationMetadata
 } from '../orm/entity-metadata.js';
 
-const isTableDef = (value: unknown): value is TableDef => {
-  return typeof value === 'object' && value !== null && 'columns' in (value as TableDef);
-};
+import { tableRef, type TableRef } from '../schema/table.js';
 
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   if (typeof target === 'function' && (target as Function).prototype === undefined) {
     return (target as () => EntityOrTableTarget)();
   }
@@ -31,22 +31,22 @@ const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget
 
 const resolveTableTarget = (
   target: EntityOrTableTargetResolver,
-  tableMap: Map<EntityConstructor<any>, TableDef>
+  tableMap: Map<EntityConstructor, TableDef>
 ): TableDef => {
   const resolved = unwrapTarget(target);
   if (isTableDef(resolved)) {
     return resolved;
   }
-  const table = tableMap.get(resolved as EntityConstructor<any>);
+  const table = tableMap.get(resolved as EntityConstructor);
   if (!table) {
-    throw new Error(`Entity '${(resolved as EntityConstructor<any>).name}' is not registered with decorators`);
+    throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
   }
   return table;
 };
 
 const buildRelationDefinitions = (
   meta: { relations: Record<string, RelationMetadata> },
-  tableMap: Map<EntityConstructor<any>, TableDef>
+  tableMap: Map<EntityConstructor, TableDef>
 ): Record<string, RelationDef> => {
   const relations: Record<string, RelationDef> = {};
 
@@ -101,9 +101,13 @@ const buildRelationDefinitions = (
   return relations;
 };
 
+/**
+ * Bootstraps all entities by building their table definitions and relations.
+ * @returns An array of table definitions for all bootstrapped entities.
+ */
 export const bootstrapEntities = (): TableDef[] => {
   const metas = getAllEntityMetadata();
-  const tableMap = new Map<EntityConstructor<any>, TableDef>();
+  const tableMap = new Map<EntityConstructor, TableDef>();
 
   for (const meta of metas) {
     const table = buildTableDef(meta);
@@ -119,7 +123,13 @@ export const bootstrapEntities = (): TableDef[] => {
   return metas.map(meta => meta.table!) as TableDef[];
 };
 
-export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>): TTable | undefined => {
+/**
+ * Gets the table definition for a given entity constructor.
+ * Bootstraps entities if necessary.
+ * @param ctor - The entity constructor.
+ * @returns The table definition or undefined if not found.
+ */
+export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor): TTable | undefined => {
   const meta = getEntityMetadata(ctor);
   if (!meta) return undefined;
   if (!meta.table) {
@@ -128,12 +138,33 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
   return meta.table as TTable;
 };
 
+/**
+ * Creates a select query builder for the given entity.
+ * @param ctor - The entity constructor.
+ * @returns A select query builder for the entity.
+ */
 export const selectFromEntity = <TTable extends TableDef = TableDef>(
-  ctor: EntityConstructor<any>
-): SelectQueryBuilder<any, TTable> => {
+  ctor: EntityConstructor
+): SelectQueryBuilder<unknown, TTable> => {
   const table = getTableDefFromEntity(ctor);
   if (!table) {
     throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
   return new SelectQueryBuilder(table as TTable);
 };
+
+/**
+ * Public API: opt-in ergonomic entity reference (decorator-level).
+ *
+ * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
+ * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
+ */
+export const entityRef = <TTable extends TableDef = TableDef>(
+  ctor: EntityConstructor
+): TableRef<TTable> => {
+  const table = getTableDefFromEntity<TTable>(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+  }
+  return tableRef(table);
+};

package/src/decorators/column.ts

@@ -9,10 +9,12 @@ import {
   DualModePropertyDecorator,
   getOrCreateMetadataBag,
   isStandardDecoratorContext,
-  registerInitializer,
   StandardDecoratorContext
 } from './decorator-metadata.js';
 
+/**
+ * Options for defining a column in an entity.
+ */
 export interface ColumnOptions {
   type: ColumnType;
   args?: ColumnDef['args'];
@@ -21,7 +23,10 @@ export interface ColumnOptions {
   tsType?: ColumnDef['tsType'];
 }
 
-export type ColumnInput = ColumnOptions | ColumnDef<any, any>;
+/**
+ * Input type for column definitions, either as options object or direct ColumnDef.
+ */
+export type ColumnInput = ColumnOptions | ColumnDef;
 
 const normalizeColumnInput = (input: ColumnInput): ColumnDefLike => {
   const asOptions = input as ColumnOptions;
@@ -60,8 +65,8 @@ const resolveConstructor = (target: unknown): EntityConstructor | undefined => {
     return target as EntityConstructor;
   }
 
-  if (target && typeof (target as any).constructor === 'function') {
-    return (target as any).constructor as EntityConstructor;
+  if (target && typeof (target as { constructor: unknown }).constructor === 'function') {
+    return (target as { constructor: unknown }).constructor as EntityConstructor;
   }
 
   return undefined;
@@ -88,15 +93,13 @@ const registerColumnFromContext = (
     bag.columns.push({ propertyName, column: { ...column } });
   }
 
-  registerInitializer(context, function () {
-    const ctor = resolveConstructor(this);
-    if (!ctor) {
-      return;
-    }
-    registerColumn(ctor, propertyName, column);
-  });
 };
 
+/**
+ * Decorator to define a column on an entity property.
+ * @param definition - The column definition or options.
+ * @returns A property decorator that registers the column metadata.
+ */
 export function Column(definition: ColumnInput) {
   const normalized = normalizeColumnInput(definition);
   const decorator: DualModePropertyDecorator = (targetOrValue, propertyKeyOrContext) => {
@@ -116,6 +119,12 @@ export function Column(definition: ColumnInput) {
   return decorator;
 }
 
+/**
+ * Decorator to define a primary key column on an entity property.
+ * Sets the primary flag to true and delegates to Column decorator.
+ * @param definition - The column definition or options.
+ * @returns A property decorator that registers the primary key column metadata.
+ */
 export function PrimaryKey(definition: ColumnInput) {
   const normalized = normalizeColumnInput(definition);
   normalized.primary = true;

package/src/decorators/decorator-metadata.ts

@@ -1,24 +1,37 @@
 import { ColumnDefLike, RelationMetadata } from '../orm/entity-metadata.js';
 
+/**
+ * Context object provided by standard decorators in newer TypeScript versions.
+ */
 export interface StandardDecoratorContext {
   kind: string;
   name?: string | symbol;
   metadata?: Record<PropertyKey, unknown>;
-  addInitializer?(initializer: (this: unknown) => void): void;
   static?: boolean;
   private?: boolean;
 }
 
+/**
+ * Dual-mode property decorator that supports both legacy and standard decorator syntax.
+ */
 export interface DualModePropertyDecorator {
   (target: object, propertyKey: string | symbol): void;
   (value: unknown, context: StandardDecoratorContext): void;
 }
 
+/**
+ * Dual-mode class decorator that supports both legacy and standard decorator syntax.
+ */
 export interface DualModeClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   <TFunction extends Function>(value: TFunction): void | TFunction;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
 }
 
+/**
+ * Bag for storing decorator metadata during the decoration phase.
+ */
 export interface DecoratorMetadataBag {
   columns: Array<{ propertyName: string; column: ColumnDefLike }>;
   relations: Array<{ propertyName: string; relation: RelationMetadata }>;
@@ -26,10 +39,20 @@ export interface DecoratorMetadataBag {
 
 const METADATA_KEY = 'metal-orm:decorators';
 
+/**
+ * Checks if a value is a StandardDecoratorContext.
+ * @param value - The value to check.
+ * @returns True if the value is a StandardDecoratorContext.
+ */
 export const isStandardDecoratorContext = (value: unknown): value is StandardDecoratorContext => {
-  return typeof value === 'object' && value !== null && 'kind' in (value as any);
+  return typeof value === 'object' && value !== null && 'kind' in (value as object);
 };
 
+/**
+ * Gets or creates a metadata bag for the given decorator context.
+ * @param context - The decorator context.
+ * @returns The metadata bag.
+ */
 export const getOrCreateMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag => {
   const metadata = context.metadata || (context.metadata = {} as Record<PropertyKey, unknown>);
   const existing = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
@@ -41,13 +64,11 @@ export const getOrCreateMetadataBag = (context: StandardDecoratorContext): Decor
   return bag;
 };
 
+/**
+ * Reads the metadata bag from the given decorator context.
+ * @param context - The decorator context.
+ * @returns The metadata bag if present.
+ */
 export const readMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag | undefined => {
   return context.metadata?.[METADATA_KEY] as DecoratorMetadataBag | undefined;
 };
-
-export const registerInitializer = (
-  context: StandardDecoratorContext,
-  initializer: (this: unknown) => void
-): void => {
-  context.addInitializer?.(initializer);
-};

package/src/decorators/entity.ts

@@ -1,4 +1,5 @@
 import { TableHooks } from '../schema/table.js';
+import { RelationKinds } from '../schema/relation.js';
 import {
   addColumnMetadata,
   addRelationMetadata,
@@ -8,6 +9,9 @@ import {
 } from '../orm/entity-metadata.js';
 import { DualModeClassDecorator, isStandardDecoratorContext, readMetadataBag } from './decorator-metadata.js';
 
+/**
+ * Options for defining an entity.
+ */
 export interface EntityOptions {
   tableName?: string;
   hooks?: TableHooks;
@@ -22,7 +26,7 @@ const toSnakeCase = (value: string): string => {
     .toLowerCase();
 };
 
-const deriveTableNameFromConstructor = (ctor: Function): string => {
+const deriveTableNameFromConstructor = (ctor: EntityConstructor<unknown>): string => {
   const fallback = 'unknown';
   const rawName = ctor.name || fallback;
   const strippedName = rawName.replace(/Entity$/i, '');
@@ -33,6 +37,11 @@ const deriveTableNameFromConstructor = (ctor: Function): string => {
   return normalized.endsWith('s') ? normalized : `${normalized}s`;
 };
 
+/**
+ * Class decorator to mark a class as an entity and configure its table mapping.
+ * @param options - Configuration options for the entity.
+ * @returns A class decorator that registers the entity metadata.
+ */
 export function Entity(options: EntityOptions = {}) {
   const decorator: DualModeClassDecorator = value => {
     const tableName = options.tableName ?? deriveTableNameFromConstructor(value);
@@ -50,14 +59,29 @@ export function Entity(options: EntityOptions = {}) {
       if (bag) {
         const meta = ensureEntityMetadata(ctor);
         for (const entry of bag.columns) {
-          if (!meta.columns[entry.propertyName]) {
-            addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
+          if (meta.columns[entry.propertyName]) {
+            throw new Error(
+              `Column '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+            );
           }
+          addColumnMetadata(ctor, entry.propertyName, { ...entry.column });
         }
         for (const entry of bag.relations) {
-          if (!meta.relations[entry.propertyName]) {
-            addRelationMetadata(ctor, entry.propertyName, entry.relation);
+          if (meta.relations[entry.propertyName]) {
+            throw new Error(
+              `Relation '${entry.propertyName}' is already defined on entity '${ctor.name}'.`
+            );
           }
+          const relationCopy =
+            entry.relation.kind === RelationKinds.BelongsToMany
+              ? {
+                ...entry.relation,
+                defaultPivotColumns: entry.relation.defaultPivotColumns
+                  ? [...entry.relation.defaultPivotColumns]
+                  : undefined
+              }
+              : { ...entry.relation };
+          addRelationMetadata(ctor, entry.propertyName, relationCopy);
         }
       }
     }

package/src/decorators/index.ts

@@ -1,3 +1,6 @@
+/**
+ * Decorators for defining entities, columns, and relations in Metal ORM.
+ */
 export * from './entity.js';
 export * from './column.js';
 export * from './relations.js';