@rvoh/dream 2.17.0 → 2.17.2

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

@@ -11,8 +11,8 @@ 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, 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
+export const baseColumnsWithTypesDescription = `space separated snake-case properties like this:
+${INDENT}    title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal
 ${INDENT}
 ${INDENT}all properties default to not nullable; null can be allowed by appending ':optional':
 ${INDENT}    subtitle:string:optional
@@ -61,8 +61,11 @@ ${INDENT}        omit the enum values to leverage an existing enum (omits the en
 ${INDENT}          type:enum:room_types or type:enum:room_types:optional
 ${INDENT}
 ${INDENT}        leveraging arrays, add the "[]" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom`;
-const columnsWithTypesDescription = baseColumnsWithTypesDescription +
-    `
+function buildColumnsWithTypesDescription(belongsToDescription) {
+    return `${baseColumnsWithTypesDescription}
+${belongsToDescription}`;
+}
+const columnsWithTypesDescription = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column, adds a database index,
@@ -80,9 +83,13 @@ ${INDENT}                                                             #   @deco.
 ${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}        Aliasing also lets you declare multiple FKs to the same model in one generator call without column collisions.`);
+export const columnsWithTypesDescriptionForStiChild = buildColumnsWithTypesDescription(`
+${INDENT}
+${INDENT}    - belongs_to:
+${INDENT}        NOT supported for STI children. STI children cannot declare associations; declare all BelongsTo,
+${INDENT}        HasOne, and HasMany associations on the STI parent model instead.`);
+const columnsWithTypesDescriptionForMigration = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column with an index.
@@ -95,7 +102,7 @@ ${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)`;
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`);
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -222,7 +229,7 @@ ${INDENT}  Settings/CommunicationPreferences   # src/app/models/Settings/Communi
             .alias('g:sti-child')
             .description(`Generates an STI (Single Table Inheritance) child model that extends an existing parent model. The child shares the parent's database table (discriminated by the \`type\` column) and can add child-specific columns. Generates a child model decorated with @STI(Parent), child serializers extending the parent's base serializers, a migration that ALTERs the parent table (not a new table), check constraints, a factory, and spec skeleton.
 ${INDENT}
-${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
+${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children cannot declare associations — declare them on the parent model instead. The generator rejects belongs_to columns. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
 ${INDENT}
 ${INDENT}The parent must already exist (typically generated with g:model --sti-base-serializer or g:resource --sti-base-serializer).
 ${INDENT}
@@ -256,7 +263,7 @@ ${INDENT}
 ${INDENT}Examples:
 ${INDENT}  Room                # extends src/app/models/Room.ts
 ${INDENT}  Health/Coach        # extends src/app/models/Health/Coach.ts`)
