@rvoh/dream 2.9.2 → 2.11.1

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

@@ -6,6 +6,7 @@ import Encrypt from '../encrypt/index.js';
 import DreamAppInitMissingCallToLoadModels from '../errors/dream-app/DreamAppInitMissingCallToLoadModels.js';
 import DreamAppInitMissingMissingProjectRoot from '../errors/dream-app/DreamAppInitMissingMissingProjectRoot.js';
 import DreamAppInitMissingPackageManager from '../errors/dream-app/DreamAppInitMissingPackageManager.js';
+import MissingDbSslDirective from '../errors/dream-app/MissingDbSslDirective.js';
 import autogeneratedFileDisclaimer from '../helpers/cli/autoGeneratedFileDisclaimer.js';
 import modelClassNameFrom from '../helpers/cli/modelClassNameFrom.js';
 import EnvInternal from '../helpers/EnvInternal.js';
@@ -345,14 +346,16 @@ A new key can also be generated from the CLI:
             case 'bypassDeprecationChecks':
                 this._bypassDeprecationChecks = options;
                 break;
-            case 'db':
-                if (typeof options === 'string') {
-                    this._dbCredentials[options] = secondaryOptions;
-                }
-                else {
-                    this._dbCredentials['default'] = options;
+            case 'db': {
+                const connectionName = typeof options === 'string' ? options : 'default';
+                const credentialOptions = (typeof options === 'string' ? secondaryOptions : options);
+                assertDbCredentialTlsDirective(credentialOptions.primary, connectionName, 'primary');
+                if (credentialOptions.replica) {
+                    assertDbCredentialTlsDirective(credentialOptions.replica, connectionName, 'replica');
                 }
+                this._dbCredentials[connectionName] = credentialOptions;
                 break;
+            }
             case 'encryption':
                 this._encryption = options;
                 break;
@@ -412,6 +415,11 @@ A new key can also be generated from the CLI:
         }
     }
 }
+function assertDbCredentialTlsDirective(credential, connectionName, credentialKey) {
+    if (credential.ssl === undefined && !credential.useSsl) {
+        throw new MissingDbSslDirective(connectionName, credentialKey);
+    }
+}
 function loggerArgToString(arg) {
     if (typeof arg === 'string')
         return arg;

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/dream-app/MissingDbSslDirective.js

@@ -0,0 +1,29 @@
+export default class MissingDbSslDirective extends Error {
+    connectionName;
+    credentialKey;
+    constructor(connectionName, credentialKey) {
+        super();
+        this.connectionName = connectionName;
+        this.credentialKey = credentialKey;
+    }
+    get message() {
+        return `
+DreamApp refused to register a db credential without an explicit TLS
+directive. Every \`SingleDbCredential\` passed to \`app.set('db', ...)\`
+must set one of:
+
+  ssl: { rejectUnauthorized: true }              // verified TLS (system CA)
+  ssl: { rejectUnauthorized: true, ca: <pem> }   // verified TLS (private CA)
+  ssl: { rejectUnauthorized: false }             // unverified TLS
+  ssl: false                                     // TLS disabled
+  useSsl: true                                   // legacy, deprecated
+
+Omitting the directive used to silently disable TLS. Throwing here
+turns the safety question into a deliberate decision at the call
+site, so a credential cannot reach production with TLS off by accident.
+
+  connection: ${this.connectionName}
+  credential: ${this.credentialKey}
+    `;
+    }
+}

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' : ''}

package/dist/esm/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/esm/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/esm/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/esm/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/types/src/cli/index.d.ts

@@ -14,7 +14,7 @@ export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
     args?: string[];
 };
 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                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
+export declare 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:\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                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -473,14 +473,13 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
  * Resolve the value passed to `pg.Pool`'s `ssl` field for a given credential.
  *
  * Precedence:
- *   1. If `connectionConf.ssl` is set (boolean or `tls.ConnectionOptions`),
- *      pass it straight through to `pg`. This is the verified-TLS path —
- *      apps configure `{ rejectUnauthorized: true, ca: <bundle> }` for
- *      authenticated TLS against a private PKI, or `true` to use Node's
- *      default verification against the system CA store.
- *   2. Else if `connectionConf.useSsl` is `true`, fall back to
+ *   1. If `connectionConf.ssl` is set (object or explicit `false`), pass it
+ *      straight through to `pg`.
+ *   2. Else if `connectionConf.useSsl` is `true` (deprecated), fall back to
  *      `{ rejectUnauthorized: false }` — encrypted but **not** authenticated.
- *      Preserved for back-compat; new code should set `ssl` explicitly.
- *   3. Else disable TLS.
+ *
+ * `assertDbCredentialTlsDirective` (in `dream-app`) throws at
+ * `app.set('db', ...)` time when both `ssl` and `useSsl` are unset, so this
+ * resolver never sees the "neither directive" state.
  */
-export declare function resolvePostgresSsl(connectionConf: SingleDbCredential): boolean | TlsConnectionOptions;
+export declare function resolvePostgresSsl(connectionConf: SingleDbCredential): TlsConnectionOptions | false;

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

