metal-orm 1.0.57 → 1.0.59

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "metal-orm",
-  "version": "1.0.57",
-  "type": "module",
-  "types": "./dist/index.d.ts",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "bin": {
-    "metal-orm-gen": "./scripts/generate-entities.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "global.d.ts",
-    "scripts"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "check": "tsc --noEmit",
-    "gen:entities": "node scripts/generate-entities.mjs",
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "show-sql": "node scripts/show-sql.mjs",
-    "lint": "node scripts/run-eslint.mjs",
-    "lint:fix": "node scripts/run-eslint.mjs --fix"
-  },
-  "peerDependencies": {
-    "mysql2": "^3.9.0",
-    "pg": "^8.0.0",
-    "sqlite3": "^5.1.6",
-    "tedious": "^16.0.0"
-  },
-  "peerDependenciesMeta": {
-    "mysql2": {
-      "optional": true
-    },
-    "pg": {
-      "optional": true
-    },
-    "sqlite3": {
-      "optional": true
-    },
-    "tedious": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@vitest/ui": "^4.0.14",
-    "@typescript-eslint/eslint-plugin": "^8.20.0",
-    "@typescript-eslint/parser": "^8.20.0",
-    "eslint": "^8.57.0",
-    "eslint-plugin-deprecation": "^3.0.0",
-    "mysql2": "^3.15.3",
-    "pg": "^8.16.3",
-    "sqlite3": "^5.1.7",
-    "tedious": "^19.1.3",
-    "tsup": "^8.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^4.0.14"
-  }
-}
+{
+  "name": "metal-orm",
+  "version": "1.0.59",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "metal-orm-gen": "./scripts/generate-entities.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "global.d.ts",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "check": "tsc --noEmit",
+    "gen:entities": "node scripts/generate-entities.mjs",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "show-sql": "node scripts/show-sql.mjs",
+    "lint": "node scripts/run-eslint.mjs",
+    "lint:fix": "node scripts/run-eslint.mjs --fix"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.9.0",
+    "pg": "^8.0.0",
+    "sqlite3": "^5.1.6",
+    "tedious": "^16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    },
+    "tedious": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.0.14",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-deprecation": "^3.0.0",
+    "mysql2": "^3.15.3",
+    "pg": "^8.16.3",
+    "sqlite3": "^5.1.7",
+    "tedious": "^19.1.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.14"
+  }
+}

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,171 +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 RelationDef
-} from '../schema/relation.js';
+  type HasManyRelation,
+  type HasOneRelation,
+  type BelongsToRelation,
+  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 } 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.
- */
-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, TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>> => {
+): 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 TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>);
-};
-
-/**
- * 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);
 }
-