uql-orm 0.75.0 → 0.76.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,12 @@ 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>;
+    /**
+     * 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
+     * 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, 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,29 @@ 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 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.
+ */
+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`);
+    }
+    row[key] = (typeof expected === 'bigint' ? expected + 1n : Number(expected) + 1);
+    return { expected, q: { ...q, $where: { $and: [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) {
+    if (meta.version) {
+        throw new TypeError(`cannot '${method}' the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
+    }
+}
 /**
  * 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.
@@ -198,9 +221,18 @@ export class AbstractQuerier {
         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)) {
-                return this.updateColumns(entity, q, row, opts, 0);
+                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) {
@@ -213,6 +245,19 @@ export class AbstractQuerier {
             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
+     * 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 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);
+    }
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     async updateColumns(entity, q, row, opts, unwritten) {
         const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
@@ -241,6 +286,7 @@ export class AbstractQuerier {
         if (!meta.softDelete) {
             throw new TypeError(`'${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 },
@@ -249,6 +295,7 @@ export class AbstractQuerier {
     /** 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 +305,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);
@@ -295,6 +343,8 @@ 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;
     }
@@ -305,6 +355,7 @@ export class AbstractQuerier {
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
+        assertUnversioned(meta, 'saveMany');
         // 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 +460,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,19 @@ 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);
+}
 /**
  * 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,19 @@
+/**
+ * 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;
+    }
+}
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -52,6 +68,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.76.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -79,6 +79,12 @@ 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, 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.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries