@rvoh/dream 2.6.1-alpha.1 → 2.7.0

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

@@ -62,6 +62,8 @@ export default class DreamBin {
                 includeInternalSerializers: options.internalSerializers ?? false,
                 ...options,
                 stiBaseSerializer: false,
+                // `@SoftDelete()` is incompatible with STI children — never auto-apply.
+                softDelete: false,
             },
             fullyQualifiedParentName,
         });

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

@@ -190,6 +190,7 @@ ${INDENT}  pnpm psy g:model --model-name=GroupDanceLesson Lesson/Dance/Group
 ${INDENT}  # model is named GroupDanceLesson instead of LessonDanceGroup`)
             .option('--admin-serializers', 'also generate AdminSerializer and AdminSummarySerializer variants for admin-facing API endpoints that may expose additional fields', false)
             .option('--internal-serializers', 'also generate InternalSerializer and InternalSummarySerializer variants for internal API endpoints that may expose additional fields', false)
+            .option('--no-soft-delete', `skip generating the @SoftDelete() decorator and the corresponding nullable \`deleted_at\` column. By default, generated models use soft-delete semantics (rows are marked deleted via \`deleted_at\` instead of being removed from the database). Pass this flag when you want records to be hard-deleted.`)
             .argument('<modelName>', `The fully qualified model name, using / for namespacing. This determines the model class name (may be overridden with \`--model-name\`), table name, and file path under src/app/models/.
 ${INDENT}
 ${INDENT}Examples:

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

@@ -9,6 +9,11 @@ import writeGeneratedFile from './writeGeneratedFile.js';
 export default async function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
     const modelClassName = modelClassNameFrom(fullyQualifiedModelName, options.modelName);
+    const isSTI = !!fullyQualifiedParentName;
+    // `@SoftDelete()` is incompatible with STI children, so we force-disable
+    // the soft-delete scaffold when generating an STI child regardless of the
+    // caller-provided value.
+    const softDelete = !isSTI && !!options.softDelete;
     await writeGeneratedFile({
         dreamPathKey: 'models',
         fileName: `${fullyQualifiedModelName}.ts`,
@@ -22,6 +27,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             connectionName: options.connectionName,
             tableName: options.tableName,
             modelClassName,
+            softDelete,
         }),
         logLabel: 'dream',
     });
@@ -37,7 +43,6 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             includeInternalSerializers: options.includeInternalSerializers ?? false,
             modelClassName,
         });
-    const isSTI = !!fullyQualifiedParentName;
     if (columnsWithTypes.length || !isSTI) {
         await generateMigration({
             connectionName: options.connectionName,
@@ -47,6 +52,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             fullyQualifiedParentName,
             tableName: options.tableName,
             modelClassName,
+            softDelete,
         });
     }
 }

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

@@ -7,19 +7,47 @@ import absoluteDreamPath from '../path/absoluteDreamPath.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
+/**
+ * Column names that are automatically emitted by the model generator (and
+ * the migration generator). When the user passes any of these explicitly,
+ * we filter them out of the attribute loop so the model class and migration
+ * don't end up with duplicate declarations.
+ */
+const AUTO_GENERATED_TIMESTAMP_COLUMN_NAMES = ['created_at', 'updated_at', 'deleted_at'];
+function columnName(columnWithType) {
+    return columnWithType.split(':')[0] ?? '';
+}
+export function hasExplicitColumn(columnsWithTypes, name) {
+    return columnsWithTypes.some(col => columnName(col) === name);
+}
+export function filterAutoGeneratedTimestampColumns(columnsWithTypes) {
+    return columnsWithTypes.filter(col => !AUTO_GENERATED_TIMESTAMP_COLUMN_NAMES.includes(columnName(col)));
+}
 export default function generateDreamContent(options) {
     const config = createModelConfig(options);
-    const baseImports = createImportConfig(config, options);
-    const attributesResult = processAttributes(options.columnsWithTypes, config.modelClassName);
+    // SoftDelete is incompatible with STI children, so it's only applied to
+    // non-STI-child models.
+    const includeSoftDelete = !config.isSTI && !!options.softDelete;
+    const hasExplicitDeletedAt = hasExplicitColumn(options.columnsWithTypes, 'deleted_at');
+    // Filter out timestamp columns that we auto-generate from the attribute
+    // processing loop so we don't double-generate them in the model class.
+    // We only dedupe on non-STI models — STI children don't get auto timestamps.
+    const columnsForAttributes = config.isSTI
+        ? options.columnsWithTypes
+        : filterAutoGeneratedTimestampColumns(options.columnsWithTypes);
+    const baseImports = createImportConfig(config, options, { includeSoftDelete });
+    const attributesResult = processAttributes(columnsForAttributes, config.modelClassName);
     const allImports = {
         ...baseImports,
         modelImportStatements: [...baseImports.modelImportStatements, ...attributesResult.imports],
     };
     const importSection = buildImportSection(allImports);
-    const classDeclaration = buildClassDeclaration(config);
+    const classDeclaration = buildClassDeclaration(config, { includeSoftDelete });
     const tableMethod = buildTableMethod(config);
     const serializersMethod = buildSerializersMethod(config, options);
-    const fieldsSection = buildFieldsSection(config, attributesResult);
+    const fieldsSection = buildFieldsSection(config, attributesResult, {
+        includeDeletedAt: includeSoftDelete || hasExplicitDeletedAt,
+    });
     return `${importSection}
 
 const deco = new Decorators<typeof ${config.modelClassName}>()
@@ -50,7 +78,7 @@ export function createModelConfig(options) {
         tableName,
     };
 }
