@rvoh/dream 2.41.0 → 2.42.0

package/dist/types/src/Dream.d.ts

@@ -938,6 +938,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 })
      * ```
@@ -977,6 +989,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
@@ -984,6 +1008,30 @@ export default class Dream {
      * @returns A dream instance
      */
     static createOrUpdateBy<T extends typeof Dream>(this: T, attributes: FindablePropertiesForClass<T>, extraOpts?: UpdateOrCreateByExtraOpts<T>): Promise<InstanceType<T>>;
+    /**
+     * @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.
+     */
+    private static createOrFindFailureCause;
+    /**
+     * @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.
+     */
+    private static defaultScopesHidingLookup;
     /**
      * Returns a new query instance with the distinct query applied.
      * If no columnName is provided, then distinct will apply to the
@@ -1008,12 +1056,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
      *
@@ -1027,15 +1088,26 @@ export default class Dream {
     static find<T extends typeof Dream, I extends InstanceType<T>>(this: T, primaryKey: PrimaryKeyForFind<I>): Promise<InstanceType<T> | null>;
     /**
      * 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 findOrFail<T extends typeof Dream, I extends InstanceType<T>>(this: T, primaryKey: PrimaryKeyForFind<I>): Promise<InstanceType<T>>;
     /**
@@ -1139,7 +1211,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' })
@@ -1153,7 +1240,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' })
@@ -1162,6 +1264,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 findOrFailBy<T extends typeof Dream, I extends InstanceType<T>>(this: T, whereStatement: WhereStatement<I>): Promise<InstanceType<T>>;
     /**

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

@@ -1,3 +1,4 @@
+import { type GenerateDreamExistingFiles } from '../helpers/cli/generateDream.js';
 export default class DreamBin {
     static sync(onSync: () => Promise<void> | void, options?: {
         schemaOnly?: boolean;
@@ -18,6 +19,11 @@ export default class DreamBin {
         internalSerializers?: boolean;
         modelName?: string;
         softDelete?: boolean;
+        /**
+         * What to do when a file the generator would write already exists.
+         * Defaults to `'refuse'`. See {@link GenerateDreamExistingFiles}.
+         */
+        existingFiles?: GenerateDreamExistingFiles;
     }): Promise<void>;
     static generateStiChild(fullyQualifiedModelName: string, fullyQualifiedParentName: string, columnsWithTypes: string[], options: {
         serializer: boolean;
@@ -31,6 +37,11 @@ export default class DreamBin {
         adminSerializers?: boolean;
         internalSerializers?: boolean;
         modelName?: string;
+        /**
+         * What to do when a file the generator would write already exists.
+         * Defaults to `'refuse'`. See {@link GenerateDreamExistingFiles}.
+         */
+        existingFiles?: GenerateDreamExistingFiles;
     }): Promise<void>;
     static generateMigration(migrationName: string, columnsWithTypes: string[], connectionName: string): Promise<void>;
     private static buildDocs;

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

@@ -79,6 +79,33 @@ export default class DreamCLI {
              * point — the CLI layer opts users in by default.
              */
             softDelete?: boolean;
+            /**
+             * What to do when a file the generator would write already exists:
+             * - `'refuse'` (the default): write nothing and throw an error listing
+             *   the existing files
+             * - `'overwrite'`: replace the model, spec, factory and serializer files
+             * - `'skip'`: keep every existing file, write only the missing ones, and
+             *   log each file kept
+             *
+             * An existing migration with the name the generator would give the
+             * model's migration is kept under `'overwrite'` and `'skip'`, never
+             * rewritten or duplicated. Under `'skip'`, no migration is written when
+             * the model file already exists, even if no migration has that name,
+             * since the model's schema may come from a migration with another name.
+             */
+            existingFiles?: 'refuse' | 'overwrite' | 'skip';
+            /**
+             * The caller's own flags for `existingFiles: 'overwrite'` and
+             * `existingFiles: 'skip'`, named in the refusal in place of Dream's
+             * `--overwrite` and `--skip-existing`. With them, the refusal names
+             * these two flags and no Dream command. For example, a caller whose
+             * flags are `--overwrite` and `--overwrite-psychic-only` passes
+             * `{ overwrite: '--overwrite', skip: '--overwrite-psychic-only' }`.
+             */
+            existingFilesFlags?: {
+                overwrite: string;
+                skip: string;
+            };
         };
         fullyQualifiedParentName?: string | undefined;
     }): Promise<void>;

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

@@ -1,6 +1,20 @@
-import { Kysely } from 'kysely';
+import { CamelCasePlugin, Kysely } from 'kysely';
 import { DreamDbConfig } from '../dream-app/index.js';
 import { DbConnectionType } from '../types/db.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 declare class DreamCamelCasePlugin extends CamelCasePlugin {
+    constructor();
+    /**
+     * the column name a query naming the given attribute targets
+     */
+    columnNameForAttribute(attributeName: string): string;
+}
 export default class DreamDbConnection {
     static getConnection<DB>(connectionName: string, connectionType: DbConnectionType, dialectProvider: DialectProviderCb): Kysely<DB>;
     private static getConnectionTypeName;

package/dist/types/src/dream/DreamClassTransactionBuilder.d.ts

@@ -269,6 +269,12 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * 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)
@@ -290,6 +296,12 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * 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)
@@ -304,7 +316,17 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
     /**
      * 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 => {
@@ -320,7 +342,17 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
     /**
      * 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 => {

package/dist/types/src/dream/Query.d.ts

@@ -237,12 +237,25 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     clone<Q extends Query<DreamInstance, QueryTypeOpts>>(this: Q, opts?: QueryOpts<DreamInstance, any>): Q;
     /**
      * Finds a record matching the Query 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.query().find(123)
      * // User{id: 123}
      *
+     * await User.query().find('abc')
+     * // null
+     *
      * await User.query().find(null)
      * // null
      *
@@ -256,8 +269,17 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     find(primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance | null>;
     /**
      * Finds a record matching the Query 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)
@@ -266,12 +288,28 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *
      * @param primaryKey - The primary key of the record to look up
      * @returns The found record
+     * @throws RecordNotFound if no record is found
      */
     findOrFail(primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance>;
     /**
      * Finds a record matching the Query and the
      * specified where statement. If not found, null
-     * is returned.
+     * 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.query().findBy({ email: 'how@yadoin' })
@@ -284,8 +322,23 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     findBy(whereStatement: WhereStatement<DreamInstance>): Promise<DreamInstance | null>;
     /**
      * Finds a record matching the Query and the
-     * specified where statement. If not found, an exception
-     * is raised.
+     * specified where statement. 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.query().findOrFailBy({ email: 'how@yadoin' })
@@ -294,8 +347,50 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *
      * @param whereStatement - The where statement used to locate the record
      * @returns The first record found matching the attributes
+     * @throws RecordNotFound if no record is found
      */
     findOrFailBy(whereStatement: WhereStatement<DreamInstance>): Promise<DreamInstance>;
+    /**
+     * @internal
+     *
+     * The first record of this Query, for `find` and `findBy`, whose `lookup`
+     * (the primary key or where statement they were given) is already applied.
+     * Returns null when the lookup's own values tell that no record can match
+     * (see `lookupValueCannotBeHeld`); every other error is raised. Preloads
+     * run after the lookup's statement, so a rejected value in a preload clause
+     * is raised.
+     */
+    private firstForLookup;
+    /**
+     * @internal
+     *
+     * Whether `error`, raised by a `find` or `findBy` statement, is a value of
+     * the lookup's own equality comparisons (see `lookupEqualityValues`) that
+     * its column cannot hold. Every matching record must equal each of those
+     * values, so when one cannot be held, no record can match. A rejected value
+     * anywhere else (a negated or OR'd clause, a join's `and` clause, a list of
+     * values, a negated or ordering operator) does not tell that, so it is
+     * raised.
+     *
+     * When Dream itself could not convert a value (a date, datetime or time
+     * string it cannot parse), nothing reached the database, and Dream's
+     * conversion of the lookup's values alone tells whether one of them was
+     * the value. When the database rejected the statement, the driver is asked
+     * whether it rejects one of the lookup's values on its own; inside a
+     * transaction it cannot be asked, since the database has aborted the
+     * transaction, so the error is raised.
+     */
+    private lookupValueCannotBeHeld;
+    /**
+     * @internal
+     *
+     * The values a `find` or `findBy` lookup compares a column of this model
+     * with `=`, as a plain value or `ops.equal`: the primary key for `find`.
+     * Lists of values, other operators, ranges, associations, subqueries and
+     * nulls are left out, since a value there that its column cannot hold does
+     * not stop a record from matching the lookup.
+     */
+    private lookupEqualityValues;
     /**
      * Finds all records matching the Query in batches,
      * and then calls the provided callback for each found record.

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -1,5 +1,6 @@
 import { CompiledQuery, DeleteQueryBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import Dream from '../../Dream.js';
+import DataIncompatibleWithDatabaseField from '../../errors/db/DataIncompatibleWithDatabaseField.js';
 import { AssociationStatement, OrderQueryStatement } from '../../types/associations/shared.js';
 import { DbConnectionType, IntrospectedDatabase, LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 import { DreamColumnNames, DreamConstructorType, DreamTableSchema } from '../../types/dream.js';
@@ -170,6 +171,22 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * is retried.
      */
     static isUniqueConstraintViolation(error: unknown): boolean;
+    /**
+     * @internal
+     *
+     * The columns of the unique index whose violation `error` reports, in index
+     * order, when that index is on `table` and is a plain one: every key is a
+     * column and it has no predicate. `createOrFindBy` and `createOrUpdateBy`
+     * ask this after a failed insert to tell which of their attributes
+     * conflicted. Returns null when the driver cannot tell, when the index is
+     * on another table, or when it is an expression or partial index; the
+     * default returns null.
+     *
+     * @param connectionName - the connection the insert ran on
+     * @param error - the error the insert raised
+     * @param table - the table the insert wrote to
+     */
+    static violatedUniqueIndexColumns(connectionName: string, error: unknown, table: string): Promise<string[] | null>;
     /**
      * @internal
      *
@@ -179,6 +196,38 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * false, and nothing is retried.
      */
     static isDeadlock(error: unknown): boolean;
+    /**
+     * @internal
+     *
+     * The Dream error to raise in place of `error` when `error` is the database
+     * rejecting a value for the column it is written to or compared with: a value
+     * the column's type cannot represent, a null in a NOT NULL column, or a CHECK
+     * constraint violation. Saves and reads (selects, aggregates, plucks and
+     * preloads) raise the returned error; bulk `Query#update` and `Query#delete`
+     * do not consult this. A driver that does not recognize the error returns
+     * null, and the original error propagates unchanged.
+     */
+    static dataIncompatibleWithDatabaseFieldError(error: unknown): DataIncompatibleWithDatabaseField | null;
+    /**
+     * @internal
+     *
+     * Whether the database rejects any of `values` as input for its `dbType`
+     * (the column type in the model's schema), judged by the database's own
+     * input rules. `find` and `findBy` ask this, outside a transaction, after
+     * the database rejected their statement, passing the values their lookup
+     * compares for equality: when one of those is rejected, no record can match
+     * the lookup, which then returns null; otherwise the rejected value was
+     * elsewhere in the Query, and the statement's error is raised. A driver that
+     * cannot tell returns false; the default does.
+     *
+     * @param connectionName - the connection the lookup ran on
+     * @param dbConnectionType - the connection type to ask on
+     * @param values - each value as sent to the database, with its column's type
+     */
+    static rejectsAnyValueForColumnType(connectionName: string, dbConnectionType: DbConnectionType, values: {
+        value: unknown;
+        dbType: string;
+    }[]): Promise<boolean>;
     /**
      * @internal
      *
@@ -405,6 +454,16 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns A Map from each present group value to the average of the aggregated column in that group
      */
     avgBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