@@ -213,27 +213,35 @@ export interface SingleDbCredential {
     /**
      * @deprecated Use `ssl` instead.
      *
-     * The legacy boolean opt-in for Postgres TLS. When `true` (and `ssl` is not
+     * Legacy boolean opt-in for Postgres TLS. When `true` (and `ssl` is not
      * set), Dream connects with `{ rejectUnauthorized: false }` — TLS is on but
-     * the server certificate is not verified. The new `ssl` field accepts a
-     * full `tls.ConnectionOptions` object so callers can opt into verified TLS
-     * (`ssl: { rejectUnauthorized: true, ca: readFileSync('ca.pem') }`) or use
-     * Node's defaults (`ssl: true`). This field is preserved for back-compat
-     * and will be removed in a future major version.
+     * the server certificate is not verified. Preserved for back-compat and
+     * will be removed in a future major version. New code should set `ssl`
+     * directly.
      */
     useSsl?: boolean;
     /**
-     * Optional explicit TLS configuration passed straight through to `pg.Pool`'s
-     * `ssl` field. Takes precedence over the deprecated `useSsl` when provided.
+     * TLS configuration passed straight through to `pg.Pool`'s `ssl` field.
+     * Takes precedence over the deprecated `useSsl` when provided.
      *
-     * - `true` lets `pg` use Node's defaults (verified TLS against the system CA).
-     * - `false` disables TLS.
-     * - An object is `tls.ConnectionOptions` — set `rejectUnauthorized: true` plus
-     *   a `ca` bundle for verified TLS against a private PKI; set
-     *   `rejectUnauthorized: false` only if you accept opportunistic-TLS-without-
-     *   authentication (the historical default produced by `useSsl: true` alone).
+     * Set `rejectUnauthorized: true` (Node's own default) for verified TLS
+     * against the system CA store — the right choice for managed providers that
+     * present a public-CA-signed certificate (Supabase, Neon, Render, Azure
+     * Database for PostgreSQL on Flexible Server, etc.).
+     *
+     * For providers that present a private-CA certificate (AWS RDS,
+     * GCP Cloud SQL), add a `ca` bundle:
+     * `ssl: { rejectUnauthorized: true, ca: readFileSync('rds-ca.pem') }`.
+     *
+     * For providers that present a self-signed certificate (Heroku Hobby,
+     * some local docker images), set `rejectUnauthorized: false` — encrypted
+     * but unauthenticated.
+     *
+     * Set `false` to disable TLS entirely. Omitting `ssl` (and `useSsl`) throws
+     * at `app.set('db', ...)` time so the safety question is a deliberate
+     * decision at the call site rather than a silent default.
      */
-    ssl?: boolean | TlsConnectionOptions;
+    ssl?: TlsConnectionOptions | false;
 }
 export type DreamLogger = {
     info: (...args: any[]) => void;

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

@@ -12,7 +12,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.
@@ -22,7 +22,7 @@ export default class Encrypt {
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
-     * @throws DecryptionWithRotationError
+     * @throws DecryptionRotationError
      */
     static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions): RetType | null;
     private static attemptDecryptionWithLegacyKeys;
@@ -59,7 +59,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: EncryptAlgorithm): string;
     static validateKey(base64EncodedKey: string, algorithm: EncryptAlgorithm): boolean;

package/dist/types/src/errors/dream-app/MissingDbSslDirective.d.ts

@@ -0,0 +1,6 @@
+export default class MissingDbSslDirective extends Error {
+    private connectionName;
+    private credentialKey;
+    constructor(connectionName: string, credentialKey: 'primary' | 'replica');
+    get message(): string;
+}

package/dist/types/src/errors/encrypt/{DecryptionWithRotationError.d.ts → DecryptionRotationError.d.ts}

@@ -1,5 +1,5 @@
 import DecryptionError from './DecryptionError.js';
-export default class DecryptionWithRotationError extends Error {
+export default class DecryptionRotationError extends Error {
     readonly currentKeyError: DecryptionError;
     readonly legacyKeyError: DecryptionError;
     constructor(currentKeyError: DecryptionError, legacyKeyError: DecryptionError);

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

@@ -37,15 +37,19 @@ export interface AttributeProcessingResult {
 }
 export default function generateDreamContent(options: GenerateDreamContentOptions): string;
 export declare function createModelConfig(options: GenerateDreamContentOptions): ModelConfig;
-export declare function createImportConfig(config: ModelConfig, options: GenerateDreamContentOptions, { includeSoftDelete }: {
+export declare function createImportConfig(config: ModelConfig, options: GenerateDreamContentOptions, { includeSoftDelete, includeDecorators }: {
     includeSoftDelete: boolean;
+    includeDecorators?: boolean;
 }): ImportConfig;
 export declare function processAttributes(columnsWithTypes: string[], modelClassName: string): AttributeProcessingResult & {
     formattedFields: string;
     formattedDecorators: string;
 };
 export declare function processAttribute(attribute: string, modelClassName: string): AttributeProcessingResult;
-export declare function createBelongsToAttribute(attributeName: string, descriptors: string[], modelClassName: string): AttributeProcessingResult;
+export declare function createBelongsToAttribute(fullyQualifiedModelInput: string, modelClassName: string, { aliasName, isOptional, }?: {
+    aliasName?: string | undefined;
+    isOptional?: boolean;
+}): AttributeProcessingResult;
 export declare function createEncryptedAttribute(attributeName: string, attribute: string, modelClassName: string): AttributeProcessingResult;
 export declare function createRegularAttribute(attributeName: string, attribute: string, modelClassName: string): AttributeProcessingResult;
 export {};