metal-orm 1.0.58 → 1.0.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/core/ddl/schema-generator.ts

@@ -1,6 +1,7 @@
 import type { TableDef } from '../../schema/table.js';
 import type { ColumnDef } from '../../schema/column-types.js';
 import type { SchemaDialect } from './schema-dialect.js';
+import type { DbExecutor } from '../execution/db-executor.js';
 import { resolvePrimaryKey } from './sql-writing.js';
 import { DialectName } from './schema-dialect.js';
 
@@ -41,7 +42,8 @@ export const renderColumnDefinition = (
   if (col.default !== undefined) {
     parts.push(`DEFAULT ${dialect.renderDefault(col.default, col)}`);
   }
-  if (options.includePrimary && col.primary) {
+  const autoIncIncludesPrimary = typeof autoInc === 'string' && /\bPRIMARY\s+KEY\b/i.test(autoInc);
+  if (options.includePrimary && col.primary && !autoIncIncludesPrimary) {
     parts.push('PRIMARY KEY');
   }
   if (col.check) {
@@ -126,6 +128,47 @@ export const generateSchemaSql = (
   return statements;
 };
 
+/**
+ * Convenience wrapper for generateSchemaSql with rest args.
+ * @param dialect - The schema dialect used to render SQL.
+ * @param tables - The table definitions to create.
+ */
+export const generateSchemaSqlFor = (
+  dialect: SchemaDialect,
+  ...tables: TableDef[]
+): string[] => generateSchemaSql(tables, dialect);
+
+/**
+ * Generates and executes schema SQL for the provided tables.
+ * @param executor - The database executor to run statements with.
+ * @param tables - The table definitions to create.
+ * @param dialect - The schema dialect used to render SQL.
+ */
+export const executeSchemaSql = async (
+  executor: DbExecutor,
+  tables: TableDef[],
+  dialect: SchemaDialect
+): Promise<void> => {
+  const statements = generateSchemaSql(tables, dialect);
+  for (const sql of statements) {
+    await executor.executeSql(sql);
+  }
+};
+
+/**
+ * Convenience wrapper for executeSchemaSql with rest args.
+ * @param executor - The database executor to run statements with.
+ * @param dialect - The schema dialect used to render SQL.
+ * @param tables - The table definitions to create.
+ */
+export const executeSchemaSqlFor = async (
+  executor: DbExecutor,
+  dialect: SchemaDialect,
+  ...tables: TableDef[]
+): Promise<void> => {
+  await executeSchemaSql(executor, tables, dialect);
+};
+
 const orderTablesByDependencies = (tables: TableDef[]): TableDef[] => {
   const map = new Map<string, TableDef>();
   tables.forEach(t => map.set(t.name, t));

package/src/decorators/bootstrap.ts

@@ -1,207 +1,244 @@
-import { SelectQueryBuilder } from '../query-builder/select.js';
-import {
-  hasMany,
-  hasOne,
-  belongsTo,
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import {
+  hasMany,
+  hasOne,
+  belongsTo,
   belongsToMany,
   RelationKinds,
   type HasManyRelation,
   type HasOneRelation,
   type BelongsToRelation,
-  type BelongsToManyRelation,
-  type RelationDef
-} from '../schema/relation.js';
+  type BelongsToManyRelation,
+  type RelationDef
+} from '../schema/relation.js';
 import { TableDef } from '../schema/table.js';
 import { isTableDef } from '../schema/table-guards.js';
 import {
   buildTableDef,
   EntityConstructor,
+  EntityMetadata,
   EntityOrTableTarget,
   EntityOrTableTargetResolver,
   getAllEntityMetadata,
-  getEntityMetadata,
-  RelationMetadata
+  getEntityMetadata
 } from '../orm/entity-metadata.js';
-
-import { tableRef, type TableRef } from '../schema/table.js';
-import {
-  SelectableKeys,
-  ColumnDef,
-  HasManyCollection,
-  HasOneReference,
-  BelongsToReference,
-  ManyToManyCollection
-} from '../schema/types.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)();
-  }
-  return target as EntityOrTableTarget;
-};
-
+
+import { tableRef, type TableRef } from '../schema/table.js';
+import {
+  SelectableKeys,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  BelongsToReference,
+  ManyToManyCollection
+} from '../schema/types.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)();
+  }
+  return target as EntityOrTableTarget;
+};
+
 const resolveTableTarget = (
   target: EntityOrTableTargetResolver,
   tableMap: Map<EntityConstructor, TableDef>
 ): TableDef => {
+  const resolved = unwrapTarget(target);
+  if (isTableDef(resolved)) {
+    return resolved;
+  }
+  const table = tableMap.get(resolved as EntityConstructor);
+  if (!table) {
+    throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
+  }
+  return table;
+};
+
+const toSnakeCase = (value: string): string => {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-z0-9_]+/gi, '_')
+    .replace(/__+/g, '_')
+    .replace(/^_|_$/g, '')
+    .toLowerCase();
+};
+
+const normalizeEntityName = (value: string): string => {
+  const stripped = value.replace(/Entity$/i, '');
+  const normalized = toSnakeCase(stripped || value);
+  return normalized || 'unknown';
+};
+
+const getPivotKeyBaseFromTarget = (target: EntityOrTableTargetResolver): string => {
   const resolved = unwrapTarget(target);
   if (isTableDef(resolved)) {
-    return resolved;
-  }
-  const table = tableMap.get(resolved as EntityConstructor);
-  if (!table) {
-    throw new Error(`Entity '${(resolved as EntityConstructor).name}' is not registered with decorators`);
+    return toSnakeCase(resolved.name || 'unknown');
   }
-  return table;
+  const ctor = resolved as EntityConstructor;
+  return normalizeEntityName(ctor.name || 'unknown');
+};
+
+const getPivotKeyBaseFromRoot = (meta: EntityMetadata): string => {
+  return normalizeEntityName(meta.target.name || meta.tableName || 'unknown');
 };
 
 const buildRelationDefinitions = (
-  meta: { relations: Record<string, RelationMetadata> },
+  meta: EntityMetadata,
   tableMap: Map<EntityConstructor, TableDef>
 ): Record<string, RelationDef> => {
   const relations: Record<string, RelationDef> = {};
 
   for (const [name, relation] of Object.entries(meta.relations)) {
-    switch (relation.kind) {
+    switch (relation.kind) {
       case RelationKinds.HasOne: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
         relations[name] = hasOne(
           resolveTableTarget(relation.target, tableMap),
-          relation.foreignKey,
+          foreignKey,
           relation.localKey,
           relation.cascade
         );
         break;
       }
       case RelationKinds.HasMany: {
+        const foreignKey = relation.foreignKey ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
         relations[name] = hasMany(
           resolveTableTarget(relation.target, tableMap),
-          relation.foreignKey,
-          relation.localKey,
-          relation.cascade
-        );
-        break;
-      }
-      case RelationKinds.BelongsTo: {
-        relations[name] = belongsTo(
-          resolveTableTarget(relation.target, tableMap),
-          relation.foreignKey,
+          foreignKey,
           relation.localKey,
           relation.cascade
         );
         break;
       }
+      case RelationKinds.BelongsTo: {
+        relations[name] = belongsTo(
+          resolveTableTarget(relation.target, tableMap),
+          relation.foreignKey,
+          relation.localKey,
+          relation.cascade
+        );
+        break;
+      }
       case RelationKinds.BelongsToMany: {
+        const pivotForeignKeyToRoot =
+          relation.pivotForeignKeyToRoot ?? `${getPivotKeyBaseFromRoot(meta)}_id`;
+        const pivotForeignKeyToTarget =
+          relation.pivotForeignKeyToTarget ?? `${getPivotKeyBaseFromTarget(relation.target)}_id`;
         relations[name] = belongsToMany(
           resolveTableTarget(relation.target, tableMap),
           resolveTableTarget(relation.pivotTable, tableMap),
           {
-            pivotForeignKeyToRoot: relation.pivotForeignKeyToRoot,
-            pivotForeignKeyToTarget: relation.pivotForeignKeyToTarget,
+            pivotForeignKeyToRoot,
+            pivotForeignKeyToTarget,
             localKey: relation.localKey,
             targetKey: relation.targetKey,
             pivotPrimaryKey: relation.pivotPrimaryKey,
             defaultPivotColumns: relation.defaultPivotColumns,
             cascade: relation.cascade
-          }
-        );
-        break;
-      }
-    }
-  }
-
-  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, TableDef>();
-
-  for (const meta of metas) {
-    const table = buildTableDef(meta);
-    tableMap.set(meta.target, table);
-  }
-
-  for (const meta of metas) {
-    const table = meta.table!;
-    const relations = buildRelationDefinitions(meta, tableMap);
-    table.relations = relations;
-  }
-
-  return metas.map(meta => meta.table!) as TableDef[];
-};
-
-/**
- * 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) {
-    bootstrapEntities();
-  }
-  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.
- */
-type NonFunctionKeys<T> = {
-  [K in keyof T]-?: T[K] extends (...args: unknown[]) => unknown ? never : K
-}[keyof T];
-
-type RelationKeys<TEntity extends object> =
-  Exclude<NonFunctionKeys<TEntity>, SelectableKeys<TEntity>> & string;
-
-type EntityTable<TEntity extends object> =
-  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
-    relations: {
-      [K in RelationKeys<TEntity>]:
-        NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
-          ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
-          : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget>
-            ? BelongsToManyRelation<EntityTable<NonNullable<TTarget> & object>>
-            : NonNullable<TEntity[K]> extends HasOneReference<infer TChild>
-              ? HasOneRelation<EntityTable<NonNullable<TChild> & object>>
-              : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent>
-                ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>>
-                : NonNullable<TEntity[K]> extends object
-                  ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
-                  : never;
-    };
-  };
-
-export const selectFromEntity = <TEntity extends object>(
+          }
+        );
+        break;
+      }
+    }
+  }
+
+  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, TableDef>();
+
+  for (const meta of metas) {
+    const table = buildTableDef(meta);
+    tableMap.set(meta.target, table);
+  }
+
+  for (const meta of metas) {
+    const table = meta.table!;
+    const relations = buildRelationDefinitions(meta, tableMap);
+    table.relations = relations;
+  }
+
+  return metas.map(meta => meta.table!) as TableDef[];
+};
+
+/**
+ * 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) {
+    bootstrapEntities();
+  }
+  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.
+ */
+type NonFunctionKeys<T> = {
+  [K in keyof T]-?: T[K] extends (...args: unknown[]) => unknown ? never : K
+}[keyof T];
+
+type RelationKeys<TEntity extends object> =
+  Exclude<NonFunctionKeys<TEntity>, SelectableKeys<TEntity>> & string;
+
+type EntityTable<TEntity extends object> =
+  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
+    relations: {
+      [K in RelationKeys<TEntity>]:
+        NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
+          ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
+          : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget, infer TPivot>
+            ? BelongsToManyRelation<
+                EntityTable<NonNullable<TTarget> & object>,
+                TPivot extends object ? EntityTable<NonNullable<TPivot> & object> : TableDef
+              >
+            : NonNullable<TEntity[K]> extends HasOneReference<infer TChild>
+              ? HasOneRelation<EntityTable<NonNullable<TChild> & object>>
+              : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent>
+                ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>>
+                : NonNullable<TEntity[K]> extends object
+                  ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
+                  : never;
+    };
+  };
+
+export const selectFromEntity = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): SelectQueryBuilder<unknown, EntityTable<TEntity>> => {
+  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 unknown as EntityTable<TEntity>);
+};
+
+/**
+ * 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 = <TEntity extends object>(
   ctor: EntityConstructor<TEntity>
-): SelectQueryBuilder<unknown, EntityTable<TEntity>> => {
+): TableRef<EntityTable<TEntity>> => {
   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 unknown as EntityTable<TEntity>);
-};
-
-/**
- * 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);
+  return tableRef(table as EntityTable<TEntity>);
 };

package/src/decorators/column-decorator.ts

@@ -1,16 +1,6 @@
 import { ColumnDef, ColumnType } from '../schema/column-types.js';
-import {
-  addColumnMetadata,
-  EntityConstructor,
-  ColumnDefLike,
-  ensureEntityMetadata
-} from '../orm/entity-metadata.js';
-import {
-  DualModePropertyDecorator,
-  getOrCreateMetadataBag,
-  isStandardDecoratorContext,
-  StandardDecoratorContext
-} from './decorator-metadata.js';
+import { ColumnDefLike } from '../orm/entity-metadata.js';
+import { getOrCreateMetadataBag } from './decorator-metadata.js';
 
 /**
  * Options for defining a column in an entity.
@@ -62,39 +52,21 @@ const normalizePropertyName = (name: string | symbol): string => {
   return name;
 };
 
-const resolveConstructor = (target: unknown): EntityConstructor | undefined => {
-  if (typeof target === 'function') {
-    return target as EntityConstructor;
-  }
-
-  if (target && typeof (target as { constructor: unknown }).constructor === 'function') {
-    return (target as { constructor: unknown }).constructor as EntityConstructor;
-  }
-
-  return undefined;
-};
-
-const registerColumn = (ctor: EntityConstructor, propertyName: string, column: ColumnDefLike): void => {
-  const meta = ensureEntityMetadata(ctor);
-  if (meta.columns[propertyName]) {
-    return;
-  }
-  addColumnMetadata(ctor, propertyName, column);
-};
-
 const registerColumnFromContext = (
-  context: StandardDecoratorContext,
+  context: ClassFieldDecoratorContext,
   column: ColumnDefLike
 ): void => {
   if (!context.name) {
     throw new Error('Column decorator requires a property name');
   }
+  if (context.private) {
+    throw new Error('Column decorator does not support private fields');
+  }
   const propertyName = normalizePropertyName(context.name);
   const bag = getOrCreateMetadataBag(context);
   if (!bag.columns.some(entry => entry.propertyName === propertyName)) {
     bag.columns.push({ propertyName, column: { ...column } });
   }
-
 };
 
 /**
@@ -104,21 +76,9 @@ const registerColumnFromContext = (
  */
 export function Column(definition: ColumnInput) {
   const normalized = normalizeColumnInput(definition);
-  const decorator: DualModePropertyDecorator = (targetOrValue, propertyKeyOrContext) => {
-    if (isStandardDecoratorContext(propertyKeyOrContext)) {
-      registerColumnFromContext(propertyKeyOrContext, normalized);
-      return;
-    }
-
-    const propertyName = normalizePropertyName(propertyKeyOrContext);
-    const ctor = resolveConstructor(targetOrValue);
-    if (!ctor) {
-      throw new Error('Unable to resolve constructor when registering column metadata');
-    }
-    registerColumn(ctor, propertyName, { ...normalized });
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerColumnFromContext(context, normalized);
   };
-
-  return decorator;
 }
 
 /**
@@ -132,4 +92,3 @@ export function PrimaryKey(definition: ColumnInput) {
   normalized.primary = true;
   return Column(normalized);
 }
-

package/src/decorators/decorator-metadata.ts

@@ -1,34 +1,5 @@
 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>;
-  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.
  */
