@rvoh/dream 2.41.0 → 2.42.0

package/dist/esm/src/Dream.js

@@ -1,5 +1,5 @@
 import yoctocolors from 'yoctocolors';
-import { pgErrorType, UNIQUE_VIOLATION } from './db/errors.js';
+import { STI_SCOPE_NAME } from './decorators/class/STI.js';
 import associationToGetterSetterProp from './decorators/field/association/associationToGetterSetterProp.js';
 import { blankAssociationsFactory } from './decorators/field/association/shared.js';
 import { blankHooksFactory } from './decorators/field/lifecycle/shared.js';
@@ -49,6 +49,7 @@ import DreamMissingRequiredOverride from './errors/DreamMissingRequiredOverride.
 import NonExistentScopeProvidedToResort from './errors/NonExistentScopeProvidedToResort.js';
 import RecordNotFound from './errors/RecordNotFound.js';
 import areEqual from './helpers/areEqual.js';
+import camelize from './helpers/camelize.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
@@ -1267,6 +1268,18 @@ export default class Dream {
      * IMPORTANT: A unique index/uniqueness constraint must exist on
      * at least one of the provided attributes
      *
+     * The lookup applies the model's default scopes, so a conflicting
+     * record they hide (for example, a soft-deleted one under a plain
+     * unique index) is never returned. When the lookup finds nothing,
+     * `CreateOrFindByFailedToCreateAndFind` is thrown. When the database
+     * identifies the violated unique index (Postgres does, unless it is an
+     * expression or partial index), its message names the `createWith`
+     * attributes that index covers as the likely cause, unless the index
+     * also covers every find attribute. When the index covers only find
+     * attributes, or every find attribute, and the record is found with the
+     * model's default scopes removed, the message names the default scope
+     * likely hiding it. Otherwise it lists the possible causes.
+     *
      * ```ts
      * const logEntry = await LogEntry.createOrFindBy({ externalId }, { createWith: params })
      * ```
@@ -1288,10 +1301,12 @@ export default class Dream {
             return dreamModel;
         }
         catch (err) {
-            if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const dreamModel = await this.findBy(findOrCreateLookupStatement(this, attributes));
+            if (Query.dbDriverClass(this.prototype.connectionName).isUniqueConstraintViolation(err)) {
+                const lookup = findOrCreateLookupStatement(this, attributes);
+                // where().first() rather than findBy: a value the database rejects is raised, never read as no match
+                const dreamModel = await this.where(lookup).first();
                 if (!dreamModel)
-                    throw new CreateOrFindByFailedToCreateAndFind(this);
+                    throw new CreateOrFindByFailedToCreateAndFind(this, await this.createOrFindFailureCause(err, lookup, extraOpts.createWith));
                 return dreamModel;
             }
             throw err;
@@ -1327,6 +1342,18 @@ export default class Dream {
      * IMPORTANT: A unique index/uniqueness constraint must exist on
      * at least one of the provided attributes
      *
+     * The lookup applies the model's default scopes, so a conflicting
+     * record they hide (for example, a soft-deleted one under a plain
+     * unique index) is never updated. When the lookup finds nothing,
+     * `CreateOrUpdateByFailedToCreateAndUpdate` is thrown. When the database
+     * identifies the violated unique index (Postgres does, unless it is an
+     * expression or partial index), its message names the `with`
+     * attributes that index covers as the likely cause, unless the index
+     * also covers every find attribute. When the index covers only find
+     * attributes, or every find attribute, and the record is found with the
+     * model's default scopes removed, the message names the default scope
+     * likely hiding it. Otherwise it lists the possible causes.
+     *
      * @param attributes - The base attributes for finding which record to update, also used when creating
      * @param extraOpts - Additional options
      * @param extraOpts.with - additional attributes to persist when updating and creating, but not used for finding
@@ -1342,10 +1369,12 @@ export default class Dream {
             }, skipHooks ? { skipHooks } : undefined);
         }
         catch (err) {
-            if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const existingRecord = await this.findBy(findOrCreateLookupStatement(this, attributes));
+            if (Query.dbDriverClass(this.prototype.connectionName).isUniqueConstraintViolation(err)) {
+                const lookup = findOrCreateLookupStatement(this, attributes);
+                // where().first() rather than findBy: a value the database rejects is raised, never read as no match
+                const existingRecord = await this.where(lookup).first();
                 if (!existingRecord)
-                    throw new CreateOrUpdateByFailedToCreateAndUpdate(this);
+                    throw new CreateOrUpdateByFailedToCreateAndUpdate(this, await this.createOrFindFailureCause(err, lookup, extraOpts.with));
                 const { with: attrs } = extraOpts;
                 if (existingRecord) {
                     existingRecord.assignAttributes(attrs ?? {});
@@ -1355,6 +1384,64 @@ export default class Dream {
             throw err;
         }
     }
+    /**
+     * @internal
+     *
+     * Used by createOrFindBy and createOrUpdateBy after their default-scoped
+     * lookup finds nothing, to tell why. The driver names the columns of the
+     * unique index the insert violated, when it can. When that index covers a
+     * `createWith`/`with` attribute but not every find attribute, one of those
+     * values likely conflicted with another record. When it covers only find
+     * attributes, or every find attribute, a record matching them that the
+     * default scopes hide is the record the insert conflicted with. Otherwise
+     * the cause is undetermined, and a hidden record matching the find
+     * attributes is only a candidate.
+     */
+    static async createOrFindFailureCause(error, lookup, extraAttributes) {
+        const connectionName = this.prototype.connectionName;
+        const indexColumns = await Query.dbDriverClass(connectionName).violatedUniqueIndexColumns(connectionName, error, this.table);
+        const indexAttributes = indexColumns?.map(column => camelize(column)) ?? null;
+        const extraAttributeNames = Object.keys(extraAttributes ? this.extractAttributesFromUpdateableProperties(extraAttributes) : {});
+        // the conflicting record holds the inserted value in every column of the index, so when the
+        // index covers every find attribute, that record matches them and is not a different record
+        const indexCoversEveryFindAttribute = !!indexAttributes && Object.keys(lookup).every(attribute => indexAttributes.includes(attribute));
+        if (!indexCoversEveryFindAttribute) {
+            const conflictingAttributes = (indexAttributes ?? []).filter(attribute => extraAttributeNames.includes(attribute));
+            if (conflictingAttributes.length)
+                return { kind: 'conflictingAttributes', attributes: conflictingAttributes };
+        }
+        const hidingDefaultScopes = await this.defaultScopesHidingLookup(lookup);
+        const indexCoversOnlyFindAttributes = !!indexAttributes?.every(attribute => attribute in lookup);
+        if (hidingDefaultScopes.length && (indexCoversOnlyFindAttributes || indexCoversEveryFindAttribute))
+            return { kind: 'hiddenByDefaultScope', defaultScopes: hidingDefaultScopes };
+        return {
+            kind: 'undetermined',
+            hidingDefaultScopes,
+            extraAttributesMayConflict: indexAttributes === null && extraAttributeNames.length > 0,
+        };
+    }
+    /**
+     * @internal
+     *
+     * Used by createOrFindFailureCause. Returns the model's removable default scopes when a
+     * record matching `lookup` exists once they are all removed, and an empty
+     * array otherwise. The STI type discriminator is never removed. One probe
+     * with every removable scope removed cannot tell which of several scopes
+     * hid the record, so all of them are returned as candidates.
+     */
+    static async defaultScopesHidingLookup(lookup) {
+        const removableDefaultScopes = this['scopes'].default
+            .map(scope => scope.method)
+            .filter(scopeName => scopeName !== STI_SCOPE_NAME);
+        if (!removableDefaultScopes.length)
+            return [];
+        let query = this.query();
+        for (const scopeName of removableDefaultScopes) {
+            query = query.removeDefaultScope(scopeName);
+        }
+        // where() rather than findBy: a value the database rejects is raised, never read as no match
+        return (await query.where(lookup).exists()) ? removableDefaultScopes : [];
+    }
     /**
      * Returns a new query instance with the distinct query applied.
      * If no columnName is provided, then distinct will apply to the
@@ -1372,12 +1459,25 @@ export default class Dream {
     }
     /**
      * Finds a record for the corresponding model with the
-     * specified primary key. Returns null if not found.
+     * specified primary key. Returns null if not found,
+     * including when the primary key is a value its column
+     * cannot hold (for example, `'abc'` for an integer
+     * primary key).
+     *
+     * When the database rejects a value elsewhere in the query (for
+     * example, in a `whereNot`, `whereAny` or `leftJoinPreload`
+     * clause), that rejection is raised as `DataTypeColumnTypeMismatch`
+     * or `ColumnOverflow`, since a record may still match. Inside a
+     * transaction, a primary key the database rejects is raised that
+     * way too, because the database has then aborted the transaction.
      *
      * ```ts
      * await User.find(123)
      * // User{id: 123}
      *
+     * await User.find('abc')
+     * // null
+     *
      * await User.find(null)
      * // null
      *
@@ -1393,15 +1493,26 @@ export default class Dream {
     }
     /**
      * Finds a record for the corresponding model with the
-     * specified primary key. If not found, an exception is raised.
+     * specified primary key. If not found, `RecordNotFound` is
+     * raised, including when the primary key is a value its
+     * column cannot hold (for example, `'abc'` for an integer
+     * primary key).
+     *
+     * When the database rejects a value elsewhere in the query (for
+     * example, in a `whereNot`, `whereAny` or `leftJoinPreload`
+     * clause), that rejection is raised as `DataTypeColumnTypeMismatch`
+     * or `ColumnOverflow`, since a record may still match. Inside a
+     * transaction, a primary key the database rejects is raised that
+     * way too, because the database has then aborted the transaction.
      *
      * ```ts
-     * await User.query().findOrFail(123)
+     * await User.findOrFail(123)
      * // User{id: 123}
      * ```
      *
      * @param primaryKey - The primaryKey of the record to look up
-     * @returns Either the found record, or else null
+     * @returns The found record
+     * @throws RecordNotFound if no record is found
      */
     static async findOrFail(primaryKey) {
         return await this.query().findOrFail(primaryKey);
@@ -1541,7 +1652,22 @@ export default class Dream {
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
-     * If not found, null is returned.
+     * If not found, null is returned, including when a value the where
+     * statement compares for equality (a plain value or
+     * `ops.equal`) is one its column cannot hold: for example,
+     * `'abc'` for a uuid column, or a date string Dream cannot
+     * parse for a date column.
+     *
+     * A value the database rejects anywhere else (in a list of values,
+     * under another operator such as `ops.not.equal` or `ops.lessThan`,
+     * or elsewhere in the query, such as a `whereNot` or `whereAny`
+     * clause) is raised as `DataTypeColumnTypeMismatch` or
+     * `ColumnOverflow`, since a record may still match; so is a date,
+     * datetime or time string there that Dream cannot parse. Inside a
+     * transaction, an equality value the database rejects is raised that
+     * way too, because the database has then aborted the transaction; a
+     * date, datetime or time string Dream cannot parse never reaches the
+     * database, so it is treated as not found there as well.
      *
      * ```ts
      * await User.findBy({ email: 'how@yadoin' })
@@ -1557,7 +1683,22 @@ export default class Dream {
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
-     * If not found, an exception is raised.
+     * If not found, `RecordNotFound` is raised, including when
+     * a value the where statement compares for equality (a plain
+     * value or `ops.equal`) is one its column cannot hold: for
+     * example, `'abc'` for a uuid column, or a date string Dream
+     * cannot parse for a date column.
+     *
+     * A value the database rejects anywhere else (in a list of values,
+     * under another operator such as `ops.not.equal` or `ops.lessThan`,
+     * or elsewhere in the query, such as a `whereNot` or `whereAny`
+     * clause) is raised as `DataTypeColumnTypeMismatch` or
+     * `ColumnOverflow`, since a record may still match; so is a date,
+     * datetime or time string there that Dream cannot parse. Inside a
+     * transaction, an equality value the database rejects is raised that
+     * way too, because the database has then aborted the transaction; a
+     * date, datetime or time string Dream cannot parse never reaches the
+     * database, so it is treated as not found there as well.
      *
      * ```ts
      * await User.findOrFailBy({ email: 'how@yadoin' })
@@ -1566,6 +1707,7 @@ export default class Dream {
      *
      * @param whereStatement - The where statement used to locate the record
      * @returns The first model found matching the whereStatement
+     * @throws RecordNotFound if no record is found
      */
     static async findOrFailBy(whereStatement) {
         return await this.query().findOrFailBy(whereStatement);

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

@@ -252,6 +252,10 @@ ${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.`)
+            .option('--overwrite', 'replace the model, spec, factory and serializer files when they already exist. Without it or --skip-existing, the generator writes nothing and lists the existing files when any of them, or the migration it would write, already exists. An existing migration is kept even with --overwrite, never rewritten or duplicated, since it may already have run; edit it by hand if the columns changed', false)
+            .addOption(new Option('--skip-existing', 'keep the model, spec, factory, serializer and migration files that already exist, write only the missing ones, and list each file kept. No migration is written when the model file already exists, even if no migration has the name the generator would use, since the model may already have one under another name. Cannot be combined with --overwrite')
+            .default(false)
+            .conflicts('overwrite'))
             .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:
@@ -261,7 +265,11 @@ ${INDENT}  Settings/CommunicationPreferences   # src/app/models/Settings/Communi
             .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (modelName, columnsWithTypes, options) => {
             await initializeDreamApp({ bypassDreamIntegrityChecks: true, bypassDbConnectionsDuringInit: true });
-            await DreamBin.generateDream(modelName, columnsWithTypes, options);
+            const { overwrite, skipExisting, ...generatorOptions } = options;
+            await DreamBin.generateDream(modelName, columnsWithTypes, {
+                ...generatorOptions,
+                existingFiles: existingFilesMode({ overwrite, skipExisting }),
+            });
             process.exit();
         });
         program
@@ -290,6 +298,10 @@ ${INDENT}  pnpm psy g:sti-child --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('--overwrite', 'replace the model, spec, factory and serializer files when they already exist. Without it or --skip-existing, the generator writes nothing and lists the existing files when any of them, or the migration it would write, already exists. An existing migration is kept even with --overwrite, never rewritten or duplicated, since it may already have run; edit it by hand if the columns changed', false)
+            .addOption(new Option('--skip-existing', 'keep the model, spec, factory, serializer and migration files that already exist, write only the missing ones, and list each file kept. No migration is written when the model file already exists, even if no migration has the name the generator would use, since the model may already have one under another name. Cannot be combined with --overwrite')
+            .default(false)
+            .conflicts('overwrite'))
             .argument('<childModelName>', `The namespaced child model path. By convention, children are nested under the parent name.
 ${INDENT}
 ${INDENT}Examples:
@@ -307,7 +319,11 @@ ${INDENT}  Health/Coach        # extends src/app/models/Health/Coach.ts`)
             await initializeDreamApp({ bypassDreamIntegrityChecks: true, bypassDbConnectionsDuringInit: true });
             if (extendsWord !== 'extends')
                 throw new Error('Expecting: `<child-name> extends <parent-name> <columns-and-types>');
-            await DreamBin.generateStiChild(childModelName, parentModelName, columnsWithTypes, options);
+            const { overwrite, skipExisting, ...generatorOptions } = options;
+            await DreamBin.generateStiChild(childModelName, parentModelName, columnsWithTypes, {
+                ...generatorOptions,
+                existingFiles: existingFilesMode({ overwrite, skipExisting }),
+            });
             process.exit();
         });
         program
@@ -364,7 +380,12 @@ ${INDENT}  pnpm psy db:migrate`)
                 await syncWithFailureContext({
                     commandName: 'db:migrate',
                     completedWork: 'Every pending migration ran successfully',
-                    recoveryAdvice: 'run `sync` on its own, or re-run `db:migrate` — the migrations it already applied are not re-applied, so it goes straight back to the sync',
+                    // never `sync` on its own here: the failed sync reverted the
+                    // generated types to their pre-migration content, and a Psychic
+                    // app's `psy sync` boots with the integrity checks on, so it
+                    // fails against them as soon as a model or serializer uses what
+                    // the migration added. db:migrate boots with them bypassed
+                    recoveryAdvice: 're-run `db:migrate` — the migrations it already applied are not re-applied, so it goes straight back to the sync',
                 }, async () => await DreamBin.sync(onSync));
             }
             process.exit();
@@ -444,8 +465,10 @@ ${INDENT}Warning: all existing data will be lost. The seed file (db/seed.ts) wil
                 // hook directly (below), while the `db:seed` *command* refuses to
                 // seed under NODE_ENV=test unless DREAM_SEED_DB_IN_TEST=1 — and
                 // NODE_ENV=test is the only environment DreamBin.sync does any
-                // work in, so it is the only environment this advice is printed in
-                recoveryAdvice: 're-run `db:reset`, which seeds directly and so picks up the skipped seeding step, or run `sync` on its own followed by `DREAM_SEED_DB_IN_TEST=1 db:seed` — this sync only runs under `NODE_ENV=test`, and a bare `db:seed` does not seed there',
+                // work in, so it is the only environment this advice is printed in.
+                // The second route re-runs db:migrate rather than `sync` for the
+                // reason given at db:migrate's own recovery advice
+                recoveryAdvice: 're-run `db:reset`, which seeds directly and so picks up the skipped seeding step, or re-run `db:migrate` followed by `DREAM_SEED_DB_IN_TEST=1 db:seed` — this sync only runs under `NODE_ENV=test`, and a bare `db:seed` does not seed there',
             }, async () => await DreamBin.sync(onSync));
             DreamCLI.logger.log(arrows, { logPrefix: ' ' });
             DreamCLI.logger.log(colorize('db:seed', { color: 'green' }), {
@@ -577,6 +600,17 @@ ${INDENT}Examples: User, Place, Room/Bedroom, Settings/CommunicationPreferences`
     }
     static _logger = undefined;
 }
+/**
+ * commander rejects --overwrite together with --skip-existing before an
+ * action runs, so at most one of them is set here.
+ */
+function existingFilesMode({ overwrite, skipExisting, }) {
+    if (overwrite)
+        return 'overwrite';
+    if (skipExisting)
+        return 'skip';
+    return 'refuse';
+}
 function myParseInt(value) {
     const parsedValue = parseInt(value, 10);
     if (isNaN(parsedValue)) {

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

@@ -11,6 +11,24 @@ import DreamApp from '../dream-app/index.js';
 import { claimedTestDatabaseIndexOrNull } from './testDatabasePool.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
+/**
+ * @internal
+ *
+ * the CamelCasePlugin every Dream connection carries: it turns each
+ * attribute name a query names into the column name it queries, and each
+ * column name a result row carries into a camelized key
+ */
+export class DreamCamelCasePlugin extends CamelCasePlugin {
+    constructor() {
+        super({ underscoreBetweenUppercaseLetters: true });
+    }
+    /**
+     * the column name a query naming the given attribute targets
+     */
+    columnNameForAttribute(attributeName) {
+        return this.snakeCase(attributeName);
+    }
+}
 let connections = {};
 export default class DreamDbConnection {
     static getConnection(connectionName, connectionType, dialectProvider) {
@@ -32,7 +50,7 @@ export default class DreamDbConnection {
                 });
             },
             dialect: dialectProvider(connectionConf),
-            plugins: [new CamelCasePlugin({ underscoreBetweenUppercaseLetters: true })],
+            plugins: [new DreamCamelCasePlugin()],
         });
         const protectedName = protectAgainstPollutingAssignment(connectionName);
         connections[protectedName] ||= {};

package/dist/esm/src/dream/DreamClassTransactionBuilder.js

@@ -294,6 +294,12 @@ export default class DreamClassTransactionBuilder {
      * Finds a record for the corresponding model with the
      * specified primary key. If not found, null is returned.
      *
+     * A value the database rejects as one its column cannot hold,
+     * whether the primary key (for example, `'abc'` for an integer
+     * primary key) or a value elsewhere in the query, raises
+     * `DataTypeColumnTypeMismatch` or `ColumnOverflow`, because the
+     * database has then aborted the transaction.
+     *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
      *   await User.txn(txn).find(123)
@@ -317,6 +323,12 @@ export default class DreamClassTransactionBuilder {
      * Finds a record for the corresponding model with the
      * specified primary key. If not found, an exception is raised.
      *
+     * A value the database rejects as one its column cannot hold,
+     * whether the primary key (for example, `'abc'` for an integer
+     * primary key) or a value elsewhere in the query, raises
+     * `DataTypeColumnTypeMismatch` or `ColumnOverflow`, because the
+     * database has then aborted the transaction.
+     *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
      *   await User.txn(txn).findOrFail(123)
@@ -333,7 +345,17 @@ export default class DreamClassTransactionBuilder {
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
-     * If not found, null is returned.
+     * If not found, null is returned, including when a value the where
+     * statement compares for equality (a plain value or `ops.equal`)
+     * is a date, datetime or time string Dream cannot parse for its
+     * column, which never reaches the database.
+     *
+     * A value the database rejects as one its column cannot hold
+     * (for example, `'abc'` for a uuid column) raises
+     * `DataTypeColumnTypeMismatch` or `ColumnOverflow`, because the
+     * database has then aborted the transaction. A date, datetime or
+     * time string Dream cannot parse anywhere else in the query raises
+     * `DataTypeColumnTypeMismatch`.
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
@@ -351,7 +373,17 @@ export default class DreamClassTransactionBuilder {
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
-     * If not found, an exception is raised.
+     * If not found, `RecordNotFound` is raised, including when a
+     * value the where statement compares for equality (a plain value
+     * or `ops.equal`) is a date, datetime or time string Dream cannot
+     * parse for its column, which never reaches the database.
+     *
+     * A value the database rejects as one its column cannot hold
+     * (for example, `'abc'` for a uuid column) raises
+     * `DataTypeColumnTypeMismatch` or `ColumnOverflow`, because the
+     * database has then aborted the transaction. A date, datetime or
+     * time string Dream cannot parse anywhere else in the query raises
+     * `DataTypeColumnTypeMismatch`.
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {