@procedures/client 0.14.1 → 0.15.0

package/src/procedures/collection/query.ts

@@ -31,6 +31,22 @@
  *   regular expressions and the limit. The default policy does not permit `$regex`.
  */
 
+// The precondition of the collection writes is a part of the wire contract too (roadmap CLI-16).
+// This entry gives it to the storage packages: the module has no imports.
+export {
+  MAX_EXPECTED_VERSION_LENGTH,
+  PRECONDITION_NOT_SUPPORTED,
+  VERSION_CONFLICTS_METADATA_KEY,
+  VersionConflictError,
+  asVersionConflictError,
+  isExpectedVersion,
+  preconditionNotSupported,
+  versionConflict,
+  versionConflicts,
+  versionConflictsOf,
+} from "./precondition.js";
+export type { CurrentItem, VersionConflict, VersionOf } from "./precondition.js";
+
 //
 // ═══ The types ═══
 //

package/src/procedures/collection/schemas.ts

@@ -16,6 +16,7 @@ import {
   type StorageSelector,
   type StorageSort,
 } from "./query.js";
+import { MAX_EXPECTED_VERSION_LENGTH, isExpectedVersion } from "./precondition.js";
 
 // =============================================================================
 // Generic Schema Builder
@@ -83,6 +84,25 @@ function withOriginOf<I extends object>(data: Record<string, unknown>, input: I)
   return (isString(origin) ? { ...input, origin } : input) as I & { origin?: string };
 }
 
+/** The message of an expected version that is not valid (roadmap CLI-16). */
+const EXPECTED_VERSION_MESSAGE = `expectedVersion must be a string of at most ${MAX_EXPECTED_VERSION_LENGTH} characters, or null`;
+
+/**
+ * The error of the field `expectedVersion` of a write input (roadmap CLI-16), or undefined. The
+ * field is absent, a string of at most 1024 characters, or `null`.
+ */
+function expectedVersionError(data: Record<string, unknown>, path: (string | number)[] = []): ZodErrorLike | undefined {
+  if (!("expectedVersion" in data) || data["expectedVersion"] === undefined || isExpectedVersion(data["expectedVersion"])) return undefined;
+  const message = path.length === 0 ? EXPECTED_VERSION_MESSAGE : `${path.join(".")}.${EXPECTED_VERSION_MESSAGE}`;
+  return { message, errors: [{ path: [...path, "expectedVersion"], message }] };
+}
+
+/** The input with the expected version of the data, when the data has one. */
+function withExpectedVersionOf<I extends object>(data: Record<string, unknown>, input: I): I & { expectedVersion?: string | null } {
+  const expected = data["expectedVersion"];
+  return (isExpectedVersion(expected) ? { ...input, expectedVersion: expected } : input) as I & { expectedVersion?: string | null };
+}
+
 // =============================================================================
 // Common Schemas
 // =============================================================================
@@ -217,6 +237,11 @@ export interface SetInput {
   value: unknown;
   /** The origin of the write, for the observers of the storage and the change event (roadmap CLI-15). */
   origin?: string;
+  /**
+   * The version that the write expects for the current item (roadmap CLI-16). `null` expects no
+   * item. A conflict changes nothing and answers `VERSION_CONFLICT` with the current item.
+   */
+  expectedVersion?: string | null;
 }
 
 export const setInputSchema : ZodLike<SetInput> = createSchema<SetInput>((data) => {
@@ -247,9 +272,9 @@ export const setInputSchema : ZodLike<SetInput> = createSchema<SetInput>((data)
       },
     };
   }
-  const error = originError(data);
+  const error = originError(data) ?? expectedVersionError(data);
   if (error) return { success: false, error };
-  return { success: true, data: withOriginOf(data, { id: data["id"], value: data["value"] }) };
+  return { success: true, data: withExpectedVersionOf(data, withOriginOf(data, { id: data["id"], value: data["value"] })) };
 });
 
 /**
@@ -270,6 +295,11 @@ export interface DeleteInput {
   id: string;
   /** The origin of the write, for the observers of the storage and the change event (roadmap CLI-15). */
   origin?: string;
+  /**
+   * The version that the delete expects for the current item (roadmap CLI-16). `null` expects no
+   * item. A conflict changes nothing and answers `VERSION_CONFLICT` with the current item.
+   */
+  expectedVersion?: string | null;
 }
 
 export const deleteInputSchema : ZodLike<DeleteInput> = createSchema<DeleteInput>((data) => {
@@ -291,9 +321,9 @@ export const deleteInputSchema : ZodLike<DeleteInput> = createSchema<DeleteInput
       },
     };
   }