@@ -39,37 +10,31 @@ 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 object);
+type MetadataCarrier = {
+  metadata?: Record<PropertyKey, unknown>;
 };
 
 /**
  * Gets or creates a metadata bag for the given decorator context.
- * @param context - The decorator context.
+ * @param context - The decorator context with metadata support.
  * @returns The metadata bag.
  */
-export const getOrCreateMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag => {
+export const getOrCreateMetadataBag = (context: MetadataCarrier): DecoratorMetadataBag => {
   const metadata = context.metadata || (context.metadata = {} as Record<PropertyKey, unknown>);
-  const existing = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
-  if (existing) {
-    return existing;
+  let bag = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
+  if (!bag) {
+    bag = { columns: [], relations: [] };
+    metadata[METADATA_KEY] = bag;
   }
-  const bag: DecoratorMetadataBag = { columns: [], relations: [] };
-  metadata[METADATA_KEY] = bag;
   return bag;
 };
 
 /**
  * Reads the metadata bag from the given decorator context.
- * @param context - The decorator context.
+ * @param context - The decorator context with metadata support.
  * @returns The metadata bag if present.
  */
-export const readMetadataBag = (context: StandardDecoratorContext): DecoratorMetadataBag | undefined => {
+export const readMetadataBag = (context: MetadataCarrier): DecoratorMetadataBag | undefined => {
   return context.metadata?.[METADATA_KEY] as DecoratorMetadataBag | undefined;
 };
 
@@ -87,7 +52,6 @@ export const readMetadataBagFromConstructor = (ctor: object): DecoratorMetadataB
 
 /**
  * Public helper to read decorator metadata from a class constructor.
- * Standard decorators only; legacy metadata is intentionally ignored.
  * @param ctor - The entity constructor.
  * @returns The metadata bag if present.
  */