@procedures/client 0.14.1 → 0.15.1

package/src/client/types.ts

@@ -326,12 +326,20 @@ export type AccumulateContext<
  * Client error thrown when response has error status.
  */
 export class ClientError extends Error {
+  /**
+   * The metadata of the error response, for example `reason` of a `FORBIDDEN` error, or
+   * `conflicts` of a `VERSION_CONFLICT` error (roadmap CLI-16). Empty when the response has none.
+   */
+  public readonly metadata: Metadata;
+
   constructor(
     public readonly status: Extract<Status, { type: "error" }>,
     public readonly responseId: string,
+    metadata: Metadata = {},
   ) {
     super(status.message);
     this.name = "ClientError";
+    this.metadata = metadata;
   }
 
   get code(): string {

package/src/events/index.ts

@@ -59,6 +59,7 @@ export {
 // The remote events: a peer subscribes to the topics of the bus of another peer (EVENTS.md)
 export { EventPublisher, topicMatcher, MAX_SUBSCRIPTION_TOPICS, MAX_TOPIC_LENGTH } from "./publisher.js";
 export type { EventPublisherOptions, TopicRule, TopicCall } from "./publisher.js";
+export type { RightsChange, SubscriptionRecheck } from "./recheck.js";
 export { EVENTS_SUBSCRIBE_PATH, SubscriptionError, remoteEvents, subscribeRemote } from "./remote.js";
 export type {
   EventItem,

package/src/events/publisher.ts

@@ -18,6 +18,8 @@
  *
  * - A value with rows (`withRows()`) reaches each subscriber through the output filter of its host
  *   (`ctx.admit`): each row passes the filter, and the subscriber gets only the admitted rows.
+ * - An open subscription gets the same checks again at a change of the rights (`rightsChanged()`,
+ *   `recheck.rightsChanges`) and after `recheck.maxAge` (roadmap CLI-44). A refusal ends it.
  *
  * The delivery is at most once. The queue of a subscription holds at most `buffer` events. When
  * it is full, the publisher drops the oldest event, and the next event tells the number of lost
@@ -36,6 +38,8 @@ import type { EventBus, Unsubscribe } from "./types.js";
 import { getGlobalEventBus } from "./bus.js";
 import { EVENTS_SUBSCRIBE_PATH, type EventItem, type SubscribeInput } from "./remote.js";
 import { admittedValue, rowsOf } from "./rows.js";
+import { realClock, type Clock } from "../clock.js";
+import { SubscriptionRechecks, type RightsChange, type SubscriptionRecheck } from "./recheck.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -73,7 +77,8 @@ export interface EventPublisherOptions {
   allow?: ((topic: string, call: TopicCall) => boolean) | undefined;
   /**
    * The number of events that one subscription holds for a slow subscriber. When the queue is
-   * full, the publisher drops the oldest event.
+   * full, the publisher drops the oldest event. The events that wait for a re-check (roadmap
+   * CLI-44) are in the same queue, so a slow check holds at most this number of events too.
    * @default 1024
    */
   buffer?: number | undefined;
@@ -89,6 +94,23 @@ export interface EventPublisherOptions {
    * @default the read of the collection of `collectionTopicTarget()`, with the repository of the call
    */
   reads?: ((topic: string) => readonly string[]) | undefined;
+  /**
+   * The clock of the re-check after `recheck.maxAge` (roadmap CLI-44). A test gives the
+   * `fakeClock` of `@mark1russell7/service/testing`. A `ProcedureServer` gives its own clock to the
+   * publisher that it makes from its option `events`.
+   * @default the clock of the platform
+   */
+  clock?: Clock | undefined;
+  /**
+   * The re-check of the admission of each open subscription (roadmap CLI-44). A right can change
+   * after the start of a subscription. The publisher then examines the subscription again with the
+   * same checks: the topic rule, the reads, `allow` and the partition. A refusal ends it, for
+   * example with `FORBIDDEN`. `maxAge` starts a check after a time on the clock, and
+   * `rightsChanges` starts a check at each change from a source of the app. `rightsChanged()` also
+   * starts a check.
+   * @default no check after the start, other than at a call of `rightsChanged()`
+   */
+  recheck?: SubscriptionRecheck | undefined;
 }
 
 /** A procedure that reads resources, for the admission of a topic under a capability. */
@@ -167,6 +189,10 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
   private closed = false;
   private failure: unknown;
   private readonly unsubscribes: Unsubscribe[];
+  /** The re-check of the admission that runs (roadmap CLI-44). The events wait for it. */
+  private recheck: Promise<void> | undefined;
+  /** The functions that run when the subscription ends */
+  private readonly endListeners: Array<() => void> = [];
 
   constructor(
     bus: EventBus,
@@ -201,7 +227,7 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     if (this.closed) return;
     const event = { type: "event" as const, topic, data, seq: ++this.seq };
     const waiter = this.waiter;
-    if (waiter && this.queue.length === 0) {
+    if (waiter && this.queue.length === 0 && !this.recheck) {
       this.waiter = undefined;
       waiter.resolve(this.deliver(event));
       return;
@@ -239,6 +265,8 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
       this.confirmation = undefined;
       return Promise.resolve({ value: confirmation, done: false });
     }
+    // The events wait for a re-check of the admission (roadmap CLI-44)
+    if (this.recheck) return this.recheck.then(() => this.next());
     const event = this.queue.shift();
     if (event) return this.deliver(event);
     if (this.failure !== undefined) {
@@ -295,9 +323,51 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
     for (const unsubscribe of this.unsubscribes) unsubscribe();
     this.signal?.removeEventListener("abort", this.onAbort);
     this.onClose(this);
+    for (const listener of this.endListeners.splice(0)) listener();
+  }
+
+  /**
+   * This function holds the events until the check ends (roadmap CLI-44). A check that passes gives
+   * the held events to the reader. A check that fails ends the subscription with its error, and the
+   * held events go. The promise ends when the check ends, and it does not reject.
+   */
+  hold(check: Promise<void>): Promise<void> {
+    if (this.closed) return check.then(ignore, ignore);
+    const running: Promise<void> = check.then(
+      () => {
+        if (this.recheck === running) this.recheck = undefined;
+        this.flush();
+      },
+      (error: unknown) => {
+        if (this.recheck === running) this.recheck = undefined;
+        this.queue.length = 0;
+        this.fail(error);
+      },
+    );
+    this.recheck = running;
+    return running;
+  }
+
+  /** This function runs the listener when the subscription ends, or at once after its end. */
+  onEnd(listener: () => void): void {
+    if (this.closed) listener();
+    else this.endListeners.push(listener);
+  }
+
+  /** This function gives the first held event to a reader that waits, after a check passes. */
+  private flush(): void {
+    const waiter = this.waiter;
+    const event = this.queue[0];
+    if (!waiter || !event || this.recheck) return;
+    this.waiter = undefined;
+    this.queue.shift();
+    waiter.resolve(this.deliver(event));
   }
 }
 
+/** This function does nothing: the end of a check of a closed subscription. */
+function ignore(): void {}
+
 /**
  * The publisher of the remote events: it serves `events.subscribe` from a bus, under a topic
  * rule. `ProcedureServer` makes one from its option `events`.
@@ -321,8 +391,11 @@ export class EventPublisher {
   private readonly defaultReads: boolean;
   private readonly buffer: number;
   private readonly open = new Set<TopicSubscription>();
+  /** The re-checks of the admission of the open subscriptions (roadmap CLI-44) */
+  private readonly rechecks: SubscriptionRechecks;
 
   constructor(options: EventPublisherOptions) {
+    this.rechecks = new SubscriptionRechecks(options.recheck ?? {}, options.clock ?? realClock);
     this.bus = options.bus ?? getGlobalEventBus();
     this.known = topicMatcher(options.topics);
     this.allow = options.allow;
@@ -360,6 +433,18 @@ export class EventPublisher {
     for (const subscription of [...this.open]) subscription.fail(stoppedError());
   }
 
+  /**
+   * This function tells the publisher that rights changed (roadmap CLI-44). Each open subscription
+   * that the change touches gets the checks of its start again: the topic rule, the reads, `allow`
+   * and the partition. Its events wait for the check. A refusal ends the subscription with its
+   * error, for example `FORBIDDEN`. The promise ends when each check ends, and it does not reject.
+   *
+   * @param change - The subscriptions that the change touches. Without it, each open subscription gets a check.
+   */
+  rightsChanged(change?: RightsChange): Promise<void> {
+    return this.rechecks.rightsChanged(change);
+  }
+
   /**
    * The topic of the bus for a topic of a subscriber (roadmap CLI-17). A topic of a partitioned
    * collection names the partition that the subscriber asks for, as the input of a procedure does:
@@ -385,11 +470,10 @@ export class EventPublisher {
   }
 
   /**
-   * The stream of one subscription. The publisher examines each topic before it adds a listener:
-   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
+   * The checks of the topics of a call: the topic rule, the reads of the capability and `allow`.
+   * A subscription passes them at its start and at each re-check (roadmap CLI-44).
    */
-  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
-    const unique = [...new Set(topics)];
+  private admitTopics(unique: readonly string[], ctx: ProcedureContext): void {
     for (const topic of unique) {
       if (!this.known(topic)) throw new TopicNotFoundError(`The host has no topic "${topic}"`);
     }
@@ -408,10 +492,36 @@ export class EventPublisher {
         }
       }
     }
+  }
+
+  /**
+   * The admission of an open subscription again (roadmap CLI-44): the checks of its start, and the
+   * partition of each topic. A refusal of the resolver throws its error. A topic whose partition
+   * changed throws `FORBIDDEN` (reason `partition-not-allowed`), because the listener has the old
+   * partition.
+   */
+  private async readmit(routes: ReadonlyArray<readonly [string, string]>, ctx: ProcedureContext): Promise<void> {
+    this.admitTopics(routes.map(([topic]) => topic), ctx);
+    for (const [topic, busTopic] of routes) {
+      if ((await this.busTopic(topic, ctx)) !== busTopic) {
+        throw new InvocationError("FORBIDDEN", `The partition of the topic "${topic}" changed, so the subscription ends`, ctx.path, "partition-not-allowed");
+      }
+    }
+  }
+
+  /**
+   * The stream of one subscription. The publisher examines each topic before it adds a listener:
+   * the topic rule, the reads, `allow`, and the partition. A call with one bad topic makes no subscription.
+   */
+  private async subscribe(topics: readonly string[], ctx: ProcedureContext): Promise<TopicSubscription> {
+    const unique = [...new Set(topics)];
+    this.admitTopics(unique, ctx);
     const routes: Array<readonly [string, string]> = [];
     for (const topic of unique) routes.push([topic, await this.busTopic(topic, ctx)]);
     const subscription = new TopicSubscription(this.bus, routes, this.buffer, ctx.signal, (closed) => this.open.delete(closed), ctx.admit, ctx.invocation);
     this.open.add(subscription);
+    // The same checks run again at a change of the rights and after the max age (roadmap CLI-44)
+    this.rechecks.watch(subscription, ctx.principal, () => this.readmit(routes, ctx));
     return subscription.closeIfAborted();
   }
 }

package/src/events/recheck.ts

@@ -0,0 +1,182 @@
+/**
+ * The re-check of the admission of the open subscriptions (roadmap CLI-44).
+ *
+ * At the start of a subscription, a publisher examines the rights of the subscriber. It examines
+ * the topic rule, the reads of the capability, `allow` and the partition. A right can change
+ * later, for example when the app removes a user from a group. Thus the publisher examines each
+ * open subscription again:
+ *
+ * - At a change of the rights. The host uses `rightsChanged()` of the publisher, or the source of
+ *   the option `recheck.rightsChanges` gives the change to its listener.
+ * - After the time `recheck.maxAge` on the clock of the publisher, from the last check.
+ *
+ * The check is the same function as at the start. While it operates, the events of the
+ * subscription wait. A refusal ends the subscription with its error, for example `FORBIDDEN`, and
+ * the events that wait go. Without a call of `rightsChanged()` and without the option, nothing
+ * changes.
+ */
+
+import type { Cancel, Clock } from "../clock.js";
+import { toMs, type Duration } from "../duration.js";
+import type { Principal } from "../server/types.js";
+
+/**
+ * The subscriptions that a change of the rights touches: the id of a principal, or a test of the
+ * principal of a subscription. A subscription without a principal (a call from this process) has
+ * no id, so only a test or a change of each subscription touches it.
+ */
+export type RightsChange = string | ((principal: Principal | undefined) => boolean);
+
+/** The options of the re-check of the open subscriptions of a publisher (roadmap CLI-44). */
+export interface SubscriptionRecheck {
+  /**
+   * The longest time from one check of a subscription to the next check, for example `minutes(1)`.
+   * The time is on the clock of the publisher. Without it, only a change of the rights starts a
+   * check.
+   */
+  readonly maxAge?: Duration | undefined;
+  /**
+   * The source of the changes of the rights of the app. While the publisher has an open
+   * subscription, the source has one listener of the publisher. The source gives the function that
+   * removes the listener. Each call of the listener is a call of `rightsChanged()`: without a
+   * change, each subscription gets a check.
+   */
+  readonly rightsChanges?: ((listener: (change?: RightsChange) => void) => () => void) | undefined;
+}
+
+/** A subscription that the re-checks can hold and watch. */
+export interface RecheckedSubscription {
+  /**
+   * This function holds the events of the subscription until the check ends. A refusal ends the
+   * subscription with its error. The promise ends with the check, and it does not reject.
+   */
+  hold(check: Promise<void>): Promise<void>;
+  /** This function runs the listener when the subscription ends. */
+  onEnd(listener: () => void): void;
+}
+
+/** One subscription that the re-checks watch. */
+interface Watch {
+  readonly principal: Principal | undefined;
+  /** The timer of the max age, or undefined. */
+  timer: Cancel | undefined;
+  /** This function starts a check at once. The promise ends when the check ends. */
+  readonly recheck: () => Promise<void>;
+}
+
+/** True when the change touches a subscription of the principal. A test that throws touches it. */
+function touches(change: RightsChange | undefined, principal: Principal | undefined): boolean {
+  if (change === undefined) return true;
+  if (typeof change === "string") return principal?.id === change;
+  try {
+    return change(principal);
+  } catch {
+    return true;
+  }
+}
+
+/** The promise of a check. A check that throws at once gives a rejected promise. */
+function started(check: () => Promise<void>): Promise<void> {
+  return new Promise<void>((resolve) => resolve(check()));
+}
+
+/**
+ * The re-checks of the open subscriptions of one publisher (roadmap CLI-44). The publisher gives
+ * each new subscription to `watch()`, with the check of its admission.
+ */
+export class SubscriptionRechecks {
+  private readonly watches = new Set<Watch>();
+  private readonly maxAgeMs: number | undefined;
+  private readonly source: SubscriptionRecheck["rightsChanges"];
+  /** The function that removes the listener of the source, while a subscription is open */
+  private stopListening: (() => void) | undefined;
+
+  constructor(
+    options: SubscriptionRecheck,
+    private readonly clock: Clock,
+  ) {
+    const maxAgeMs = options.maxAge === undefined ? undefined : toMs(options.maxAge, "recheck.maxAge");
+    if (maxAgeMs !== undefined && !(maxAgeMs > 0)) {
+      throw new TypeError(`recheck.maxAge must be more than 0 ms, got ${maxAgeMs} ms`);
+    }
+    this.maxAgeMs = maxAgeMs;
+    this.source = options.rightsChanges;
+  }
+
+  /** The number of the subscriptions that the re-checks watch. */
+  get size(): number {
+    return this.watches.size;
+  }
+
+  /**
+   * This function watches a subscription until it ends. A change of the rights of its principal
+   * and its max age start the check. The check must throw the refusal.
+   */
+  watch(subscription: RecheckedSubscription, principal: Principal | undefined, check: () => Promise<void>): void {
+    const watch: Watch = {
+      principal,
+      timer: undefined,
+      recheck: () => {
+        this.stopTimer(watch);
+        return subscription.hold(started(check)).then(() => {
+          // A check that passes gives the admission a new age
+          if (this.watches.has(watch)) this.startTimer(watch);
+        });
+      },
+    };
+    this.watches.add(watch);
+    subscription.onEnd(() => this.unwatch(watch));
+    if (!this.watches.has(watch)) return;
+    this.startTimer(watch);
+    if (this.source && !this.stopListening) {
+      try {
+        this.stopListening = this.source((change) => void this.rightsChanged(change));
+      } catch (error) {
+        // A source that cannot listen cannot tell a revocation: the subscription ends
+        void subscription.hold(Promise.reject(error));
+      }
+    }
+  }
+
+  /**
+   * This function starts a check of each watched subscription that the change touches. The
+   * promise ends when each check ends.
+   */
+  rightsChanged(change?: RightsChange): Promise<void> {
+    const checks: Array<Promise<void>> = [];
+    for (const watch of [...this.watches]) {
+      if (touches(change, watch.principal)) checks.push(watch.recheck());
+    }
+    return Promise.all(checks).then(() => undefined);
+  }
+
+  /** This function stops the watch of a subscription that ended. */
+  private unwatch(watch: Watch): void {
+    this.stopTimer(watch);
+    if (!this.watches.delete(watch) || this.watches.size > 0) return;
+    // The last subscription ended: the publisher does not listen to the source
+    const stop = this.stopListening;
+    this.stopListening = undefined;
+    stop?.();
+  }
+
+  /** This function starts the timer of the max age of a subscription. */
+  private startTimer(watch: Watch): void {
+    if (this.maxAgeMs === undefined) return;
+    this.stopTimer(watch);
+    const timer = this.clock.after(this.maxAgeMs, () => {
+      if (watch.timer === timer) watch.timer = undefined;
+      void watch.recheck();
+    });
+    // A check does not keep a Node process alive
+    timer.unref?.();
+    watch.timer = timer;
+  }
+
+  /** This function stops the timer of the max age of a subscription. */
+  private stopTimer(watch: Watch): void {
+    const timer = watch.timer;
+    watch.timer = undefined;
+    timer?.();
+  }
+}

package/src/procedures/collection/index.ts

@@ -84,6 +84,8 @@ export type {
   StorageChanges,
   StorageMetadata,
   StorageWriteOptions,
+  StorageItemWriteOptions,
+  StorageBatchWriteOptions,
   StorageSetChange,
   StorageDeleteChange,
   StorageClearChange,
@@ -92,6 +94,21 @@ export type {
   StorageObserver,
 } from "./storage.js";
 
+// The precondition of the writes: the expected version and VERSION_CONFLICT (roadmap CLI-16)
+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 query language of the storages: the same JSON on the wire and in query() (roadmap CLI-34:
 // the one copy of the language)
 export {

package/src/procedures/collection/precondition.ts

@@ -0,0 +1,180 @@
+/**
+ * The precondition of a collection write (roadmap CLI-16, decision D11).
+ *
+ * - `set` and `delete` take `expectedVersion`. `setBatch` takes `expectedVersions`, with one
+ *   expected version for each id. The value is the version of the current item that the write
+ *   expects. `null` expects no item.
+ * - The version of an item is the value that the function `versionOf` of the storage gives for
+ *   the item, for example a revision field. `HybridStorage` reads the same versions with its own
+ *   `versionOf`, so its queue can send the base version of a write as the expected version.
+ * - The storage tests the precondition and writes in one step. When the version of the current
+ *   item is not the expected version, the write changes nothing, and it rejects with
+ *   `VersionConflictError`.
+ * - The error has the code `VERSION_CONFLICT` (HTTP 409). It has the current item and its version
+ *   for each conflict. On the wire, the conflicts go in the metadata key `conflicts`.
+ * - A storage without `versionOf` cannot test a precondition. It rejects such a write with a
+ *   `TypeError`, and changes nothing. It never ignores a precondition.
+ * - A write without a precondition is the same as before: the last write wins.
+ *
+ * This module has no imports: `@procedures/client/query` exports it for the storage packages.
+ */
+
+/** One conflict of a write with a precondition (roadmap CLI-16). The data is JSON. */
+export interface VersionConflict {
+  /** The id of the item. */
+  readonly id: string;
+  /** The version that the write expected. `null`: the write expected no item. */
+  readonly expected: string | null;
+  /** True when the id has an item now. */
+  readonly found: boolean;
+  /** The current item, when `found` is true. */
+  readonly value?: unknown;
+  /**
+   * The version of the current item: `null` when the id has no item. When the current item has no
+   * version, the field is absent.
+   */
+  readonly version?: string | null;
+}
+
+/** The function that gives the version of an item, or undefined for an item without a version. */
+export type VersionOf<T> = (item: T) => string | undefined;
+
+/** The current state of an id: no item, or an item. */
+export type CurrentItem<T> = { readonly found: false } | { readonly found: true; readonly value: T };
+
+/** The metadata key of the conflicts of a `VERSION_CONFLICT` error on the wire. */
+export const VERSION_CONFLICTS_METADATA_KEY = "conflicts";
+
+/** The longest expected version, in characters. */
+export const MAX_EXPECTED_VERSION_LENGTH = 1024;
+
+/** The message of an error with some conflicts. */
+function conflictMessage(conflicts: readonly VersionConflict[]): string {
+  const ids = conflicts.slice(0, 10).map((conflict) => JSON.stringify(conflict.id)).join(", ");
+  const more = conflicts.length > 10 ? ` and ${conflicts.length - 10} more` : "";
+  return `The version of the current item is not the expected version: ${ids}${more}`;
+}
+
+/**
+ * A write with a precondition found an item with another version (roadmap CLI-16). The write
+ * changed nothing. `conflicts` has the current item and its version for each id of a conflict.
+ */
+export class VersionConflictError extends Error {
+  override readonly name = "VersionConflictError";
+  /** The error code of the protocol: HTTP 409, not retryable. */
+  readonly code = "VERSION_CONFLICT";
+  /** A retry of the same write fails again: the caller reads the current item first. */
+  readonly retryable = false;
+  /** The conflicts, one for each id whose current item does not have the expected version. */
+  readonly conflicts: readonly VersionConflict[];
+
+  constructor(conflicts: readonly VersionConflict[], message?: string) {
+    super(message ?? conflictMessage(conflicts));
+    this.conflicts = conflicts;
+  }
+}
+
+/**
+ * This function gives the conflict of one id, or undefined when the current item has the expected
+ * version. `null` expects no item. An item without a version never has an expected string version.
+ *
+ * @param id - The id of the item
+ * @param expected - The expected version, or `null` for no item
+ * @param current - The current state of the id
+ * @param versionOf - The version of an item
+ */
+export function versionConflict<T>(id: string, expected: string | null, current: CurrentItem<T>, versionOf: VersionOf<T>): VersionConflict | undefined {
+  if (!current.found) return expected === null ? undefined : { id, expected, found: false, version: null };
+  const version = versionOf(current.value);
+  if (expected !== null && version === expected) return undefined;
+  return version === undefined ? { id, expected, found: true, value: current.value } : { id, expected, found: true, value: current.value, version };
+}
+
+/**
+ * This function tests the preconditions of a write against the current items, and gives the
+ * conflicts. The list is empty when each precondition holds.
+ *
+ * @param expected - The expected version of each id
+ * @param currentOf - The current state of an id, before the write
+ * @param versionOf - The version of an item
+ */
+export function versionConflicts<T>(
+  expected: Iterable<readonly [string, string | null]>,
+  currentOf: (id: string) => CurrentItem<T>,
+  versionOf: VersionOf<T>,
+): VersionConflict[] {
+  const conflicts: VersionConflict[] = [];
+  for (const [id, version] of expected) {
+    const conflict = versionConflict(id, version, currentOf(id), versionOf);
+    if (conflict) conflicts.push(conflict);
+  }
+  return conflicts;
+}
+
+/** The code of the error of a write with a precondition on a storage that cannot test it. */
+export const PRECONDITION_NOT_SUPPORTED = "PRECONDITION_NOT_SUPPORTED";
+
+/**
+ * The error of a write with a precondition on a storage that cannot test it: a storage without
+ * `versionOf`. The storage changes nothing. The error is a `TypeError` with the code
+ * `PRECONDITION_NOT_SUPPORTED`, so a sync does not take it for a network failure.
+ *
+ * @param storage - The name of the storage, for the message
+ * @param remedy - What makes the test possible
+ */
+export function preconditionNotSupported(storage: string, remedy = "give it the option versionOf"): TypeError & { readonly code: string; readonly retryable: false } {
+  return Object.assign(new TypeError(`${storage} cannot test expectedVersion: ${remedy}`), { code: PRECONDITION_NOT_SUPPORTED, retryable: false as const });
+}
+
+/** True for a value that a precondition can expect: a string of at most 1024 characters, or `null`. */
+export function isExpectedVersion(value: unknown): value is string | null {
+  return value === null || (typeof value === "string" && value.length <= MAX_EXPECTED_VERSION_LENGTH);
+}
+
+/** The conflicts of untrusted data from the wire, or undefined when the data is not a list of conflicts. */
+function conflictsOfData(data: unknown): VersionConflict[] | undefined {
+  if (!Array.isArray(data)) return undefined;
+  const conflicts: VersionConflict[] = [];
+  for (const entry of data) {
+    if (typeof entry !== "object" || entry === null) return undefined;
+    const record = entry as Record<string, unknown>;
+    const { id, expected, found, version } = record;
+    if (typeof id !== "string" || typeof found !== "boolean" || !(expected === null || typeof expected === "string")) return undefined;
+    if (!(version === undefined || version === null || typeof version === "string")) return undefined;
+    conflicts.push({
+      id,
+      expected,
+      found,
+      ...(found && Object.prototype.hasOwnProperty.call(record, "value") && { value: record["value"] }),
+      ...(version !== undefined && { version }),
+    });
+  }
+  return conflicts;
+}
+
+/**
+ * This function gives the conflicts of an error with the code `VERSION_CONFLICT`: the `conflicts`
+ * of a `VersionConflictError`, or the metadata key `conflicts` of an error from the wire (a
+ * `ClientError`). It gives undefined for another error. A `VERSION_CONFLICT` error without
+ * readable conflicts gives an empty list.
+ */
+export function versionConflictsOf(error: unknown): readonly VersionConflict[] | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  if (error instanceof VersionConflictError) return error.conflicts;
+  const { code, conflicts, metadata } = error as { code?: unknown; conflicts?: unknown; metadata?: unknown };
+  if (code !== "VERSION_CONFLICT") return undefined;
+  const fromMetadata = typeof metadata === "object" && metadata !== null ? (metadata as Record<string, unknown>)[VERSION_CONFLICTS_METADATA_KEY] : undefined;
+  return conflictsOfData(conflicts) ?? conflictsOfData(fromMetadata) ?? [];
+}
+
+/**
+ * This function gives a `VersionConflictError` for an error with the code `VERSION_CONFLICT`, with
+ * its conflicts and its message. It gives undefined for another error.
+ */
+export function asVersionConflictError(error: unknown): VersionConflictError | undefined {
+  if (error instanceof VersionConflictError) return error;
+  const conflicts = versionConflictsOf(error);
+  if (conflicts === undefined) return undefined;
+  const message = error instanceof Error ? error.message : undefined;
+  return new VersionConflictError(conflicts, message);
+}