metal-orm 1.0.49 → 1.0.51

package/package.json

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

package/scripts/generate-entities/cli.mjs

@@ -1,8 +1,107 @@
+import fs from 'node:fs';
 import process from 'node:process';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { parseArgs as parseCliArgs } from 'node:util';
 
 const DIALECTS = new Set(['postgres', 'mysql', 'sqlite', 'mssql']);
+const NODE_NEXT_MODULE_RESOLUTIONS = new Set(['node16', 'nodenext']);
+
+const TS_CONFIG_BASE_NAMES = ['tsconfig.json', 'tsconfig.base.json', 'tsconfig.app.json', 'tsconfig.build.json'];
+const nodeRequire = createRequire(import.meta.url);
+
+const normalizeCompilerOption = value => (typeof value === 'string' ? value.trim().toLowerCase() : '');
+
+const hasNodeNextModuleResolution = compilerOptions => {
+  if (!compilerOptions || typeof compilerOptions !== 'object') return false;
+  const moduleResolution = normalizeCompilerOption(compilerOptions.moduleResolution);
+  const moduleOption = normalizeCompilerOption(compilerOptions.module);
+  return (
+    NODE_NEXT_MODULE_RESOLUTIONS.has(moduleResolution) || NODE_NEXT_MODULE_RESOLUTIONS.has(moduleOption)
+  );
+};
+
+const resolveExtendsPath = (extendsValue, baseDir) => {
+  if (!extendsValue || typeof extendsValue !== 'string') return undefined;
+  const candidatePaths = [];
+  const normalizedValue = extendsValue.trim();
+  candidatePaths.push(path.resolve(baseDir, normalizedValue));
+  if (!path.extname(normalizedValue)) {
+    candidatePaths.push(`${path.resolve(baseDir, normalizedValue)}.json`);
+  }
+  for (const candidate of candidatePaths) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  try {
+    return nodeRequire.resolve(normalizedValue, { paths: [baseDir] });
+  } catch {
+    return undefined;
+  }
+};
+
+const inspectTsConfig = (configPath, visited) => {
+  if (!configPath) return false;
+  const normalized = path.resolve(configPath);
+  if (visited.has(normalized)) return false;
+  if (!fs.existsSync(normalized)) return false;
+  visited.add(normalized);
+  let raw;
+  try {
+    raw = fs.readFileSync(normalized, 'utf8');
+  } catch {
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  if (hasNodeNextModuleResolution(parsed.compilerOptions)) {
+    return true;
+  }
+  if (parsed.extends) {
+    const extended = resolveExtendsPath(parsed.extends, path.dirname(normalized));
+    if (extended && inspectTsConfig(extended, visited)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const discoverTsConfigPaths = cwd => {
+  const candidates = new Set();
+  for (const name of TS_CONFIG_BASE_NAMES) {
+    const fullPath = path.join(cwd, name);
+    if (fs.existsSync(fullPath)) {
+      candidates.add(fullPath);
+    }
+  }
+  try {
+    const entries = fs.readdirSync(cwd);
+    for (const entry of entries) {
+      const lower = entry.toLowerCase();
+      if (lower.startsWith('tsconfig') && lower.endsWith('.json')) {
+        candidates.add(path.join(cwd, entry));
+      }
+    }
+  } catch {
+    // ignore readdir errors
+  }
+  return Array.from(candidates);
+};
+
+const shouldUseJsImportExtensions = cwd => {
+  const paths = discoverTsConfigPaths(cwd);
+  if (!paths.length) return false;
+  const visited = new Set();
+  for (const configPath of paths) {
+    if (inspectTsConfig(configPath, visited)) {
+      return true;
+    }
+  }
+  return false;
+};
 
 export const parseOptions = (argv = process.argv.slice(2), env = process.env, cwd = process.cwd()) => {
   const parser = {
@@ -52,6 +151,8 @@ export const parseOptions = (argv = process.argv.slice(2), env = process.env, cw
     dryRun: Boolean(values['dry-run'])
   };
 
+  opts.useJsImportExtensions = shouldUseJsImportExtensions(cwd);
+
   if (!DIALECTS.has(opts.dialect)) {
     throw new Error(`Unsupported dialect "${opts.dialect}". Supported: ${Array.from(DIALECTS).join(', ')}`);
   }

package/scripts/generate-entities/render.mjs

@@ -4,11 +4,47 @@ import { buildSchemaMetadata } from './schema.mjs';
 
 const escapeJsString = value => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
 
+const formatJsDoc = comment => {
+  if (!comment) return null;
+  const normalized = comment.replace(/\r\n?/g, '\n').trim();
+  if (!normalized) return null;
+  const lines = normalized.split('\n').map(line => line.replace(/\*\//g, '*\\/'));
+  return ['/**', ...lines.map(line => ` * ${line}`), ' */'].join('\n');
+};
+
+const appendJsDoc = (lines, comment, indent = '') => {
+  const doc = formatJsDoc(comment);
+  if (!doc) return;
+  doc.split('\n').forEach(line => lines.push(`${indent}${line}`));
+};
+
+const normalizeReferenceTable = (refTable, sourceSchema, defaultSchema) => {
+  if (!refTable || typeof refTable !== 'string') return refTable;
+  const parts = refTable.split('.');
+  if (parts.length === 1) return refTable;
+
+  if (parts.length === 2) {
+    const [schema, table] = parts;
+    return schema === sourceSchema || (defaultSchema && schema === defaultSchema) ? table : refTable;
+  }
+
+  if (parts.length === 3) {
+    const [db, schema, table] = parts;
+    if (schema === sourceSchema || (defaultSchema && schema === defaultSchema)) {
+      return `${db}.${table}`;
+    }
+    return refTable;
+  }
+
+  return refTable;
+};
+
 const parseColumnType = colTypeRaw => {
   const type = (colTypeRaw || '').toLowerCase();
   const lengthMatch = type.match(/\((\d+)(?:\s*,\s*(\d+))?\)/);
   const length = lengthMatch ? Number(lengthMatch[1]) : undefined;
   const scale = lengthMatch && lengthMatch[2] ? Number(lengthMatch[2]) : undefined;
+  const isMaxLength = /\(max\)/.test(type);
 
   const base = type.replace(/\(.*\)/, '');
 
@@ -18,7 +54,8 @@ const parseColumnType = colTypeRaw => {
   if (base.includes('uuid') || base.includes('uniqueidentifier')) return { factory: 'col.uuid()', ts: 'string' };
   if (base === 'date') return { factory: 'col.date<Date>()', ts: 'Date' };
   if (base.includes('datetime') || base === 'time') return { factory: 'col.datetime<Date>()', ts: 'Date' };
-  if (base.includes('char') || base.includes('text')) {
+  if (base.includes('text') || (isMaxLength && base.includes('char'))) return { factory: 'col.text()', ts: 'string' };
+  if (base.includes('char')) {
     const lenArg = length ? `${length}` : '255';
     return { factory: `col.varchar(${lenArg})`, ts: 'string' };
   }
@@ -64,7 +101,65 @@ const normalizeDefault = value => {
   return { kind: 'value', code: JSON.stringify(value) };
 };
 
-const renderColumnExpression = (column, tablePk) => {
+const formatDefaultValueForDoc = value => {
+  const normalized = normalizeDefault(value);
+  if (!normalized) return null;
+  const code = normalized.code;
+  if (typeof code !== 'string') {
+    return `${code}`;
+  }
+  if (normalized.kind === 'raw') {
+    const trimmed = code.trim();
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+      return trimmed.slice(1, -1);
+    }
+    return trimmed;
+  }
+  return code;
+};
+
+const buildColumnRemarks = column => {
+  const notes = [];
+  if (column.autoIncrement) {
+    notes.push('Auto-increment identity column');
+  }
+  if (column.generated) {
+    const verb = column.generated === 'always' ? 'Generated always' : 'Generated by default';
+    notes.push(`${verb} column`);
+  }
+  if (column.check) {
+    notes.push(`Check constraint: ${column.check}`);
+  }
+  if (column.references) {
+    const ref = column.references;
+    const actions = [];
+    if (ref.onDelete) actions.push(`on delete ${ref.onDelete}`);
+    if (ref.onUpdate) actions.push(`on update ${ref.onUpdate}`);
+    const actionSuffix = actions.length ? ` (${actions.join(', ')})` : '';
+    notes.push(`References ${ref.table}.${ref.column}${actionSuffix}`);
+  }
+  if (!notes.length) return null;
+  return notes.join('; ');
+};
+
+const buildColumnDoc = column => {
+  const entries = [];
+  if (column.comment) {
+    entries.push(column.comment);
+  }
+  const defaultValue = formatDefaultValueForDoc(column.default);
+  if (defaultValue) {
+    entries.push(`@defaultValue ${defaultValue}`);
+  }
+  const remarks = buildColumnRemarks(column);
+  if (remarks) {
+    entries.push(`@remarks ${remarks}`);
+  }
+  if (!entries.length) return null;
+  return entries.join('\n');
+};
+
+const renderColumnExpression = (column, tablePk, tableSchema, defaultSchema) => {
   const base = parseColumnType(column.type);
   let expr = base.factory;
 
@@ -88,8 +183,9 @@ const renderColumnExpression = (column, tablePk) => {
     }
   }
   if (column.references) {
+    const refTable = normalizeReferenceTable(column.references.table, tableSchema, defaultSchema);
     const refParts = [
-      `table: '${escapeJsString(column.references.table)}'`,
+      `table: '${escapeJsString(refTable)}'`,
       `column: '${escapeJsString(column.references.column)}'`
     ];
     if (column.references.onDelete) refParts.push(`onDelete: '${escapeJsString(column.references.onDelete)}'`);
@@ -106,7 +202,8 @@ const renderColumnExpression = (column, tablePk) => {
     decorator,
     expr,
     tsType,
-    optional
+    optional,
+    comment: buildColumnDoc(column)
   };
 };
 
@@ -126,16 +223,20 @@ const METAL_ORM_IMPORT_ORDER = [
   'getTableDefFromEntity'
 ];
 
-const renderEntityClassLines = ({ table, className, naming, relations, resolveClassName }) => {
+const renderEntityClassLines = ({ table, className, naming, relations, resolveClassName, defaultSchema }) => {
   const lines = [];
   const derivedDefault = naming.defaultTableNameFromClass(className);
   const needsTableNameOption = table.name !== derivedDefault;
   const entityOpts = needsTableNameOption ? `{ tableName: '${escapeJsString(table.name)}' }` : '';
+  if (table.comment) {
+    appendJsDoc(lines, table.comment);
+  }
   lines.push(`@Entity(${entityOpts})`);
   lines.push(`export class ${className} {`);
 
   for (const col of table.columns) {
-    const rendered = renderColumnExpression(col, table.primaryKey);
+    const rendered = renderColumnExpression(col, table.primaryKey, table.schema, defaultSchema);
+    appendJsDoc(lines, rendered.comment, '  ');
     lines.push(`  @${rendered.decorator}(${rendered.expr})`);
     lines.push(`  ${col.name}${rendered.optional ? '?:' : '!:'} ${rendered.tsType};`);
     lines.push('');
@@ -188,7 +289,7 @@ const renderEntityClassLines = ({ table, className, naming, relations, resolveCl
   return lines;
 };
 
-const computeTableUsage = (table, relations) => {
+const computeTableUsage = (table, relations, defaultSchema) => {
   const usage = {
     needsCol: false,
     needsEntity: true,
@@ -205,7 +306,7 @@ const computeTableUsage = (table, relations) => {
 
   for (const col of table.columns) {
     usage.needsCol = true;
-    const rendered = renderColumnExpression(col, table.primaryKey);
+    const rendered = renderColumnExpression(col, table.primaryKey, table.schema, defaultSchema);
     if (rendered.decorator === 'PrimaryKey') {
       usage.needsPrimaryKeyDecorator = true;
     } else {
@@ -257,11 +358,16 @@ const buildMetalOrmImportStatement = names => {
   return `import { ${ordered.join(', ')} } from 'metal-orm';`;
 };
 
-const getRelativeModuleSpecifier = (from, to) => {
+const appendJsExtension = (specifier, useExtension) => (useExtension ? `${specifier}.js` : specifier);
+
+const getRelativeModuleSpecifier = (from, to, extension = '') => {
   const rel = path.relative(path.dirname(from), to).replace(/\\/g, '/');
-  if (!rel) return './';
+  if (!rel) {
+    return './';
+  }
   const withoutExt = rel.replace(/\.ts$/i, '');
-  return withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
+  const normalized = withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
+  return `${normalized}${extension}`;
 };
 
 export const renderEntityFile = (schema, options) => {
@@ -285,7 +391,7 @@ export const renderEntityFile = (schema, options) => {
 
   for (const table of tables) {
     const rels = relations.get(table.name) || [];
-    const tableUsage = computeTableUsage(table, rels);
+    const tableUsage = computeTableUsage(table, rels, options.schema);
     aggregateUsage.needsCol ||= tableUsage.needsCol;
     aggregateUsage.needsColumnDecorator ||= tableUsage.needsColumnDecorator;
     aggregateUsage.needsPrimaryKeyDecorator ||= tableUsage.needsPrimaryKeyDecorator;
@@ -318,7 +424,8 @@ export const renderEntityFile = (schema, options) => {
       className,
       naming,
       relations: relations.get(table.name) || [],
-      resolveClassName: metadata.resolveClassName
+      resolveClassName: metadata.resolveClassName,
+      defaultSchema: options.schema
     });
     lines.push(...classLines);
   }
@@ -345,7 +452,7 @@ export const renderSplitEntityFiles = (schema, options) => {
   for (const table of metadata.tables) {
     const className = metadata.classNames.get(table.name);
     const relations = metadata.relations.get(table.name) || [];
-    const usage = computeTableUsage(table, relations);
+    const usage = computeTableUsage(table, relations, options.schema);
     const metalImportNames = getMetalOrmImportNamesFromUsage(usage);
     const metalImportStatement = buildMetalOrmImportStatement(metalImportNames);
 
@@ -368,7 +475,8 @@ export const renderSplitEntityFiles = (schema, options) => {
       importLines.push(metalImportStatement);
     }
     for (const targetClass of Array.from(relationImports).sort()) {
-      importLines.push(`import { ${targetClass} } from './${targetClass}';`);
+      const specifier = appendJsExtension(`./${targetClass}`, options.useJsImportExtensions);
+      importLines.push(`import { ${targetClass} } from '${specifier}';`);
     }
 
     const lines = [
@@ -384,7 +492,8 @@ export const renderSplitEntityFiles = (schema, options) => {
       className,
       naming,
       relations,
-      resolveClassName: metadata.resolveClassName
+      resolveClassName: metadata.resolveClassName,
+      defaultSchema: options.schema
     });
     lines.push(...classLines);
 
@@ -404,7 +513,11 @@ export const renderSplitIndexFile = (metadata, options) => {
   for (const table of metadata.tables) {
     const className = metadata.classNames.get(table.name);
     const filePath = path.join(options.outDir, `${className}.ts`);
-    const moduleSpecifier = getRelativeModuleSpecifier(options.out, filePath);
+    const moduleSpecifier = getRelativeModuleSpecifier(
+      options.out,
+      filePath,
+      options.useJsImportExtensions ? '.js' : ''
+    );
     importLines.push(`import { ${className} } from '${moduleSpecifier}';`);
     exportedClasses.push(className);
   }

package/scripts/inflection/compound.mjs

@@ -0,0 +1,72 @@
+export const stripDiacritics = value =>
+  String(value || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '');
+
+export const normalizeLookup = value => stripDiacritics(value).toLowerCase().trim();
+
+export const detectTextFormat = text => {
+  if (/^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/.test(text)) return 'SCREAMING_SNAKE';
+  if (/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/.test(text)) return 'snake_case';
+  if (/^[A-Z][a-zA-Z0-9]*$/.test(text) && /[a-z]/.test(text)) return 'PascalCase';
+  if (/^[a-z][a-zA-Z0-9]*$/.test(text) && /[A-Z]/.test(text)) return 'camelCase';
+  return 'normal';
+};
+
+export const splitIntoWords = (text, format) => {
+  switch (format) {
+    case 'camelCase':
+    case 'PascalCase':
+      return text
+        .replace(/([a-z])([A-Z])/g, '$1\0$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1\0$2')
+        .split('\0')
+        .map(p => p.toLowerCase());
+    case 'snake_case':
+      return text.toLowerCase().split('_');
+    case 'SCREAMING_SNAKE':
+      return text.toLowerCase().split('_');
+    default:
+      return text.toLowerCase().split(/\s+/);
+  }
+};
+
+const capitalize = value => (value ? value.charAt(0).toUpperCase() + value.slice(1).toLowerCase() : '');
+
+export const rebuildFromWords = (words, format, originalText) => {
+  switch (format) {
+    case 'camelCase':
+      return words.map((w, i) => (i === 0 ? w : capitalize(w))).join('');
+    case 'PascalCase':
+      return words.map(capitalize).join('');
+    case 'snake_case':
+      return words.join('_');
+    case 'SCREAMING_SNAKE':
+      return words.map(w => w.toUpperCase()).join('_');
+    default: {
+      const result = words.join(' ');
+      return originalText && originalText[0] === originalText[0].toUpperCase() ? capitalize(result) : result;
+    }
+  }
+};
+
+export const applyToCompoundHead = (term, { connectors, transformWord } = {}) => {
+  if (!term || !String(term).trim()) return '';
+  const original = String(term).trim();
+  const format = detectTextFormat(original);
+  const words = splitIntoWords(original, format);
+
+  let transformed = false;
+  const out = words.map(word => {
+    const normalized = normalizeLookup(word);
+    if (connectors?.has?.(normalized)) return word;
+    if (!transformed) {
+      transformed = true;
+      return transformWord ? transformWord(word) : word;
+    }
+    return word;
+  });
+
+  return rebuildFromWords(out, format, original);
+};
+

package/scripts/inflection/en.mjs

@@ -0,0 +1,26 @@
+export const EN_DEFAULT_IRREGULARS = {};
+
+export const pluralizeWordEn = word => {
+  const lower = String(word || '').toLowerCase();
+  if (!lower) return '';
+  if (lower.endsWith('y')) return `${lower.slice(0, -1)}ies`;
+  if (lower.endsWith('s')) return `${lower}es`;
+  return `${lower}s`;
+};
+
+export const singularizeWordEn = word => {
+  const lower = String(word || '').toLowerCase();
+  if (!lower) return '';
+  if (lower.endsWith('ies')) return `${lower.slice(0, -3)}y`;
+  if (lower.endsWith('ses')) return lower.slice(0, -2);
+  if (lower.endsWith('s')) return lower.slice(0, -1);
+  return lower;
+};
+
+export const createEnglishInflector = () => ({
+  locale: 'en',
+  defaultIrregulars: EN_DEFAULT_IRREGULARS,
+  pluralizeWord: pluralizeWordEn,
+  singularizeWord: singularizeWordEn
+});
+

package/scripts/inflection/index.mjs

@@ -0,0 +1,29 @@
+import { createEnglishInflector } from './en.mjs';
+import { createPtBrInflector } from './pt-br.mjs';
+
+const INFLECTOR_FACTORIES = new Map();
+
+export const registerInflector = (localePrefix, factory) => {
+  const key = String(localePrefix || '').toLowerCase();
+  if (!key) throw new Error('localePrefix is required');
+  if (typeof factory !== 'function') throw new Error('factory must be a function that returns an inflector');
+  INFLECTOR_FACTORIES.set(key, factory);
+};
+
+registerInflector('en', createEnglishInflector);
+registerInflector('pt', createPtBrInflector);
+
+export const resolveInflector = locale => {
+  const normalized = String(locale || 'en').toLowerCase();
+  let bestFactory = undefined;
+  let bestPrefixLength = 0;
+  for (const [prefix, factory] of INFLECTOR_FACTORIES) {
+    if (!normalized.startsWith(prefix)) continue;
+    if (prefix.length > bestPrefixLength) {
+      bestPrefixLength = prefix.length;
+      bestFactory = factory;
+    }
+  }
+  if (bestFactory) return bestFactory();
+  return createEnglishInflector();
+};