@rvoh/dream 2.3.0 → 2.3.2

package/dist/esm/src/cli/index.js

@@ -6,8 +6,9 @@ import EnvInternal from '../helpers/EnvInternal.js';
 import loadRepl from '../helpers/loadRepl.js';
 import sspawn from '../helpers/sspawn.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
-const INDENT = '                  ';
-const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name) properties like this:
+export const CLI_INDENT = '                  ';
+const INDENT = CLI_INDENT;
+export const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name) properties like this:
 ${INDENT}    title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal User:belongs_to
 ${INDENT}
 ${INDENT}all properties default to not nullable; null can be allowed by appending ':optional':
@@ -99,6 +100,9 @@ export default class DreamCLI {
     }
     /**
      * @internal
+     *
+     * Called by Psychic (and other consumers) to programmatically generate a
+     * Dream model with all associated files.
      */
     static async generateDream(opts) {
         await generateDream(opts);
@@ -128,6 +132,9 @@ export default class DreamCLI {
             .option('--no-serializer')
             .option('--connection-name <connectionName>', 'the db connection you want this attached to (defaults to the default db connection)', 'default')
             .option('--sti-base-serializer')
+            .option('--table-name <tableName>', 'explicit table name to use instead of the auto-generated one (useful when model namespaces produce long names)')
+            .option('--model-name <modelName>', 'explicit model class name to use instead of the auto-generated one (e.g. --model-name=Kitchen for Room/Kitchen)')
+            .option('--admin-serializers', 'generate admin serializer variants (AdminSerializer and AdminSummarySerializer) in addition to the default serializers')
             .argument('<modelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
             .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (modelName, columnsWithTypes, options) => {
@@ -141,6 +148,8 @@ export default class DreamCLI {
             .description('Generates a Dream model that extends another Dream model, leveraging STI (single table inheritance), with corresponding spec factory, serializer, and migration.')
             .option('--no-serializer')
             .option('--connection-name', 'the db connection you want this model attached to (defaults to the default connection)', 'default')
+            .option('--model-name <modelName>', 'explicit model class name to use instead of the auto-generated one (e.g. --model-name=Kitchen for Room/Kitchen)')
+            .option('--admin-serializers', 'generate admin serializer variants (AdminSerializer and AdminSummarySerializer) in addition to the default serializers')
             .argument('<childModelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
             .argument('<extends>', 'just the word "extends"')
             .argument('<parentModelName>', `fully qualified name of the parent model, e.g.:

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/QueryDriver/Kysely.js

@@ -33,7 +33,6 @@ import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
 import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
 import NotNullViolation from '../../errors/db/NotNullViolation.js';
 import UnexpectedUndefined from '../../errors/UnexpectedUndefined.js';
-import camelize from '../../helpers/camelize.js';
 import ASTGlobalSchemaBuilder from '../../helpers/cli/ASTGlobalSchemaBuilder.js';
 import ASTSchemaBuilder from '../../helpers/cli/ASTSchemaBuilder.js';
 import generateMigration from '../../helpers/cli/generateMigration.js';
@@ -533,18 +532,20 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         let kyselyQuery = new this.constructor(this.query).buildSelect({
             bypassSelectAll: true,
         });
-        const aliases = [];
-        fields.forEach((field) => {
-            // field will already be namespaced in a join situation, but when the field to pluck is on the
-            // base model, it will be underscored (to match the table name), but when the selected column
-            // comes back from Kysely camelCased
-            aliases.push(field.includes('_') ? camelize(field) : field);
+        // Use short aliases to avoid PostgreSQL's 63-byte identifier truncation.
+        // Previously, the full namespaced field (e.g. "longAlias.columnName") was used as the
+        // AS alias, which Kysely's CamelCasePlugin converts to a single snake_case identifier
+        // that can exceed 63 bytes. Short aliases like "pluck0" avoid this entirely.
+        const shortAliases = [];
+        fields.forEach((field, index) => {
+            const shortAlias = `pluck${index}`;
+            shortAliases.push(shortAlias);
             //  namespace the selection so that when plucking the same column name from
-            // multpile tables, they don't get saved as the same name (e.g. select results with two `id` columns,
+            // multiple tables, they don't get saved as the same name (e.g. select results with two `id` columns,
             // which the pg package then returns in an object with a single `id` key)
-            kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(field)} as ${field}`);
+            kyselyQuery = kyselyQuery.select(`${this.namespaceColumn(field)} as ${shortAlias}`);
         });
-        return (await executeDatabaseQuery(kyselyQuery, 'execute')).map(singleResult => aliases.map(alias => singleResult[alias]));
+        return (await executeDatabaseQuery(kyselyQuery, 'execute')).map(singleResult => shortAliases.map(alias => singleResult[alias]));
     }
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used

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,

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                          scale,precision 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;