uql-orm 0.76.0 → 0.77.1

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, 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,29 +38,44 @@ 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 value the payload carried, out of the payload and
- * into the filter, and the next one back in its place. The bump is a plain value rather than SQL
- * arithmetic, since the filter pins what the column holds, which spares every engine a read-back.
+ * An optimistic lock as one update applies it: the version the payload carried, the one that replaces
+ * it, and the filter pinning what the column still holds. The bump is a plain value rather than SQL
+ * arithmetic, since that filter already pins it, which spares every engine a read-back.
  */
 function lockVersion(meta, key, q, row) {
     const expected = row[key];
-    if (expected === undefined || expected === null) {
-        throw new TypeError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
+    if (typeof expected !== 'number' && typeof expected !== 'bigint') {
+        throw new UqlUsageError(`an update of '${entityName(meta)}' carries no '${key}': a versioned row is written against the version it was read at`);
     }
-    row[key] = (typeof expected === 'bigint' ? expected + 1n : Number(expected) + 1);
-    return { expected, q: { ...q, $where: { $and: [q.$where ?? {}, { [key]: expected }] } } };
+    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
+    // the version contradicts itself into matching nothing, which is what they asked for.
+    return { expected, next, q: { ...q, $where: { ...q.$where, [key]: expected } } };
 }
 /**
  * Refuses a write that cannot carry the lock, rather than writing over whatever the row holds now.
  * An upsert has no portable way to match a version - MySQL's `ON DUPLICATE KEY UPDATE` takes no
  * `WHERE` - and a write the library itself composes has no version to carry.
  */
-function assertUnversioned(meta, method) {
+function assertUnversioned(meta, what) {
     if (meta.version) {
-        throw new TypeError(`cannot '${method}' 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`);
+    }
+}
+/**
+ * What a versioned update has to be for its lock to hold: one row, named by its id, written by one
+ * statement. A filter naming more than one row cannot say which of them the payload's single version
+ * belongs to, and anything settled first - a page, a relation write, a filter an engine cannot read in
+ * an `UPDATE` - reads the ids and writes them separately, putting the race back in the gap between.
+ */
+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 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`);
     }
 }
 /**
@@ -101,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.`);
                 }
             }
         }