-  const error = originError(data);
+  const error = originError(data) ?? expectedVersionError(data);
   if (error) return { success: false, error };
-  return { success: true, data: withOriginOf(data, { id: data["id"] }) };
+  return { success: true, data: withExpectedVersionOf(data, withOriginOf(data, { id: data["id"] })) };
 });
 
 /**
@@ -810,7 +840,12 @@ export const getBatchOutputSchema : ZodLike<Record<string, unknown>> = createSch
  * Input for setBatch operation.
  */
 export interface SetBatchInput {
-  items: Array<{ id: string; value: unknown }>;
+  /**
+   * The items. An item can have `expectedVersion`: the version that the write expects for the
+   * current item of its id (roadmap CLI-16). When one item has a conflict, the batch changes no
+   * item and answers `VERSION_CONFLICT`.
+   */
+  items: Array<{ id: string; value: unknown; expectedVersion?: string | null }>;
   /** The origin of the write, for the observers of the storage and the change event (roadmap CLI-15). */
   origin?: string;
 }
@@ -845,13 +880,15 @@ export const setBatchInputSchema : ZodLike<SetBatchInput> = createSchema<SetBatc
         },
       };
     }
+    const versionError = expectedVersionError(item, ["items", i]);
+    if (versionError) return { success: false, error: versionError };
   }
   const error = originError(data);
   if (error) return { success: false, error };
   return {
     success: true,
     data: withOriginOf(data, {
-      items: data["items"].map((item: any) => ({ id: item["id"], value: item["value"] })),
+      items: data["items"].map((item: any) => withExpectedVersionOf(item, { id: item["id"], value: item["value"] })),
     }),
   };
 });

package/src/procedures/collection/storage.ts

@@ -20,6 +20,9 @@
  * - `query()` gives the result of `queryEntries()` of `@procedures/collections` for the entries.
  * - `observe()` gives one batch for each write that changes the storage, before the write resolves.
  * - `patch()` merges the fields into the item in one step.
+ * - A write with `expectedVersion` (`set`, `delete`) or `expectedVersions` (`setBatch`) tests the
+ *   version of the current item and writes in one step. A conflict changes nothing and rejects
+ *   with `VersionConflictError` (roadmap CLI-16).
  */
 
 import type { StoragePatch, StorageQueryOptions, StorageQueryPolicy, StorageSelector } from "./query.js";