-            .argument('[columnsWithTypes...]', columnsWithTypesDescription)
+            .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForStiChild)
             .action(async (childModelName, extendsWord, parentModelName, columnsWithTypes, options) => {
             await initializeDreamApp({ bypassDreamIntegrityChecks: true, bypassDbConnectionsDuringInit: true });
             if (extendsWord !== 'extends')

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

@@ -58,11 +58,20 @@ const state = {
  * probe so they always agree on the index range.
  */
 export function testDatabasePoolSize(parallelTests) {
-    const n = typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
-        ? Math.floor(parallelTests)
-        : 1;
+    const n = normalizeTestDatabaseParallelism(parallelTests);
     return 2 * Math.max(1, n) + POOL_MARGIN;
 }
+/**
+ * Normalize configured test parallelism to the minimum safe pool width input.
+ * Even a serial vitest run can overlap old/new worker processes, so missing,
+ * invalid, zero, or fractional-below-one values all mean "one active worker",
+ * not "disable the per-live-worker database pool".
+ */
+export function normalizeTestDatabaseParallelism(parallelTests) {
+    return typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
+        ? Math.max(1, Math.floor(parallelTests))
+        : 1;
+}
 /**
  * The database name for a pool index given the un-suffixed base name. Index 1
  * is the base itself (no suffix); higher indexes are `<base>_<index>`. This is

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

@@ -1,5 +1,5 @@
 import * as util from 'node:util';
-import { claimedTestDatabaseIndexOrNull, claimTestDatabase, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
+import { claimedTestDatabaseIndexOrNull, claimTestDatabase, normalizeTestDatabaseParallelism, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
 import validateTable from '../db/validators/validateTable.js';
 import Query from '../dream/Query.js';
 import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
@@ -208,7 +208,7 @@ A new key can also be generated from the CLI:
     }
     _parallelTests;
     get parallelTests() {
-        return process.env.NODE_ENV === 'test' ? this._parallelTests : undefined;
+        return process.env.NODE_ENV === 'test' ? normalizeTestDatabaseParallelism(this._parallelTests) : undefined;
     }
     _unicodeNormalization = 'NFC';
     get unicodeNormalization() {
@@ -276,7 +276,7 @@ A new key can also be generated from the CLI:
             this._inflections = opts.inflections;
         if (opts?.serializerCasing)
             this._serializerCasing = opts.serializerCasing;
-        if (opts?.parallelTests)
+        if (opts?.parallelTests !== undefined)
             this._parallelTests = opts.parallelTests;
         this._paths = {
             conf: opts?.paths?.conf || 'src/conf',
@@ -483,9 +483,8 @@ A new key can also be generated from the CLI:
                 };
                 break;
             case 'parallelTests':
-                if (process.env.NODE_ENV === 'test' && !Number.isNaN(Number(options)) && Number(options) > 1) {
+                if (process.env.NODE_ENV === 'test')
                     this._parallelTests = options;
-                }
                 break;
             case 'unicodeNormalization':
                 this._unicodeNormalization = options;

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

@@ -8,6 +8,7 @@ import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
 import parseAttribute from './parseAttribute.js';
+import validateStiChildColumns from './validateStiChildColumns.js';
 /**
  * Column names that are automatically emitted by the model generator (and
  * the migration generator). When the user passes any of these explicitly,
@@ -26,6 +27,8 @@ export function filterAutoGeneratedTimestampColumns(columnsWithTypes) {
 }
 export default function generateDreamContent(options) {
     const config = createModelConfig(options);
+    if (config.isSTI)
+        validateStiChildColumns(options.columnsWithTypes);
     // SoftDelete is incompatible with STI children, so it's only applied to
     // non-STI-child models.
     const includeSoftDelete = !config.isSTI && !!options.softDelete;
@@ -59,15 +62,19 @@ export default function generateDreamContent(options) {
         includeDeletedAt: includeSoftDelete || hasExplicitDeletedAt,
     });
     const decoBlock = decoratorsInUse
-        ? `const deco = new Decorators<typeof ${config.modelClassName}>()`
-        : `// Uncomment when adding decorators (@deco.BelongsTo, @deco.Validates, etc.):
+        ? `const deco = new Decorators<typeof ${config.modelClassName}>()
+
+`
+        : config.isSTI
+            ? ''
+            : `// 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}
+`;
+    return `${importSection}
 
-${classDeclaration}
+${decoBlock}${classDeclaration}
 ${tableMethod}${serializersMethod}${fieldsSection}
 }
 `.replace(/^\s*$/gm, '');

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

@@ -8,7 +8,8 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
-const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
+const DELETED_AT_COLUMN_NAME = 'deleted_at';
+const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME, DELETED_AT_COLUMN_NAME];
 export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
@@ -25,8 +26,8 @@ export default function generateMigrationContent({ connectionName = 'default', t
             return name !== 'created_at' && name !== 'updated_at' && name !== 'deleted_at';
         });
     const emitDeletedAtColumn = !altering && (softDelete || userExplicitlyPassedDeletedAt);
-    const { columnDefs, columnDrops, indexDefs, indexDrops } = processedColumnsWithTypes.reduce((acc, attributeDeclaration) => {
-        const { columnDefs, columnDrops, indexDefs, indexDrops } = acc;
+    const { columnDefs, columnDrops, indexDefs } = processedColumnsWithTypes.reduce((acc, attributeDeclaration) => {
+        const { columnDefs, columnDrops, indexDefs } = acc;
         const [rawSegmentOne, _attributeType, ...descriptors] = attributeDeclaration.split(':');
         if (!rawSegmentOne)
             return acc;
@@ -129,13 +130,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         columnDrops.push(`.dropColumn('${attributeName}')`);
         if (processedAttrType === 'belongsto' || COLUMNS_TO_INDEX.includes(attributeName)) {
-            const indexName = `${table}_${attributeName}`;
-            indexDefs.push(`await db.schema
-    .createIndex('${indexName}')
-    .on('${table}')
-    .column('${attributeName}')
-    .execute()`);
-            indexDrops.push(`await db.schema.dropIndex('${indexName}').execute()`);
+            indexDefs.push(columnIndexStatement(table, attributeName));
         }
         if (stiChildClassName && !userWantsThisOptional && !arrayAttribute && !isBooleanColumn) {
             checkConstraints.push(`
@@ -149,7 +144,10 @@ export default function generateMigrationContent({ connectionName = 'default', t
     .execute()`);
         }
         return acc;
-    }, { columnDefs: [], columnDrops: [], indexDefs: [], indexDrops: [] });
+    }, { columnDefs: [], columnDrops: [], indexDefs: [] });
+    if (emitDeletedAtColumn) {
+        indexDefs.push(columnIndexStatement(table, DELETED_AT_COLUMN_NAME));
+    }
     if (!table) {
         return `\
 import { Kysely, sql } from 'kysely'
@@ -196,7 +194,7 @@ ${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function down(db: Kysely<any>): Promise<void> {
-  ${indexDrops.join(newlineIndent)}${indexDrops.length ? newlineIndent : ''}${altering
+  ${altering
         ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
         : `await db.schema.dropTable('${table}').execute()`}${generateEnumDropStatements(columnsWithTypes)}
 }\
@@ -393,6 +391,14 @@ function lookupReferencesTable(snakeAssociationName, originalAssociationName) {
 function associationNameToForeignKey(associationName) {
     return snakeify(associationName.replace(/\//g, '_').replace(/_id$/, '') + '_id');
 }
+function columnIndexStatement(table, attributeName) {
+    const indexName = `${table}_${attributeName}`;
+    return `await db.schema
+    .createIndex('${indexName}')
+    .on('${table}')
+    .column('${attributeName}')
+    .execute()`;
+}
 export function optionalFromDescriptors(descriptors) {
     const optional = descriptors.at(-1) === 'optional';
     if (optional)

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

@@ -0,0 +1,7 @@
+import parseAttribute from './parseAttribute.js';
+export default function validateStiChildColumns(columnsWithTypes) {
+    const belongsToColumns = columnsWithTypes.filter(columnWithType => parseAttribute(columnWithType)?.normalizedAttributeType === 'belongsto');
+    if (belongsToColumns.length) {
+        throw new Error(`STI children cannot declare belongs_to associations. Declare associations on the STI parent instead. Unsupported columns: ${belongsToColumns.join(', ')}`);
+    }
+}

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

@@ -11,8 +11,8 @@ 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, 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
+export const baseColumnsWithTypesDescription = `space separated snake-case properties like this:
+${INDENT}    title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal
 ${INDENT}
 ${INDENT}all properties default to not nullable; null can be allowed by appending ':optional':
 ${INDENT}    subtitle:string:optional
@@ -61,8 +61,11 @@ ${INDENT}        omit the enum values to leverage an existing enum (omits the en
 ${INDENT}          type:enum:room_types or type:enum:room_types:optional
 ${INDENT}
 ${INDENT}        leveraging arrays, add the "[]" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom`;
-const columnsWithTypesDescription = baseColumnsWithTypesDescription +
-    `
+function buildColumnsWithTypesDescription(belongsToDescription) {
+    return `${baseColumnsWithTypesDescription}
+${belongsToDescription}`;
+}
+const columnsWithTypesDescription = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column, adds a database index,
@@ -80,9 +83,13 @@ ${INDENT}                                                             #   @deco.
 ${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}        Aliasing also lets you declare multiple FKs to the same model in one generator call without column collisions.`);
+export const columnsWithTypesDescriptionForStiChild = buildColumnsWithTypesDescription(`
+${INDENT}
+${INDENT}    - belongs_to:
+${INDENT}        NOT supported for STI children. STI children cannot declare associations; declare all BelongsTo,
+${INDENT}        HasOne, and HasMany associations on the STI parent model instead.`);
+const columnsWithTypesDescriptionForMigration = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column with an index.
@@ -95,7 +102,7 @@ ${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)`;
+${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`);
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -222,7 +229,7 @@ ${INDENT}  Settings/CommunicationPreferences   # src/app/models/Settings/Communi
             .alias('g:sti-child')
             .description(`Generates an STI (Single Table Inheritance) child model that extends an existing parent model. The child shares the parent's database table (discriminated by the \`type\` column) and can add child-specific columns. Generates a child model decorated with @STI(Parent), child serializers extending the parent's base serializers, a migration that ALTERs the parent table (not a new table), check constraints, a factory, and spec skeleton.
 ${INDENT}
-${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
+${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children cannot declare associations — declare them on the parent model instead. The generator rejects belongs_to columns. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
 ${INDENT}
 ${INDENT}The parent must already exist (typically generated with g:model --sti-base-serializer or g:resource --sti-base-serializer).
 ${INDENT}
@@ -256,7 +263,7 @@ ${INDENT}
 ${INDENT}Examples:
 ${INDENT}  Room                # extends src/app/models/Room.ts
 ${INDENT}  Health/Coach        # extends src/app/models/Health/Coach.ts`)
-            .argument('[columnsWithTypes...]', columnsWithTypesDescription)
+            .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForStiChild)
             .action(async (childModelName, extendsWord, parentModelName, columnsWithTypes, options) => {
             await initializeDreamApp({ bypassDreamIntegrityChecks: true, bypassDbConnectionsDuringInit: true });
             if (extendsWord !== 'extends')

package/dist/esm/src/db/testDatabasePool.js

@@ -58,11 +58,20 @@ const state = {
  * probe so they always agree on the index range.
  */
 export function testDatabasePoolSize(parallelTests) {
-    const n = typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
-        ? Math.floor(parallelTests)
-        : 1;
+    const n = normalizeTestDatabaseParallelism(parallelTests);
     return 2 * Math.max(1, n) + POOL_MARGIN;
 }
+/**
+ * Normalize configured test parallelism to the minimum safe pool width input.
+ * Even a serial vitest run can overlap old/new worker processes, so missing,
+ * invalid, zero, or fractional-below-one values all mean "one active worker",
+ * not "disable the per-live-worker database pool".
+ */
+export function normalizeTestDatabaseParallelism(parallelTests) {
+    return typeof parallelTests === 'number' && Number.isFinite(parallelTests) && parallelTests > 0
+        ? Math.max(1, Math.floor(parallelTests))
+        : 1;
+}
 /**
  * The database name for a pool index given the un-suffixed base name. Index 1
  * is the base itself (no suffix); higher indexes are `<base>_<index>`. This is

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

@@ -1,5 +1,5 @@
 import * as util from 'node:util';
-import { claimedTestDatabaseIndexOrNull, claimTestDatabase, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
+import { claimedTestDatabaseIndexOrNull, claimTestDatabase, normalizeTestDatabaseParallelism, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
 import validateTable from '../db/validators/validateTable.js';
 import Query from '../dream/Query.js';
 import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
@@ -208,7 +208,7 @@ A new key can also be generated from the CLI:
     }
     _parallelTests;
     get parallelTests() {
-        return process.env.NODE_ENV === 'test' ? this._parallelTests : undefined;
+        return process.env.NODE_ENV === 'test' ? normalizeTestDatabaseParallelism(this._parallelTests) : undefined;
     }
     _unicodeNormalization = 'NFC';
     get unicodeNormalization() {
@@ -276,7 +276,7 @@ A new key can also be generated from the CLI:
             this._inflections = opts.inflections;
         if (opts?.serializerCasing)
             this._serializerCasing = opts.serializerCasing;
-        if (opts?.parallelTests)
+        if (opts?.parallelTests !== undefined)
             this._parallelTests = opts.parallelTests;
         this._paths = {
             conf: opts?.paths?.conf || 'src/conf',
@@ -483,9 +483,8 @@ A new key can also be generated from the CLI:
                 };
                 break;
             case 'parallelTests':
-                if (process.env.NODE_ENV === 'test' && !Number.isNaN(Number(options)) && Number(options) > 1) {
+                if (process.env.NODE_ENV === 'test')
                     this._parallelTests = options;
-                }
                 break;
             case 'unicodeNormalization':
                 this._unicodeNormalization = options;

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

@@ -8,6 +8,7 @@ import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
 import parseAttribute from './parseAttribute.js';
+import validateStiChildColumns from './validateStiChildColumns.js';
 /**
  * Column names that are automatically emitted by the model generator (and
  * the migration generator). When the user passes any of these explicitly,
@@ -26,6 +27,8 @@ export function filterAutoGeneratedTimestampColumns(columnsWithTypes) {
 }
 export default function generateDreamContent(options) {
     const config = createModelConfig(options);
+    if (config.isSTI)
+        validateStiChildColumns(options.columnsWithTypes);
     // SoftDelete is incompatible with STI children, so it's only applied to
     // non-STI-child models.
     const includeSoftDelete = !config.isSTI && !!options.softDelete;
@@ -59,15 +62,19 @@ export default function generateDreamContent(options) {
         includeDeletedAt: includeSoftDelete || hasExplicitDeletedAt,
     });
     const decoBlock = decoratorsInUse
-        ? `const deco = new Decorators<typeof ${config.modelClassName}>()`
-        : `// Uncomment when adding decorators (@deco.BelongsTo, @deco.Validates, etc.):
+        ? `const deco = new Decorators<typeof ${config.modelClassName}>()
+
+`
+        : config.isSTI
+            ? ''
+            : `// 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}
+`;
+    return `${importSection}
 
-${classDeclaration}
+${decoBlock}${classDeclaration}
 ${tableMethod}${serializersMethod}${fieldsSection}
 }
 `.replace(/^\s*$/gm, '');

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

@@ -8,7 +8,8 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
-const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
+const DELETED_AT_COLUMN_NAME = 'deleted_at';
+const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME, DELETED_AT_COLUMN_NAME];
 export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
@@ -25,8 +26,8 @@ export default function generateMigrationContent({ connectionName = 'default', t
             return name !== 'created_at' && name !== 'updated_at' && name !== 'deleted_at';
         });
     const emitDeletedAtColumn = !altering && (softDelete || userExplicitlyPassedDeletedAt);
-    const { columnDefs, columnDrops, indexDefs, indexDrops } = processedColumnsWithTypes.reduce((acc, attributeDeclaration) => {
-        const { columnDefs, columnDrops, indexDefs, indexDrops } = acc;
+    const { columnDefs, columnDrops, indexDefs } = processedColumnsWithTypes.reduce((acc, attributeDeclaration) => {
+        const { columnDefs, columnDrops, indexDefs } = acc;
         const [rawSegmentOne, _attributeType, ...descriptors] = attributeDeclaration.split(':');
         if (!rawSegmentOne)
             return acc;
@@ -129,13 +130,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         columnDrops.push(`.dropColumn('${attributeName}')`);
         if (processedAttrType === 'belongsto' || COLUMNS_TO_INDEX.includes(attributeName)) {
-            const indexName = `${table}_${attributeName}`;
-            indexDefs.push(`await db.schema
-    .createIndex('${indexName}')
-    .on('${table}')
-    .column('${attributeName}')
-    .execute()`);
-            indexDrops.push(`await db.schema.dropIndex('${indexName}').execute()`);
+            indexDefs.push(columnIndexStatement(table, attributeName));
         }
         if (stiChildClassName && !userWantsThisOptional && !arrayAttribute && !isBooleanColumn) {
             checkConstraints.push(`
@@ -149,7 +144,10 @@ export default function generateMigrationContent({ connectionName = 'default', t
     .execute()`);
         }
         return acc;
-    }, { columnDefs: [], columnDrops: [], indexDefs: [], indexDrops: [] });
+    }, { columnDefs: [], columnDrops: [], indexDefs: [] });
+    if (emitDeletedAtColumn) {
+        indexDefs.push(columnIndexStatement(table, DELETED_AT_COLUMN_NAME));
+    }
     if (!table) {
         return `\
 import { Kysely, sql } from 'kysely'
@@ -196,7 +194,7 @@ ${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function down(db: Kysely<any>): Promise<void> {
-  ${indexDrops.join(newlineIndent)}${indexDrops.length ? newlineIndent : ''}${altering
+  ${altering
         ? `await db.schema${newlineDoubleIndent}.alterTable('${table}')${columnDropLines}.execute()`
         : `await db.schema.dropTable('${table}').execute()`}${generateEnumDropStatements(columnsWithTypes)}
 }\
@@ -393,6 +391,14 @@ function lookupReferencesTable(snakeAssociationName, originalAssociationName) {
 function associationNameToForeignKey(associationName) {
     return snakeify(associationName.replace(/\//g, '_').replace(/_id$/, '') + '_id');
 }
+function columnIndexStatement(table, attributeName) {
+    const indexName = `${table}_${attributeName}`;
+    return `await db.schema
+    .createIndex('${indexName}')
+    .on('${table}')
+    .column('${attributeName}')
+    .execute()`;
+}
 export function optionalFromDescriptors(descriptors) {
     const optional = descriptors.at(-1) === 'optional';
     if (optional)

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

@@ -0,0 +1,7 @@
+import parseAttribute from './parseAttribute.js';
+export default function validateStiChildColumns(columnsWithTypes) {
+    const belongsToColumns = columnsWithTypes.filter(columnWithType => parseAttribute(columnWithType)?.normalizedAttributeType === 'belongsto');
+    if (belongsToColumns.length) {
+        throw new Error(`STI children cannot declare belongs_to associations. Declare associations on the STI parent instead. Unsupported columns: ${belongsToColumns.join(', ')}`);
+    }
+}

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

@@ -14,7 +14,8 @@ 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, 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 declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\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 columnsWithTypesDescriptionForStiChild: string;
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/types/src/db/testDatabasePool.d.ts

@@ -5,6 +5,13 @@ import type DreamApp from '../dream-app/index.js';
  * probe so they always agree on the index range.
  */
 export declare function testDatabasePoolSize(parallelTests: number | undefined): number;
+/**
+ * Normalize configured test parallelism to the minimum safe pool width input.
+ * Even a serial vitest run can overlap old/new worker processes, so missing,
+ * invalid, zero, or fractional-below-one values all mean "one active worker",
+ * not "disable the per-live-worker database pool".
+ */
+export declare function normalizeTestDatabaseParallelism(parallelTests: number | undefined): number;
 /**
  * The database name for a pool index given the un-suffixed base name. Index 1
  * is the base itself (no suffix); higher indexes are `<base>_<index>`. This is

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

@@ -0,0 +1 @@
+export default function validateStiChildColumns(columnsWithTypes: string[]): void;