@rvoh/dream 2.19.0 → 2.21.1

package/dist/cjs/src/Dream.js

@@ -1461,6 +1461,12 @@ export default class Dream {
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
+     * 6. leftJoinPreload must enumerate every compiled column of every joined
+     * model, so unlike base-model reads, `preload`/`load`, and saves, it does
+     * not tolerate schema/image skew from an unplanned column drop during a
+     * rolling deploy; see {@link Query.leftJoinPreload} and the
+     * `ignoredColumns` getter for the two-deploy process that makes a
+     * planned drop safe.
      *
      * ```ts
      * const user = await User.leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
@@ -2340,6 +2346,83 @@ export default class Dream {
     get table() {
         throw new DreamMissingRequiredOverride(this.constructor, 'table');
     }
+    /**
+     * Columns that Dream should behave as though they do not exist.
+     *
+     * Declaring a column ignored removes it from the generated types the next
+     * time `sync` runs: it is omitted from both the db types file (the Kysely
+     * `DB` interface) and the dream schema file, so it disappears from
+     * `columns()` and from every place that flows from `columns()` — select
+     * lists built for `preload`/`load` and `leftJoinPreload`, save hydration,
+     * attribute definition, and param safety. References to the column in
+     * application code become type errors, which is the point: they must be
+     * removed before the column can be dropped.
+     *
+     * This enables safely dropping a column under rolling deploys — the same
+     * problem Rails solves with `ignored_columns`. The safety requirement is
+     * that no image that can run against the post-drop schema names the
+     * column in any SQL it generates. To satisfy it: remove all application
+     * code that uses the column, declare it here, and run `sync`; then let
+     * the drop migration run only once no image lacking the declaration can
+     * run against the database — whether the migration ships in a later
+     * deploy of its own, or together with the declaration in a pipeline that
+     * runs migrations only after the new images have rolled out. Once the
+     * column is dropped, remove this declaration and resync.
+     *
+     * Precondition: as soon as an image built with this declaration runs,
+     * the column is never placed in INSERT column lists, so before that
+     * image can run, the column must be nullable or carry a database
+     * default — a live `NOT NULL` column without a default fails every
+     * create against the table.
+     *
+     * Dropping the column while an image that names it can still run leaves
+     * a window during which those containers (including a rolled-back image)
+     * fail with `42703 column does not exist` — `leftJoinPreload` in
+     * particular has no runtime tolerance for this, since it must enumerate
+     * aliased columns.
+     *
+     * This is a mechanism for the drop window, not for permanently hiding
+     * wide columns: the ignored column is still transferred from the
+     * database on every `RETURNING *` / `select *` until it is actually
+     * dropped.
+     *
+     * The declaration is read only while `sync` generates the types files; it
+     * has no runtime behavior of its own. A declared-but-not-synced model is
+     * therefore not yet protected — CI should verify that `sync` produces no
+     * diff. `sync` will fail loudly if a declared name is not camelCase
+     * (generated column names are camelized, so any other shape could never
+     * match and would be silently inert), if models sharing a table declare
+     * different ignored columns, or if a model attempts to ignore a column
+     * the framework itself reads and writes by name: its primary key, an STI
+     * model's `type` column, any association's foreign key, polymorphic type
+     * field, or `primaryKeyOverride` column, an `@Sortable` position field or
+     * plain-column `@Sortable` scope, an `@Encrypted` backing column, or a
+     * SoftDelete model's `deletedAt` column.
+     *
+     * Because an ignored column vanishes from `columns()`, runtime access via
+     * type escape hatches behaves exactly like any unknown attribute: reads
+     * return `undefined`, and writes assign a plain instance property that is
+     * never persisted.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   public override get ignoredColumns() {
+     *     return ['legacyEmail'] as const
+     *   }
+     * }
+     * ```
+     *
+     * NOTE: this getter is intentionally typed as `readonly string[]` rather
+     * than as a union of known column names: during the deploy that declares
+     * a column ignored, the regenerated types no longer contain the column,
+     * so a column-name-derived type would reject the very declaration that
+     * removed it.
+     *
+     * @returns The list of column names this model should ignore
+     */
+    get ignoredColumns() {
+        return [];
+    }
     /**
      * @internal
      *

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

@@ -45,6 +45,8 @@ ${INDENT}    - timetz
 ${INDENT}    - timetz[]
 ${INDENT}    - integer
 ${INDENT}    - integer[]
+${INDENT}    - boolean
+${INDENT}    - boolean[]
 ${INDENT}
 ${INDENT}    - decimal:
 ${INDENT}    - decimal[]:
@@ -153,16 +155,17 @@ ${INDENT}  # Add columns to an existing table (suffix with -to-<table_name> for
 ${INDENT}  pnpm psy g:migration add-timezone-to-users timezone:string
 ${INDENT}  pnpm psy g:migration add-bio-to-users bio:text:optional avatar_url:string:optional
 ${INDENT}
-${INDENT}  # Remove columns (suffix with -from-<table_name>)
-${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts
+${INDENT}  # Remove columns (suffix with -from-<table_name>; columns are described with
+${INDENT}  # their types, same shorthand as -to-, so the rollback (down) can recreate them)
+${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts legacy_status:string
 ${INDENT}
 ${INDENT}  # General schema change (no table suffix — generates empty up/down methods)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
             .argument('<migrationName>', `Kebab-case name describing the change. End with -to-<table_name> or -from-<table_name> to auto-generate an alterTable scaffold for that table.
 ${INDENT}
 ${INDENT}Examples:
-${INDENT}  add-phone-to-users          # scaffolds alterTable('users', ...)
-${INDENT}  remove-status-from-posts    # scaffolds alterTable('posts', ...)
+${INDENT}  add-phone-to-users phone:encrypted           # scaffolds alterTable('users', ...)
+${INDENT}  remove-status-from-posts status:string      # scaffolds alterTable('posts', ...)
 ${INDENT}  create-join-table-host-places  # empty migration (no table suffix match)`)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
             .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForMigration)

package/dist/cjs/src/dream/Query.js

@@ -442,6 +442,17 @@ export default class Query {
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
+     * 6. unlike base-model reads, `preload`/`load`, and saves — which tolerate
+     * schema/image skew (e.g. a rolling deploy dropping a column while
+     * containers compiled against the previous schema are still draining) —
+     * leftJoinPreload must enumerate every compiled column of every joined
+     * model under per-alias names (per-alias `*` is not expressible in a
+     * single flat row), so an **unplanned** column drop breaks
+     * leftJoinPreload queries for the duration of the rollout window. A
+     * **planned** drop is safe when performed via the two-deploy process
+     * documented on the `ignoredColumns` getter of Dream: declaring the
+     * column ignored removes it from the generated schema, so leftJoinPreload
+     * stops naming it a full deploy before the column is actually dropped.
      *
      *
      * ```ts

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

@@ -734,6 +734,27 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * is provided as a second argument, it will use that transaction
      * to encapsulate the persisting of the dream, as well as any
      * subsequent model hooks that are fired.
+     *
+     * `RETURNING *` (rather than enumerating the compiled column list) keeps
+     * writes working under schema/image skew: during a rolling deploy, a
+     * container built before a drop-column migration would otherwise name the
+     * dropped column in `RETURNING` and fail with `42703 column does not
+     * exist` on every write, even writes that never touch that column. The
+     * `SET`/`VALUES` half still names only dirty attributes, so a write that
+     * actually sets a dropped column still fails loudly. The returned row is
+     * filtered to the compiled column list before hydration (see
+     * internal/saveDream.ts), so a column the image doesn't know about never
+     * reaches `setAttributes`.
+     *
+     * KNOWN CONSTRAINT: star-selects are only safe because nothing in this
+     * stack uses named prepared statements — node-postgres prepares a
+     * statement only when given an explicit `name`, and Kysely never names
+     * them, so every query is re-planned. With named prepared statements, a
+     * concurrent `ADD COLUMN` changes a cached plan's result shape and
+     * Postgres raises `cached plan must not change result type` (the reason
+     * Rails added `enumerate_columns_in_select_statements`). If a future
+     * driver or pooling layer enables named prepared statements, revisit
+     * every `RETURNING *` / `select *` in this driver.
      */
     static async saveDream(dream, txn = null) {
         const connectionName = dream.connectionName || 'default';
@@ -745,13 +766,13 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     .updateTable(dream.table)
                     .set(sqlifiedAttributes)
                     .where(namespaceColumn(dream['_primaryKey'], dream.table), '=', dream.primaryKeyValue());
-                return await executeDatabaseQuery(query.returning([...dream.columns()]), 'executeTakeFirstOrThrow');
+                return await executeDatabaseQuery(query.returningAll(), 'executeTakeFirstOrThrow');
             }
             else {
                 const query = db
                     .insertInto(dream.table)
                     .values(sqlifiedAttributes)
-                    .returning([...dream.columns()]);
+                    .returningAll();
                 return await executeDatabaseQuery(query, 'executeTakeFirstOrThrow');
             }
         }
