@rvoh/dream 2.3.1 → 2.3.3

package/dist/esm/src/dream/Query.js

@@ -20,6 +20,8 @@ import ops from '../ops/index.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
 import extractNestedPaths from './internal/extractNestedPaths.js';
+// Cache for extractNestedPaths results, keyed by "${sanitizedName}:${serializerKey}"
+const extractedNestedPathsCache = new Map();
 export default class Query {
     /**
      * @internal
@@ -524,7 +526,13 @@ export default class Query {
      * @returns A Query with all serialization associations preloaded
      */
     preloadFor(serializerKey, modifierFn) {
-        const preloadArgs = extractNestedPaths(this.dreamClass['serializationMap'](serializerKey));
+        const cacheKey = `${this.dreamClass.sanitizedName}:${serializerKey ?? 'default'}`;
+        let preloadArgs = extractedNestedPathsCache.get(cacheKey);
+        if (!preloadArgs) {
+            // Cache miss - compute and store
+            preloadArgs = extractNestedPaths(this.dreamClass['serializationMap'](serializerKey));
+            extractedNestedPathsCache.set(cacheKey, preloadArgs);
+        }
         let query = this;
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
             query = query.preload(...convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));

package/dist/esm/src/dream-app/index.js

@@ -7,6 +7,7 @@ import DreamAppInitMissingCallToLoadModels from '../errors/dream-app/DreamAppIni
 import DreamAppInitMissingMissingProjectRoot from '../errors/dream-app/DreamAppInitMissingMissingProjectRoot.js';
 import DreamAppInitMissingPackageManager from '../errors/dream-app/DreamAppInitMissingPackageManager.js';
 import autogeneratedFileDisclaimer from '../helpers/cli/autoGeneratedFileDisclaimer.js';
+import modelClassNameFrom from '../helpers/cli/modelClassNameFrom.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import globalClassNameFromFullyQualifiedModelName from '../helpers/globalClassNameFromFullyQualifiedModelName.js';
 import absoluteDreamPath from '../helpers/path/absoluteDreamPath.js';
@@ -87,6 +88,7 @@ export default class DreamApp {
     static get system() {
         return {
             globalClassNameFromFullyQualifiedModelName,
+            modelClassNameFrom,
             absoluteDreamPath,
             dreamPath,
             standardizeFullyQualifiedModelName,
@@ -412,6 +414,10 @@ function loggerArgToString(arg) {
         return arg;
     if (typeof arg === 'boolean')
         return arg;
+    if (arg === null)
+        return 'null';
+    if (arg === undefined)
+        return 'undefined';
     if (arg instanceof DateTime || arg instanceof CalendarDate || arg instanceof BaseClockTime) {
         return arg.toISO();
     }

package/dist/esm/src/helpers/cli/generateDream.js

@@ -1,39 +1,31 @@
-import * as fs from 'node:fs/promises';
-import DreamCLI from '../../cli/index.js';
-import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
-import dreamPath from '../path/dreamPath.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import generateDreamContent from './generateDreamContent.js';
 import generateFactory from './generateFactory.js';
 import generateMigration from './generateMigration.js';
 import generateSerializer from './generateSerializer.js';
 import generateUnitSpec from './generateUnitSpec.js';
+import modelClassNameFrom from './modelClassNameFrom.js';
+import writeGeneratedFile from './writeGeneratedFile.js';
 export default async function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
-    const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(dreamPath('models'), `${fullyQualifiedModelName}.ts`);
-    try {
-        DreamCLI.logger.log(`[dream] generating dream: ${relFilePath}`);
-        await fs.mkdir(absDirPath, { recursive: true });
-        await fs.writeFile(absFilePath, generateDreamContent({
+    const modelClassName = modelClassNameFrom(fullyQualifiedModelName, options.modelName);
+    await writeGeneratedFile({
+        dreamPathKey: 'models',
+        fileName: `${fullyQualifiedModelName}.ts`,
+        content: generateDreamContent({
             fullyQualifiedModelName,
             columnsWithTypes,
             fullyQualifiedParentName,
             serializer: options.serializer,
             includeAdminSerializers: options.includeAdminSerializers,
             connectionName: options.connectionName,
-        }));
-    }
-    catch (error) {
-        throw new Error(`
-      Something happened while trying to create the Dream file:
-        ${relFilePath}
-
-      Does this file already exist? Here is the error that was raised:
-        ${error.message}
-    `);
-    }
+            tableName: options.tableName,
+            modelClassName,
+        }),
+        logLabel: 'dream',
+    });
     await generateUnitSpec({ fullyQualifiedModelName });
-    await generateFactory({ fullyQualifiedModelName, columnsWithTypes });
+    await generateFactory({ fullyQualifiedModelName, columnsWithTypes, modelClassName });
     if (options.serializer)
         await generateSerializer({
             fullyQualifiedModelName,
@@ -41,6 +33,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             fullyQualifiedParentName,
             stiBaseSerializer: options.stiBaseSerializer,
             includeAdminSerializers: options.includeAdminSerializers,
+            modelClassName,
         });
     const isSTI = !!fullyQualifiedParentName;
     if (columnsWithTypes.length || !isSTI) {
@@ -50,6 +43,8 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             columnsWithTypes,
             fullyQualifiedModelName,
             fullyQualifiedParentName,
+            tableName: options.tableName,
+            modelClassName,
         });
     }
 }

package/dist/esm/src/helpers/cli/generateDreamContent.js

@@ -31,7 +31,7 @@ ${tableMethod}${serializersMethod}${fieldsSection}
 }
 export function createModelConfig(options) {
     const fullyQualifiedModelName = standardizeFullyQualifiedModelName(options.fullyQualifiedModelName);
-    const modelClassName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedModelName);
+    const modelClassName = options.modelClassName;
     const isSTI = !!options.fullyQualifiedParentName;
     let parentModelClassName;
     if (isSTI) {
@@ -40,7 +40,7 @@ export function createModelConfig(options) {
     }
     const connectionName = options.connectionName || 'default';
     const applicationModelName = connectionName === 'default' ? 'ApplicationModel' : `${pascalize(connectionName)}ApplicationModel`;
-    const tableName = snakeify(pluralize(fullyQualifiedModelName.replace(/\//g, '_')));
+    const tableName = options.tableName || snakeify(pluralize(fullyQualifiedModelName.replace(/\//g, '_')));
     return {
         fullyQualifiedModelName,
         modelClassName,

package/dist/esm/src/helpers/cli/generateFactory.js

@@ -1,24 +1,10 @@
-import * as fs from 'node:fs/promises';
-import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
-import dreamPath from '../path/dreamPath.js';
-import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import generateFactoryContent from './generateFactoryContent.js';
-import DreamCLI from '../../cli/index.js';
-export default async function generateFactory({ fullyQualifiedModelName, columnsWithTypes, }) {
-    fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
-    const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(dreamPath('factories'), `${fullyQualifiedModelName}Factory.ts`);
-    try {
-        DreamCLI.logger.log(`[dream] generating factory: ${relFilePath}`);
-        await fs.mkdir(absDirPath, { recursive: true });
-        await fs.writeFile(absFilePath, generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes }));
-    }
-    catch (error) {
-        throw new Error(`
-      Something happened while trying to create the spec file:
-        ${relFilePath}
-
-      Does this file already exist? Here is the error that was raised:
-        ${error.message}
-    `);
-    }
+import writeGeneratedFile from './writeGeneratedFile.js';
+export default async function generateFactory({ fullyQualifiedModelName, columnsWithTypes, modelClassName, }) {
+    await writeGeneratedFile({
+        dreamPathKey: 'factories',
+        fileName: `${fullyQualifiedModelName}Factory.ts`,
+        content: generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, modelClassName }),
+        logLabel: 'factory',
+    });
 }

package/dist/esm/src/helpers/cli/generateFactoryContent.js

@@ -4,7 +4,7 @@ import absoluteDreamPath from '../path/absoluteDreamPath.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
 import { optionalFromDescriptors } from './generateMigrationContent.js';
-export default function generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, }) {
+export default function generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, modelClassName, }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
     const dreamTypeImports = ['UpdateableProperties'];
     const dreamImports = [];
@@ -129,7 +129,6 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
         }
     }
     const relativePath = absoluteDreamPath('models', fullyQualifiedModelName);
-    const modelClassName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedModelName);
     return `\
 ${nodeImports.length ? `import { ${uniq(nodeImports).join(', ')} } from 'node:crypto'\n` : ''}${dreamImports.length ? `import { ${uniq(dreamImports).join(', ')} } from '@rvoh/dream'\n` : ''}import { ${uniq(dreamTypeImports).join(', ')} } from '@rvoh/dream/types'
 import ${modelClassName} from '${relativePath}'${additionalImports.length ? '\n' + uniq(additionalImports).join('\n') : ''}

package/dist/esm/src/helpers/cli/generateMigration.js

@@ -1,4 +1,3 @@
-import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import pluralize from 'pluralize-esm';
 import generateMigrationContent from '../cli/generateMigrationContent.js';
@@ -6,52 +5,45 @@ import primaryKeyType from '../db/primaryKeyType.js';
 import hyphenize from '../hyphenize.js';
 import migrationVersion from '../migrationVersion.js';
 import pascalizePath from '../pascalizePath.js';
-import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
 import dreamPath from '../path/dreamPath.js';
 import snakeify from '../snakeify.js';
 import generateStiMigrationContent from './generateStiMigrationContent.js';
-import DreamCLI from '../../cli/index.js';
-export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, }) {
-    const { relFilePath, absFilePath } = connectionName === 'default'
-        ? dreamFileAndDirPaths(path.join(dreamPath('db'), 'migrations'), `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`)
-        : dreamFileAndDirPaths(path.join(dreamPath('db'), 'migrations', connectionName), `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`);
+import writeGeneratedFile from './writeGeneratedFile.js';
+export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, }) {
+    const migrationsBasePath = connectionName === 'default'
+        ? path.join(dreamPath('db'), 'migrations')
+        : path.join(dreamPath('db'), 'migrations', connectionName);
+    const fileName = `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`;
     const isSTI = !!fullyQualifiedParentName;
-    let finalContent = '';
+    let content = '';
     if (isSTI) {
-        finalContent = generateStiMigrationContent({
+        content = generateStiMigrationContent({
             table: snakeify(pluralize(pascalizePath(fullyQualifiedParentName))),
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
-            stiChildClassName: pascalizePath(fullyQualifiedModelName),
+            stiChildClassName: modelClassName || pascalizePath(fullyQualifiedModelName),
         });
     }
     else if (fullyQualifiedModelName) {
-        finalContent = generateMigrationContent({
-            table: snakeify(pluralize(pascalizePath(fullyQualifiedModelName))),
+        content = generateMigrationContent({
+            table: explicitTableName || snakeify(pluralize(pascalizePath(fullyQualifiedModelName))),
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
         });
     }
     else {
         const tableName = migrationName.match(/-to-(.+)$/)?.[1];
-        finalContent = generateMigrationContent({
+        content = generateMigrationContent({
             table: tableName ? pluralize(snakeify(tableName)) : '<table-name>',
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             createOrAlter: 'alter',
         });
     }
-    try {
-        DreamCLI.logger.log(`[dream] generating migration: ${relFilePath}`);
-        await fs.writeFile(absFilePath, finalContent);
-    }
-    catch (error) {
-        throw new Error(`
-      Something happened while trying to create the migration file:
-        ${relFilePath}
-
-      Does this file already exist? Here is the error that was raised:
-        ${error.message}
-    `);
-    }
+    await writeGeneratedFile({
+        basePath: migrationsBasePath,
+        fileName,
+        content,
+        logLabel: 'migration',
+    });
 }

package/dist/esm/src/helpers/cli/generateMigrationContent.js

@@ -1,9 +1,12 @@
 import pluralize from 'pluralize-esm';
+import lookupModelByGlobalName from '../../dream-app/helpers/lookupModelByGlobalName.js';
 import Query from '../../dream/Query.js';
 import InvalidDecimalFieldPassedToGenerator from '../../errors/InvalidDecimalFieldPassedToGenerator.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
+import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
 import snakeify from '../snakeify.js';
+import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
 export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, } = {}) {
@@ -43,6 +46,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 columnDefs.push(generateBelongsToStr(connectionName, attributeName, {
                     primaryKeyType,
                     omitInlineNonNull,
+                    originalAssociationName: nonStandardAttributeName,
                 }));
                 attributeName = snakeify(nonStandardAttributeName.split('/').pop());
                 attributeName = associationNameToForeignKey(attributeName);
@@ -279,10 +283,10 @@ function attributeTypeString(attributeType) {
             }
     }
 }
-function generateBelongsToStr(connectionName, associationName, { primaryKeyType, omitInlineNonNull: optional = false, }) {
+function generateBelongsToStr(connectionName, associationName, { primaryKeyType, omitInlineNonNull: optional = false, originalAssociationName, }) {
     const dbDriverClass = Query.dbDriverClass(connectionName);
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
-    const references = pluralize(associationName.replace(/\//g, '_').replace(/_id$/, ''));
+    const references = lookupReferencesTable(associationName, originalAssociationName);
     return `.addColumn('${associationNameToForeignKey(associationName.split('/').pop())}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
 }
 function generateIdStr({ primaryKeyType }) {
@@ -312,6 +316,27 @@ function generateIdStr({ primaryKeyType }) {
             return `.addColumn('id', '${primaryKeyType}', col => col.primaryKey())`;
     }
 }
+/**
+ * Determines the referenced table name for a belongs_to association.
+ * First tries to look up the actual model to get its table name (handles
+ * custom table name overrides). Falls back to deriving the table name
+ * from the association string if the model isn't found.
+ */
+function lookupReferencesTable(snakeAssociationName, originalAssociationName) {
+    if (originalAssociationName) {
+        try {
+            const globalName = globalClassNameFromFullyQualifiedModelName(standardizeFullyQualifiedModelName(originalAssociationName));
+            const model = lookupModelByGlobalName(globalName);
+            if (model?.table) {
+                return model.table;
+            }
+        }
+        catch {
+            // Model not found or DreamApp not initialized — fall through to string derivation
+        }
+    }
+    return pluralize(snakeAssociationName.replace(/\//g, '_').replace(/_id$/, ''));
+}
 function associationNameToForeignKey(associationName) {
     return snakeify(associationName.replace(/\//g, '_').replace(/_id$/, '') + '_id');
 }

package/dist/esm/src/helpers/cli/generateSerializer.js

@@ -1,30 +1,17 @@
-import * as fs from 'node:fs/promises';
-import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
-import dreamPath from '../path/dreamPath.js';
-import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import generateSerializerContent from './generateSerializerContent.js';
-import DreamCLI from '../../cli/index.js';
-export default async function generateSerializer({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, }) {
-    fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
-    const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(dreamPath('serializers'), `${fullyQualifiedModelName}Serializer.ts`);
-    try {
-        DreamCLI.logger.log(`[dream] generating serializer: ${relFilePath}`);
-        await fs.mkdir(absDirPath, { recursive: true });
-        await fs.writeFile(absFilePath, generateSerializerContent({
+import writeGeneratedFile from './writeGeneratedFile.js';
+export default async function generateSerializer({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, modelClassName, }) {
+    await writeGeneratedFile({
+        dreamPathKey: 'serializers',
+        fileName: `${fullyQualifiedModelName}Serializer.ts`,
+        content: generateSerializerContent({
             fullyQualifiedModelName,
             columnsWithTypes,
             fullyQualifiedParentName,
             stiBaseSerializer,
             includeAdminSerializers,
-        }));
-    }
-    catch (error) {
-        throw new Error(`
-      Something happened while trying to create the serializer file:
-        ${relFilePath}
-
-      Does this file already exist? Here is the error that was raised:
-        ${error.message}
-    `);
-    }
+            modelClassName,
+        }),
+        logLabel: 'serializer',
+    });
 }

package/dist/esm/src/helpers/cli/generateSerializerContent.js

@@ -4,7 +4,7 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import absoluteDreamPath from '../path/absoluteDreamPath.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
-export default function generateSerializerContent({ fullyQualifiedModelName, columnsWithTypes = [], fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, }) {
+export default function generateSerializerContent({ fullyQualifiedModelName, columnsWithTypes = [], fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, modelClassName, }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
     const additionalImports = [];
     const dreamImports = [];
@@ -16,8 +16,7 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
     else {
         dreamImports.push('DreamSerializer');
     }
-    const relatedModelImport = importStatementForModel(fullyQualifiedModelName);
-    const modelClassName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedModelName);
+    const relatedModelImport = importStatementForModel(modelClassName, fullyQualifiedModelName);
     const modelInstanceName = camelize(modelClassName);
     const modelSerializerSignature = stiBaseSerializer
         ? `<T extends ${modelClassName}>(StiChildClass: typeof ${modelClassName}, ${modelInstanceName}: T)`
@@ -94,10 +93,9 @@ function importStatementForSerializer(originModelName, destinationModelName) {
     const importFrom = absoluteDreamPath('serializers', destinationModelName);
     return `import { ${defaultSerializer}, ${summarySerializer} } from '${importFrom}'\n`;
 }
-function importStatementForModel(originModelName, destinationModelName = originModelName) {
-    const modelName = globalClassNameFromFullyQualifiedModelName(destinationModelName);
-    const importFrom = absoluteDreamPath('models', destinationModelName);
-    return `import ${modelName} from '${importFrom}'\n`;
+function importStatementForModel(modelClassName, fullyQualifiedModelName) {
+    const importFrom = absoluteDreamPath('models', fullyQualifiedModelName);
+    return `import ${modelClassName} from '${importFrom}'\n`;
 }
 function fullyQualifiedModelNameToSerializerBaseName(fullyQualifiedModelName) {
     return fullyQualifiedModelName.replace(/\//g, '');

package/dist/esm/src/helpers/cli/generateUnitSpec.js

@@ -1,24 +1,10 @@
-import * as fs from 'node:fs/promises';
-import DreamCLI from '../../cli/index.js';
-import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
-import dreamPath from '../path/dreamPath.js';
-import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import generateUnitSpecContent from './generateUnitSpecContent.js';
+import writeGeneratedFile from './writeGeneratedFile.js';
 export default async function generateUnitSpec({ fullyQualifiedModelName, }) {
-    fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
-    const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(dreamPath('modelSpecs'), `${fullyQualifiedModelName}.spec.ts`);
-    try {
-        DreamCLI.logger.log(`[dream] generating spec: ${relFilePath}`);
-        await fs.mkdir(absDirPath, { recursive: true });
-        await fs.writeFile(absFilePath, generateUnitSpecContent({ fullyQualifiedModelName }));
-    }
-    catch (error) {
-        throw new Error(`
-      Something happened while trying to create the spec file:
-        ${relFilePath}
-
-      Does this file already exist? Here is the error that was raised:
-        ${error.message}
-    `);
-    }
+    await writeGeneratedFile({
+        dreamPathKey: 'modelSpecs',
+        fileName: `${fullyQualifiedModelName}.spec.ts`,
+        content: generateUnitSpecContent({ fullyQualifiedModelName }),
+        logLabel: 'spec',
+    });
 }

package/dist/esm/src/helpers/cli/modelClassNameFrom.js

@@ -0,0 +1,15 @@
+import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
+import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
+/**
+ * Returns the model class name, either from an explicit override or derived
+ * from the fully qualified model name.
+ *
+ * @param fullyQualifiedModelName - e.g. "Room/Kitchen"
+ * @param modelNameOverride - optional explicit class name, e.g. "Kitchen"
+ * @returns The model class name, e.g. "RoomKitchen" (derived) or "Kitchen" (override)
+ */
+export default function modelClassNameFrom(fullyQualifiedModelName, modelNameOverride) {
+    if (modelNameOverride)
+        return modelNameOverride;
+    return globalClassNameFromFullyQualifiedModelName(standardizeFullyQualifiedModelName(fullyQualifiedModelName));
+}

package/dist/esm/src/helpers/cli/writeGeneratedFile.js

@@ -0,0 +1,26 @@
+import * as fs from 'node:fs/promises';
+import DreamCLI from '../../cli/index.js';
+import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
+import dreamPath from '../path/dreamPath.js';
+/**
+ * Common file-writing helper used by all Dream generators.
+ * Handles directory creation, file writing, logging, and error wrapping.
+ */
+export default async function writeGeneratedFile({ dreamPathKey, basePath, fileName, content, logLabel, }) {
+    const resolvedBasePath = basePath ?? dreamPath(dreamPathKey);
+    const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(resolvedBasePath, fileName);
+    try {
+        DreamCLI.logger.log(`[dream] generating ${logLabel}: ${relFilePath}`);
+        await fs.mkdir(absDirPath, { recursive: true });
+        await fs.writeFile(absFilePath, content);
+    }
+    catch (error) {
+        throw new Error(`
+      Something happened while trying to create the ${logLabel} file:
+        ${relFilePath}
+
+      Does this file already exist? Here is the error that was raised:
+        ${error.message}
+    `);
+    }
+}

package/dist/types/src/bin/index.d.ts

@@ -13,10 +13,15 @@ export default class DreamBin {
         serializer: boolean;
         stiBaseSerializer: boolean;
         connectionName: string;
+        tableName?: string;
+        adminSerializers?: boolean;
+        modelName?: string;
     }): Promise<void>;
     static generateStiChild(fullyQualifiedModelName: string, fullyQualifiedParentName: string, columnsWithTypes: string[], options: {
         serializer: boolean;
         connectionName: string;
+        adminSerializers?: boolean;
+        modelName?: string;
     }): Promise<void>;
     static generateMigration(migrationName: string, columnsWithTypes: string[], connectionName: string): Promise<void>;
     private static buildDocs;

package/dist/types/src/cli/index.d.ts

@@ -2,6 +2,8 @@ import { SpawnOptions } from 'child_process';
 import { Command } from 'commander';
 import DreamApp, { DreamAppInitOptions } from '../dream-app/index.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
+export declare const CLI_INDENT = "                  ";
+export declare const baseColumnsWithTypesDescription = "space separated snake-case (except for belongs_to model name) properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal User:belongs_to\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -17,6 +19,9 @@ export default class DreamCLI {
     }): void;
     /**
      * @internal
+     *
+     * Called by Psychic (and other consumers) to programmatically generate a
+     * Dream model with all associated files.
      */
     static generateDream(opts: {
         fullyQualifiedModelName: string;
@@ -26,6 +31,12 @@ export default class DreamCLI {
             serializer: boolean;
             stiBaseSerializer: boolean;
             includeAdminSerializers: boolean;
+            tableName?: string | undefined;
+            /**
+             * Optional model class name override. If provided, generators use it
+             * instead of deriving the class name from the fully qualified model name.
+             */
+            modelName?: string | undefined;
         };
         fullyQualifiedParentName?: string | undefined;
     }): Promise<void>;

package/dist/types/src/dream-app/index.d.ts

@@ -4,6 +4,7 @@ import Dream from '../Dream.js';
 import QueryDriverBase from '../dream/QueryDriver/Base.js';
 import { EncryptOptions } from '../encrypt/index.js';
 import autogeneratedFileDisclaimer from '../helpers/cli/autoGeneratedFileDisclaimer.js';
+import modelClassNameFrom from '../helpers/cli/modelClassNameFrom.js';
 import globalClassNameFromFullyQualifiedModelName from '../helpers/globalClassNameFromFullyQualifiedModelName.js';
 import absoluteDreamPath from '../helpers/path/absoluteDreamPath.js';
 import dreamPath from '../helpers/path/dreamPath.js';
@@ -56,6 +57,7 @@ export default class DreamApp {
      */
     static get system(): {
         globalClassNameFromFullyQualifiedModelName: typeof globalClassNameFromFullyQualifiedModelName;
+        modelClassNameFrom: typeof modelClassNameFrom;
         absoluteDreamPath: typeof absoluteDreamPath;
         dreamPath: typeof dreamPath;
         standardizeFullyQualifiedModelName: typeof standardizeFullyQualifiedModelName;

package/dist/types/src/helpers/cli/generateDream.d.ts

@@ -1,11 +1,14 @@
+export interface GenerateDreamOptions {
+    connectionName: string;
+    serializer: boolean;
+    stiBaseSerializer: boolean;
+    includeAdminSerializers: boolean;
+    tableName?: string | undefined;
+    modelName?: string | undefined;
+}
 export default function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }: {
     fullyQualifiedModelName: string;
     columnsWithTypes: string[];
-    options: {
-        connectionName: string;
-        serializer: boolean;
-        stiBaseSerializer: boolean;
-        includeAdminSerializers: boolean;
-    };
+    options: GenerateDreamOptions;
     fullyQualifiedParentName?: string | undefined;
 }): Promise<void>;

package/dist/types/src/helpers/cli/generateDreamContent.d.ts

@@ -5,6 +5,9 @@ interface GenerateDreamContentOptions {
     connectionName?: string;
     serializer: boolean;
     includeAdminSerializers: boolean;
+    tableName?: string | undefined;
+    /** Model class name, computed once via modelClassNameFrom in the orchestrator. */
+    modelClassName: string;
 }
 export interface ModelConfig {
     fullyQualifiedModelName: string;

package/dist/types/src/helpers/cli/generateFactory.d.ts

@@ -1,4 +1,5 @@
-export default function generateFactory({ fullyQualifiedModelName, columnsWithTypes, }: {
+export default function generateFactory({ fullyQualifiedModelName, columnsWithTypes, modelClassName, }: {
     fullyQualifiedModelName: string;
     columnsWithTypes: string[];
+    modelClassName: string;
 }): Promise<void>;

package/dist/types/src/helpers/cli/generateFactoryContent.d.ts

@@ -1,4 +1,6 @@
-export default function generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, }: {
+export default function generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, modelClassName, }: {
     fullyQualifiedModelName: string;
     columnsWithTypes: string[];
+    /** Model class name, computed once via modelClassNameFrom in the orchestrator. */
+    modelClassName: string;
 }): string;

package/dist/types/src/helpers/cli/generateMigration.d.ts

@@ -1,7 +1,14 @@
-export default function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, }: {
+export default function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, }: {
     migrationName: string;
     columnsWithTypes: string[];
     connectionName: string;
     fullyQualifiedModelName?: string | undefined;
     fullyQualifiedParentName?: string | undefined;
+    tableName?: string | undefined;
+    /**
+     * Model class name, computed once via modelClassNameFrom in the orchestrator.
+     * Required when generating a migration for a model (especially STI children).
+     * Omitted for standalone `g:migration` commands.
+     */
+    modelClassName?: string | undefined;
 }): Promise<void>;

package/dist/types/src/helpers/cli/generateSerializer.d.ts

@@ -1,7 +1,8 @@
-export default function generateSerializer({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, }: {
+export default function generateSerializer({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, stiBaseSerializer, includeAdminSerializers, modelClassName, }: {
     fullyQualifiedModelName: string;
     columnsWithTypes: string[];
     fullyQualifiedParentName?: string | undefined;
     stiBaseSerializer: boolean;
     includeAdminSerializers: boolean;
+    modelClassName: string;
 }): Promise<void>;