-export function createImportConfig(config, options) {
+export function createImportConfig(config, options, { includeSoftDelete }) {
     const dreamTypeImports = ['DreamColumn'];
     const dreamImports = ['Decorators'];
     if (options.serializer) {
@@ -59,6 +87,9 @@ export function createImportConfig(config, options) {
     if (config.isSTI) {
         dreamImports.push('STI');
     }
+    if (includeSoftDelete) {
+        dreamImports.push('SoftDelete');
+    }
     const baseModelName = config.isSTI ? options.fullyQualifiedParentName : config.applicationModelName;
     const modelImportStatements = [importStatementForModel(baseModelName)];
     return {
@@ -150,10 +181,11 @@ function buildImportSection(imports) {
     const modelImports = uniq(imports.modelImportStatements).join('');
     return `${dreamImportLine}${typeImportLine}${modelImports}`;
 }
-function buildClassDeclaration(config) {
+function buildClassDeclaration(config, { includeSoftDelete }) {
     const stiDecorator = config.isSTI ? `@STI(${config.parentModelClassName})\n` : '';
+    const softDeleteDecorator = includeSoftDelete ? '@SoftDelete()\n' : '';
     const extendsClause = config.isSTI ? config.parentModelClassName : config.applicationModelName;
-    return `${stiDecorator}export default class ${config.modelClassName} extends ${extendsClause} {`;
+    return `${stiDecorator}${softDeleteDecorator}export default class ${config.modelClassName} extends ${extendsClause} {`;
 }
 function buildTableMethod(config) {
     if (config.isSTI)
@@ -195,14 +227,17 @@ function buildSerializersMethod(config, options) {
 
 `;
 }
-function buildFieldsSection(config, attributes) {
+function buildFieldsSection(config, attributes, { includeDeletedAt }) {
     if (config.isSTI) {
         return `${attributes.formattedFields}${attributes.formattedDecorators}`;
     }
     const idField = `  public id: DreamColumn<${config.modelClassName}, 'id'>`;
+    const deletedAtLine = includeDeletedAt
+        ? `\n  public deletedAt: DreamColumn<${config.modelClassName}, 'deletedAt'>`
+        : '';
     let timestamps = `
   public createdAt: DreamColumn<${config.modelClassName}, 'createdAt'>
-  public updatedAt: DreamColumn<${config.modelClassName}, 'updatedAt'>
+  public updatedAt: DreamColumn<${config.modelClassName}, 'updatedAt'>${deletedAtLine}
 `;
     if (!attributes.formattedDecorators.length) {
         timestamps = timestamps.replace(/\n$/, '');

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

@@ -9,7 +9,7 @@ import dreamPath from '../path/dreamPath.js';
 import snakeify from '../snakeify.js';
 import generateStiMigrationContent from './generateStiMigrationContent.js';
 import writeGeneratedFile from './writeGeneratedFile.js';
-export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, }) {
+export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
         : path.join(dreamPath('db'), 'migrations', connectionName);
@@ -29,6 +29,7 @@ export default async function generateMigration({ migrationName, columnsWithType
             table: explicitTableName || snakeify(pluralize(pascalizePath(fullyQualifiedModelName))),
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
+            softDelete,
         });
     }
     else {

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

@@ -9,11 +9,23 @@ import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, } = {}) {
+export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
     const checkConstraints = [];
-    const { columnDefs, columnDrops, indexDefs, indexDrops } = columnsWithTypes.reduce((acc, attributeDeclaration) => {
+    // When creating a new table, we automatically emit `created_at`,
+    // `updated_at`, and (when soft delete is on) `deleted_at` columns. Filter
+    // these out of the user-supplied column list so we don't emit duplicate
+    // `.addColumn(...)` calls if the user also specified them explicitly.
+    const userExplicitlyPassedDeletedAt = !altering && columnsWithTypes.some(col => (col.split(':')[0] ?? '') === 'deleted_at');
+    const processedColumnsWithTypes = altering
+        ? columnsWithTypes
+        : columnsWithTypes.filter(col => {
+            const name = col.split(':')[0] ?? '';
+            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 [nonStandardAttributeName, _attributeType, ...descriptors] = attributeDeclaration.split(':');
         if (!nonStandardAttributeName)
@@ -143,18 +155,20 @@ export async function down(db: Kysely<any>): Promise<void> {
     const columnDropLines = columnDrops.length
         ? newlineDoubleIndent + columnDrops.join(newlineDoubleIndent) + newlineDoubleIndent
         : '';
+    const timestampColumnLines = altering
+        ? ''
+        : newlineDoubleIndent +
+            ".addColumn('created_at', 'timestamp', col => col.notNull())" +
+            newlineDoubleIndent +
+            ".addColumn('updated_at', 'timestamp', col => col.notNull())" +
+            (emitDeletedAtColumn ? newlineDoubleIndent + ".addColumn('deleted_at', 'timestamp')" : '');
     return `\
 ${dreamDbImports.length ? `import { ${dreamDbImports.join(', ')} } from '@rvoh/dream/db'\n` : ''}import { ${kyselyImports.join(', ')} } from 'kysely'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function up(db: Kysely<any>): Promise<void> {
 ${citextExtension}${generateEnumStatements(columnsWithTypes)}  await db.schema
-    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${altering
-        ? ''
-        : newlineDoubleIndent +
-            ".addColumn('created_at', 'timestamp', col => col.notNull())" +
-            newlineDoubleIndent +
-            ".addColumn('updated_at', 'timestamp', col => col.notNull())"}
+    .${altering ? 'alterTable' : 'createTable'}('${table}')${altering ? '' : newlineDoubleIndent + generateIdStr({ primaryKeyType })}${columnDefLines}${timestampColumnLines}
     .execute()${indexDefs.length ? `\n${newlineIndent}` : ''}${indexDefs.join(doubleNewlineIndent)}${checkConstraints.join('')}
 }
 
@@ -184,7 +198,10 @@ function getAttributeType(attributeType, descriptors) {
 }
 function enumAttributeType(descriptors, asArray = false) {
     const suffix = asArray ? '[]' : '';
-    return `sql\`${descriptors[0]}_enum${suffix}\``;
+    return `sql\`${appendEnumSuffix(descriptors[0])}${suffix}\``;
+}
+function appendEnumSuffix(name) {
+    return name?.endsWith('_enum') ? name : `${name}_enum`;
 }
 const ENUM_OR_ENUM_ARRAY_REGEX = /:enum:.*:|:enum\[\]:.*:/;
 function generateEnumStatements(columnsWithTypes) {
@@ -197,7 +214,7 @@ function generateEnumStatements(columnsWithTypes) {
             return;
         const columnsWithTypes = columnsWithTypesString.split(/,\s{0,}/);
         return `  await db.schema
-    .createType('${enumName}_enum')
+    .createType('${appendEnumSuffix(enumName)}')
     .asEnum([
       ${columnsWithTypes.map(attr => `'${attr}'`).join(',\n      ')}
     ])
@@ -213,7 +230,7 @@ function generateEnumDropStatements(columnsWithTypes) {
         const columnsWithTypesString = descriptors[0];
         if (columnsWithTypesString === undefined)
             return;
-        return `await db.schema.dropType('${enumName}_enum').execute()`;
+        return `await db.schema.dropType('${appendEnumSuffix(enumName)}').execute()`;
     }));
     return finalStatements.length ? '\n\n  ' + finalStatements.join('\n  ') : '';
 }

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

@@ -5,8 +5,53 @@ import isDatabaseArrayColumn from '../helpers/db/types/isDatabaseArrayColumn.js'
 import CurriedOpsStatement from './curried-ops-statement.js';
 import OpsStatement from './ops-statement.js';
 const ops = {
+    /**
+     * Creates an `OpsStatement` with an arbitrary Kysely comparison operator or trigram operator.
+     * Use this as an escape hatch when none of the named helpers cover your use case.
+     *
+     * @param operator - Any Kysely comparison operator (e.g. `'='`, `'<'`) or trigram operator.
+     * @param value - The value to compare against.
+     * @returns An `OpsStatement` wrapping the given operator and value.
+     *
+     * @example
+     * User.where({ name: ops.expression('like', '%ello%') })
+     */
     expression: (operator, value) => new OpsStatement(operator, value),
+    /**
+     * Creates an `OpsStatement` that checks whether a JSONB column contains the given object
+     * using the PostgreSQL `@>` (contains) operator.
+     *
+     * @param searchObj - A plain object whose key/value pairs must be present in the JSONB column.
+     * @returns An `OpsStatement` using `@> <searchObj>::jsonb`.
+     *
+     * @example
+     * Post.where({ metadata: ops.jsonb({ published: true }) })
+     */
+    jsonb: (searchObj) => new OpsStatement('@>', sql `${searchObj}::jsonb`),
+    /**
+     * Creates an `OpsStatement` for a SQL `IN` clause, matching rows whose column value
+     * is one of the provided array elements.
+     *
+     * @param arr - The array of values to match against.
+     * @returns An `OpsStatement` using the `in` operator.
+     *
+     * @example
+     * User.where({ status: ops.in(['active', 'pending']) })
+     */
     in: (arr) => new OpsStatement('in', arr),
+    /**
+     * Creates a `CurriedOpsStatement` that checks whether a PostgreSQL array column contains
+     * the given value using `@> ARRAY[value]::type`. The column type is resolved at query-build
+     * time from the Dream model's schema.
+     *
+     * Throws `AnyRequiresArrayColumn` if the target column is not a database array type.
+     *
+     * @param value - The scalar value that must be present in the array column.
+     * @returns A `CurriedOpsStatement` that resolves to an `OpsStatement` once bound to a model and field.
+     *
+     * @example
+     * Post.where({ tags: ops.any('typescript') })
+     */
     any: (value) => new CurriedOpsStatement(function (dreamClass, fieldName) {
         const column = fieldName.replace(/^.*\./, '');
         if (!isDatabaseArrayColumn(dreamClass, column))
@@ -14,27 +59,226 @@ const ops = {
         const castType = cachedTypeForAttribute(dreamClass, column);
         return new OpsStatement('@>', sql `ARRAY[${sql.join([value])}]::${sql.raw(castType)}`);
     }),
+    /**
+     * Creates an `OpsStatement` using the SQL `LIKE` operator for case-sensitive pattern matching.
+     * Use `%` as a wildcard in the pattern string.
+     *
+     * @param like - The pattern string (e.g. `'%hello%'`).
+     * @returns An `OpsStatement` using the `like` operator.
+     *
+     * @example
+     * User.where({ name: ops.like('%alice%') })
+     */
     like: (like) => new OpsStatement('like', like),
+    /**
+     * Creates an `OpsStatement` using the SQL `ILIKE` operator for case-insensitive pattern matching.
+     * Use `%` as a wildcard in the pattern string.
+     *
+     * @param ilike - The pattern string (e.g. `'%hello%'`).
+     * @returns An `OpsStatement` using the `ilike` operator.
+     *
+     * @example
+     * User.where({ name: ops.ilike('%alice%') })
+     */
     ilike: (ilike) => new OpsStatement('ilike', ilike),
+    /**
+     * Creates an `OpsStatement` that matches a column against a POSIX regular expression.
+     * By default the match is case-sensitive (`~`); pass `{ caseInsensitive: true }` to use `~*`.
+     *
+     * @param match - The regular expression pattern.
+     * @param options.caseInsensitive - When `true`, uses the `~*` operator instead of `~`. Defaults to `false`.
+     * @returns An `OpsStatement` using `~` or `~*`.
+     *
+     * @example
+     * User.where({ email: ops.match('^admin', { caseInsensitive: true }) })
+     */
     match: (match, { caseInsensitive = false } = {}) => new OpsStatement(caseInsensitive ? '~*' : '~', match),
-    // current
+    /**
+     * Creates an `OpsStatement` using the `=` operator for strict equality.
+     *
+     * @param equal - The value the column must equal.
+     * @returns An `OpsStatement` using the `=` operator.
+     *
+     * @example
+     * User.where({ role: ops.equal('admin') })
+     */
     equal: (equal) => new OpsStatement('=', equal),
+    /**
+     * Creates an `OpsStatement` using the `<` operator.
+     *
+     * @param lessThan - The value the column must be less than.
+     * @returns An `OpsStatement` using the `<` operator.
+     *
+     * @example
+     * Order.where({ total: ops.lessThan(100) })
+     */
     lessThan: (lessThan) => new OpsStatement('<', lessThan),
+    /**
+     * Creates an `OpsStatement` using the `<=` operator.
+     *
+     * @param lessThanOrEqualTo - The value the column must be less than or equal to.
+     * @returns An `OpsStatement` using the `<=` operator.
+     *
+     * @example
+     * Order.where({ total: ops.lessThanOrEqualTo(100) })
+     */
     lessThanOrEqualTo: (lessThanOrEqualTo) => new OpsStatement('<=', lessThanOrEqualTo),
+    /**
+     * Creates an `OpsStatement` using the `>` operator.
+     *
+     * @param greaterThan - The value the column must be greater than.
+     * @returns An `OpsStatement` using the `>` operator.
+     *
+     * @example
+     * Order.where({ total: ops.greaterThan(50) })
+     */
     greaterThan: (greaterThan) => new OpsStatement('>', greaterThan),
+    /**
+     * Creates an `OpsStatement` using the `>=` operator.
+     *
+     * @param greaterThanOrEqualTo - The value the column must be greater than or equal to.
+     * @returns An `OpsStatement` using the `>=` operator.
+     *
+     * @example
+     * Order.where({ total: ops.greaterThanOrEqualTo(50) })
+     */
     greaterThanOrEqualTo: (greaterThanOrEqualTo) => new OpsStatement('>=', greaterThanOrEqualTo),
+    /**
+     * Creates an `OpsStatement` for PostgreSQL trigram similarity (`%` operator).
+     * Rows are included when the similarity score meets or exceeds `score`.
+     *
+     * Requires the `pg_trgm` extension to be enabled.
+     *
+     * @param similarity - The string to compare against the column.
+     * @param options.score - Minimum similarity threshold (0–1). Defaults to `0.3`.
+     * @returns An `OpsStatement` using the `%` trigram operator.
+     *
+     * @example
+     * User.where({ name: ops.similarity('alice', { score: 0.4 }) })
+     */
     similarity: (similarity, { score = 0.3 } = {}) => new OpsStatement('%', similarity, { score }),
+    /**
+     * Creates an `OpsStatement` for PostgreSQL word similarity (`<%` operator).
+     * Rows are included when the word similarity score meets or exceeds `score`.
+     *
+     * Requires the `pg_trgm` extension to be enabled.
+     *
+     * @param similarity - The string to compare against the column.
+     * @param options.score - Minimum word similarity threshold (0–1). Defaults to `0.5`.
+     * @returns An `OpsStatement` using the `<%` trigram operator.
+     *
+     * @example
+     * Article.where({ title: ops.wordSimilarity('postgres', { score: 0.6 }) })
+     */
     wordSimilarity: (similarity, { score = 0.5 } = {}) => new OpsStatement('<%', similarity, { score }),
+    /**
+     * Creates an `OpsStatement` for PostgreSQL strict word similarity (`<<%` operator).
+     * Rows are included when the strict word similarity score meets or exceeds `score`.
+     *
+     * Requires the `pg_trgm` extension to be enabled.
+     *
+     * @param similarity - The string to compare against the column.
+     * @param options.score - Minimum strict word similarity threshold (0–1). Defaults to `0.6`.
+     * @returns An `OpsStatement` using the `<<%` trigram operator.
+     *
+     * @example
+     * Article.where({ title: ops.strictWordSimilarity('postgres', { score: 0.7 }) })
+     */
     strictWordSimilarity: (similarity, { score = 0.6 } = {}) => new OpsStatement('<<%', similarity, { score }),
+    /** Negated variants of the standard comparison operators. */
     not: {
+        /**
+         * Creates an `OpsStatement` for a SQL `NOT IN` clause, excluding rows whose column value
+         * is one of the provided array elements.
+         *
+         * @param arr - The array of values to exclude.
+         * @returns An `OpsStatement` using the `not in` operator.
+         *
+         * @example
+         * User.where({ status: ops.not.in(['banned', 'deleted']) })
+         */
         in: (arr) => new OpsStatement('not in', arr),
+        /**
+         * Creates an `OpsStatement` using the `NOT LIKE` operator for case-sensitive pattern exclusion.
+         *
+         * @param like - The pattern string (e.g. `'%spam%'`).
+         * @returns An `OpsStatement` using the `not like` operator.
+         *
+         * @example
+         * User.where({ email: ops.not.like('%@example.com') })
+         */
         like: (like) => new OpsStatement('not like', like),
+        /**
+         * Creates an `OpsStatement` using the `NOT ILIKE` operator for case-insensitive pattern exclusion.
+         *
+         * @param ilike - The pattern string (e.g. `'%spam%'`).
+         * @returns An `OpsStatement` using the `not ilike` operator.
+         *
+         * @example
+         * User.where({ email: ops.not.ilike('%@example.com') })
+         */
         ilike: (ilike) => new OpsStatement('not ilike', ilike),
+        /**
+         * Creates an `OpsStatement` that excludes rows matching a POSIX regular expression.
+         * By default the match is case-sensitive (`!~`); pass `{ caseInsensitive: true }` to use `!~*`.
+         *
+         * @param match - The regular expression pattern.
+         * @param options.caseInsensitive - When `true`, uses `!~*` instead of `!~`. Defaults to `false`.
+         * @returns An `OpsStatement` using `!~` or `!~*`.
+         *
+         * @example
+         * User.where({ email: ops.not.match('^admin', { caseInsensitive: true }) })
+         */
         match: (match, { caseInsensitive = false } = {}) => new OpsStatement(caseInsensitive ? '!~*' : '!~', match),
+        /**
+         * Creates an `OpsStatement` using the `!=` operator for inequality.
+         *
+         * @param equal - The value the column must not equal.
+         * @returns An `OpsStatement` using the `!=` operator.
+         *
+         * @example
+         * User.where({ role: ops.not.equal('guest') })
+         */
         equal: (equal) => new OpsStatement('!=', equal),
+        /**
+         * Creates an `OpsStatement` that negates `<`, equivalent to `>=`.
+         *
+         * @param lessThan - The value used as the lower bound (inclusive).
+         * @returns An `OpsStatement` using `>=`.
+         *
+         * @example
+         * Order.where({ total: ops.not.lessThan(100) }) // total >= 100
+         */
         lessThan: (lessThan) => new OpsStatement('>=', lessThan),
+        /**
+         * Creates an `OpsStatement` that negates `<=`, equivalent to `>`.
+         *
+         * @param lessThanOrEqualTo - The value used as the lower bound (exclusive).
+         * @returns An `OpsStatement` using `>`.
+         *
+         * @example
+         * Order.where({ total: ops.not.lessThanOrEqualTo(100) }) // total > 100
+         */
         lessThanOrEqualTo: (lessThanOrEqualTo) => new OpsStatement('>', lessThanOrEqualTo),
+        /**
+         * Creates an `OpsStatement` that negates `>`, equivalent to `<=`.
+         *
+         * @param greaterThan - The value used as the upper bound (inclusive).
+         * @returns An `OpsStatement` using `<=`.
+         *
+         * @example
+         * Order.where({ total: ops.not.greaterThan(50) }) // total <= 50
+         */
         greaterThan: (greaterThan) => new OpsStatement('<=', greaterThan),
+        /**
+         * Creates an `OpsStatement` that negates `>=`, equivalent to `<`.
+         *
+         * @param greaterThanOrEqualTo - The value used as the upper bound (exclusive).
+         * @returns An `OpsStatement` using `<`.
+         *
+         * @example
+         * Order.where({ total: ops.not.greaterThanOrEqualTo(50) }) // total < 50
+         */
         greaterThanOrEqualTo: (greaterThanOrEqualTo) => new OpsStatement('<', greaterThanOrEqualTo),
     },
 };

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

@@ -62,6 +62,8 @@ export default class DreamBin {
                 includeInternalSerializers: options.internalSerializers ?? false,
                 ...options,
                 stiBaseSerializer: false,
+                // `@SoftDelete()` is incompatible with STI children — never auto-apply.
+                softDelete: false,
             },
             fullyQualifiedParentName,
         });

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

@@ -190,6 +190,7 @@ ${INDENT}  pnpm psy g:model --model-name=GroupDanceLesson Lesson/Dance/Group
 ${INDENT}  # model is named GroupDanceLesson instead of LessonDanceGroup`)
             .option('--admin-serializers', 'also generate AdminSerializer and AdminSummarySerializer variants for admin-facing API endpoints that may expose additional fields', false)
             .option('--internal-serializers', 'also generate InternalSerializer and InternalSummarySerializer variants for internal API endpoints that may expose additional fields', false)
+            .option('--no-soft-delete', `skip generating the @SoftDelete() decorator and the corresponding nullable \`deleted_at\` column. By default, generated models use soft-delete semantics (rows are marked deleted via \`deleted_at\` instead of being removed from the database). Pass this flag when you want records to be hard-deleted.`)
             .argument('<modelName>', `The fully qualified model name, using / for namespacing. This determines the model class name (may be overridden with \`--model-name\`), table name, and file path under src/app/models/.
 ${INDENT}
 ${INDENT}Examples:

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

@@ -9,6 +9,11 @@ import writeGeneratedFile from './writeGeneratedFile.js';
 export default async function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
     const modelClassName = modelClassNameFrom(fullyQualifiedModelName, options.modelName);
+    const isSTI = !!fullyQualifiedParentName;
+    // `@SoftDelete()` is incompatible with STI children, so we force-disable
+    // the soft-delete scaffold when generating an STI child regardless of the
+    // caller-provided value.
+    const softDelete = !isSTI && !!options.softDelete;
     await writeGeneratedFile({
         dreamPathKey: 'models',
         fileName: `${fullyQualifiedModelName}.ts`,
@@ -22,6 +27,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             connectionName: options.connectionName,
             tableName: options.tableName,
             modelClassName,
+            softDelete,
         }),
         logLabel: 'dream',
     });
@@ -37,7 +43,6 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             includeInternalSerializers: options.includeInternalSerializers ?? false,
             modelClassName,
         });
-    const isSTI = !!fullyQualifiedParentName;
     if (columnsWithTypes.length || !isSTI) {
         await generateMigration({
             connectionName: options.connectionName,
@@ -47,6 +52,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             fullyQualifiedParentName,
             tableName: options.tableName,
             modelClassName,
+            softDelete,
         });
     }
 }