@procedures/client 0.14.0 → 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

@@ -133,6 +133,9 @@ export {
   PARTITION_PATTERN,
   collectionTopicPartition,
   collectionTopicTarget,
+  // The rules of the rows of a collection (roadmap CLI-41)
+  admittedStorage,
+  admitsRow,
   DEFAULT_FIND_LIMIT,
   DEFAULT_QUERY_OPERATORS,
   DEFAULT_QUERY_POLICY,
@@ -147,11 +150,30 @@ 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,
+  CollectionAdmission,
+  CollectionRow,
+  CollectionWrite,
+  CollectionWriteGuard,
   CollectionPartitions,
   PartitionInput,
   PartitionResolver,

package/src/procedures/invoke.ts

@@ -76,8 +76,10 @@ export type InvocationErrorCode =
  *   subscription (`documentation/EVENTS.md`).
  * - `partition-not-allowed`: the partition resolver of the collection procedures refuses the
  *   partition of a call (roadmap CLI-17).
+ * - `write-not-allowed`: the guard of a collection (`admission.guard`) refuses a write (roadmap
+ *   CLI-41).
  */
-export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed" | "topic-not-allowed" | "partition-not-allowed";
+export type ForbiddenReason = CapabilityRefusalReason | "outside-root" | "host-not-allowed" | "topic-not-allowed" | "partition-not-allowed" | "write-not-allowed";
 
 /** An error of the invocation itself. An error that the handler throws passes through unchanged. */
 export class InvocationError extends Error {
@@ -87,7 +89,8 @@ export class InvocationError extends Error {
   readonly retryable: boolean = false;
   /**
    * The reason of a `FORBIDDEN` error: `effects-undeclared`, `effects-exceeded`, `clearance`,
-   * `deadline`, `outside-root`, `host-not-allowed`, `topic-not-allowed` or `partition-not-allowed`.
+   * `deadline`, `outside-root`, `host-not-allowed`, `topic-not-allowed`, `partition-not-allowed` or
+   * `write-not-allowed`.
    */
   readonly reason: ForbiddenReason | undefined;
 
@@ -550,6 +553,8 @@ export function createProcedureContext(
   if (options.principal !== undefined) context.principal = options.principal;
   // The procedure of the parent invocation made this call (roadmap R33: the root of the files)
   if (invocation?.parent) context.caller = invocation.parent.procedure;
+  // The rules of the rows of a collection get the invocation of the call (roadmap CLI-41)
+  if (invocation) context.invocation = invocation;
   // The output filter of the host, for the data that a handler sends later (roadmap CLI-15)
   const admitItem = options.admitItem;
   if (invocation && invocation.depth === 0 && admitItem) context.admit = async (item) => admitItem(item, invocation);

package/src/procedures/types.ts

@@ -14,6 +14,7 @@ import type { CollectionStorage } from "./collection/storage.js";
 import type { EventBus } from "../events/types.js";
 import type { HydrationEvent } from "./ref.js";
 import type { Principal } from "../server/types.js";
+import type { Invocation } from "./invoke.js";
 
 // =============================================================================
 // Procedure Path
@@ -419,6 +420,13 @@ export interface ProcedureContext {
    * examines each row with it. Absent for a nested call, or when the host has no filter.
    */
   admit?: ((item: unknown) => Promise<boolean>) | undefined;
+
+  /**
+   * The invocation of this call: the procedure, the path, the principal and the capability
+   * (roadmap CLI-41). A rule with the shape of `AdmitItem` gets it, for example the rules of the
+   * rows of a collection. Absent for a context without an invocation.
+   */
+  invocation?: Invocation | undefined;
 }
 
 /**

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/index.ts

@@ -11,9 +11,13 @@
  * - Handler registry with pattern matching
  * - Graceful shutdown
  *
+ * The server transports have the entry `@procedures/client/node` (CLI-6). This entry still
+ * exports them as deprecated aliases. The next MINOR removes the aliases.
+ *
  * @example
  * ```typescript
- * import { Server, HttpServerTransport } from "@common/server";
+ * import { Server } from "@procedures/client/server";
+ * import { HttpServerTransport } from "@procedures/client/node";
  *
  * const server = new Server();
  *
@@ -34,6 +38,19 @@
  * ```
  */
 
+import { HttpServerTransport as NodeHttpServerTransport } from "../adapters/http/server/transport.js";
+import type {
+  HttpServerTransportOptions as NodeHttpServerTransportOptions,
+  HttpUrlStrategy as NodeHttpUrlStrategy,
+} from "../adapters/http/server/types.js";
+import { WebSocketServerTransport as NodeWebSocketServerTransport } from "../adapters/websocket/server/transport.js";
+import type {
+  WebSocketServerTransportOptions as NodeWebSocketServerTransportOptions,
+  WebSocketAuthHandler as NodeWebSocketAuthHandler,
+  WebSocketConnectionHandler as NodeWebSocketConnectionHandler,
+  WebSocketMessage as NodeWebSocketMessage,
+} from "../adapters/websocket/server/types.js";
+
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
 
@@ -59,19 +76,79 @@ export {
   type ServerTransport,
 } from "./types.js";
 
-export {
-  HttpServerTransport,
-  defaultServerUrlStrategy,
-  rpcServerUrlStrategy,
-} from "../adapters/http/server/index.js";
-export type {
-  HttpServerTransportOptions,
-  HttpUrlStrategy,
-} from "../adapters/http/server/index.js";
-export { WebSocketServerTransport } from "../adapters/websocket/server/index.js";
-export type {
-  WebSocketServerTransportOptions,
-  WebSocketAuthHandler,
-  WebSocketConnectionHandler,
-  WebSocketMessage,
-} from "../adapters/websocket/server/index.js";
+export { defaultServerUrlStrategy, rpcServerUrlStrategy } from "../adapters/http/server/strategies.js";
+
+// ============================================================================
+// The server transports: deprecated here (CLI-6 step 1)
+// ============================================================================
+// Their entry is `@procedures/client/node`. This entry and the root (which re-exports these
+// names from this module) give them through deprecated aliases until the next MINOR, so an
+// editor marks each old import. Each alias is the same class or type as the export of ./node.
+
+/**
+ * The HTTP server transport of Express, a shim over `procedureHandler`.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export const HttpServerTransport: typeof NodeHttpServerTransport = NodeHttpServerTransport;
+/**
+ * The HTTP server transport of Express, a shim over `procedureHandler`.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type HttpServerTransport = NodeHttpServerTransport;
+
+/**
+ * The options of `HttpServerTransport`.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type HttpServerTransportOptions = NodeHttpServerTransportOptions;
+
+/**
+ * The URL strategy of `HttpServerTransport`: it gives the method of an Express request.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type HttpUrlStrategy = NodeHttpUrlStrategy;
+
+/**
+ * The WebSocket server transport, on the `ws` package.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export const WebSocketServerTransport: typeof NodeWebSocketServerTransport = NodeWebSocketServerTransport;
+/**
+ * The WebSocket server transport, on the `ws` package.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type WebSocketServerTransport = NodeWebSocketServerTransport;
+
+/**
+ * The options of `WebSocketServerTransport`.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type WebSocketServerTransportOptions = NodeWebSocketServerTransportOptions;
+
+/**
+ * The authentication handler of `WebSocketServerTransport`, for each upgrade request.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type WebSocketAuthHandler = NodeWebSocketAuthHandler;
+
+/**
+ * The connection handler of `WebSocketServerTransport`, for each new connection.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type WebSocketConnectionHandler = NodeWebSocketConnectionHandler;
+
+/**
+ * The RPC message of `WebSocketServerTransport`.
+ *
+ * @deprecated Import it from `@procedures/client/node`. The root and `@procedures/client/server` stop exporting it in the next MINOR (CLI-6).
+ */
+export type WebSocketMessage<TReq = unknown> = NodeWebSocketMessage<TReq>;

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,