metal-orm 1.0.102 → 1.0.104

package/package.json

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

package/scripts/generate-entities/cli.mjs

@@ -188,7 +188,7 @@ Flags:
   --include=tbl1,tbl2   Only include these tables
   --exclude=tbl3,tbl4   Exclude these tables
   --locale=pt-BR        Naming locale for class/relation names (default: en)
-  --naming-overrides    Path to JSON map of irregular plurals { "singular": "plural" }
+  --naming-overrides    Path to JSON config for naming customizations (see docs)
   --dry-run             Print to stdout instead of writing a file
   --out=<file>          Override the generated file (defaults to generated-entities.ts or the index inside --out-dir)
   --out-dir=<dir>       Emit one file per entity inside this directory plus the shared index

package/scripts/generate-entities/generate.mjs

@@ -5,7 +5,7 @@ import { loadDriver } from './drivers.mjs';
 import { renderEntityFile, renderSplitEntityFiles, renderSplitIndexFile } from './render.mjs';
 import { printDryRun, writeSingleFile, writeSplitFiles } from './emit.mjs';
 
-const loadIrregulars = async (filePath, fsPromises) => {
+const loadNamingOverrides = async (filePath, fsPromises) => {
   const raw = await fsPromises.readFile(filePath, 'utf8');
   let parsed;
   try {
@@ -13,22 +13,31 @@ const loadIrregulars = async (filePath, fsPromises) => {
   } catch (err) {
     throw new Error(`Failed to parse naming overrides at ${filePath}: ${err.message || err}`);
   }
-  const irregulars =
-    parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed.irregulars && typeof parsed.irregulars === 'object' && !Array.isArray(parsed.irregulars)
-        ? parsed.irregulars
-        : parsed
-      : undefined;
-  if (!irregulars) {
-    throw new Error(`Naming overrides at ${filePath} must be an object or { "irregulars": { ... } }`);
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Naming overrides at ${filePath} must be an object`);
   }
-  return irregulars;
+
+  // Support both flat format { "singular": "plural" } and structured { irregulars: {...}, relationOverrides: {...} }
+  const hasStructuredFormat = parsed.irregulars || parsed.relationOverrides;
+
+  const irregulars = hasStructuredFormat
+    ? (parsed.irregulars && typeof parsed.irregulars === 'object' ? parsed.irregulars : {})
+    : parsed;
+
+  const relationOverrides = hasStructuredFormat && parsed.relationOverrides && typeof parsed.relationOverrides === 'object'
+    ? parsed.relationOverrides
+    : {};
+
+  return { irregulars, relationOverrides };
 };
 
 export const generateEntities = async (opts, context = {}) => {
   const { fs: fsPromises = fs, logger = console } = context;
-  const irregulars = opts.namingOverrides ? await loadIrregulars(opts.namingOverrides, fsPromises) : undefined;
-  const naming = createNamingStrategy(opts.locale, irregulars);
+  const { irregulars, relationOverrides } = opts.namingOverrides
+    ? await loadNamingOverrides(opts.namingOverrides, fsPromises)
+    : { irregulars: undefined, relationOverrides: {} };
+  const naming = createNamingStrategy(opts.locale, irregulars, relationOverrides);
 
   const { executor, cleanup } = await loadDriver(opts.dialect, opts.url, opts.dbPath);
   let schema;

package/scripts/generate-entities/render.mjs

@@ -259,26 +259,27 @@ const renderEntityClassLines = ({ table, className, naming, relations, resolveCl
   for (const rel of relations) {
     const targetClass = resolveClassName(rel.target);
     if (!targetClass) continue;
+    const propName = naming.applyRelationOverride(className, rel.property);
     switch (rel.kind) {
       case 'belongsTo':
         lines.push(
           `  @BelongsTo({ target: () => ${targetClass}, foreignKey: '${escapeJsString(rel.foreignKey)}' })`
         );
-        lines.push(`  ${rel.property}!: BelongsToReference<${targetClass}>;`);
+        lines.push(`  ${propName}!: BelongsToReference<${targetClass}>;`);
         lines.push('');
         break;
       case 'hasMany':
         lines.push(
           `  @HasMany({ target: () => ${targetClass}, foreignKey: '${escapeJsString(rel.foreignKey)}' })`
         );
-        lines.push(`  ${rel.property}!: HasManyCollection<${targetClass}>;`);
+        lines.push(`  ${propName}!: HasManyCollection<${targetClass}>;`);
         lines.push('');
         break;
       case 'hasOne':
         lines.push(
           `  @HasOne({ target: () => ${targetClass}, foreignKey: '${escapeJsString(rel.foreignKey)}' })`
         );
-        lines.push(`  ${rel.property}!: HasOneReference<${targetClass}>;`);
+        lines.push(`  ${propName}!: HasOneReference<${targetClass}>;`);
         lines.push('');
         break;
       case 'belongsToMany': {
@@ -289,7 +290,7 @@ const renderEntityClassLines = ({ table, className, naming, relations, resolveCl
             rel.pivotForeignKeyToRoot
           )}', pivotForeignKeyToTarget: '${escapeJsString(rel.pivotForeignKeyToTarget)}' })`
         );
-        lines.push(`  ${rel.property}!: ManyToManyCollection<${targetClass}>;`);
+        lines.push(`  ${propName}!: ManyToManyCollection<${targetClass}>;`);
         lines.push('');
         break;
       }

package/scripts/naming-strategy.mjs

@@ -1,10 +1,12 @@
 import { resolveInflector } from './inflection/index.mjs';
 
 export class BaseNamingStrategy {
-  constructor(irregulars = {}, inflector = resolveInflector('en')) {
+  constructor(irregulars = {}, inflector = resolveInflector('en'), relationOverrides = {}) {
     this.irregulars = new Map();
     this.inverseIrregulars = new Map();
     this.inflector = inflector;
+    this.relationOverrides = new Map();
+
     for (const [singular, plural] of Object.entries(irregulars)) {
       if (!singular || !plural) continue;
       const normalize = this.inflector.normalizeForIrregularKey || (value => String(value).toLowerCase());
@@ -13,6 +15,20 @@ export class BaseNamingStrategy {
       this.irregulars.set(singularKey, pluralValue);
       this.inverseIrregulars.set(pluralValue, singularKey);
     }
+
+    // Build relation overrides map: className -> { originalProp -> newProp }
+    for (const [className, overrides] of Object.entries(relationOverrides)) {
+      if (!overrides || typeof overrides !== 'object') continue;
+      this.relationOverrides.set(className, new Map(Object.entries(overrides)));
+    }
+  }
+
+  applyRelationOverride(className, propertyName) {
+    const classOverrides = this.relationOverrides.get(className);
+    if (classOverrides?.has(propertyName)) {
+      return classOverrides.get(propertyName);
+    }
+    return propertyName;
   }
 
   applyIrregular(word, direction) {
@@ -109,8 +125,8 @@ export class PortugueseNamingStrategy extends BaseNamingStrategy {
   }
 }
 
-export const createNamingStrategy = (locale = 'en', irregulars) => {
+export const createNamingStrategy = (locale = 'en', irregulars, relationOverrides = {}) => {
   const inflector = resolveInflector(locale);
   const mergedIrregulars = { ...(inflector.defaultIrregulars || {}), ...(irregulars || {}) };
-  return new BaseNamingStrategy(mergedIrregulars, inflector);
+  return new BaseNamingStrategy(mergedIrregulars, inflector, relationOverrides);
 };

package/src/orm/entity-relations.ts

@@ -1,207 +1,209 @@
-import { TableDef } from '../schema/table.js';
-import { EntityInstance, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
-import { EntityMeta, RelationKey } from './entity-meta.js';
-import { DefaultHasManyCollection } from './relations/has-many.js';
-import { DefaultHasOneReference } from './relations/has-one.js';
-import { DefaultBelongsToReference } from './relations/belongs-to.js';
-import { DefaultManyToManyCollection } from './relations/many-to-many.js';
-import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
-import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
-import { relationLoaderCache } from './entity-relation-cache.js';
-
-export type RelationEntityFactory = (
-  table: TableDef,
-  row: Record<string, unknown>
-) => EntityInstance<TableDef>;
-
-const proxifyRelationWrapper = <T extends object>(wrapper: T): T => {
-  return new Proxy(wrapper, {
-    get(target, prop, receiver) {
-      if (typeof prop === 'symbol') {
-        return Reflect.get(target, prop, receiver);
-      }
-
-      if (prop in target) {
-        return Reflect.get(target, prop, receiver);
-      }
-
-      const getItems = (target as { getItems?: () => unknown }).getItems;
-      if (typeof getItems === 'function') {
-        const items = getItems.call(target);
-        if (items && prop in (items as object)) {
-          const propName = prop as string;
-          const value = (items as Record<string, unknown>)[propName];
-          return typeof value === 'function' ? value.bind(items) : value;
-        }
-      }
-
-      const getRef = (target as { get?: () => unknown }).get;
-      if (typeof getRef === 'function') {
-        const current = getRef.call(target);
-        if (current && prop in (current as object)) {
-          const propName = prop as string;
-          const value = (current as Record<string, unknown>)[propName];
-          return typeof value === 'function' ? value.bind(current) : value;
-        }
-      }
-
-      return undefined;
-    },
-
-    set(target, prop, value, receiver) {
-      if (typeof prop === 'symbol') {
-        return Reflect.set(target, prop, value, receiver);
-      }
-
-      if (prop in target) {
-        return Reflect.set(target, prop, value, receiver);
-      }
-
-      const getRef = (target as { get?: () => unknown }).get;
-      if (typeof getRef === 'function') {
-        const current = getRef.call(target);
-        if (current && typeof current === 'object') {
-          return Reflect.set(current as object, prop, value);
-        }
-      }
-
-      const getItems = (target as { getItems?: () => unknown }).getItems;
-      if (typeof getItems === 'function') {
-        const items = getItems.call(target);
-        return Reflect.set(items as object, prop, value);
-      }
-
-      return Reflect.set(target, prop, value, receiver);
-    }
-  });
-};
-
-/**
- * Gets a relation wrapper for an entity.
- * @param meta - The entity metadata
- * @param relationName - The relation name
- * @param owner - The owner entity
- * @param createEntity - The entity factory for relation rows
- * @returns The relation wrapper or undefined
- */
-export const getRelationWrapper = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: RelationKey<TTable> | string,
-  owner: unknown,
-  createEntity: RelationEntityFactory
-): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
-  const relationKey = relationName as string;
-
-  if (meta.relationWrappers.has(relationKey)) {
-    return meta.relationWrappers.get(relationKey) as HasManyCollection<unknown>;
-  }
-
-  const relation = meta.table.relations[relationKey];
-  if (!relation) return undefined;
-
-  const wrapper = instantiateWrapper(meta, relationKey, relation, owner, createEntity);
-  if (!wrapper) return undefined;
-
-  const proxied = proxifyRelationWrapper(wrapper as object);
-  meta.relationWrappers.set(relationKey, proxied);
-  return proxied as HasManyCollection<unknown>;
-};
-
-/**
- * Instantiates the appropriate relation wrapper based on relation type.
- * @param meta - The entity metadata
- * @param relationName - The relation name
- * @param relation - The relation definition
- * @param owner - The owner entity
- * @param createEntity - The entity factory for relation rows
- * @returns The relation wrapper or undefined
- */
-const instantiateWrapper = <TTable extends TableDef>(
-  meta: EntityMeta<TTable>,
-  relationName: string,
-  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
-  owner: unknown,
-  createEntity: RelationEntityFactory
-): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
-  const metaBase = meta as unknown as EntityMeta<TableDef>;
-  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
-    relationLoaderCache(metaBase, relationName, factory);
-  const resolveOptions = () => meta.lazyRelationOptions.get(relationName);
-  switch (relation.type) {
-    case RelationKinds.HasOne: {
-      const hasOne = relation as HasOneRelation;
-      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, resolveOptions())
-      );
-      return new DefaultHasOneReference(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        hasOne,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(hasOne.target, row),
-        localKey
-      );
-    }
-    case RelationKinds.HasMany: {
-      const hasMany = relation as HasManyRelation;
-      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, resolveOptions())
-      );
-      return new DefaultHasManyCollection(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        hasMany,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        localKey
-      );
-    }
-    case RelationKinds.BelongsTo: {
-      const belongsTo = relation as BelongsToRelation;
-      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
-      const loader = () => loadCached(() =>
-        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, resolveOptions())
-      );
-      return new DefaultBelongsToReference(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        belongsTo,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        targetKey
-      );
-    }
-    case RelationKinds.BelongsToMany: {
-      const many = relation as BelongsToManyRelation;
-      const localKey = many.localKey || findPrimaryKey(meta.table);
-      const loader = () => loadCached(() =>
-        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, resolveOptions())
-      );
-      return new DefaultManyToManyCollection(
-        meta.ctx,
-        metaBase,
-        owner,
-        relationName,
-        many,
-        meta.table,
-        loader,
-        (row: Record<string, unknown>) => createEntity(relation.target, row),
-        localKey
-      );
-    }
-    default:
-      return undefined;
-  }
-};
+import { TableDef } from '../schema/table.js';
+import { EntityInstance, HasManyCollection, HasOneReference, BelongsToReference, ManyToManyCollection } from '../schema/types.js';
+import { EntityMeta, RelationKey } from './entity-meta.js';
+import { DefaultHasManyCollection } from './relations/has-many.js';
+import { DefaultHasOneReference } from './relations/has-one.js';
+import { DefaultBelongsToReference } from './relations/belongs-to.js';
+import { DefaultManyToManyCollection } from './relations/many-to-many.js';
+import { HasManyRelation, HasOneRelation, BelongsToRelation, BelongsToManyRelation, RelationKinds } from '../schema/relation.js';
+import { loadHasManyRelation, loadHasOneRelation, loadBelongsToRelation, loadBelongsToManyRelation } from './lazy-batch.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+import { relationLoaderCache } from './entity-relation-cache.js';
+
+export type RelationEntityFactory = (
+  table: TableDef,
+  row: Record<string, unknown>
+) => EntityInstance<TableDef>;
+
+const proxifyRelationWrapper = <T extends object>(wrapper: T): T => {
+  return new Proxy(wrapper, {
+    get(target, prop, _receiver) {
+      if (typeof prop === 'symbol') {
+        const value = Reflect.get(target, prop, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      }
+
+      if (prop in target) {
+        const value = Reflect.get(target, prop, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      }
+
+      const getItems = (target as { getItems?: () => unknown }).getItems;
+      if (typeof getItems === 'function') {
+        const items = getItems.call(target);
+        if (items && prop in (items as object)) {
+          const propName = prop as string;
+          const value = (items as Record<string, unknown>)[propName];
+          return typeof value === 'function' ? value.bind(items) : value;
+        }
+      }
+
+      const getRef = (target as { get?: () => unknown }).get;
+      if (typeof getRef === 'function') {
+        const current = getRef.call(target);
+        if (current && prop in (current as object)) {
+          const propName = prop as string;
+          const value = (current as Record<string, unknown>)[propName];
+          return typeof value === 'function' ? value.bind(current) : value;
+        }
+      }
+
+      return undefined;
+    },
+
+    set(target, prop, value, _receiver) {
+      if (typeof prop === 'symbol') {
+        return Reflect.set(target, prop, value, target);
+      }
+
+      if (prop in target) {
+        return Reflect.set(target, prop, value, target);
+      }
+
+      const getRef = (target as { get?: () => unknown }).get;
+      if (typeof getRef === 'function') {
+        const current = getRef.call(target);
+        if (current && typeof current === 'object') {
+          return Reflect.set(current as object, prop, value);
+        }
+      }
+
+      const getItems = (target as { getItems?: () => unknown }).getItems;
+      if (typeof getItems === 'function') {
+        const items = getItems.call(target);
+        return Reflect.set(items as object, prop, value);
+      }
+
+      return Reflect.set(target, prop, value, target);
+    }
+  });
+};
+
+/**
+ * Gets a relation wrapper for an entity.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param owner - The owner entity
+ * @param createEntity - The entity factory for relation rows
+ * @returns The relation wrapper or undefined
+ */
+export const getRelationWrapper = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: RelationKey<TTable> | string,
+  owner: unknown,
+  createEntity: RelationEntityFactory
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
+  const relationKey = relationName as string;
+
+  if (meta.relationWrappers.has(relationKey)) {
+    return meta.relationWrappers.get(relationKey) as HasManyCollection<unknown>;
+  }
+
+  const relation = meta.table.relations[relationKey];
+  if (!relation) return undefined;
+
+  const wrapper = instantiateWrapper(meta, relationKey, relation, owner, createEntity);
+  if (!wrapper) return undefined;
+
+  const proxied = proxifyRelationWrapper(wrapper as object);
+  meta.relationWrappers.set(relationKey, proxied);
+  return proxied as HasManyCollection<unknown>;
+};
+
+/**
+ * Instantiates the appropriate relation wrapper based on relation type.
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param relation - The relation definition
+ * @param owner - The owner entity
+ * @param createEntity - The entity factory for relation rows
+ * @returns The relation wrapper or undefined
+ */
+const instantiateWrapper = <TTable extends TableDef>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  relation: HasManyRelation | HasOneRelation | BelongsToRelation | BelongsToManyRelation,
+  owner: unknown,
+  createEntity: RelationEntityFactory
+): HasManyCollection<unknown> | HasOneReference<object> | BelongsToReference<object> | ManyToManyCollection<unknown> | undefined => {
+  const metaBase = meta as unknown as EntityMeta<TableDef>;
+  const loadCached = <T extends Map<string, unknown>>(factory: () => Promise<T>) =>
+    relationLoaderCache(metaBase, relationName, factory);
+  const resolveOptions = () => meta.lazyRelationOptions.get(relationName);
+  switch (relation.type) {
+    case RelationKinds.HasOne: {
+      const hasOne = relation as HasOneRelation;
+      const localKey = hasOne.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasOneRelation(meta.ctx, meta.table, relationName, hasOne, resolveOptions())
+      );
+      return new DefaultHasOneReference(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        hasOne,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(hasOne.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.HasMany: {
+      const hasMany = relation as HasManyRelation;
+      const localKey = hasMany.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadHasManyRelation(meta.ctx, meta.table, relationName, hasMany, resolveOptions())
+      );
+      return new DefaultHasManyCollection(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        hasMany,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        localKey
+      );
+    }
+    case RelationKinds.BelongsTo: {
+      const belongsTo = relation as BelongsToRelation;
+      const targetKey = belongsTo.localKey || findPrimaryKey(belongsTo.target);
+      const loader = () => loadCached(() =>
+        loadBelongsToRelation(meta.ctx, meta.table, relationName, belongsTo, resolveOptions())
+      );
+      return new DefaultBelongsToReference(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        belongsTo,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        targetKey
+      );
+    }
+    case RelationKinds.BelongsToMany: {
+      const many = relation as BelongsToManyRelation;
+      const localKey = many.localKey || findPrimaryKey(meta.table);
+      const loader = () => loadCached(() =>
+        loadBelongsToManyRelation(meta.ctx, meta.table, relationName, many, resolveOptions())
+      );
+      return new DefaultManyToManyCollection(
+        meta.ctx,
+        metaBase,
+        owner,
+        relationName,
+        many,
+        meta.table,
+        loader,
+        (row: Record<string, unknown>) => createEntity(relation.target, row),
+        localKey
+      );
+    }
+    default:
+      return undefined;
+  }
+};