@rvoh/dream 2.10.0 → 2.11.2

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/db/DreamDbConnection.js

@@ -9,6 +9,7 @@
 import { CamelCasePlugin, Kysely } from 'kysely';
 import DreamApp from '../dream-app/index.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
+import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
 let connections = {};
 export default class DreamDbConnection {
     static getConnection(connectionName, connectionType, dialectProvider) {
@@ -19,6 +20,9 @@ export default class DreamDbConnection {
             return connection;
         }
         const connectionConf = dreamApp.dbConnectionConfig(connectionName, connectionType);
+        // Must run before dialectProvider() constructs the pg.Pool. Idempotent and
+        // a no-op unless DREAM_DB_LEAK_DIAGNOSTICS is set.
+        installDbConnectionLeakDiagnosticsIfEnabled();
         const dbConn = new Kysely({
             log(event) {
                 const dreamApp = DreamApp.getOrFail();
@@ -50,11 +54,51 @@ export async function closeAllDbConnections() {
     }
     connections = {};
 }
+/**
+ * Upper bound (ms) on how long {@link closeAllConnectionsForConnectionName}
+ * waits for a single Kysely connection's underlying pool to drain.
+ *
+ * `conn.destroy()` resolves to `pg`'s `pool.end()`, which only settles once
+ * every checked-out client has been released back to the pool. A client that
+ * was leased by a query still in flight when shutdown began — an aborted HTTP
+ * request during a SIGTERM drain, a feature-spec whose page is torn down
+ * mid-request — is never released, so `pool.end()` blocks forever and takes
+ * the whole shutdown with it. Bounding the wait keeps shutdown deterministic;
+ * the leaked socket is reaped by the OS when the process exits.
+ */
+const DB_CONNECTION_CLOSE_TIMEOUT_MS = 10_000;
 export async function closeAllConnectionsForConnectionName(connectionName) {
     const protectedName = protectAgainstPollutingAssignment(connectionName);
     return await Promise.allSettled(Object.keys(connections[protectedName]).map(async (key) => {
         const conn = connections[protectedName][key];
-        await conn.destroy();
+        // Remove from the registry first so a subsequent getConnection() builds a
+        // fresh pool even if this drain times out and the old pool is abandoned.
         delete connections[protectedName][key];
+        await destroyConnectionWithinTimeout(conn, `${connectionName}:${key}`);
     }));
 }
+async function destroyConnectionWithinTimeout(conn, label) {
+    let timer;
+    const timedOut = Symbol('timedOut');
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve(timedOut), DB_CONNECTION_CLOSE_TIMEOUT_MS);
+        // Don't let the timer itself keep the event loop (or `process.exit`) alive.
+        timer.unref?.();
+    });
+    try {
+        const result = await Promise.race([conn.destroy(), timeout]);
+        if (result === timedOut) {
+            DreamApp.logWithLevel('warn', `[dream] timed out after ${DB_CONNECTION_CLOSE_TIMEOUT_MS}ms waiting for db connection "${label}" ` +
+                `to close; abandoning the drain so shutdown can proceed. A pooled client was most likely held ` +
+                `past shutdown by an in-flight or aborted query. ` +
+                `Re-run with NODE_DEBUG=dream to log the acquire stack of the offending query.`);
+            // No-op unless NODE_DEBUG=dream; when set, this prints the acquire
+            // stack(s) of the client(s) that never got released.
+            reportLeakedDbConnections(label);
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/cjs/src/db/dbConnectionLeakDiagnostics.js

@@ -0,0 +1,117 @@
+// after building for esm, importing pg using the following:
+//
+//  import * as pg from 'pg'
+//
+// will crash. This is difficult to discover, since it only happens
+// when being imported from our esm build.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import pg from 'pg';
+import { debuglog } from 'node:util';
+import DreamApp from '../dream-app/index.js';
+/**
+ * Opt-in connection-leak diagnostics.
+ *
+ * `closeAllConnectionsForConnectionName` bounds the shutdown drain, but when it
+ * times out it can only say *that* a pooled client was held past shutdown, not
+ * *where* it was acquired. Finding the offending query then means hand-patching
+ * `pg` — exactly the multi-hour spelunk this is meant to delete.
+ *
+ * Enable with `NODE_DEBUG=dream` (the same `node:util` debug-channel
+ * convention Psychic uses for `NODE_DEBUG=psychic`). Dev/CI only — it patches
+ * `pg.Pool.prototype.connect` process-wide and retains references to
+ * checked-out clients, so it is never installed unless explicitly asked for.
+ * When the close timeout fires, the acquire stack of every still-checked-out
+ * client is logged.
+ *
+ * Like the rest of the ecosystem's `debuglog` usage, the channel is resolved
+ * once by Node on first call and cached for the process lifetime — this is a
+ * process-level switch, not a runtime toggle.
+ */
+// Resolved once at module load (Node caches the channel), mirroring
+// `const debugEnabled = debuglog('psychic').enabled` in Psychic.
+const dreamDebugEnabled = debuglog('dream').enabled;
+// Map (not WeakMap) so entries can be enumerated at report time. Entries are
+// deleted on release, so only genuinely-leaked clients accumulate, and only
+// when diagnostics are explicitly enabled.
+const checkedOutClients = new Map();
+const INSTALLED = Symbol.for('dream:dbLeakDiagnosticsInstalled');
+let enabled = false;
+function track(client, stack) {
+    if (!client)
+        return;
+    checkedOutClients.set(client, { stack: stack ?? '(no stack captured)', since: Date.now() });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const c = client;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (c.__dreamReleasePatched)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const originalRelease = c.release;
+    if (typeof originalRelease !== 'function')
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.__dreamReleasePatched = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.release = function patchedRelease(...args) {
+        checkedOutClients.delete(client);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+        return originalRelease.apply(this, args);
+    };
+}
+/**
+ * Idempotent. Patches `pg.Pool.prototype.connect` to stamp the caller's stack
+ * onto each leased client. No-op unless `DREAM_DB_LEAK_DIAGNOSTICS` is set.
+ */
+export function installDbConnectionLeakDiagnosticsIfEnabled() {
+    if (!dreamDebugEnabled)
+        return;
+    enabled = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    const Pool = pg.Pool;
+    if (!Pool?.prototype)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (Pool.prototype[INSTALLED])
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype[INSTALLED] = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
+    const originalConnect = Pool.prototype.connect;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype.connect = function patchedConnect(cb) {
+        const acquireStack = new Error('db connection acquired here').stack;
+        if (typeof cb === 'function') {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+            return originalConnect.call(this, (err, client, release) => {
+                track(client, acquireStack);
+                // `track()` replaces `client.release` with an untracking wrapper.
+                // Callback-style users call the 3rd `release` arg, which pg captured
+                // *before* that swap — so hand them the wrapped one instead, or a
+                // correctly-released client would be reported as a false leak.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const wrappedRelease = client ? client.release : release;
+                cb(err, client, wrappedRelease);
+            });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        return originalConnect.call(this).then((client) => {
+            track(client, acquireStack);
+            return client;
+        });
+    };
+}
+/**
+ * If diagnostics are enabled, log the acquire stack of every client still
+ * checked out. Called from the shutdown-drain timeout path.
+ */
+export function reportLeakedDbConnections(label) {
+    if (!enabled || checkedOutClients.size === 0)
+        return;
+    const now = Date.now();
+    const report = Array.from(checkedOutClients.values())
+        .map((entry, i) => `  [#${i}] held ${now - entry.since}ms\n${entry.stack}`)
+        .join('\n\n');
+    DreamApp.logWithLevel('warn', `[dream] connection-leak diagnostics: ${checkedOutClients.size} pg client(s) still checked out ` +
+        `when "${label}" hit the close timeout. Acquired at:\n\n${report}`);
+}

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -92,16 +92,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return _db(connectionName || 'default', dbConnectionType, this.dialectProvider(connectionName, dbConnectionType));
     }
     static dialectProvider(connectionName, dbConnectionType) {
-        return (connectionConf) => new PostgresDialect({
-            pool: new pg.Pool({
+        return (connectionConf) => {
+            const pool = new pg.Pool({
+                // Spread pg passthrough first; Dream's resolved fields follow and
+                // always win (per-connection database name, TLS directive).
+                ...(connectionConf.pg ?? {}),
                 user: connectionConf.user || '',
                 password: connectionConf.password || '',
                 database: DreamApp.getOrFail().dbName(connectionName, dbConnectionType),
                 host: connectionConf.host || 'localhost',
                 port: connectionConf.port || 5432,
                 ssl: resolvePostgresSsl(connectionConf),
-            }),
-        });
+            });
+            // node-postgres explicitly warns: a Pool that emits 'error' with no
+            // listener crashes the Node process. Idle pooled clients emit 'error'
+            // on backend restart / failover / a load balancer reaping idle TCP.
+            // Log via Dream's logger instead of taking the process down; the pool
+            // discards the dead client and recovers on the next acquire.
+            pool.on('error', err => {
+                DreamApp.getOrFail().logger.error(`[dream] idle pg client error on connection "${connectionName}:${dbConnectionType}" ` +
+                    `(handled — process kept alive): ${err.stack ?? String(err)}`);
+            });
+            return new PostgresDialect({ pool });
+        };
     }
     static async ensureAllMigrationsHaveBeenRun(connectionName) {
         const migrationsNeedToBeRun = await checkForNeedToBeRunMigrations({

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';