@rvoh/dream 2.18.1 → 2.20.0

package/dist/cjs/src/dream/internal/filterRowToKnownColumns.js

@@ -0,0 +1,41 @@
+import protectAgainstPollutingAssignment from '../../helpers/protectAgainstPollutingAssignment.js';
+/**
+ * @internal
+ *
+ * Returns an object containing only the keys of `row` that are columns
+ * the compiled schema knows about (per the provided column set).
+ *
+ * Under schema/image skew (e.g. a rolling deploy in which a migration adds
+ * a column while containers built against the previous schema are still
+ * draining, or application code is rolled back after an add-column
+ * migration), a `RETURNING *` / `select *` row can include columns this
+ * build has never heard of. Passing such keys to `setAttributes` would
+ * assign them as plain properties — invoking a same-named user-defined
+ * setter, or throwing on a getter-only property — so they must be dropped
+ * before hydration.
+ *
+ * Keys are intersected rather than enumerated from the column set so that
+ * a column missing from the row (the dropped-column direction of skew)
+ * simply does not appear, rather than appearing with an `undefined` value.
+ *
+ * Identity fast path: when every key of `row` is a known column (the
+ * no-skew steady state), `row` itself is returned unchanged, without
+ * allocating a copy; a filtered copy is built only when at least one
+ * unknown key is present.
+ *
+ * @param row - a raw database row
+ * @param columns - the compiled column set for the Dream class being hydrated
+ * @returns `row` itself when every key is a known column; otherwise a new
+ * object containing only the known-column entries of `row`
+ */
+export default function filterRowToKnownColumns(row, columns) {
+    const keys = Object.keys(row);
+    if (keys.every(key => columns.has(key)))
+        return row;
+    const filtered = {};
+    keys.forEach(key => {
+        if (columns.has(key))
+            filtered[protectAgainstPollutingAssignment(key)] = row[key];
+    });
+    return filtered;
+}

package/dist/cjs/src/dream/internal/saveDream.js

@@ -2,6 +2,7 @@ import ValidationError from '../../errors/ValidationError.js';
 import sqlAttributes from '../../helpers/sqlAttributes.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
 import Query from '../Query.js';