@@ -2401,15 +2422,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             const preloadedPolymorphicBelongsTos = await this.preloadPolymorphicBelongsTo(association, dreamClassToHydrate, dreams);
             return preloadedPolymorphicBelongsTos;
         }
-        const dreamClassToHydrateColumns = [...dreamClassToHydrate.columns()];
-        const columnsToPluck = dreamClassToHydrateColumns.map(column => this.namespaceColumn(column.toString(), alias));
-        columnsToPluck.push(this.namespaceColumn(dreamClass.primaryKey, dreamClass.table));
+        const dreamClassToHydrateColumns = dreamClassToHydrate.columns();
+        // The base-model primary key rides along under a short alias so each
+        // associated row can be matched back to the dream it belongs to. The
+        // alias is lowercase without underscores so Kysely's CamelCasePlugin
+        // passes it through untouched (the same strategy as `pluck0` /
+        // `groupvalue`), and is extended until it cannot collide with a real
+        // column of the associated table. That collision loop can only consult
+        // the compiled column set, so under add-column skew a live column
+        // literally named like the alias would produce two identically-named
+        // result fields. The aliased base PK is deliberately selected last,
+        // and node-postgres resolves duplicate field names last-wins, so the
+        // base PK still wins even in that pathological case — and the
+        // hydration filter strips the colliding key from the instance's
+        // attributes.
+        let basePrimaryKeyAlias = 'preloadbasepk';
+        while (dreamClassToHydrateColumns.has(basePrimaryKeyAlias))
+            basePrimaryKeyAlias += '0';
         const baseClass = dreamClass['stiBaseClassOrOwnClass']['getAssociationMetadata'](associationName)
             ? dreamClass['stiBaseClassOrOwnClass']
             : dreamClass;
         const associationDataScope = this.dreamClassQueryWithScopeBypasses(baseClass, {
             // In order to stay DRY, preloading leverages the association logic built into
-            // `joins` (by using `pluck`, which calls `joins`). However, baseClass may have
+            // `joins`. However, baseClass may have
             // default scopes that would preclude finding that instance. We remove all
             // default scopes on baseClass, but not subsequent associations, so that the
             // single query will be able to find each row corresponding to a Dream in `dreams`,
@@ -2418,16 +2453,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         }).where({
             [dreamClass.primaryKey]: dreams.map(obj => obj.primaryKeyValue()),
         });
