uql-orm 0.76.0 → 0.77.1

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;
+    }
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.76.0",
+  "version": "0.77.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -82,9 +82,7 @@ export class Post {
 - `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, makes the column an
   optimistic lock: every update payload must carry the version it read (a compile error otherwise), the update
   matches on it and writes the next one, and a write against a row someone else moved on throws
-  `UqlOptimisticLockError` (`status` 409) instead of overwriting it. Save, upsert and `restoreMany` are refused on such
-  an entity (restore with `updateOneById`, `{ filters: { softDelete: false } }`); `updateMany` writes only the rows
-  still at the version it carries, and delete needs none.
+  `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409) instead of overwriting it. Save and upsert are refused on such an entity; the update is named by its id, so `updateMany` over a many-row filter is refused too, and delete and restore carry no version.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -126,6 +124,12 @@ const users = await pool.findMany(User, {
 - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0,
   so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$set`, `$unset`,
   `$push`, `$pull`.
+- `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row
+  someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and
+  refuse it.
+- `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`,
+  `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage` - so catch by kind rather than by
+  a driver's code or an `instanceof`.
 - `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
 
 ## Connections and transactions