+    /**
+     * Returns true if a record matches the Query, false otherwise
+     *
+     * ```ts
+     * await User.where({ email: 'how@yadoin' }).exists()
+     * ```
+     *
+     * @returns true if any records match the Query, false otherwise
+     */
+    exists(): Promise<boolean>;
     /**
      * Retrieves the number of records in the database
      *

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -264,6 +264,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * @returns A Map from each present group value to the average of the aggregated column in that group
      */
     avgBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
+    exists(): Promise<boolean>;
     /**
      * Retrieves the number of records in the database
      *
@@ -367,6 +368,14 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
      * every `RETURNING *` / `select *` in this driver.
      */
     static saveDream(dream: Dream, txn?: DreamTransaction<Dream> | null): Promise<any>;
+    /**
+     * @internal
+     *
+     * Runs a read statement (a select, aggregate, pluck or preload), raising the
+     * driver's Dream error for a value the database rejects in place of the
+     * database's own error (see `dataIncompatibleWithDatabaseFieldError`).
+     */
+    private executeReadQuery;
     dbConnectionType(sqlCommandType: SqlCommandType): DbConnectionType;
     private isReplicaSafe;
     /**

package/dist/types/src/dream/QueryDriver/Postgres.d.ts

@@ -1,6 +1,10 @@
 import { type SelectQueryBuilder } from 'kysely';
+import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
+import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
+import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
+import NotNullViolation from '../../errors/db/NotNullViolation.js';
 import Dream from '../../Dream.js';
-import { IntrospectedDatabase } from '../../types/db.js';
+import { DbConnectionType, IntrospectedDatabase } from '../../types/db.js';
 import DreamTransaction from '../DreamTransaction.js';
 import KyselyQueryDriver from './Kysely.js';
 import type { TestDatabaseLockSession } from './Base.js';
@@ -57,7 +61,31 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
     applyRowLock(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
     static supportsAdvisoryTransactionLocks: boolean;
     static isUniqueConstraintViolation(error: unknown): boolean;
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.violatedUniqueIndexColumns}.
+     * A unique violation names the index it hit in the error's `constraint`
+     * field (a unique constraint's index shares its name), and one catalog query
+     * reads that index's key columns. `INCLUDE` columns are not keys and are
+     * left out.
+     */
+    static violatedUniqueIndexColumns(connectionName: string, error: unknown, table: string): Promise<string[] | null>;
     static isDeadlock(error: unknown): boolean;