@@ -129,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];
@@ -145,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.
@@ -156,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);
@@ -218,45 +251,55 @@ export class AbstractQuerier {
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     async updateMany(entity, q, payload, opts) {
         assertNamesRows(entity, 'updateMany', q, opts);
+        return this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, getMeta(entity).version));
+    }
+    /**
+     * The write every update runs, matching the version `lockKey` names where one is being held. Only a
+     * restore passes none: it writes no content, so there is no update of anyone's to lose.
+     */
+    async updateRows(entity, q, row, opts, lockKey) {
         const meta = getMeta(entity);
-        return this.hooked(entity, 'Update', [payload], async ([row]) => {
-            fillOnFields(meta, [row], 'onUpdate');
-            const { version } = meta;
-            const lock = version && lockVersion(meta, version, q, row);
-            const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
-            if (!relKeys.length && !this.settlesWrite(entity, q)) {
-                const changes = await this.updateColumns(entity, lock ? lock.q : q, row, opts, 0);
-                return lock && !changes ? this.throwStaleVersion(entity, version, q, lock.expected, opts) : changes;
-            }
-            if (lock) {
-                // Everything below reads the ids first and writes them in a second statement, which puts the
-                // race back in the gap between the two - the very thing the version is here to close.
-                // `settlesWrite` covers the paged forms, so `$sort`, `$limit` and `$skip` land here as well.
-                throw new TypeError(`cannot update '${entityName(meta)}' this way: a versioned row is matched and written in one statement, so it takes no '$sort', '$limit' or '$skip', writes no relation, and filters by none`);
-            }
-            const ids = await this.settleIds(entity, q, opts);
-            if (!ids.length) {
-                return 0;
-            }
-            const changes = await this.updateColumns(entity, { $where: whereIds(meta, ids) }, row, opts, ids.length);
-            for (const relKey of relKeys) {
-                await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
-            }
-            return changes;
-        });
+        fillOnFields(meta, [row], 'onUpdate');
+        const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
+        const settles = !!relKeys.length || this.settlesWrite(entity, q);
+        if (lockKey) {
+            assertLockableUpdate(meta, q, settles);
+            const lock = lockVersion(meta, lockKey, q, row);
+            row[lockKey] = lock.next;
+            const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
+            return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
+        }
+        if (!settles) {
+            return this.updateColumns(entity, q, row, opts, 0);
+        }
+        const ids = await this.settleIds(entity, q, opts);
+        if (!ids.length) {
+            return 0;
+        }
+        const changes = await this.updateColumns(entity, { $where: whereIds(meta, ids) }, row, opts, ids.length);
+        for (const relKey of relKeys) {
+            await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
+        }
+        return changes;
     }
     /**
-     * Why an update matched no row: another writer moved the version on, or the row is gone. One read
-     * without the version predicate answers it, and it runs only on the failure, so the happy path
+     * Why an update matched no row. The filter named the row by its id, so reading by that id alone
+     * separates the three: the row is gone, another writer moved the version on, or the rest of the
+     * filter excluded a row still at that version. One read, only on the failure, so the happy path
      * still costs one statement. Best effort by nature - the row can change again while we ask.
      */
     async throwStaleVersion(entity, key, q, expected, opts) {
         const meta = getMeta(entity);
-        const row = await this.findOne(entity, { $select: { [key]: true }, $where: q.$where }, opts);
+        const where = q.$where;
+        const byId = Object.fromEntries(meta.ids.map((id) => [id, where[id]]));
+        const row = await this.findOne(entity, { $select: { [key]: true }, $where: byId }, opts);
         const actual = row?.[key];
-        throw new UqlOptimisticLockError(actual === undefined
-            ? `no row of '${entityName(meta)}' matched the update: it is gone, or the filter names none`
-            : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`, expected, actual);
+        const message = actual === undefined
+            ? `no row of '${entityName(meta)}' has that id any more: it is gone`
+            : actual === expected
+                ? `'${entityName(meta)}' is still at '${key}' ${String(actual)}: another condition of the update's '$where' excluded it`
+                : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
+        throw new UqlOptimisticLockError(message, expected, actual);
     }
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     async updateColumns(entity, q, row, opts, unwritten) {
@@ -284,18 +327,17 @@ 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'`);
         }
-        assertUnversioned(meta, 'restoreMany');
         const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
-        return this.updateMany(entity, { ...q, $where }, { [meta.softDelete]: null }, {
-            filters: { softDelete: false },
-        });
+        // No version: a restore only undoes the stamp a delete left, which takes none either, and two of
+        // them racing agree on the result anyway. A lock is for content, and a restore writes none.
+        return this.hooked(entity, 'Update', [{ [meta.softDelete]: null }], ([row]) => this.updateRows(entity, { ...q, $where }, row, { filters: { softDelete: false } }, undefined));
     }
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     async upsertOne(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'upsertOne');
+        assertUnversioned(meta, "'upsertOne'");
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
             const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
             adoptReportedIds(meta, rows, ids);
@@ -305,7 +347,7 @@ export class AbstractQuerier {
     }
     async upsertMany(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'upsertMany');
+        assertUnversioned(meta, "'upsertMany'");
         return this.hooked(entity, 'Upsert', payload, async (rows) => {
             const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
             adoptReportedIds(meta, rows, ids);
@@ -343,8 +385,6 @@ export class AbstractQuerier {
         return changes;
     }
     async saveOne(entity, payload) {
-        // Named here as well as in `saveMany`, so the refusal names the method the caller reached for.
-        assertUnversioned(getMeta(entity), 'saveOne');
         const [id] = await this.saveMany(entity, [payload]);
         return id;
     }
@@ -355,7 +395,7 @@ export class AbstractQuerier {
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
-        assertUnversioned(meta, 'saveMany');
+        assertUnversioned(meta, "'save'");
         // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
         // passed, which concatenating the branches did not do.
         const toInsert = [];

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,23 +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);
-}
 /**
  * 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,19 +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;
-    }
-}
+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'],
@@ -68,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