@@ -76,10 +79,13 @@ export interface CollectionStorage<T> {
   has(id: string): Promise<boolean>;
   /** The number of items. */
   size(): Promise<number>;
-  /** Set the item of an id. The options give the origin of the write to the observers. */
-  set(id: string, value: T, options?: StorageWriteOptions): Promise<void>;
-  /** Delete the item of an id. True when it existed. */
-  delete(id: string, options?: StorageWriteOptions): Promise<boolean>;
+  /**
+   * Set the item of an id. The options give the origin of the write to the observers, and the
+   * expected version of the current item (roadmap CLI-16).
+   */
+  set(id: string, value: T, options?: StorageItemWriteOptions): Promise<void>;
+  /** Delete the item of an id. True when it existed. The options can expect a version, as for `set`. */
+  delete(id: string, options?: StorageItemWriteOptions): Promise<boolean>;
   /** Delete every item. */
   clear(options?: StorageWriteOptions): Promise<void>;
   /**
@@ -88,8 +94,8 @@ export interface CollectionStorage<T> {
    * procedure `patch` uses it. A storage without it gets a read and a write of the item.
    */
   patch?(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined>;
-  /** Set several items. */
-  setBatch(items: Array<[string, T]>, options?: StorageWriteOptions): Promise<void>;
+  /** Set several items. The options can expect a version for each id (roadmap CLI-16). */
+  setBatch(items: Array<[string, T]>, options?: StorageBatchWriteOptions): Promise<void>;
   /** Delete several items. The number of items that existed. */
   deleteBatch(ids: string[], options?: StorageWriteOptions): Promise<number>;
   /** The items of several ids. An id with no item is not in the map. */
@@ -114,6 +120,30 @@ export interface StorageWriteOptions {
   readonly origin?: string | undefined;
 }
 
+/**
+ * The options of `set` and `delete`: the origin, and the precondition of the write (roadmap
+ * CLI-16). `precondition.ts` gives the rules.
+ */
+export interface StorageItemWriteOptions extends StorageWriteOptions {
+  /**
+   * The version that the write expects for the current item, from `versionOf` of the storage.
+   * `null` expects no item. When the current item has another version, the write changes nothing
+   * and rejects with `VersionConflictError`. A storage without `versionOf` rejects it with a
+   * `TypeError`. Absent: no precondition.
+   */
+  readonly expectedVersion?: string | null | undefined;
+}
+
+/** The options of `setBatch`: the origin, and the precondition of each id (roadmap CLI-16). */
+export interface StorageBatchWriteOptions extends StorageWriteOptions {
+  /**
+   * The version that the write expects for the current item of each id, as for `expectedVersion`.
+   * When one id has a conflict, the batch changes no item. An id without an entry has no
+   * precondition.
+   */
+  readonly expectedVersions?: ReadonlyArray<readonly [string, string | null]> | undefined;
+}
+
 /** A change of `observe()`: an id got a value. */
 export interface StorageSetChange<T> {
   readonly type: "set";

package/src/procedures/index.ts

@@ -150,8 +150,23 @@ export {
   queryEntries,
   queryOptionsProblems,
   selectorProblems,
+  MAX_EXPECTED_VERSION_LENGTH,
+  PRECONDITION_NOT_SUPPORTED,
+  VERSION_CONFLICTS_METADATA_KEY,
+  VersionConflictError,
+  asVersionConflictError,
+  isExpectedVersion,
+  preconditionNotSupported,
+  versionConflict,
+  versionConflicts,
+  versionConflictsOf,
 } from "./collection/index.js";
 export type {
+  CurrentItem,
+  VersionConflict,
+  VersionOf,
+  StorageItemWriteOptions,
+  StorageBatchWriteOptions,
   CollectionProceduresOptions,
   CollectionChangeEventsOptions,
   CollectionChangeEvent,

package/src/protocol.ts

@@ -48,7 +48,8 @@ export type ProtocolErrorCode =
   | "CONNECTION_CLOSED"
   | "CONNECTION_NOT_FOUND"
   | "TOPIC_NOT_FOUND"
-  | "TOPIC_CLEARED";
+  | "TOPIC_CLEARED"
+  | "VERSION_CONFLICT";
 
 /**
  * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
@@ -80,6 +81,7 @@ export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
   CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
   TOPIC_NOT_FOUND: { http: 404, retryable: false, meaning: "The topic rule of the host has no topic with this name" },
   TOPIC_CLEARED: { http: 410, retryable: false, meaning: "The host cleared a topic of the subscription: clear() of its bus removed the listener" },
+  VERSION_CONFLICT: { http: 409, retryable: false, meaning: "The current item does not have the version that the write expects. The metadata key conflicts has the current items" },
 };
 
 /** True when a code is an error code of the protocol. */

package/src/server/procedure-server.ts

@@ -20,6 +20,7 @@ import { createCollectionProcedures } from "../procedures/collection/procedures.
 import { InvocationError, invokeProcedure, type AdmitItem, type Interceptor, type Invocation } from "../procedures/invoke.js";
 import type { Capability, ClearanceOrder, ProcedureContext, ResourcesOf } from "../procedures/types.js";
 import type { CollectionPartitions } from "../procedures/collection/partition.js";
+import { VERSION_CONFLICTS_METADATA_KEY, versionConflictsOf } from "../procedures/collection/precondition.js";
 import { TIMEOUT_METADATA_KEY, effectsOf, joinNarrowing, narrowCapability } from "../procedures/capability.js";
 import { IdempotencyCache, idempotencyKeyOf, isRepeatable, type IdempotencyOptions } from "../procedures/idempotency.js";
 import { optionalMs, type Duration } from "../duration.js";
@@ -335,6 +336,9 @@ export function errorResponse(id: string, error: unknown): ServerResponse<unknow
   const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)?.retryAfterMs;
   const metadata: Record<string, unknown> = reason ? { reason } : {};
   if (typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) metadata["retry-after"] = retryAfterMs;
+  // A VERSION_CONFLICT error tells the current item of each conflict (roadmap CLI-16)
+  const conflicts = versionConflictsOf(error);
+  if (conflicts !== undefined) metadata[VERSION_CONFLICTS_METADATA_KEY] = conflicts;
   const code = errorCodeOf(error);
   return {
     id,