+    static dataIncompatibleWithDatabaseFieldError(error: unknown): CheckConstraintViolation | ColumnOverflow | DataTypeColumnTypeMismatch | NotNullViolation | null;
+    /**
+     * @internal
+     *
+     * Postgres implementation of {@link QueryDriverBase.rejectsAnyValueForColumnType}.
+     * One statement casts every value to its type, so Postgres's own input
+     * function for each type is the judge: a cast it rejects raises `22P02` or
+     * `22003`. Callers never ask inside a transaction, which a rejected cast
+     * would abort.
+     */
+    static rejectsAnyValueForColumnType(connectionName: string, dbConnectionType: DbConnectionType, values: {
+        value: unknown;
+        dbType: string;
+    }[]): Promise<boolean>;
     /**
      * @internal
      *

package/dist/types/src/dream/internal/executeDatabaseQuery.d.ts

@@ -1,2 +1,3 @@
-export default function executeDatabaseQuery<Command extends DbQueryCommand, ReturnType extends Command extends 'execute' ? any[] : Command extends 'executeTakeFirst' ? any : Command extends 'executeTakeFirstOrThrow' ? any : never>(kyselyQuery: any, command: Command): Promise<ReturnType>;
+export default function executeDatabaseQuery<Command extends DbQueryCommand, ReturnType extends ExecuteDatabaseQueryReturnType<Command>>(kyselyQuery: any, command: Command): Promise<ReturnType>;
 export type DbQueryCommand = 'execute' | 'executeTakeFirst' | 'executeTakeFirstOrThrow';
+export type ExecuteDatabaseQueryReturnType<Command extends DbQueryCommand> = Command extends 'execute' ? any[] : Command extends 'executeTakeFirst' ? any : Command extends 'executeTakeFirstOrThrow' ? any : never;