uql-orm 0.77.0 → 0.77.1

package/dist/dialect/queryJoins.js

@@ -1,5 +1,6 @@
 import { getMeta, relationOf } from '../entity/index.js';
 import { getKeys, getRelationRequestSummary, hasKeys, isRecord, isToManyRelation, isVectorSearch, parseRelationAtKey, parseRelationSize, parseSortByCount, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -49,7 +50,7 @@ export function groupPathField(joins, path) {
     }
     const join = joins.get(path.slice(0, -1).join('.'));
     if (!join) {
-        throw new TypeError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
+        throw new UqlUsageError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
     }
     return { key, join };
 }
@@ -149,14 +150,14 @@ function addPathJoins(joins, claimAlias, meta, map, required, parent) {
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
 export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
     if (isToManyRelation(relation)) {
-        throw new TypeError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
+        throw new UqlUsageError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);
     }
     if (!isSortMap(value)) {
-        throw new TypeError(`$sort by relation '${path}' expects a map of its fields, got ${String(value)}`);
+        throw new UqlUsageError(`$sort by relation '${path}' expects a map of its fields, got ${String(value)}`);
     }
     const join = joins.get(path);
     if (!join) {
-        throw new TypeError(unjoinable);
+        throw new UqlUsageError(unjoinable);
     }
     return { join, sort: value };
 }
@@ -177,7 +178,7 @@ export function relationSortTerms(relKey, path, value) {
             return [];
         }
         if (search.$project !== undefined) {
-            throw new TypeError(`cannot $project the distance of relation '${path}': it ranks the parent, and no one row answers under it`);
+            throw new UqlUsageError(`cannot $project the distance of relation '${path}': it ranks the parent, and no one row answers under it`);
         }
         return [{ spec: { relation: relKey, op: '$min', field, search }, direction: undefined }];
     });

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,6 @@
 import { unsupportedVectorMetric } from '../type/vector.js';
 import { findVectorIndex, findVectorSort, vectorCandidates, vectorDistanceOf } from '../util/dialect.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { AbstractDialect } from './abstractDialect.js';
 import { encodeFloat32s } from './vectorCast.js';
 /**
@@ -70,7 +71,7 @@ export class VectorSqlDialect extends AbstractDialect {
      */
     appendVectorDistance(ctx, meta, key, search, prefix) {
         if (this.vectorMetrics.size === 0) {
-            throw new TypeError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
+            throw new UqlUsageError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
         }
         const { colName, distance, field } = this.resolveVectorDistance(meta, key, search);
         const metric = this.vectorMetrics.get(distance);

package/dist/http/query.js

@@ -5,6 +5,8 @@ import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUER
 import { RAW_VALUE } from '../type/queryRaw.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys, isWhereMap } from '../util/object.util.js';
+// the error class alone, from its own leaf module: `queryError.ts` carries every driver's code map
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * Keys accepted from the wire - query structure ({@link Query}) plus the `hardDelete`/`count` scalar
  * flags. Anything else (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't
@@ -35,7 +37,7 @@ export function parseQueryParams(params = {}) {
     const query = {};
     for (const key of getKeys(params)) {
         if (REJECTED_QUERY_KEYS.has(key)) {
-            throw Object.assign(new TypeError(`'${key}' is not supported over HTTP`), { status: 400 });
+            throw new UqlUsageError(`'${key}' is not supported over HTTP`);
         }
         if (ALLOWED_QUERY_KEYS.has(key)) {
             query[key] = params[key];
@@ -54,7 +56,7 @@ export function parseQueryParams(params = {}) {
     }
     query['$where'] ??= {};
     if (!isWhereMap(query['$where'])) {
-        throw Object.assign(new TypeError("'$where' must be a JSON object"), { status: 400 });
+        throw new UqlUsageError("'$where' must be a JSON object");
     }
     // A query string carries every value as text, so what decodes a clause is the shape its group
     // declares. `'false'` is the reason the boolean pass exists rather than the raw value being taken:

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { withDeleted } from './util/filters.util.js';
 export type { HookContext } from './util/hook.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export * from './util/uqlError.js';

package/dist/index.js

@@ -7,3 +7,4 @@ export * from './type/index.js';
 export { withDeleted } from './util/filters.util.js';
 export { DefaultLogger } from './util/logger.js';
 export { raw, refs } from './util/raw.js';
+export * from './util/uqlError.js';

package/dist/maria/mariaDialect.js

@@ -1,6 +1,6 @@
 import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
-import { MYSQL_FEATURES, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
+import { MYSQL_FEATURES, MYSQL_ROW_LOCKS, MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
 import { columnFamily } from '../util/field.util.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
@@ -18,7 +18,7 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorBytes: true,
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
-        rowLockOf: false,
+        rowLocks: { ...MYSQL_ROW_LOCKS, of: false },
     };
     /**
      * A derived table here reads no column of the statement around it, so the aggregate reads the

package/dist/mongo/mongoDialect.d.ts

@@ -95,12 +95,6 @@ export declare class MongoDialect extends AbstractDialect {
     private static compareCount;
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     private subtractsKey;
-    /**
-     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
-     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
-     * lock silently removes the mutual exclusion the caller asked for.
-     */
-    assertNoLock<E>(q: Query<E>): void;
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     private assertNoRaw;
     /**

package/dist/mongo/mongoDialect.js

@@ -6,6 +6,7 @@ import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
 import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { decodeBigIntsExcept } from '../util/wideNumber.js';
 import { textLanguage } from './textLanguage.js';
 import { vectorDistanceExpr } from './vectorDistance.js';
@@ -30,6 +31,7 @@ export const mongoDialectFeatures = {
     supportsUnsigned: false,
     serverSideCursors: false,
     correlatedWrites: false,
+    rowLocks: false, // its concurrency control is the transaction plus atomic document updates
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
 const HEX_24 = /^[0-9a-f]{24}$/i;
@@ -109,7 +111,7 @@ export class MongoDialect extends AbstractDialect {
             else if (meta.relations[key]) {
                 this.assertNoRaw(val);
                 if (!lookups) {
-                    throw new TypeError(`filtering by relation '${key}' is not supported here on MongoDB`);
+                    throw new UqlUsageError(`filtering by relation '${key}' is not supported here on MongoDB`);
                 }
                 this.appendRelationLookup(filter, meta, key, val, lookups);
             }
@@ -118,7 +120,7 @@ export class MongoDialect extends AbstractDialect {
                 this.assertKnownPathRoot(meta, key);
                 if (aggregateOf(meta.fields[key])) {
                     if (!lookups) {
-                        throw new TypeError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
+                        throw new UqlUsageError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
                     }
                     this.appendAggregateField(meta, key, lookups);
                 }
@@ -270,7 +272,7 @@ export class MongoDialect extends AbstractDialect {
             ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
             : [{ [op]: [count, bound] }]);
         if (!comparisons.length) {
-            throw new TypeError('$size needs at least one comparison');
+            throw new UqlUsageError('$size needs at least one comparison');
         }
         return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
     }
@@ -279,20 +281,10 @@ export class MongoDialect extends AbstractDialect {
         const at = (map) => map?.[key];
         return at(exclude) === true || at(select) === false;
     }
-    /**
-     * MongoDB has no row-level lock to map `$lock` onto: its concurrency control is the transaction
-     * plus atomic document updates. Rejected rather than ignored, like `raw()` below, since a dropped
-     * lock silently removes the mutual exclusion the caller asked for.
-     */
-    assertNoLock(q) {
-        if (q.$lock) {
-            throw new TypeError('$lock (row-level locking) is not supported on MongoDB');
-        }
-    }
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
     assertNoRaw(value) {
         if (value instanceof QueryRaw) {
-            throw new TypeError('raw() in $where is not supported on MongoDB');
+            throw new UqlUsageError('raw() in $where is not supported on MongoDB');
         }
     }
     /**
@@ -305,7 +297,7 @@ export class MongoDialect extends AbstractDialect {
         if (root === MongoDialect.ID_KEY || meta.fields[root]) {
             return;
         }
-        throw new TypeError(`path ${key} does not exist in ${entityName(meta)}`);
+        throw new UqlUsageError(`path ${key} does not exist in ${entityName(meta)}`);
     }
     /** String operators -> { pattern: (v) => regex, caseInsensitive } */
     static REGEX_OP_MAP = new Map([
@@ -383,7 +375,7 @@ export class MongoDialect extends AbstractDialect {
                 case '$near':
                     // Atlas offers only a similarity threshold, on the index's own scale, which UQL neither emits nor
                     // reads: converting a distance would mean guessing the metric, so this refuses.
-                    throw new TypeError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
+                    throw new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
                         "Project the score with $sort's $project and filter on it instead.");
                 default:
                     result[op] = val;
@@ -430,7 +422,7 @@ export class MongoDialect extends AbstractDialect {
             return {};
         }
         if (Array.isArray(select)) {
-            throw new TypeError('raw $select is not supported on MongoDB');
+            throw new UqlUsageError('raw $select is not supported on MongoDB');
         }
         const selectMap = asSelectMap(select);
         // Projected by column, not by field key; `normalizeId` maps them back on the way out.
@@ -497,7 +489,7 @@ export class MongoDialect extends AbstractDialect {
             const relation = meta.relations[key];
             if (key === '$text') {
                 if (path) {
-                    throw new TypeError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
+                    throw new UqlUsageError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
                 }
                 const { order, project } = textSortOf(sort);
                 out[project ?? TEXT_SCORE_ALIAS] = sortDirection(order);
@@ -508,7 +500,7 @@ export class MongoDialect extends AbstractDialect {
                 // so one reaching it is a second. `sortDirection` would read the operator object as "ascending"
                 // and order by the raw vector column instead, a silent answer where the caller asked for a rank.
                 if (isVectorSearch(value)) {
-                    throw new TypeError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
+                    throw new UqlUsageError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
                 }
                 const docPath = path + this.pathOf(meta, key);
                 const nulls = sortNulls(value);
@@ -530,7 +522,7 @@ export class MongoDialect extends AbstractDialect {
                 // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
                 // parent document left to hang it off.
                 if (path) {
-                    throw new TypeError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
+                    throw new UqlUsageError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
                 }
                 if (spec.search) {
                     nearest[sortAggregateField(spec)] = 1;
@@ -773,10 +765,10 @@ export class MongoDialect extends AbstractDialect {
         // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
         // the same terms the SQL dialects refuse `SELECT DISTINCT` ordered by an unselected column.
         if (q.$distinct && aggregated.fields.length) {
-            throw new TypeError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
+            throw new UqlUsageError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
         }
         if (q.$distinct && sortOnly.length) {
-            throw new TypeError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
+            throw new UqlUsageError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
         }
         // `$distinct` inverts the usual order twice over: the projection decides which columns make two
         // rows the same, so it has to run *before* the grouping, and the grouping collapses rows, so the
@@ -1141,7 +1133,7 @@ export class MongoDialect extends AbstractDialect {
      */
     buildGroupSpec(meta, groupEntries, joins) {
         if (!groupEntries.length) {
-            throw new TypeError('aggregate requires at least one $group column or $select function');
+            throw new UqlUsageError('aggregate requires at least one $group column or $select function');
         }
         const groupId = {};
         const accumulators = {};
@@ -1204,7 +1196,7 @@ export class MongoDialect extends AbstractDialect {
             return this.columnOf(meta, key);
         }
         if (aggregateOf(join.meta.fields[key])) {
-            throw new TypeError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
+            throw new UqlUsageError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
         }
         return `${join.path}.${this.columnOf(join.meta, key)}`;
     }
@@ -1221,14 +1213,14 @@ export class MongoDialect extends AbstractDialect {
                 const { join, negate } = MongoDialect.GROUP_OPS[key];
                 const clauses = MongoDialect.groupClauses(key, where[key]).map((clause) => {
                     if (clause instanceof QueryRaw) {
-                        throw new TypeError('raw SQL is not supported in an aggregate $where on MongoDB');
+                        throw new UqlUsageError('raw SQL is not supported in an aggregate $where on MongoDB');
                     }
                     return this.whereExpression(meta, clause, named);
                 });
                 return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
             }
             if (key.startsWith('$')) {
-                throw new TypeError(`aggregate $where operator '${key}' is not supported on MongoDB`);
+                throw new UqlUsageError(`aggregate $where operator '${key}' is not supported on MongoDB`);
             }
             const val = where[key];
             named.push(key);
@@ -1271,7 +1263,7 @@ export class MongoDialect extends AbstractDialect {
                 case '$isNotNull':
                     return operand ? present : MongoDialect.isNullExpr(ref);
                 default:
-                    throw new TypeError(`aggregate $where operator '${op}' is not supported on MongoDB`);
+                    throw new UqlUsageError(`aggregate $where operator '${op}' is not supported on MongoDB`);
             }
         });
         return terms.length === 1 ? terms[0] : { $and: terms };
@@ -1326,12 +1318,12 @@ export class MongoDialect extends AbstractDialect {
         const meta = getMeta(entity);
         const field = meta.fields[key];
         if (!field) {
-            throw new TypeError(`Field '${key}' not found in entity '${meta.name}'`);
+            throw new UqlUsageError(`Field '${key}' not found in entity '${meta.name}'`);
         }
         const colName = this.resolveColumnName(key, field);
         const indexName = this.vectorSearchIndexName(findVectorIndex(meta, key)?.name, colName);
         if (!limit) {
-            throw new TypeError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
+            throw new UqlUsageError(`$vectorSearch requires $limit (vector sort on '${key}' of '${meta.name}')`);
         }
         const stage = {
             index: indexName,

package/dist/mongo/mongodbQuerier.js

@@ -58,7 +58,6 @@ export class MongodbQuerier extends AbstractQuerier {
      * for a read and a stream alike, so both load the same relations.
      */
     readCursor(entity, q, opts) {
-        this.dialect.assertNoLock(q);
         const vectorSort = this.dialect.extractVectorSort(q.$sort);
         const pipeline = vectorSort
             ? this.buildVectorPipeline(entity, q, vectorSort, opts)

package/dist/mssql/mssqlDialect.d.ts

@@ -69,11 +69,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     returningId<E>(meta: EntityMeta<E>): string;
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
     protected mergeReturning(expression: string): string;
-    /**
-     * A row lock is a hint on the table here, not a clause at the end of the statement, so
-     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
-     */
-    protected appendLock<E>(_ctx: QueryContext, entity: Type<E>, q: Query<E>): void;
+    /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     protected lockHint<E>(q: Query<E>): string;
     /**
      * `N'...'`, always. A bare literal is `VARCHAR`, whose codepage silently destroys anything outside

package/dist/mssql/mssqlDialect.js

@@ -10,6 +10,7 @@ import { parseQueryLock } from '../type/index.js';
 import { isAutoIncrement } from '../util/field.util.js';
 import { assertNonNegativeInteger } from '../util/index.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /** What SQL Server has. */
 const MSSQL_FEATURES = {
     // Neither object takes an `IF NOT EXISTS`; both need a `sys` catalogue lookup around them, which
@@ -31,10 +32,8 @@ const MSSQL_FEATURES = {
     supportsUnsigned: false,
     serverSideCursors: false,
     correlatedWrites: true,
-    rowLocks: true,
-    rowLockWithWindow: true,
+    rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
     nullsOrdering: 'case',
-    rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
@@ -164,13 +163,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     mergeReturning(expression) {
         return `OUTPUT ${expression}`;
     }
-    /**
-     * A row lock is a hint on the table here, not a clause at the end of the statement, so
-     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
-     */
-    appendLock(_ctx, entity, q) {
-        this.assertLockSupported(entity, q);
-    }
+    /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     lockHint(q) {
         const wait = parseQueryLock(q.$lock);
         if (!wait) {
@@ -324,7 +317,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     jsonSet(ctx, expr, set, _field) {
         for (const [key, value] of Object.entries(set)) {
             if (value === null) {
-                throw new TypeError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
+                throw new UqlUsageError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
             }
         }
         return Object.entries(set).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);

package/dist/querier/abstractQuerier.d.ts

@@ -18,7 +18,14 @@ export declare abstract class AbstractQuerier implements Querier {
     protected readonly logger: LoggerWrapper;
     abstract readonly dialect: AbstractDialect;
     constructor(extra?: ExtraOptions | undefined);
-    protected validateProjectionQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
+    /** What every read is checked for before it runs, whichever backend runs it. */
+    protected validateReadQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
+    /**
+     * 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.
+     */
+    private assertLockable;
     private validateProjectionQueryRecursive;
     /** `[entity, query, opts]` from either call form, `(entity, q, opts)` or `({ $entity, ...q }, opts)`. */
     protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {

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);