uql-orm 0.77.0 → 0.78.0

package/dist/querier/abstractQuerier.js

@@ -1,13 +1,15 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
+import { parseQueryLock } from '../type/index.js';
 import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, hasKeys, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
-import { enrichError, UqlLockUsageError, UqlOptimisticLockError } from './queryError.js';
+import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
+import { enrichError } from './queryError.js';
 /**
  * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
  * which would address every row agreeing on the rest. Callers are `async`, so it always rejects.
  */
 function assertIdValue(entity, id) {
     if (id === undefined || id === null) {
-        throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
+        throw new UqlUsageError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
     }
     if (isScalarId(id)) {
         // One value names one column, which `whereIds` refuses on a composite.
@@ -20,7 +22,7 @@ function assertIdValue(entity, id) {
     const { ids } = getMeta(entity);
     const missing = ids.filter((key) => given[key] == null);
     if (missing.length) {
-        throw new TypeError(`'${entity.name}' is addressed by an object carrying every key of its primary key (${ids.join(', ')}); missing ${missing.join(', ')}.`);
+        throw new UqlUsageError(`'${entity.name}' is addressed by an object carrying every key of its primary key (${ids.join(', ')}); missing ${missing.join(', ')}.`);
     }
 }
 /** The column a write matches a parent's sole key against, on the junction or the child. */
@@ -36,7 +38,7 @@ function assertNamesRows(entity, method, q, opts) {
     if (opts?.unfiltered || hasKeys(q?.$where) || q?.$limit !== undefined) {
         return;
     }
-    throw new TypeError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
+    throw new UqlUsageError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
 }
 /**
  * An optimistic lock as one update applies it: the version the payload carried, the one that replaces
@@ -46,7 +48,7 @@ function assertNamesRows(entity, method, q, opts) {
 function lockVersion(meta, key, q, row) {
     const expected = row[key];
     if (typeof expected !== 'number' && typeof expected !== 'bigint') {
-        throw new UqlLockUsageError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
+        throw new UqlUsageError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
     }
     const next = typeof expected === 'bigint' ? expected + 1n : expected + 1;
     // Spread, as every other added predicate here is: one flat `AND`, and a caller already filtering on
@@ -60,7 +62,7 @@ function lockVersion(meta, key, q, row) {
  */
 function assertUnversioned(meta, what) {
     if (meta.version) {
-        throw new UqlLockUsageError(`cannot ${what} the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
+        throw new UqlUsageError(`cannot ${what} the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
     }
 }
 /**
@@ -73,7 +75,7 @@ function assertLockableUpdate(meta, q, settles) {
     const where = q.$where;
     const namesOneRow = meta.ids.every((key) => where?.[key] !== undefined && isScalarId(where[key]));
     if (!namesOneRow || settles) {
-        throw new UqlLockUsageError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it is named by its ${meta.ids.map((id) => `'${id}'`).join(', ')}, takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
+        throw new UqlUsageError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it is named by its ${meta.ids.map((id) => `'${id}'`).join(', ')}, takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
     }
 }
 /**
@@ -116,15 +118,31 @@ export class AbstractQuerier {
         this.extra = extra;
         this.logger = queryLoggerFor(extra);
     }
-    validateProjectionQuery(entity, q) {
+    /** What every read is checked for before it runs, whichever backend runs it. */
+    validateReadQuery(entity, q) {
+        this.assertLockable(entity, q);
         this.validateProjectionQueryRecursive(entity, q, entityName(getMeta(entity)));
     }
+    /**
+     * Refuses a `$lock` the engine cannot take, then one outside a transaction, where the lock would
+     * drop as the statement commits: only the querier knows whether one is open. Here rather than in
+     * each backend's read, so the rule reaches a find, a stream and a paged count alike.
+     */
+    assertLockable(entity, q) {
+        if (!parseQueryLock(q.$lock)) {
+            return;
+        }
+        this.dialect.assertLockSupported(entity, q);
+        if (!this.hasOpenTransaction) {
+            throw new UqlUsageError('$lock requires an open transaction');
+        }
+    }
     validateProjectionQueryRecursive(entity, q, path) {
         const meta = getMeta(entity);
         if (q.$select && q.$exclude) {
             for (const [key, value] of Object.entries(q.$select)) {
                 if (key in meta.fields && value) {
-                    throw new TypeError(`Cannot combine $select and $exclude when $select includes positive scalar fields (${key}) at ${path}. Use either $select (whitelist) or $exclude (subtractive) in a single query.`);
+                    throw new UqlUsageError(`Cannot combine $select and $exclude when $select includes positive scalar fields (${key}) at ${path}. Use either $select (whitelist) or $exclude (subtractive) in a single query.`);
                 }
             }
         }
@@ -144,7 +162,7 @@ export class AbstractQuerier {
         }
         const q = entityOrQuery;
         if (!q.$entity) {
-            throw new TypeError('$entity is required when using query-object syntax');
+            throw new UqlUsageError('$entity is required when using query-object syntax');
         }
         const { $entity, ...query } = q;
         return [$entity, query, maybeQueryOrOpts];
@@ -160,7 +178,7 @@ export class AbstractQuerier {
     }
     async findMany(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
-        this.validateProjectionQuery(entity, q);
+        this.validateReadQuery(entity, q);
         const founds = await this.internalFindMany(entity, q, opts);
         // Guarded here rather than only inside: awaiting a call that returns at once still costs every read
         // a promise and a turn of the microtask queue, and most reads hook nothing.
@@ -171,12 +189,12 @@ export class AbstractQuerier {
     }
     findManyStream(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
-        this.validateProjectionQuery(entity, q);
+        this.validateReadQuery(entity, q);
         return this.internalFindManyStream(entity, q, opts);
     }
     async findManyAndCount(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
-        this.validateProjectionQuery(entity, q);
+        this.validateReadQuery(entity, q);
         const [founds, count] = await this.internalFindManyAndCount(entity, q, opts);
         if (this.listensForLoad(entity, q.$populate)) {
             await this.emitLoaded(entity, founds, q.$populate);
@@ -309,7 +327,7 @@ export class AbstractQuerier {
     async restoreMany(entity, q) {
         const meta = getMeta(entity);
         if (!meta.softDelete) {
-            throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
+            throw new UqlUsageError(`'${entity.name}' has not enabled 'softDelete'`);
         }
         const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
         // No version: a restore only undoes the stamp a delete left, which takes none either, and two of

package/dist/querier/abstractSqlQuerier.d.ts

@@ -38,11 +38,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     private query;
     /** Runs a statement the dialect builds. */
     private exec;
-    /**
-     * Refuses a `$lock` the engine lacks, then one outside a transaction, where the lock would drop as the
-     * statement commits; only the querier knows whether one is open.
-     */
-    protected assertLockable<E>(entity: Type<E>, q: Query<E>): void;
     /**
      * Runs the `SET`s tuning an ANN index for the query on its connection, refusing where they would apply to
      * nothing: a `SET LOCAL` outside a transaction.

package/dist/querier/abstractSqlQuerier.js

@@ -3,6 +3,7 @@ import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, namesKey } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
 import { buildUpdateResult, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { streamViaCursor } from './cursorStream.js';
 import { enrichError } from './queryError.js';
@@ -117,19 +118,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         build(ctx);
         return this.run(ctx.sql, ctx.values);
     }
-    /**
-     * Refuses a `$lock` the engine lacks, then one outside a transaction, where the lock would drop as the
-     * statement commits; only the querier knows whether one is open.
-     */
-    assertLockable(entity, q) {
-        if (!q.$lock) {
-            return;
-        }
-        this.dialect.assertLockSupported(entity, q);
-        if (!this.hasOpenTransaction) {
-            throw new TypeError('$lock requires an open transaction');
-        }
-    }
     /**
      * Runs the `SET`s tuning an ANN index for the query on its connection, refusing where they would apply to
      * nothing: a `SET LOCAL` outside a transaction.
@@ -143,7 +131,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             return;
         }
         if (this.dialect.features.vectorTuningNeedsTransaction && !this.hasOpenTransaction) {
-            throw new TypeError(`$candidates requires an open transaction on ${this.dialect.dialectName}; run the query inside pool.transaction(...)`);
+            throw new UqlUsageError(`$candidates requires an open transaction on ${this.dialect.dialectName}; run the query inside pool.transaction(...)`);
         }
         for (const statement of statements) {
             await this.internalRun(statement);
@@ -164,7 +152,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
      * so those count apart.
      */
     async internalFindManyAndCount(entity, q, opts) {
-        if (q.$distinct || (q.$lock && !this.dialect.features.rowLockWithWindow)) {
+        const { rowLocks } = this.dialect.features;
+        if (q.$distinct || (q.$lock && !(rowLocks && rowLocks.withWindow))) {
             return Promise.all([this.internalFindMany(entity, q, opts), this.countUnpaged(entity, q, opts)]);
         }
         const rows = await this.selectRows(entity, q, opts, TOTAL_ALIAS);
@@ -175,7 +164,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         return [this.hydrateRows(entity, rows), total];
     }
     async selectRows(entity, q, opts, totalAlias) {
-        this.assertLockable(entity, q);
         // Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
         // path defers a microtask on every read, which reorders the two statements `findManyAndCount`
         // issues concurrently. Keep the guard at any new call site.
@@ -190,7 +178,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         return founds;
     }
     async *internalFindManyStream(entity, q, opts) {
-        this.assertLockable(entity, q);
         // Guarded for the reason `selectRows` above spells out.
         if (q.$candidates !== undefined) {
             await this.applyVectorTuning(entity, q);

package/dist/querier/queryError.d.ts

@@ -1,4 +1,5 @@
 import type { LoggerWrapper } from '../util/logger.js';
+import { type QueryErrorKind } from '../util/uqlError.js';
 /**
  * A driver error tagged by {@link enrichError}: `query` always, `values` only when the logger already
  * surfaces them, since they can carry PII or tokens into whatever serializes the error.
@@ -7,33 +8,6 @@ export interface QueryError extends Error {
     query?: string;
     values?: unknown[];
 }
-/**
- * What a failed query ran into, named the same on every engine. `retryable` is a deadlock, a
- * serialization failure, a lock timeout or a busy database: the transaction can simply run again.
- */
-export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable';
-/**
- * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
- * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
- * where there is no row left. `status` is what an HTTP transport answers with.
- */
-export declare class UqlOptimisticLockError extends Error {
-    readonly expected: unknown;
-    readonly actual: unknown;
-    name: string;
-    readonly status = 409;
-    constructor(message: string, expected: unknown, actual: unknown);
-}
-/**
- * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
- * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
- * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
- * failure, and an untyped client is exactly who reaches this.
- */
-export declare class UqlLockUsageError extends TypeError {
-    name: string;
-    readonly status = 400;
-}
 /**
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
  * read, so it works on any driver error, whether or not a querier saw it first.

package/dist/querier/queryError.js

@@ -1,29 +1,4 @@
-/**
- * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
- * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
- * where there is no row left. `status` is what an HTTP transport answers with.
- */
-export class UqlOptimisticLockError extends Error {
-    expected;
-    actual;
-    name = 'UqlOptimisticLockError';
-    status = 409;
-    constructor(message, expected, actual) {
-        super(message);
-        this.expected = expected;
-        this.actual = actual;
-    }
-}
-/**
- * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
- * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
- * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
- * failure, and an untyped client is exactly who reaches this.
- */
-export class UqlLockUsageError extends TypeError {
-    name = 'UqlLockUsageError';
-    status = 400;
-}
+import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -78,8 +53,8 @@ export function queryErrorKind(err) {
     if (typeof err !== 'object' || err === null) {
         return undefined;
     }
-    if (err instanceof UqlOptimisticLockError) {
-        return 'optimisticLock';
+    if (err instanceof UqlOptimisticLockError || err instanceof UqlUsageError) {
+        return err.kind;
     }
     const { code, errno, number, errorLabels, message } = err;
     const text = typeof message === 'string' ? message : '';

package/dist/sqlite/sqliteDialect.js

@@ -34,9 +34,7 @@ export const SQLITE_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: false,
-    rowLockWithWindow: true,
     nullsOrdering: 'clause',
-    rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,

package/dist/type/dialect.d.ts

@@ -135,15 +135,27 @@ export interface DialectFeatures {
      * such a write reads the ids of the rows it names first.
      */
     readonly correlatedWrites: boolean;
+    /**
+     * What the engine's row locks can do, or `false` where it has none: the SQLite family locks the
+     * database and MongoDB has no row lock at all, so both refuse `$lock` rather than ignoring it. One
+     * value rather than a flag each, since the details mean nothing without a lock.
+     */
+    readonly rowLocks: RowLockFeatures | false;
+}
+/** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
+export interface RowLockFeatures {
+    /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
+    readonly of: boolean;
+    /** Whether the lock may share a statement with a window function, which the Postgres family refuses. */
+    readonly withWindow: boolean;
+    /**
+     * Where the lock is spelled: after the statement (`FOR UPDATE`), or as a hint on the table it reads
+     * (`WITH (UPDLOCK)`, SQL Server). A dialect's `lockHint` states the hint itself.
+     */
+    readonly placement: 'suffix' | 'tableHint';
 }
 /** What a SQL engine can do beyond {@link DialectFeatures}, read where a statement is built. */
 export interface SqlDialectFeatures extends DialectFeatures {
-    /** Whether the engine has row locks at all. The SQLite family locks the database instead. */
-    readonly rowLocks: boolean;
-    /** Whether `FOR UPDATE` may share a statement with a window function, which the Postgres family refuses. */
-    readonly rowLockWithWindow: boolean;
-    /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
-    readonly rowLockOf: boolean;
     /**
      * How a `$sort` states where nulls land: the `NULLS FIRST/LAST` clause, a leading `IS NULL` term
      * (MySQL, MariaDB), or a leading `CASE` (SQL Server, which has no orderable boolean).

package/dist/type/queryAggregate.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../util/uqlError.js';
 const QUERY_AGGREGATE_OPS = ['$count', '$sum', '$avg', '$min', '$max'];
 /**
  * Whether `op` is one of {@link QueryAggregateOp}'s known aggregate operators - validates operator
@@ -17,5 +18,5 @@ export function resolveAggregateOp(key) {
     if (isQueryAggregateOp(key)) {
         return { op: key, distinct: false };
     }
-    throw new TypeError(`unsupported aggregate operator: ${key}`);
+    throw new UqlUsageError(`unsupported aggregate operator: ${key}`);
 }

package/dist/type/queryLock.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../util/uqlError.js';
 const QUERY_LOCK_WAITS = ['nowait', 'skip'];
 function isOneOf(vals, val) {
     return vals.includes(val);
@@ -15,7 +16,7 @@ export function parseQueryLock(lock) {
         return 'block';
     }
     if (!isOneOf(QUERY_LOCK_WAITS, lock.$wait)) {
-        throw new TypeError(`unknown $lock wait policy: ${String(lock.$wait)}`);
+        throw new UqlUsageError(`unknown $lock wait policy: ${String(lock.$wait)}`);
     }
     return lock.$wait;
 }

package/dist/type/queryWhere.d.ts

@@ -1,7 +1,7 @@
 import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QuerySelect } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
+import type { AtLeastOne, ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
 /**
  * options for full-text-search operator.
@@ -95,12 +95,13 @@ export type QuerySizeComparisonOps = {
 };
 /**
  * Filter by distance to a vector, `{ $near: { $vector: v, $lt: 0.35 } }`: ordered bounds only, since a
- * distance is a float. Each clause names its own `$vector`, and `$distance` falls back to the field's.
- * One with no bound is refused at run time, where `/http` input is checked anyway.
+ * distance is a float, and at least one, since none would filter nothing. Each clause names its own
+ * `$vector`, and `$distance` falls back to the field's. `/http` input is untyped, so the dialect
+ * checks it again at run time.
  */
-export type QueryVectorNear = QueryVectorQuery & {
-    [K in QueryOrderedOp]?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
-};
+export type QueryVectorNear = QueryVectorQuery & AtLeastOne<{
+    [K in QueryOrderedOp]: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
+}>;
 export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
     /**
      * whether a value is equal to the given value.

package/dist/type/utility.d.ts

@@ -59,6 +59,14 @@ export type RejectKeys<K> = [K] extends [never] ? unknown : Record<K & string, n
 export type ExactlyOne<T> = {
     [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
 }[keyof T];
+/**
+ * At least one key of `T` with its value, the rest optional: the looser sibling of {@link ExactlyOne},
+ * for options that combine but cannot all be left out. `Pick`, so every key stays linked to `T`'s own
+ * property and renames follow it through.
+ */
+export type AtLeastOne<T> = Partial<T> & {
+    [K in keyof T]: Pick<T, K>;
+}[keyof T];
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
 /**
  * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a

package/dist/util/dialect.util.js

@@ -4,6 +4,7 @@ import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index
 import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { getFieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 /** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
@@ -194,7 +195,7 @@ export function findVectorSort(sort) {
 export function vectorCandidates(q) {
     const candidates = q.$candidates;
     if (candidates !== undefined && (!Number.isInteger(candidates) || candidates < 1)) {
-        throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
+        throw new UqlUsageError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
     }
     return candidates;
 }
@@ -260,7 +261,7 @@ export function isFieldUpdateOp(value) {
  */
 export function fieldUpdateOf(key, value) {
     if (value.$inc !== undefined && value.$mul !== undefined) {
-        throw new TypeError(`'${key}' takes one of $inc and $mul`);
+        throw new UqlUsageError(`'${key}' takes one of $inc and $mul`);
     }
     return value.$inc === undefined ? ['$mul', value.$mul] : ['$inc', value.$inc];
 }
@@ -280,7 +281,7 @@ export function whereIds(meta, ids) {
  */
 export function assertWhere(meta, where) {
     if (!isWhereMap(where)) {
-        throw new TypeError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
+        throw new UqlUsageError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
     }
 }
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
@@ -353,7 +354,7 @@ export function parseRelationSize(val) {
     }
     const siblings = getKeys(val).filter((key) => key !== '$size');
     if (siblings.length) {
-        throw new TypeError(`$size on a relation cannot be combined with other conditions: ${siblings.join(', ')}`);
+        throw new UqlUsageError(`$size on a relation cannot be combined with other conditions: ${siblings.join(', ')}`);
     }
     return val.$size;
 }
@@ -368,7 +369,7 @@ export function parseSortByCount(val) {
     }
     const siblings = getKeys(val).filter((key) => key !== '$count');
     if (siblings.length) {
-        throw new TypeError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
+        throw new UqlUsageError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
     }
     return val.$count;
 }
@@ -393,13 +394,13 @@ export function parseGroupMap(group, select) {
         const call = select[alias];
         const key = getKeys(call).find((name) => name !== '$where');
         if (key === undefined) {
-            throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
+            throw new UqlUsageError(`aggregate '${alias}' names no op, only a $where`);
         }
         // `$countDistinct` normalizes to `$count` plus a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
         const field = aggregateField(alias, call[key]);
         if (field === undefined && (op !== '$count' || distinct)) {
-            throw new TypeError(`aggregate '${alias}' takes '*' only as a $count`);
+            throw new UqlUsageError(`aggregate '${alias}' takes '*' only as a $count`);
         }
         entries.push({ kind: 'fn', alias, op, distinct, ...(field && { field }), ...(hasKeys(where) ? { where } : {}) });
     }
@@ -409,7 +410,7 @@ export function parseGroupMap(group, select) {
 function groupRefPath(alias, ref) {
     const [key, ...rest] = isRecord(ref) ? getKeys(ref) : [];
     if (!isRecord(ref) || key === undefined || rest.length) {
-        throw new TypeError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
+        throw new UqlUsageError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
     }
     return ref[key] === true ? [key] : [key, ...groupRefPath(alias, ref[key])];
 }
@@ -420,7 +421,7 @@ function aggregateField(alias, arg) {
     }
     const [field, ...rest] = namedKeys(arg);
     if (field === undefined || rest.length) {
-        throw new TypeError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
+        throw new UqlUsageError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
     }
     return field;
 }
@@ -454,7 +455,7 @@ export function isJsonObject(value) {
  */
 export function assertNonNegativeInteger(value, clause) {
     if (!Number.isInteger(value) || value < 0) {
-        throw new TypeError(`${clause} must be a non-negative integer, got ${value}`);
+        throw new UqlUsageError(`${clause} must be a non-negative integer, got ${value}`);
     }
     return value;
 }
@@ -464,7 +465,7 @@ export function assertNonNegativeInteger(value, clause) {
  * SQL and MongoDB refuse the same query with the same words.
  */
 export function throwUnknownAggregateColumn(key, clause) {
-    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
+    throw new UqlUsageError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
 }
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export function assertAggregateColumns(clauseMap, emitted, clause) {
@@ -529,7 +530,7 @@ export function textSortOf(sort) {
  */
 export function rankedTextSearch(where) {
     if (!where?.$text) {
-        throw new TypeError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
+        throw new UqlUsageError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
     }
     return where.$text;
 }
@@ -551,5 +552,5 @@ export function textSearchFields(meta, search) {
     const declared = fulltext.length
         ? `${fulltext.length} fulltext indexes to choose from`
         : 'no fulltext index to search';
-    throw new TypeError(`$text on '${name}' names no $fields, and '${name}' declares ${declared}. Name them with $fields.`);
+    throw new UqlUsageError(`$text on '${name}' names no $fields, and '${name}' declares ${declared}. Name them with $fields.`);
 }

package/dist/util/relationQuery.util.js

@@ -1,5 +1,6 @@
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_STATEMENT_CLAUSES, } from '../type/query.js';
 import { getKeys, isRecord, someKey } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 /** What a query populating nothing requests, shared: most reads populate nothing, and ask on every one. */
 const NOTHING_REQUESTED = Object.freeze({
     requestedKeys: Object.freeze([]),
@@ -65,7 +66,7 @@ function assertJoinableRelationQuery(relKey, value) {
     }
     for (const [key, reason] of JOINED_RELATION_REJECTED_KEYS) {
         if (key in value) {
-            throw new TypeError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
+            throw new UqlUsageError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
         }
     }
 }
@@ -138,7 +139,7 @@ export function parseRelationQueryValue(value) {
     if (isRecord(value)) {
         const statementOnly = QUERY_STATEMENT_CLAUSES.find((clause) => clause in value);
         if (statementOnly) {
-            throw new TypeError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
+            throw new UqlUsageError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
         }
     }
     if (isRelationQueryObject(value)) {
@@ -152,7 +153,7 @@ export function parseRelationQueryValue(value) {
         return { query: { $select: selectMap }, required: false, nested: false };
     }
     if (value !== undefined && value !== null && value !== true && value !== 1) {
-        throw new TypeError(`Invalid relation query value '${String(value)}'. Expected true/1, relation query object, or relation $populate array.`);
+        throw new UqlUsageError(`Invalid relation query value '${String(value)}'. Expected true/1, relation query object, or relation $populate array.`);
     }
     return { query: {}, required: false, nested: false };
 }

package/dist/util/uqlError.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a failed query ran into, named the same on every engine - what {@link queryErrorKind} answers
+ * with, whether a driver raised the error or UQL did. `retryable` is a deadlock, a serialization
+ * failure, a lock timeout or a busy database: the transaction can simply run again. `usage` is the
+ * caller's own mistake, which running it again will not fix.
+ */
+export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable' | 'usage';
+/**
+ * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
+ * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
+ * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
+ */
+export declare class UqlUsageError extends TypeError {
+    name: string;
+    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
+    readonly kind = "usage";
+    /** What an HTTP transport answers with. */
+    readonly status = 400;
+}
+/**
+ * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
+ * same class under both names, so an existing `instanceof` keeps working.
+ */
+export declare const UqlLockUsageError: typeof UqlUsageError;
+export type UqlLockUsageError = UqlUsageError;
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left.
+ */
+export declare class UqlOptimisticLockError extends Error {
+    readonly expected: unknown;
+    readonly actual: unknown;
+    name: string;
+    readonly kind = "optimisticLock";
+    readonly status = 409;
+    constructor(message: string, expected: unknown, actual: unknown);
+}

package/dist/util/uqlError.js

@@ -0,0 +1,35 @@
+/**
+ * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
+ * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
+ * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
+ */
+export class UqlUsageError extends TypeError {
+    name = 'UqlUsageError';
+    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
+    kind = 'usage';
+    /** What an HTTP transport answers with. */
+    status = 400;
+}
+/**
+ * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
+ * same class under both names, so an existing `instanceof` keeps working.
+ */
+export const UqlLockUsageError = UqlUsageError;
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left.
+ */
+export class UqlOptimisticLockError extends Error {
+    expected;
+    actual;
+    name = 'UqlOptimisticLockError';
+    kind = 'optimisticLock';
+    status = 409;
+    constructor(message, expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}