@rvoh/dream 2.10.0 → 2.11.1

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

@@ -11,7 +11,7 @@ import DreamCliLogger from './logger/DreamCliLogger.js';
 import colorize from './logger/loggable/colorize.js';
 export const CLI_INDENT = '                  ';
 const INDENT = CLI_INDENT;
-export const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name) properties like this:
+export const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name, which may take an @alias suffix to rename the FK) 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':
@@ -71,7 +71,16 @@ ${INDENT}
 ${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
 ${INDENT}          User:belongs_to                  # creates user_id column + BelongsTo association
 ${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column + BelongsTo association
-${INDENT}          User:belongs_to:optional          # nullable foreign key (for optional associations)`;
+${INDENT}          User:belongs_to:optional          # nullable foreign key (for optional associations)
+${INDENT}
+${INDENT}        rename the association with Model@alias — the snake_case alias drives the FK column name AND the
+${INDENT}        @deco.BelongsTo association + typed FK property on the generated model:
+${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column, canceledById property, canceledBy association,
+${INDENT}                                                             #   @deco.BelongsTo('InternalUser', { on: 'canceledById', optional: true })
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column, templateId property, template association
+${INDENT}                                                             #   (strips the namespace from the property/association names while keeping
+${INDENT}                                                             #   the namespaced model reference intact)
+${INDENT}        Aliasing also lets you declare multiple FKs to the same model in one generator call without column collisions.`;
 const columnsWithTypesDescriptionForMigration = baseColumnsWithTypesDescription +
     `
 ${INDENT}
@@ -82,7 +91,11 @@ ${INDENT}
 ${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
 ${INDENT}          User:belongs_to                  # creates user_id column with index
 ${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column with index
-${INDENT}          User:belongs_to:optional          # nullable foreign key`;
+${INDENT}          User:belongs_to:optional          # nullable foreign key
+${INDENT}
+${INDENT}        rename the FK column with Model@alias (snake_case alias becomes the column name):
+${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column with index
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`;
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/cjs/src/encrypt/index.js

@@ -1,5 +1,5 @@
 import DecryptionError from '../errors/encrypt/DecryptionError.js';
-import DecryptionWithRotationError from '../errors/encrypt/DecryptionWithRotationError.js';
+import DecryptionRotationError from '../errors/encrypt/DecryptionRotationError.js';
 import MissingEncryptionKey from '../errors/encrypt/MissingEncryptionKey.js';
 import decryptAESGCM from './algorithms/aes-gcm/decryptAESGCM.js';
 import encryptAESGCM from './algorithms/aes-gcm/encryptAESGCM.js';
@@ -34,7 +34,7 @@ export default class Encrypt {
      *
      * **Three-arg form** (rotation): tries the current key first; on
      * `DecryptionError` falls back to the legacy key. If both fail, throws
-     * `DecryptionWithRotationError` carrying both per-key errors. A
+     * `DecryptionRotationError` carrying both per-key errors. A
      * `DecryptionParseError` from the current key is **not** retried — the
      * cipher already matched, so a parse failure means the encrypted format
      * is wrong (an app bug), not a wrong key.
@@ -44,7 +44,7 @@ export default class Encrypt {
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
-     * @throws DecryptionWithRotationError
+     * @throws DecryptionRotationError
      */
     static decrypt(encrypted, { algorithm, key }, legacyOpts) {
         if (legacyOpts)
@@ -81,7 +81,7 @@ export default class Encrypt {
         catch (err) {
             if (!(err instanceof DecryptionError))
                 throw err;
-            throw new DecryptionWithRotationError(currentKeyError, err);
+            throw new DecryptionRotationError(currentKeyError, err);
         }
     }
     /**
@@ -117,7 +117,7 @@ export default class Encrypt {
      *   not forced to re-authenticate.
      * - For `@Encrypted` columns: until every existing row has been
      *   re-encrypted under the new key. Dropping `legacy` early will cause
-     *   `DecryptionWithRotationError` on any not-yet-rewritten row.
+     *   `DecryptionRotationError` on any not-yet-rewritten row.
      */
     static generateKey(algorithm) {
         switch (algorithm) {

package/dist/cjs/src/errors/encrypt/{DecryptionWithRotationError.js → DecryptionRotationError.js}

@@ -1,4 +1,4 @@
-export default class DecryptionWithRotationError extends Error {
+export default class DecryptionRotationError extends Error {
     currentKeyError;
     legacyKeyError;
     constructor(currentKeyError, legacyKeyError) {

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

@@ -7,6 +7,7 @@ import absoluteDreamPath from '../path/absoluteDreamPath.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
+import parseAttribute from './parseAttribute.js';
 /**
  * Column names that are automatically emitted by the model generator (and
  * the migration generator). When the user passes any of these explicitly,
@@ -35,8 +36,17 @@ export default function generateDreamContent(options) {
     const columnsForAttributes = config.isSTI
         ? options.columnsWithTypes
         : filterAutoGeneratedTimestampColumns(options.columnsWithTypes);
-    const baseImports = createImportConfig(config, options, { includeSoftDelete });
     const attributesResult = processAttributes(columnsForAttributes, config.modelClassName);
+    // Decorators is only referenced via `@deco.*` annotations on fields (e.g.,
+    // BelongsTo, Encrypted). If the generated body emits none of those, the
+    // import + declaration would trigger lint errors for unused identifiers,
+    // so emit them commented out instead — keeps the boilerplate present for
+    // the developer to uncomment when they add their first decorator.
+    const decoratorsInUse = attributesResult.formattedDecorators.length > 0;
+    const baseImports = createImportConfig(config, options, {
+        includeSoftDelete,
+        includeDecorators: decoratorsInUse,
+    });
     const allImports = {
         ...baseImports,
         modelImportStatements: [...baseImports.modelImportStatements, ...attributesResult.imports],
@@ -48,9 +58,14 @@ export default function generateDreamContent(options) {
     const fieldsSection = buildFieldsSection(config, attributesResult, {
         includeDeletedAt: includeSoftDelete || hasExplicitDeletedAt,
     });
+    const decoBlock = decoratorsInUse
+        ? `const deco = new Decorators<typeof ${config.modelClassName}>()`
+        : `// Uncomment when adding decorators (@deco.BelongsTo, @deco.Validates, etc.):
+// import { Decorators } from '@rvoh/dream'
+// const deco = new Decorators<typeof ${config.modelClassName}>()`;
     return `${importSection}
 
-const deco = new Decorators<typeof ${config.modelClassName}>()
+${decoBlock}
 
 ${classDeclaration}
 ${tableMethod}${serializersMethod}${fieldsSection}
@@ -78,9 +93,11 @@ export function createModelConfig(options) {
         tableName,
     };
 }
-export function createImportConfig(config, options, { includeSoftDelete }) {
+export function createImportConfig(config, options, { includeSoftDelete, includeDecorators = true }) {
     const dreamTypeImports = ['DreamColumn'];
-    const dreamImports = ['Decorators'];
+    const dreamImports = [];
+    if (includeDecorators)
+        dreamImports.push('Decorators');
     if (options.serializer) {
         dreamTypeImports.push('DreamSerializers');
     }
@@ -119,32 +136,41 @@ export function processAttributes(columnsWithTypes, modelClassName) {
     };
 }
 export function processAttribute(attribute, modelClassName) {
-    const [attributeName, attributeType, ...descriptors] = attribute.split(':');
-    if (attributeName === undefined)
+    const [rawName, rawType] = attribute.split(':');
+    if (rawName === undefined)
         return { content: '', imports: [] };
-    if (!attributeType) {
-        throw new Error(`must pass a column type for ${attributeName} (i.e. ${attributeName}:string)`);
+    if (!rawType) {
+        throw new Error(`must pass a column type for ${rawName} (i.e. ${rawName}:string)`);
     }
-    const processedAttrType = camelize(attributeType).toLowerCase();
-    switch (processedAttrType) {
+    const parsed = parseAttribute(attribute);
+    // Malformed-but-parseable shapes (e.g., `Model@:belongs_to` with an empty
+    // alias) yield no content rather than throwing — the call site has already
+    // validated the basic name/type segments above.
+    if (!parsed)
+        return { content: '', imports: [] };
+    switch (parsed.normalizedAttributeType) {
         case 'belongsto':
-            return createBelongsToAttribute(attributeName, descriptors, modelClassName);
+            return createBelongsToAttribute(parsed.rawAttributeName, modelClassName, {
+                aliasName: parsed.aliasName,
+                isOptional: parsed.isOptional,
+            });
         case 'hasone':
         case 'hasmany':
             return { content: '', imports: [] };
         case 'encrypted':
-            return createEncryptedAttribute(attributeName, attribute, modelClassName);
+            return createEncryptedAttribute(parsed.rawAttributeName, attribute, modelClassName);
         default:
-            return createRegularAttribute(attributeName, attribute, modelClassName);
+            return createRegularAttribute(parsed.rawAttributeName, attribute, modelClassName);
     }
 }
-export function createBelongsToAttribute(attributeName, descriptors, modelClassName) {
-    const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
+export function createBelongsToAttribute(fullyQualifiedModelInput, modelClassName, { aliasName, isOptional = false, } = {}) {
+    const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelInput);
     const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);
     const associationImportStatement = importStatementForModel(fullyQualifiedAssociatedModelName);
-    const associationName = camelize(fullyQualifiedAssociatedModelName.split('/').pop());
+    const associationName = aliasName
+        ? camelize(aliasName)
+        : camelize(fullyQualifiedAssociatedModelName.split('/').pop());
     const associationForeignKey = `${associationName}Id`;
-    const isOptional = descriptors.includes('optional');
     const content = `
 @deco.BelongsTo('${fullyQualifiedAssociatedModelName}', { on: '${associationForeignKey}'${isOptional ? ', optional: true' : ''} })
 public ${associationName}: ${associationModelName}${isOptional ? ' | null' : ''}

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

@@ -17,14 +17,23 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
     const attributeDefaults = [];
     let counterVariableIncremented = false;
     for (const attribute of columnsWithTypes) {
-        const [attributeName, _attributeType, ...descriptors] = attribute.split(':');
-        if (attributeName === undefined)
+        const [rawSegmentOne, _attributeType, ...descriptors] = attribute.split(':');
+        if (rawSegmentOne === undefined)
             continue;
         if (_attributeType === undefined)
             continue;
         const optional = optionalFromDescriptors(descriptors);
         if (optional)
             continue;
+        // Extract optional `@alias` from segment-1 (Model@alias:belongs_to form).
+        // Non-association tokens never contain `@`, so this is a no-op for scalars.
+        const atIdx = rawSegmentOne.indexOf('@');
+        const aliasName = atIdx !== -1 ? rawSegmentOne.slice(atIdx + 1) : undefined;
+        const attributeName = atIdx !== -1 ? rawSegmentOne.slice(0, atIdx) : rawSegmentOne;
+        if (!attributeName)
+            continue;
+        if (atIdx !== -1 && !aliasName)
+            continue;
         const attributeVariable = camelize(attributeName.replace(/\//g, ''));
         if (/^type$/.test(attributeName))
             continue;
@@ -36,7 +45,9 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
         const safeAttributeType = camelize(attributeType)?.toLowerCase();
         switch (safeAttributeType) {
             case 'belongsto': {
-                const attributeVariable = camelize(attributeName.split('/').pop());
+                // When `Model@alias:belongs_to`, the factory property uses the alias;
+                // otherwise it uses the model's last namespace segment (legacy form).
+                const attributeVariable = aliasName ? camelize(aliasName) : camelize(attributeName.split('/').pop());
                 const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
                 const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);
                 const associationFactoryImportStatement = `import create${associationModelName} from '${absoluteDreamPath('factories', fullyQualifiedAssociatedModelName)}'`;
@@ -66,11 +77,27 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
                 counterVariableIncremented = true;
                 break;
             case 'enum':
-                attributeDefaults.push(`${attributeVariable}: '${(descriptors.at(-1) || '<tbd>').split(',')[0]}',`);
-                break;
-            case 'enum[]':
-                attributeDefaults.push(`${attributeVariable}: ['${(descriptors.at(-1) || '<tbd>').split(',')[0]}'],`);
+            case 'enum[]': {
+                // When the user passed `name:enum:enum_type_name` (reuse form, no
+                // inline values), descriptors has exactly one element — the enum
+                // type name. The factory cannot see the enum's values, so emit a
+                // TS-rejecting placeholder rather than the type name itself (the
+                // previous behavior emitted `'enum_type_name'` as the literal value,
+                // which compiles in the factory but fails at runtime).
+                const isReuseWithoutValues = descriptors.length === 1;
+                const isArrayEnum = safeAttributeType === 'enum[]';
+                if (isReuseWithoutValues) {
+                    const enumTypeName = descriptors[0];
+                    const placeholder = isArrayEnum ? `['TODO']` : `'TODO'`;
+                    attributeDefaults.push(`// TODO: replace with a value from the \`${enumTypeName}\` enum\n    ${attributeVariable}: ${placeholder},`);
+                }
+                else {
+                    const firstValue = (descriptors.at(-1) || '<tbd>').split(',')[0];
+                    const literal = isArrayEnum ? `['${firstValue}']` : `'${firstValue}'`;
+                    attributeDefaults.push(`${attributeVariable}: ${literal},`);
+                }
                 break;
+            }
             case 'integer':
                 attributeDefaults.push(`${attributeVariable}: 1,`);
                 break;

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

@@ -27,9 +27,19 @@ export default function generateMigrationContent({ connectionName = 'default', t
     const emitDeletedAtColumn = !altering && (softDelete || userExplicitlyPassedDeletedAt);
     const { columnDefs, columnDrops, indexDefs, indexDrops } = processedColumnsWithTypes.reduce((acc, attributeDeclaration) => {
         const { columnDefs, columnDrops, indexDefs, indexDrops } = acc;
-        const [nonStandardAttributeName, _attributeType, ...descriptors] = attributeDeclaration.split(':');
+        const [rawSegmentOne, _attributeType, ...descriptors] = attributeDeclaration.split(':');
+        if (!rawSegmentOne)
+            return acc;
+        // Extract optional `@alias` from segment-1 (Model@alias:belongs_to form).
+        // The model name (without alias) is what gets standardized / referenced
+        // by table lookup; the alias drives the column / index naming when present.
+        const atIdx = rawSegmentOne.indexOf('@');
+        const aliasName = atIdx !== -1 ? rawSegmentOne.slice(atIdx + 1) : undefined;
+        const nonStandardAttributeName = atIdx !== -1 ? rawSegmentOne.slice(0, atIdx) : rawSegmentOne;
         if (!nonStandardAttributeName)
             return acc;
+        if (atIdx !== -1 && !aliasName)
+            return acc;
         /**
          * Automatically set email columns to citext since different casings of
          * email address are the same email address
@@ -64,8 +74,14 @@ export default function generateMigrationContent({ connectionName = 'default', t
                     primaryKeyType,
                     omitInlineNonNull,
                     originalAssociationName: nonStandardAttributeName,
+                    aliasName,
                 }));
-                attributeName = snakeify(nonStandardAttributeName.split('/').pop());
+                // Resolve the actual column name used for index + drop emission.
+                // When an alias is present (Model@alias:belongs_to), the column is
+                // `${alias}_id`; otherwise it's derived from the model's last segment.
+                attributeName = aliasName
+                    ? snakeify(aliasName)
+                    : snakeify(nonStandardAttributeName.split('/').pop());
                 attributeName = associationNameToForeignKey(attributeName);
                 break;
             case 'enum':
@@ -268,6 +284,7 @@ function generateColumnStr(attributeName, attributeType, descriptors, { omitInli
     const isUnique = /(email|token|uuid)$/.test(attributeName);
     const hasExtraValues = providedDefault || notNull || isUnique;
     const isArray = /\[\]$/.test(attributeType);
+    const needsJsonDefault = notNull && !isArray && (attributeType === 'jsonb' || attributeType === 'json');
     if (hasExtraValues)
         returnStr += ', col => col';
     if (notNull)
@@ -278,6 +295,12 @@ function generateColumnStr(attributeName, attributeType, descriptors, { omitInli
         returnStr += `.defaultTo('${providedDefault}')`;
     else if (isArray)
         returnStr += `.defaultTo('{}')`;
+    // jsonb / json columns get an empty-object default so calling create() on a
+    // model without explicitly setting the column doesn't trip NOT NULL. Mirrors
+    // the existing boolean → false and array → '{}' auto-defaults. Optional
+    // jsonb columns skip the default since null is the intended initial state.
+    else if (needsJsonDefault)
+        returnStr += `.defaultTo(sql\`'{}'::${attributeType}\`)`;
     returnStr = `${returnStr})`;
     if (attributeName === STI_TYPE_COLUMN_NAME)
         returnStr = `// CONSIDER: when using type for STI, always use an enum
@@ -306,11 +329,14 @@ function attributeTypeString(attributeType) {
             }
     }
 }
-function generateBelongsToStr(connectionName, associationName, { primaryKeyType, omitInlineNonNull: optional = false, originalAssociationName, }) {
+function generateBelongsToStr(connectionName, associationName, { primaryKeyType, omitInlineNonNull: optional = false, originalAssociationName, aliasName, }) {
     const dbDriverClass = Query.dbDriverClass(connectionName);
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
     const references = lookupReferencesTable(associationName, originalAssociationName);
-    return `.addColumn('${associationNameToForeignKey(associationName.split('/').pop())}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
+    // When the user passed `Model@alias:belongs_to`, the column name comes from
+    // the alias; otherwise it's the model's last segment (existing behavior).
+    const columnNameSource = aliasName ? snakeify(aliasName) : associationName.split('/').pop();
+    return `.addColumn('${associationNameToForeignKey(columnNameSource)}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
 }
 function generateIdStr({ primaryKeyType }) {
     switch (primaryKeyType) {

package/dist/cjs/src/helpers/cli/parseAttribute.js

@@ -0,0 +1,61 @@
+import camelize from '../camelize.js';
+/**
+ * Parse a single `columnsWithTypes` CLI token into its structural pieces.
+ *
+ * Centralizes the splitting + normalization logic shared across the model
+ * generator (`generateDreamContent`), the migration generator
+ * (`generateMigrationContent`), the factory generator
+ * (`generateFactoryContent`), and Psychic's resource/controller generators.
+ * Keeps the shared layer thin: consumers handle their own coercions (e.g.,
+ * migration's `email$ → citext`) and filters (e.g., Psychic's `_type`/`_id`
+ * exclusion).
+ *
+ * Returns `null` for malformed tokens (missing name or type).
+ *
+ * Supported forms (segment-1 only — see `rawAttributeType` for the full
+ * vocabulary of types/associations recognized by individual generators):
+ *
+ *   - `name:type`                          → standard column
+ *   - `name:type:optional`                 → nullable column
+ *   - `Model:belongs_to[:optional]`        → association with model-derived alias
+ *   - `Model@alias:belongs_to[:optional]`  → association with explicit alias
+ */
+export default function parseAttribute(attribute) {
+    const segments = attribute.split(':');
+    const rawSegmentOne = segments[0];
+    const rawAttributeType = segments[1];
+    const descriptors = segments.slice(2);
+    if (!rawSegmentOne || !rawAttributeType)
+        return null;
+    // Split segment-1 on `@` to extract an optional alias. Empty alias after `@`
+    // (e.g., `Model@:belongs_to`) is treated as malformed.
+    let rawAttributeName = rawSegmentOne;
+    let aliasName;
+    const atIndex = rawSegmentOne.indexOf('@');
+    if (atIndex !== -1) {
+        rawAttributeName = rawSegmentOne.slice(0, atIndex);
+        const rawAlias = rawSegmentOne.slice(atIndex + 1);
+        if (!rawAttributeName || !rawAlias)
+            return null;
+        aliasName = rawAlias;
+    }
+    // Pop trailing `optional` keyword off the descriptors list. Mirrors
+    // `optionalFromDescriptors` in generateMigrationContent.ts so the keyword
+    // behaves identically regardless of which consumer parses the token.
+    let isOptional = false;
+    if (descriptors[descriptors.length - 1] === 'optional') {
+        descriptors.pop();
+        isOptional = true;
+    }
+    const normalizedAttributeType = camelize(rawAttributeType).toLowerCase();
+    const isArray = /\[\]$/.test(rawAttributeType);
+    return {
+        rawAttributeName,
+        aliasName,
+        rawAttributeType,
+        normalizedAttributeType,
+        descriptors,
+        isOptional,
+        isArray,
+    };
+}

package/dist/cjs/src/package-exports/errors.js

@@ -7,6 +7,9 @@ export { default as DataIncompatibleWithDatabaseField } from '../errors/db/DataI
 export { default as DataTypeColumnTypeMismatch } from '../errors/db/DataTypeColumnTypeMismatch.js';
 export { default as NotNullViolation } from '../errors/db/NotNullViolation.js';
 export { default as GlobalNameNotSet } from '../errors/dream-app/GlobalNameNotSet.js';
+export { default as DecryptionError } from '../errors/encrypt/DecryptionError.js';
+export { default as DecryptionParseError } from '../errors/encrypt/DecryptionParseError.js';
+export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
 export { default as MissingSerializersDefinition } from '../errors/serializers/MissingSerializersDefinition.js';
 export { default as ValidationError } from '../errors/ValidationError.js';

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

@@ -11,7 +11,7 @@ import DreamCliLogger from './logger/DreamCliLogger.js';
 import colorize from './logger/loggable/colorize.js';
 export const CLI_INDENT = '                  ';
 const INDENT = CLI_INDENT;
-export const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name) properties like this:
+export const baseColumnsWithTypesDescription = `space separated snake-case (except for belongs_to model name, which may take an @alias suffix to rename the FK) 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':
@@ -71,7 +71,16 @@ ${INDENT}
 ${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
 ${INDENT}          User:belongs_to                  # creates user_id column + BelongsTo association
 ${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column + BelongsTo association
-${INDENT}          User:belongs_to:optional          # nullable foreign key (for optional associations)`;
+${INDENT}          User:belongs_to:optional          # nullable foreign key (for optional associations)
+${INDENT}
+${INDENT}        rename the association with Model@alias — the snake_case alias drives the FK column name AND the
+${INDENT}        @deco.BelongsTo association + typed FK property on the generated model:
+${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column, canceledById property, canceledBy association,
+${INDENT}                                                             #   @deco.BelongsTo('InternalUser', { on: 'canceledById', optional: true })
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column, templateId property, template association
+${INDENT}                                                             #   (strips the namespace from the property/association names while keeping
+${INDENT}                                                             #   the namespaced model reference intact)
+${INDENT}        Aliasing also lets you declare multiple FKs to the same model in one generator call without column collisions.`;
 const columnsWithTypesDescriptionForMigration = baseColumnsWithTypesDescription +
     `
 ${INDENT}
@@ -82,7 +91,11 @@ ${INDENT}
 ${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
 ${INDENT}          User:belongs_to                  # creates user_id column with index
 ${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column with index
-${INDENT}          User:belongs_to:optional          # nullable foreign key`;
+${INDENT}          User:belongs_to:optional          # nullable foreign key
+${INDENT}
+${INDENT}        rename the FK column with Model@alias (snake_case alias becomes the column name):
+${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column with index
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`;
 export default class DreamCLI {
     /**
      * Starts the Dream console

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

@@ -1,5 +1,5 @@
 import DecryptionError from '../errors/encrypt/DecryptionError.js';
-import DecryptionWithRotationError from '../errors/encrypt/DecryptionWithRotationError.js';
+import DecryptionRotationError from '../errors/encrypt/DecryptionRotationError.js';
 import MissingEncryptionKey from '../errors/encrypt/MissingEncryptionKey.js';
 import decryptAESGCM from './algorithms/aes-gcm/decryptAESGCM.js';
 import encryptAESGCM from './algorithms/aes-gcm/encryptAESGCM.js';
@@ -34,7 +34,7 @@ export default class Encrypt {
      *
      * **Three-arg form** (rotation): tries the current key first; on
      * `DecryptionError` falls back to the legacy key. If both fail, throws
-     * `DecryptionWithRotationError` carrying both per-key errors. A
+     * `DecryptionRotationError` carrying both per-key errors. A
      * `DecryptionParseError` from the current key is **not** retried — the
      * cipher already matched, so a parse failure means the encrypted format
      * is wrong (an app bug), not a wrong key.
@@ -44,7 +44,7 @@ export default class Encrypt {
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
-     * @throws DecryptionWithRotationError
+     * @throws DecryptionRotationError
      */
     static decrypt(encrypted, { algorithm, key }, legacyOpts) {
         if (legacyOpts)
@@ -81,7 +81,7 @@ export default class Encrypt {
         catch (err) {
             if (!(err instanceof DecryptionError))
                 throw err;
-            throw new DecryptionWithRotationError(currentKeyError, err);
+            throw new DecryptionRotationError(currentKeyError, err);
         }
     }
     /**
@@ -117,7 +117,7 @@ export default class Encrypt {
      *   not forced to re-authenticate.
      * - For `@Encrypted` columns: until every existing row has been
      *   re-encrypted under the new key. Dropping `legacy` early will cause
-     *   `DecryptionWithRotationError` on any not-yet-rewritten row.
+     *   `DecryptionRotationError` on any not-yet-rewritten row.
      */
     static generateKey(algorithm) {
         switch (algorithm) {

package/dist/esm/src/errors/encrypt/{DecryptionWithRotationError.js → DecryptionRotationError.js}

@@ -1,4 +1,4 @@
-export default class DecryptionWithRotationError extends Error {
+export default class DecryptionRotationError extends Error {
     currentKeyError;
     legacyKeyError;
     constructor(currentKeyError, legacyKeyError) {

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

@@ -7,6 +7,7 @@ import absoluteDreamPath from '../path/absoluteDreamPath.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
+import parseAttribute from './parseAttribute.js';
 /**
  * Column names that are automatically emitted by the model generator (and
  * the migration generator). When the user passes any of these explicitly,
@@ -35,8 +36,17 @@ export default function generateDreamContent(options) {
     const columnsForAttributes = config.isSTI
         ? options.columnsWithTypes
         : filterAutoGeneratedTimestampColumns(options.columnsWithTypes);
-    const baseImports = createImportConfig(config, options, { includeSoftDelete });
     const attributesResult = processAttributes(columnsForAttributes, config.modelClassName);
+    // Decorators is only referenced via `@deco.*` annotations on fields (e.g.,
+    // BelongsTo, Encrypted). If the generated body emits none of those, the
+    // import + declaration would trigger lint errors for unused identifiers,
+    // so emit them commented out instead — keeps the boilerplate present for
+    // the developer to uncomment when they add their first decorator.
+    const decoratorsInUse = attributesResult.formattedDecorators.length > 0;
+    const baseImports = createImportConfig(config, options, {
+        includeSoftDelete,
+        includeDecorators: decoratorsInUse,
+    });
     const allImports = {
         ...baseImports,
         modelImportStatements: [...baseImports.modelImportStatements, ...attributesResult.imports],
@@ -48,9 +58,14 @@ export default function generateDreamContent(options) {
     const fieldsSection = buildFieldsSection(config, attributesResult, {
         includeDeletedAt: includeSoftDelete || hasExplicitDeletedAt,
     });
+    const decoBlock = decoratorsInUse
+        ? `const deco = new Decorators<typeof ${config.modelClassName}>()`
+        : `// Uncomment when adding decorators (@deco.BelongsTo, @deco.Validates, etc.):
+// import { Decorators } from '@rvoh/dream'
+// const deco = new Decorators<typeof ${config.modelClassName}>()`;
     return `${importSection}
 
-const deco = new Decorators<typeof ${config.modelClassName}>()
+${decoBlock}
 
 ${classDeclaration}
 ${tableMethod}${serializersMethod}${fieldsSection}
@@ -78,9 +93,11 @@ export function createModelConfig(options) {
         tableName,
     };
 }
-export function createImportConfig(config, options, { includeSoftDelete }) {
+export function createImportConfig(config, options, { includeSoftDelete, includeDecorators = true }) {
     const dreamTypeImports = ['DreamColumn'];
-    const dreamImports = ['Decorators'];
+    const dreamImports = [];
+    if (includeDecorators)
+        dreamImports.push('Decorators');
     if (options.serializer) {
         dreamTypeImports.push('DreamSerializers');
     }
@@ -119,32 +136,41 @@ export function processAttributes(columnsWithTypes, modelClassName) {
     };
 }
 export function processAttribute(attribute, modelClassName) {
-    const [attributeName, attributeType, ...descriptors] = attribute.split(':');
-    if (attributeName === undefined)
+    const [rawName, rawType] = attribute.split(':');
+    if (rawName === undefined)
         return { content: '', imports: [] };
-    if (!attributeType) {
-        throw new Error(`must pass a column type for ${attributeName} (i.e. ${attributeName}:string)`);
+    if (!rawType) {
+        throw new Error(`must pass a column type for ${rawName} (i.e. ${rawName}:string)`);
     }
-    const processedAttrType = camelize(attributeType).toLowerCase();
-    switch (processedAttrType) {
+    const parsed = parseAttribute(attribute);
+    // Malformed-but-parseable shapes (e.g., `Model@:belongs_to` with an empty
+    // alias) yield no content rather than throwing — the call site has already
+    // validated the basic name/type segments above.
+    if (!parsed)
+        return { content: '', imports: [] };
+    switch (parsed.normalizedAttributeType) {
         case 'belongsto':
-            return createBelongsToAttribute(attributeName, descriptors, modelClassName);
+            return createBelongsToAttribute(parsed.rawAttributeName, modelClassName, {
+                aliasName: parsed.aliasName,
+                isOptional: parsed.isOptional,
+            });
         case 'hasone':
         case 'hasmany':
             return { content: '', imports: [] };
         case 'encrypted':
-            return createEncryptedAttribute(attributeName, attribute, modelClassName);
+            return createEncryptedAttribute(parsed.rawAttributeName, attribute, modelClassName);
         default:
-            return createRegularAttribute(attributeName, attribute, modelClassName);
+            return createRegularAttribute(parsed.rawAttributeName, attribute, modelClassName);
     }
 }
-export function createBelongsToAttribute(attributeName, descriptors, modelClassName) {
-    const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
+export function createBelongsToAttribute(fullyQualifiedModelInput, modelClassName, { aliasName, isOptional = false, } = {}) {
+    const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelInput);
     const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);
     const associationImportStatement = importStatementForModel(fullyQualifiedAssociatedModelName);
-    const associationName = camelize(fullyQualifiedAssociatedModelName.split('/').pop());
+    const associationName = aliasName
+        ? camelize(aliasName)
+        : camelize(fullyQualifiedAssociatedModelName.split('/').pop());
     const associationForeignKey = `${associationName}Id`;
-    const isOptional = descriptors.includes('optional');
     const content = `
 @deco.BelongsTo('${fullyQualifiedAssociatedModelName}', { on: '${associationForeignKey}'${isOptional ? ', optional: true' : ''} })
 public ${associationName}: ${associationModelName}${isOptional ? ' | null' : ''}