+import filterRowToKnownColumns from './filterRowToKnownColumns.js';
 import runHooksFor from './runHooksFor.js';
 export default async function saveDream(dream, txn = null, { skipHooks = false } = {}) {
     const alreadyPersisted = dream.isPersisted;
@@ -30,7 +31,11 @@ export default async function saveDream(dream, txn = null, { skipHooks = false }
     if (!alreadyPersisted || hasUnsavedData) {
         const data = await Query.dbDriverClass(dream.connectionName || 'default').saveDream(dream, txn);
         dream['isPersisted'] = true;
-        dream.setAttributes(data);
+        // the row returned by the driver comes from `RETURNING *` (or a
+        // `select *` reload on drivers without RETURNING support), so under
+        // schema/image skew it can contain columns this build's compiled
+        // schema doesn't know about; those must never reach setAttributes
+        dream.setAttributes(filterRowToKnownColumns(data, dream.columns()));
     }
     // set frozen attributes to what has already been saved
     dream['freezeAttributes']();

package/dist/cjs/src/dream/internal/sqlResultToDreamInstance.js

@@ -1,10 +1,17 @@
 import STIChildMissing from '../../errors/sti/STIChildMissing.js';
+import filterRowToKnownColumns from './filterRowToKnownColumns.js';
 export default function sqlResultToDreamInstance(dreamClass, sqlResult) {
+    // base-model reads select `*`, so under schema/image skew (or with a
+    // column declared in ignoredColumns but not yet dropped) the row can
+    // contain columns the compiled schema doesn't know about. Passing such
+    // keys into the constructor would assign them as plain properties —
+    // invoking a same-named user-defined setter, or throwing on a
+    // getter-only property — so they are dropped before hydration.
     if (dreamClass['isSTIBase']) {
         const extendingDreamClass = findExtendingDreamClass(dreamClass, sqlResult.type);
         if (!extendingDreamClass)
             throw new STIChildMissing(dreamClass, sqlResult.type, sqlResult[dreamClass.primaryKey]);
-        const dreamModel = new extendingDreamClass(sqlResult, {
+        const dreamModel = new extendingDreamClass(filterRowToKnownColumns(sqlResult, extendingDreamClass.columns()), {
             bypassUserDefinedSetters: true,
             isPersisted: true,
             _internalUseOnly: true,
@@ -13,7 +20,7 @@ export default function sqlResultToDreamInstance(dreamClass, sqlResult) {
         return dreamModel;
     }
     else {
-        const dreamModel = new dreamClass(sqlResult, {
+        const dreamModel = new dreamClass(filterRowToKnownColumns(sqlResult, dreamClass.columns()), {
             bypassUserDefinedSetters: true,
             isPersisted: true,
             _internalUseOnly: true,

package/dist/cjs/src/errors/CannotNamespaceAssociationFilterToAnotherTable.js

@@ -0,0 +1,27 @@
+export default class CannotNamespaceAssociationFilterToAnotherTable extends Error {
+    dreamClass;
+    key;
+    expectedAlias;
+    constructor(dreamClass, key, expectedAlias) {
+        super();
+        this.dreamClass = dreamClass;
+        this.key = key;
+        this.expectedAlias = expectedAlias;
+    }
+    get message() {
+        return `
+Cannot filter on an association via a where-clause key namespaced to another table.
+
+dream class: ${this.dreamClass.sanitizedName}
+where-clause key: ${this.key}
+table alias this where clause applies to: ${this.expectedAlias}
+
+A Dream instance (or array of Dream instances) as a where-clause value resolves
+an association on the model the where clause applies to, so the key may not be
+namespaced to a different table. To filter a joined table by one of its
+associations, pass the filter in the join's on-clause instead, e.g.:
+
+  .innerJoin('association', { and: { myBelongsToAssociation: instances } })
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreAssociationColumn.js

@@ -0,0 +1,38 @@
+export default class CannotIgnoreAssociationColumn extends Error {
+    tableName;
+    columnName;
+    modelClass;
+    association;
+    columnRole;
+    constructor(tableName, columnName, modelClass, association, columnRole) {
+        super();
+        this.tableName = tableName;
+        this.columnName = columnName;
+        this.modelClass = modelClass;
+        this.association = association;
+        this.columnRole = columnRole;
+    }
+    get message() {
+        return `
+The models backed by the "${this.tableName}" table declare
+"${this.columnName}" in ignoredColumns, but "${this.columnName}" is the
+${this.columnRole} of the ${this.association.type} association
+"${this.association.as}" on ${this.modelClass.sanitizedName}.
+
+Associations read and write their columns by name, so ignoring
+"${this.columnName}" would silently break "${this.association.as}" at
+runtime: ${this.consequence}. Remove the
+"${this.association.as}" association from ${this.modelClass.sanitizedName}
+(or point it at a different column) before ignoring "${this.columnName}".
+`;
+    }
+    get consequence() {
+        if (this.columnRole === 'primary key override')
+            return `associating a record would read "${this.columnName}" from an
+instance that no longer hydrates it, silently persisting an empty foreign
+key, and association loads would join on a column missing from the
+generated schema`;
+        return `writes to the column would stop persisting, and association loads
+would reference a column missing from the generated schema`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreEncryptedColumn.js

@@ -0,0 +1,20 @@
+export default class CannotIgnoreEncryptedColumn extends Error {
+    modelClass;
+    columnName;
+    constructor(modelClass, columnName) {
+        super();
+        this.modelClass = modelClass;
+        this.columnName = columnName;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares "${this.columnName}" in
+ignoredColumns, but "${this.columnName}" is the backing column of an
+@Encrypted property on ${this.modelClass.sanitizedName}.
+
+@Encrypted stores its ciphertext in this column, so it can never be
+ignored. Remove the @Encrypted declaration (and its property) from
+${this.modelClass.sanitizedName} before ignoring "${this.columnName}".
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnorePrimaryKey.js

@@ -0,0 +1,18 @@
+export default class CannotIgnorePrimaryKey extends Error {
+    modelClass;
+    constructor(modelClass) {
+        super();
+        this.modelClass = modelClass;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares its primary key ("${this.modelClass.primaryKey}")
+in ignoredColumns.
+
+The primary key is required to identify rows for hydration, updates, and
+associations, so it can never be ignored. Remove
+"${this.modelClass.primaryKey}" from the ignoredColumns getter on
+${this.modelClass.sanitizedName}.
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreSoftDeleteColumn.js

@@ -0,0 +1,21 @@
+export default class CannotIgnoreSoftDeleteColumn extends Error {
+    modelClass;
+    columnName;
+    constructor(modelClass, columnName) {
+        super();
+        this.modelClass = modelClass;
+        this.columnName = columnName;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares "${this.columnName}" in
+ignoredColumns, but ${this.modelClass.sanitizedName} is a SoftDelete model
+and "${this.columnName}" is its deletedAtField.
+
+SoftDelete writes this column on destroy and filters on it in its default
+scope, so it can never be ignored. Remove the @SoftDelete decorator from
+${this.modelClass.sanitizedName} (or point deletedAtField at a different
+column) before ignoring "${this.columnName}".
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreSortablePositionColumn.js

@@ -0,0 +1,20 @@
+export default class CannotIgnoreSortablePositionColumn extends Error {
+    modelClass;
+    columnName;
+    constructor(modelClass, columnName) {
+        super();
+        this.modelClass = modelClass;
+        this.columnName = columnName;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares "${this.columnName}" in
+ignoredColumns, but "${this.columnName}" is the position field of an
+@Sortable declaration on ${this.modelClass.sanitizedName}.
+
+@Sortable reads and rewrites this column to keep positions contiguous, so
+it can never be ignored. Remove the @Sortable decorator (and its property)
+from ${this.modelClass.sanitizedName} before ignoring "${this.columnName}".
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreSortableScopeColumn.js

@@ -0,0 +1,24 @@
+export default class CannotIgnoreSortableScopeColumn extends Error {
+    modelClass;
+    columnName;
+    positionField;
+    constructor(modelClass, columnName, positionField) {
+        super();
+        this.modelClass = modelClass;
+        this.columnName = columnName;
+        this.positionField = positionField;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares "${this.columnName}" in
+ignoredColumns, but "${this.columnName}" is a scope column of the @Sortable
+declaration on "${this.positionField}" on ${this.modelClass.sanitizedName}.
+
+@Sortable reads this column by name on every save and destroy to partition
+position values, so it can never be ignored. Remove "${this.columnName}"
+from the @Sortable scope on "${this.positionField}" (or remove the
+@Sortable decorator and its property) on ${this.modelClass.sanitizedName}
+before ignoring "${this.columnName}".
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/CannotIgnoreStiTypeColumn.js

@@ -0,0 +1,17 @@
+export default class CannotIgnoreStiTypeColumn extends Error {
+    modelClass;
+    constructor(modelClass) {
+        super();
+        this.modelClass = modelClass;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} participates in single-table inheritance
+and declares the STI "type" column in ignoredColumns.
+
+The "type" column determines which model class each row hydrates into, so
+an STI model can never ignore it. Remove "type" from the ignoredColumns
+getter on ${this.modelClass.sanitizedName}.
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/ConflictingIgnoredColumns.js

@@ -0,0 +1,27 @@
+export default class ConflictingIgnoredColumns extends Error {
+    tableName;
+    modelClasses;
+    constructor(tableName, modelClasses) {
+        super();
+        this.tableName = tableName;
+        this.modelClasses = modelClasses;
+    }
+    get message() {
+        const declarations = this.modelClasses
+            .map(modelClass => `    ${modelClass.sanitizedName}: [${[...modelClass.prototype.ignoredColumns]
+            .sort()
+            .map(column => `'${column}'`)
+            .join(', ')}]`)
+            .join('\n');
+        return `
+Models sharing the table "${this.tableName}" declare different ignoredColumns:
+
+${declarations}
+
+There is only one generated schema per table, so every model backed by a
+table must agree on which of its columns are ignored. Align the
+ignoredColumns getters (STI children inherit the base model's getter, so
+the common fix is to declare ignored columns only on the base model).
+`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/IgnoredColumnMustBeCamelCase.js

@@ -0,0 +1,21 @@
+import camelize from '../../helpers/camelize.js';
+export default class IgnoredColumnMustBeCamelCase extends Error {
+    modelClass;
+    columnName;
+    constructor(modelClass, columnName) {
+        super();
+        this.modelClass = modelClass;
+        this.columnName = columnName;
+    }
+    get message() {
+        return `
+${this.modelClass.sanitizedName} declares "${this.columnName}" in
+ignoredColumns, but ignored columns must be declared in camelCase.
+
+Dream camelizes database column names when generating types, so a
+declaration that is not camelCase can never match a generated column and
+would be silently inert. Declare "${camelize(this.columnName)}" in the
+ignoredColumns getter on ${this.modelClass.sanitizedName} instead.
+`;
+    }
+}

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

@@ -11,6 +11,7 @@ import intersection from '../intersection.js';
 import sortBy from '../sortBy.js';
 import uniq from '../uniq.js';
 import ASTBuilder from './ASTBuilder.js';
+import resolveIgnoredColumns from './resolveIgnoredColumns.js';
 /**
  * @internal
  *
@@ -265,12 +266,48 @@ may need to update the table getter in the corresponding Dream.
                 default: uniq(models.flatMap(model => model['scopes'].default.map(scopeStatement => scopeStatement.method))),
                 named: uniq(models.flatMap(model => model['scopes'].named.map(scopeStatement => scopeStatement.method))),
             },
-            columns: await this.getColumnData(tableName, associationData),
+            columns: this.withoutIgnoredColumns(await this.getColumnData(tableName, associationData), tableName),
             virtualColumns: uniq(models.flatMap(model => model['virtualAttributes'].map(prop => prop.property) || [])),
             associations: associationData,
             serializerKeys,
         };
     }
+    /**
+     * @internal
+     *
+     * resolves the ignored columns declared by the models backed by the
+     * given table (validating the declarations; see resolveIgnoredColumns)
+     */
+    ignoredColumnsForTable(tableName) {
+        const dreamApp = DreamApp.getOrFail();
+        const allModels = Object.values(dreamApp.models).filter(model => model.prototype?.connectionName === this.connectionName);
+        const models = allModels.filter(model => model.table === tableName);
+        return resolveIgnoredColumns(models, tableName, allModels);
+    }
+    /**
+     * @internal
+     *
+     * returns the provided column data without the columns that the table's
+     * models declare in ignoredColumns. This is what removes ignored columns
+     * from the generated dream schema file: `columns()` reads the generated
+     * schema at runtime, so every column enumeration built from `columns()`
+     * (preload and join-load select lists, save hydration, attribute
+     * definition) inherits this filtering. A column that is ignored but not
+     * present in the introspected table (e.g. after the drop migration has
+     * run but before the declaration is removed) is a no-op.
+     */
+    withoutIgnoredColumns(columnData, tableName) {
+        const ignoredColumns = this.ignoredColumnsForTable(tableName);
+        if (!ignoredColumns.size)
+            return columnData;
+        return Object.keys(columnData)
+            .filter(columnName => !ignoredColumns.has(columnName))
+            .reduce((filtered, columnName) => {
+            ;
+            filtered[columnName] = columnData[columnName];
+            return filtered;
+        }, {});
+    }
     /**
      * @internal
      *

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

@@ -25,6 +25,7 @@ export default class ASTKyselyCodegenEnhancer extends ASTConnectionBuilder {
     async enhance() {
         let dbSourceFile = await this.getDbSourceFile();
         dbSourceFile = this.camelizeKeys(dbSourceFile);
+        dbSourceFile = this.removeIgnoredColumns(dbSourceFile);
         dbSourceFile = this.replaceTimestampExport(dbSourceFile);
         dbSourceFile = await this.replaceTimeFieldsInInterfaces(dbSourceFile);
         dbSourceFile = this.addMissingImports(dbSourceFile);
@@ -283,6 +284,65 @@ ${output}`);
         const result = ts.transform(dbSourceFile, [transformer]);
         return result.transformed[0];
     }
+    /**
+     * @internal
+     *
+     * removes columns declared in model `ignoredColumns` getters from the
+     * table interfaces generated by kysely-codegen. This is what removes
+     * ignored columns from the generated db types file: every column-name
+     * level type (`DreamColumnNames`, `UpdateableProperties`, where-clause
+     * statements) derives from the Kysely `DB` interface, so filtering here
+     * turns any remaining code reference to an ignored column into a type
+     * error. Runs after camelizeKeys so that member names align with the
+     * camelCase column names models declare in ignoredColumns.
+     */
+    removeIgnoredColumns(dbSourceFile) {
+        const dbInterface = this.findDbExport(dbSourceFile, 'DB');
+        if (!dbInterface)
+            return dbSourceFile;
+        // the DB interface maps table names to table interfaces (e.g.
+        // `collars: Collars`), so it provides the table name each table
+        // interface corresponds to
+        const ignoredColumnsByInterfaceName = {};
+        dbInterface.members.forEach(member => {
+            if (!ts.isPropertySignature(member))
+                return;
+            if (!member.type || !ts.isTypeReferenceNode(member.type))
+                return;
+            if (!ts.isIdentifier(member.type.typeName))
+                return;
+            const tableName = ts.isIdentifier(member.name)
+                ? member.name.text
+                : ts.isStringLiteral(member.name)
+                    ? member.name.text
+                    : null;
+            if (!tableName)
+                return;
+            const ignoredColumns = this.ignoredColumnsForTable(tableName);
+            if (ignoredColumns.size)
+                ignoredColumnsByInterfaceName[member.type.typeName.text] = ignoredColumns;
+        });
+        if (!Object.keys(ignoredColumnsByInterfaceName).length)
+            return dbSourceFile;
+        // @ts-expect-error cannot lock this type down, though implementation is correct
+        const transformer = context => {
+            const visit = node => {
+                const interfaceNode = this.exportedInterfaceOrNull(node);
+                const ignoredColumns = interfaceNode
+                    ? ignoredColumnsByInterfaceName[interfaceNode.name.text]
+                    : undefined;
+                if (interfaceNode && ignoredColumns) {
+                    return f.updateInterfaceDeclaration(interfaceNode, interfaceNode.modifiers, interfaceNode.name, interfaceNode.typeParameters, interfaceNode.heritageClauses, interfaceNode.members.filter(member => !(ts.isPropertySignature(member) &&
+                        (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)) &&
+                        ignoredColumns.has(member.name.text))));
+                }
+                return ts.visitEachChild(node, visit, context);
+            };
+            return node => ts.visitNode(node, visit);
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
     /**
      * @internal
      *

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

@@ -8,8 +8,13 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
-const DELETED_AT_COLUMN_NAME = 'deleted_at';
-const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME, DELETED_AT_COLUMN_NAME];
+// deleted_at is deliberately NOT in this list: the SoftDelete default scope's
+// `WHERE deleted_at IS NULL` is unselective on healthy tables, Dream internals
+// never issue a query a deleted_at index could serve, and the useful partial
+// index alternatives are dialect-specific SQL the generator must not emit by
+// default. See spec/unit/cli/generateMigrationContent.spec.ts
+// ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
+const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
 export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
@@ -43,13 +48,18 @@ export default function generateMigrationContent({ connectionName = 'default', t
             return acc;
         /**
          * Automatically set email columns to citext since different casings of
-         * email address are the same email address
+         * email address are the same email address. Skip this when the user
+         * explicitly asked for an encrypted column, since encrypted columns
+         * are always stored as encrypted text and must not be overridden by
+         * the name-based heuristic.
          */
-        const attributeType = /email$/.test(nonStandardAttributeName)
-            ? 'citext'
-            : /uuid$/.test(nonStandardAttributeName)
-                ? 'uuid'
-                : _attributeType;
+        const attributeType = _attributeType === 'encrypted' || _attributeType === 'encrypted[]'
+            ? _attributeType
+            : /email$/.test(nonStandardAttributeName)
+                ? 'citext'
+                : /uuid$/.test(nonStandardAttributeName)
+                    ? 'uuid'
+                    : _attributeType;
         const processedAttrType = camelize(attributeType)?.toLowerCase();
         const userWantsThisOptional = optionalFromDescriptors(descriptors);
         // when creating a migration for an STI child, we don't want to include notNull;
@@ -115,6 +125,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 attributeName = `encrypted_${attributeName}`;
                 columnDefs.push(generateColumnStr(attributeName, 'text', descriptors, {
                     omitInlineNonNull,
+                    skipUniqueHeuristic: true,
                 }));
                 break;
             // TODO: determine if we need to support encrypted[] in the future
@@ -145,9 +156,6 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         return acc;
     }, { columnDefs: [], columnDrops: [], indexDefs: [] });
-    if (emitDeletedAtColumn) {
-        indexDefs.push(columnIndexStatement(table, DELETED_AT_COLUMN_NAME));
-    }
     if (!table) {
         return `\
 import { Kysely, sql } from 'kysely'
@@ -274,12 +282,12 @@ function generateDecimalStr(attributeName, { descriptors, omitInlineNonNull: opt
         : `'decimal(${scale}, ${precision})'`;
     return `.addColumn('${attributeName}', ${decimalStatement}${optional ? '' : `, col => ${columnModifiers}`})`;
 }
-function generateColumnStr(attributeName, attributeType, descriptors, { omitInlineNonNull: optional }) {
+function generateColumnStr(attributeName, attributeType, descriptors, { omitInlineNonNull: optional, skipUniqueHeuristic = false, }) {
     let returnStr = `.addColumn('${attributeName}', ${attributeTypeString(attributeType)}`;
     const providedDefaultArg = descriptors.find(d => /^default\(/.test(d));
     const providedDefault = providedDefaultArg?.replace(/^default\(/, '')?.replace(/\)$/, '');
     const notNull = !optional;
-    const isUnique = /(email|token|uuid)$/.test(attributeName);
+    const isUnique = !skipUniqueHeuristic && /(email|token|uuid)$/.test(attributeName);
     const hasExtraValues = providedDefault || notNull || isUnique;
     const isArray = /\[\]$/.test(attributeType);
     const needsJsonDefault = notNull && !isArray && (attributeType === 'jsonb' || attributeType === 'json');