-        const hydrationData = await associationDataScope['_connection'](this.connectionOverride)
-            .innerJoin(associationName, (onStatement || {}))
-            .pluck(...columnsToPluck);
-        const preloadedDreamsAndWhatTheyPointTo = hydrationData.map(pluckedData => {
-            const attributes = {};
-            dreamClassToHydrateColumns.forEach((columnName, index) => (attributes[protectAgainstPollutingAssignment(columnName)] = pluckedData[index]));
-            const hydratedDream = this.dbResultToDreamInstance(attributes, dreamClassToHydrate);
+        const joinedQuery = associationDataScope['_connection'](this.connectionOverride).innerJoin(associationName, (onStatement || {}));
+        // Select the association's row wholesale (`"alias".*`) rather than
+        // enumerating the compiled column list. Enumerating made every preload
+        // assert the compiled schema against the live database: under
+        // schema/image skew (rolling deploy or rollback around a drop-column
+        // migration), naming a dropped column fails the whole preload with
+        // `42703 column does not exist`. The raw row is passed straight to
+        // hydration, where sqlResultToDreamInstance — the single filtering
+        // point — intersects it with the compiled column list (also stripping
+        // the base-PK alias key), so a column the image doesn't know about
+        // (the add-column direction of skew) never reaches the instance. See
+        // the prepared-statements note on `saveDream` before changing this
+        // back to an enumerated select.
+        const kyselyQuery = new this.constructor(joinedQuery)
+            .buildSelect({ bypassSelectAll: true })
+            .selectAll(alias)
+            .select(`${this.namespaceColumn(dreamClass.primaryKey, dreamClass.table)} as ${basePrimaryKeyAlias}`);
+        const rows = await executeDatabaseQuery(kyselyQuery, 'execute');
+        const preloadedDreamsAndWhatTheyPointTo = rows.map((row) => {
+            const hydratedDream = this.dbResultToDreamInstance(row, dreamClassToHydrate);
             return {
                 dream: hydratedDream,
-                pointsToPrimaryKey: pluckedData.at(-1),
+                pointsToPrimaryKey: row[basePrimaryKeyAlias],
             };
         });
         this.hydrateAssociation(dreams, association, preloadedDreamsAndWhatTheyPointTo);

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/NoColumnsToAlterMigration.js

@@ -0,0 +1,17 @@
+export default class NoColumnsToAlterMigration extends Error {
+    table;
+    alterDirection;
+    constructor(table, alterDirection) {
+        super();
+        this.table = table;
+        this.alterDirection = alterDirection;
+    }
+    get message() {
+        return `
+no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+
+Pass at least one column declaration with a resolvable type, e.g.:
+  name:string
+    `;
+    }
+}

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

@@ -0,0 +1,16 @@
+export default class UnparseableMigrationColumn extends Error {
+    declaration;
+    constructor(declaration) {
+        super();
+        this.declaration = declaration;
+    }
+    get message() {
+        return `
+could not determine a column type for the following migration column declaration:
+  ${this.declaration}
+
+Make sure the column includes a type, e.g.:
+  ${this.declaration.split(':')[0]}:string
+    `;
+    }
+}

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.
+`;
+    }
+}