uql-orm 0.75.0 → 0.77.0

package/dist/entity/decorator/members.d.ts

@@ -1,4 +1,4 @@
-import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
+import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, VersionKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to, on a class `O`. */
 type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
@@ -31,12 +31,14 @@ type DeclaredValue<O> = O extends {
 /**
  * The `null` a column reads back: every one holds it unless `nullable: false` says otherwise, so the
  * property admits it too. A key holds none, whether `@Id` or `@Field({ isId: true })` declares it, since
- * it is NOT NULL on every engine.
+ * it is NOT NULL on every engine, and neither does a version, which is NOT NULL DEFAULT 0.
  */
 type NullOf<O> = O extends {
     readonly nullable: false;
 } | {
     readonly isId: true;
+} | {
+    readonly version: true;
 } ? never : null;
 /** The enum's members, or a named complaint where they widened for lack of `as const`, which would check nothing. */
 type EnumValue<Members, Declared> = Declared extends Members ? {
@@ -51,7 +53,7 @@ export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, Thi
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
+}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O & VersionIsBranded<O, This>): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
 /**
  * Declares a field a relation aggregate computes, `@Field({ computed: (user) => user.resources.count() })`.
  * The aggregate says what the field holds, so it takes no `type`, and only `count` and `sum` - the two a
@@ -80,6 +82,16 @@ type AggregateOptions<E> = (Except<FieldOptions<never, E>, 'computed' | 'stored'
 type KeyIsNamed<This> = [NamedIdKey<This>] extends [never] ? {
     readonly __keyNeedsIdKeyBrand: true;
 } : unknown;
+/**
+ * An optimistic lock the type level cannot see. `version: true` is what makes the column a lock at run
+ * time; the `versionKey` brand is what makes an update payload require it, and a lock only half
+ * declared would be a guarantee nothing enforces, so the decorator asks for both.
+ */
+type VersionIsBranded<O, This> = O extends {
+    readonly version: true;
+} ? [VersionKey<This>] extends [never] ? {
+    readonly __versionNeedsVersionKeyBrand: true;
+} : unknown : unknown;
 /** {@link MemberDecorator} that also constrains the class, which is where a key is named. */
 type IdDecorator<V> = <This>(value: undefined, context: ClassFieldDecoratorContext<This, V> & KeyIsNamed<This>) => void;
 /**

package/dist/entity/metadata/definition.js

@@ -213,6 +213,18 @@ export function defineEntity(entity, opts = {}) {
         meta.softDelete = softDeleteKeys[0];
         (meta.filters ??= {})[SOFT_DELETE_FILTER] = { where: { [meta.softDelete]: null }, default: true };
     }
+    // The optimistic lock, derived the same way and just as singular: one row has one version.
+    const versionKeys = getKeys(meta.fields).filter((key) => meta.fields[key]?.version);
+    if (versionKeys.length > 1) {
+        throw TypeError(`'${entity.name}' must have at most one field with 'version'`);
+    }
+    if (versionKeys.length) {
+        meta.version = versionKeys[0];
+        // Implied rather than stated: the DDL default covers a row written around the ORM, and `onInsert`
+        // covers MongoDB, which has no DDL to default. Both, so every backend starts a row at the same 0.
+        const field = meta.fields[meta.version];
+        meta.fields[meta.version] = { ...field, nullable: false, defaultValue: 0, onInsert: 0 };
+    }
     const ids = getIdKeys(meta);
     if (!ids.length) {
         throw TypeError(`'${entity.name}' must have at least one id field (use @Id, defineId, or defineEntity({ fields: { ..., isId: true } }))`);

package/dist/querier/abstractQuerier.d.ts

@@ -86,6 +86,18 @@ export declare abstract class AbstractQuerier implements Querier {
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    /**
+     * 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.
+     */
+    private updateRows;
+    /**
+     * 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.
+     */
+    private throwStaleVersion;
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     private updateColumns;
     /**

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,6 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/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 } from './queryError.js';
+import { enrichError, UqlLockUsageError, UqlOptimisticLockError } 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.
@@ -38,6 +38,44 @@ function assertNamesRows(entity, method, q, opts) {
     }
     throw new TypeError(`'${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
+ * 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 (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`);
+    }
+    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, 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`);
+    }
+}
+/**
+ * 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 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`);
+    }
+}
 /**
  * The id each written row is named by, in payload order. Read off the rows as written, so a key the
  * database generated or the ORM filled is there, and a composite is named by every column of it.
@@ -195,23 +233,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 relKeys = filterPersistableRelationKeys(meta, row, 'persist');
-            if (!relKeys.length && !this.settlesWrite(entity, q)) {
-                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;
-        });
+        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. 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 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];
+        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) {
@@ -242,13 +312,14 @@ export class AbstractQuerier {
             throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
         }
         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'");
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
             const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
             adoptReportedIds(meta, rows, ids);
@@ -258,6 +329,7 @@ export class AbstractQuerier {
     }
     async upsertMany(entity, conflictPaths, payload) {
         const meta = getMeta(entity);
+        assertUnversioned(meta, "'upsertMany'");
         return this.hooked(entity, 'Upsert', payload, async (rows) => {
             const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
             adoptReportedIds(meta, rows, ids);
@@ -305,6 +377,7 @@ export class AbstractQuerier {
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
+        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 = [];
@@ -409,6 +482,9 @@ export class AbstractQuerier {
     }
     /** Each parent gets its own referenced row, and its own column pointing at it. */
     async saveManyToOne(entity, relEntity, localColumn, writes) {
+        // Before anything is written: the follow-up that points each row at its new relation carries no
+        // version, and half an insert is worse than a refusal.
+        assertUnversioned(getMeta(entity), 'save a to-one relation of');
         const pointing = writes.filter(({ value }) => value);
         const referenceIds = await this.insertMany(relEntity, pointing.map(({ value }) => value));
         for (const [index, { id }] of pointing.entries()) {

package/dist/querier/queryError.d.ts

@@ -11,7 +11,29 @@ export interface QueryError extends Error {
  * 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' | 'retryable';
+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,3 +1,29 @@
+/**
+ * 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;
+}
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -52,6 +78,9 @@ export function queryErrorKind(err) {
     if (typeof err !== 'object' || err === null) {
         return undefined;
     }
+    if (err instanceof UqlOptimisticLockError) {
+        return 'optimisticLock';
+    }
     const { code, errno, number, errorLabels, message } = err;
     const text = typeof message === 'string' ? message : '';
     return (SQLSTATE_KINDS.get(code) ??

package/dist/type/entity.d.ts

@@ -6,6 +6,12 @@ import type { Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked,
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
+/**
+ * Brands the property holding an entity's optimistic-lock version, which is what makes an update
+ * payload require it. No conventional name, unlike {@link idKey}: a field merely called `version`
+ * must not start demanding one.
+ */
+export declare const versionKey: unique symbol;
 /** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
 export declare const SOFT_DELETE_FILTER = "softDelete";
 /** A filter name an entity may declare: any but {@link SOFT_DELETE_FILTER}, which a refusal names. */
@@ -30,8 +36,20 @@ export type WritableKey<E> = {
 }[FieldKey<E>];
 /** A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write. */
 export type EntityWrite<E> = EntityData<E, WritableKey<E>>;
-/** A partial write as a caller supplies one: {@link UpdatePayload} without them. */
-export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>>;
+/**
+ * The property an entity brands with {@link versionKey} as its optimistic lock, `never` where it
+ * brands none. The brand is what carries `@Field({ version: true })` to the type level, since a
+ * decorator's options never reach `E`.
+ */
+export type VersionKey<E> = E extends {
+    [versionKey]?: infer K;
+} ? K & FieldKey<E> : never;
+/**
+ * A partial write as a caller supplies one: {@link UpdatePayload} without the fields it cannot write,
+ * and with the version where the entity keeps one - a write that cannot say which row state it read
+ * is refused here rather than silently overwriting whatever is there now.
+ */
+export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>> & Required<Pick<E, VersionKey<E>>>;
 /** The relation names of an entity: every key but its fields and its methods, so the two sets cannot drift. */
 export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
 /**
@@ -247,6 +265,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
      * stamps `new Date()`, anything else is the value or callback stamped, `softDelete: () => Date.now()`.
      */
     readonly softDelete?: true | OnFieldCallback<V>;
+    /**
+     * Makes the column an optimistic lock: an update matches the version its payload carries and writes
+     * the next one, so a write against a row someone else moved on throws instead of overwriting it. The
+     * column is `NOT NULL DEFAULT 0`, and the entity brands the property with {@link versionKey}.
+     */
+    readonly version?: true;
     /** The SQL type, where it differs from the one `type` implies: `type: String, columnType: 'decimal'`. */
     readonly columnType?: ColumnType;
     /** A string column's length. */
@@ -643,6 +667,8 @@ export type EntityMeta<E> = {
     /** Every column of the primary key, in declaration order. */
     ids: readonly IdKey<E>[];
     softDelete?: FieldKey<E>;
+    /** The optimistic lock's column, from `@Field({ version: true })`. */
+    version?: FieldKey<E>;
     /** Named, default-on `$where` filters applied to every query unless bypassed. */
     filters?: Record<string, FilterOptions<E>>;
     fields: {

package/dist/type/entity.js

@@ -1,5 +1,11 @@
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export const idKey = Symbol('idKey');
+/**
+ * Brands the property holding an entity's optimistic-lock version, which is what makes an update
+ * payload require it. No conventional name, unlike {@link idKey}: a field merely called `version`
+ * must not start demanding one.
+ */
+export const versionKey = Symbol('versionKey');
 /** The filter `@Field({ softDelete })` registers, a name reserved against an entity's own filters. */
 export const SOFT_DELETE_FILTER = 'softDelete';
 /** Every SQL column type a field may declare, by family: the unions below and `columnFamily` both read it. */

package/dist/util/dialect.util.js

@@ -69,7 +69,9 @@ export function getSoftDeleteValue(field) {
 /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
 export function fillOnFields(meta, payload, callbackKey) {
     const payloads = Array.isArray(payload) ? payload : [payload];
-    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey]);
+    // By presence, not truthiness, as `addInsertFieldKeys` above reads it: `onInsert: 0` and `onInsert: ''`
+    // are values a caller meant, and a falsy one was silently never filled.
+    const keys = getKeys(meta.fields).filter((key) => meta.fields[key][callbackKey] !== undefined);
     if (keys.length === 0) {
         return payloads;
     }

package/dist/util/fieldOption.util.d.ts

@@ -20,6 +20,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly onInsert: '*';
     readonly onUpdate: '*';
     readonly softDelete: '*';
+    readonly version: 'numeric';
     readonly columnType: '*';
     readonly length: 'string';
     readonly precision: 'numeric';
@@ -44,8 +45,15 @@ type InlineRead = (typeof INLINE_READS)[number];
  * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
  * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
  */
-declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement"];
+declare const GENERATED_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "version"];
 type GeneratedWrite = (typeof GENERATED_WRITES)[number];
+/**
+ * What an optimistic lock cannot use: the querier writes the column on every update and matches the
+ * value the payload carried, so anything else deciding it would be fighting that, and the three that
+ * would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
+ */
+declare const VERSION_WRITES: readonly ["updatable", "onInsert", "onUpdate", "softDelete", "defaultValue", "autoIncrement", "computed", "stored", "isId"];
+type VersionWrite = (typeof VERSION_WRITES)[number];
 /**
  * The first option `opts` cannot use, phrased as the tail of `'Entity.field' ...`, or `undefined`
  * where every option applies. The runtime half of the decorators' check, so the imperative API and
@@ -68,7 +76,12 @@ type DeadOptions<O> = (O extends {
     readonly nullable: true;
 } ? 'nullable' : never) | (O extends {
     readonly updatable: false;
-} ? 'onUpdate' : never);
+} ? 'onUpdate' : never) | (O extends {
+    readonly version: true;
+} ? VersionWrite : never) | (O extends {
+    readonly version: true;
+    readonly nullable: true;
+} ? 'nullable' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
 type Offending<O> = {
     [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;

package/dist/util/fieldOption.util.js

@@ -21,6 +21,7 @@ const FIELD_OPTION_FAMILY = {
     onInsert: '*',
     onUpdate: '*',
     softDelete: '*',
+    version: 'numeric',
     columnType: '*',
     length: 'string',
     precision: 'numeric',
@@ -46,12 +47,8 @@ const INLINE_READS = [
     'eager',
     'distance',
 ];
-/**
- * What a column the *database* writes cannot use. A stored computed column is a real column - it has
- * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
- * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
- */
-const GENERATED_WRITES = [
+/** Every option that decides what a column holds, or whether it is written at all. */
+const VALUE_DECIDERS = [
     'updatable',
     'onInsert',
     'onUpdate',
@@ -60,19 +57,37 @@ const GENERATED_WRITES = [
     'autoIncrement',
 ];
 /**
- * Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. Only
- * `nullable: true` contradicts a key: `nullable: false` says what the key already is, and rejecting
- * an accurate statement teaches an author to distrust the check.
+ * What a column the *database* writes cannot use. A stored computed column is a real column - it has
+ * DDL, an index, a comment, a name - so only the write half is dead on one: the engine fills it, and
+ * `GENERATED ALWAYS AS` and `DEFAULT` are mutually exclusive on every engine that has both.
+ */
+const GENERATED_WRITES = [...VALUE_DECIDERS, 'version'];
+/**
+ * What an optimistic lock cannot use: the querier writes the column on every update and matches the
+ * value the payload carried, so anything else deciding it would be fighting that, and the three that
+ * would make it another kind of column entirely. Its `nullable: false` and `DEFAULT 0` are implied.
  */
+const VERSION_WRITES = [...VALUE_DECIDERS, 'computed', 'stored', 'isId'];
+/**
+ * Whether `key` is the `nullable: true` a NOT NULL column contradicts. `nullable: false` says what
+ * such a column already is, and rejecting an accurate statement teaches an author to distrust the check.
+ */
+function contradictsNotNull(opts, key) {
+    return key === 'nullable' && opts.nullable === true;
+}
+/** Whatever leaves `key` unread, named for the message, or `undefined` where the field reads it. */
 function deadOn(opts, key) {
     if (isInlinedExpression(opts) && !INLINE_READS.some((read) => read === key))
         return 'an inlined computed field';
     if (opts.stored === true && GENERATED_WRITES.some((write) => write === key))
         return 'a stored computed column';
-    if (opts.isId === true && key === 'nullable' && opts.nullable === true)
+    if (opts.isId === true && contradictsNotNull(opts, key))
         return 'a primary key';
     if (opts.updatable === false && key === 'onUpdate')
         return "a field declared 'updatable: false'";
+    if (opts.version === true && (VERSION_WRITES.some((write) => write === key) || contradictsNotNull(opts, key))) {
+        return 'a version field';
+    }
     return undefined;
 }
 /**

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.75.0",
+  "version": "0.77.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -79,6 +79,10 @@ export class Post {
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
 - `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
 - `@Index((post) => [post.authorId], { where: { archived: { $ne: true } } })` states a partial index's filter as the predicate the query passes, never as `raw`: a planner matches the two by shape, so `raw` that means the same thing leaves the index unused.
+- `@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 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