@sanity-labs/client-fake-for-test 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -110,6 +110,15 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Pluggable write interceptor — runs on each write through the document
+   * mutation API (create/patch/delete/transaction; not the release/version
+   * action API) before the store changes, and may throw to reject it. The
+   * client has no opinion about the policy; callers (e.g. a workflow test bench
+   * enforcing lake mutation guards) supply it. Inherited by `withConfig`
+   * siblings. See {@link MutationGuard}.
+   */
+  mutationGuard?: MutationGuard;
   /**
    * Default perspective applied to reads. Per-fetch `options.perspective`
    * overrides this. `withConfig({ perspective })` returns a sibling
@@ -259,6 +268,8 @@ export declare type FakeMutation =
  *
  * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
  *   scoped to the current dataset.
+ * - `simulateConcurrentEdit()` — force the next N revision-guarded writes
+ *   to a document to 409, for optimistic-locking retry tests.
  * - `datasets()` — lists known dataset keys in this registry.
  *
  * Methods deliberately omitted:
@@ -329,6 +340,58 @@ export declare interface MultipleMutationResult {
   }[];
 }
 
+/**
+ * A pluggable write interceptor, configured via
+ * `createTestClient({ mutationGuard })`. It runs on each write through the
+ * document mutation API — `create` / `createOrReplace` / `createIfNotExists` /
+ * `patch` / `delete` and the equivalent `transaction()` operations — before the
+ * store changes; **throw to reject the write** (the throw propagates out of the
+ * client call, exactly as a real lake rejection would). The release/version
+ * action API (`client.action`, `client.releases.*`, `createVersion`) is **not**
+ * intercepted.
+ *
+ * The client itself has no opinion about *what* a guard is — it only provides
+ * the seam and the before/after/identity context. Callers (e.g. a workflow test
+ * bench) supply the policy: evaluate lake mutation guards, enforce field locks,
+ * etc. Keeping the policy in the caller avoids duplicating guard-evaluation
+ * logic the client has no business owning.
+ */
+export declare type MutationGuard = (
+  context: MutationGuardContext,
+) => void | Promise<void>;
+
+/** The kind of write a {@link MutationGuard} is asked to vet. */
+export declare type MutationGuardAction = "create" | "update" | "delete";
+
+/**
+ * The before/after image of a single document write, handed to a
+ * {@link MutationGuard} before it is applied.
+ *
+ * - `before` is null on create; `after` is null on delete.
+ * - `identity` is the acting user — the id bound to the client's token
+ *   (its `accessControl.currentUser`), or undefined when the client has no
+ *   identity configured.
+ *
+ * Treat `before`/`after` as read-only — they are the live store images, not
+ * copies; a guard that mutates them corrupts the store.
+ */
+export declare interface MutationGuardContext {
+  action: MutationGuardAction;
+  before:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  after:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  identity: string | undefined;
+}
+
 /** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
 export declare interface MutationLogEntry {
   transactionId: string;
@@ -706,6 +769,12 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /**
+       * Rebind the acting identity (and its grants) on a sibling that shares
+       * the same store — the test analogue of a token-scoped client. Lets two
+       * actors write the same dataset, e.g. for `identity()`-based guards.
+       */
+      accessControl: TestClientAccessControl;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -718,6 +787,15 @@ export declare interface TestClient {
   snapshot: () => readonly SanityDocument[];
   /** Direct store access for the current dataset. */
   store: () => TestStore;
+  /**
+   * Simulate `count` concurrent edits to `id` in the current dataset: the
+   * next `count` revision-guarded mutations (those passing `ifRevisionId`)
+   * to that document throw a 409-shaped conflict, as if another client
+   * committed between the caller's read and write. Lets a test exercise
+   * optimistic-locking retry paths deterministically, without timing or
+   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
+   */
+  simulateConcurrentEdit: (id: string, count?: number) => void;
   /** List `(projectId, dataset)` pairs known in this registry. */
   datasets: () => {
     projectId: string;

package/dist/index.d.ts

@@ -110,6 +110,15 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Pluggable write interceptor — runs on each write through the document
+   * mutation API (create/patch/delete/transaction; not the release/version
+   * action API) before the store changes, and may throw to reject it. The
+   * client has no opinion about the policy; callers (e.g. a workflow test bench
+   * enforcing lake mutation guards) supply it. Inherited by `withConfig`
+   * siblings. See {@link MutationGuard}.
+   */
+  mutationGuard?: MutationGuard;
   /**
    * Default perspective applied to reads. Per-fetch `options.perspective`
    * overrides this. `withConfig({ perspective })` returns a sibling
@@ -259,6 +268,8 @@ export declare type FakeMutation =
  *
  * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
  *   scoped to the current dataset.
+ * - `simulateConcurrentEdit()` — force the next N revision-guarded writes
+ *   to a document to 409, for optimistic-locking retry tests.
  * - `datasets()` — lists known dataset keys in this registry.
  *
  * Methods deliberately omitted:
@@ -329,6 +340,58 @@ export declare interface MultipleMutationResult {
   }[];
 }
 
+/**
+ * A pluggable write interceptor, configured via
+ * `createTestClient({ mutationGuard })`. It runs on each write through the
+ * document mutation API — `create` / `createOrReplace` / `createIfNotExists` /
+ * `patch` / `delete` and the equivalent `transaction()` operations — before the
+ * store changes; **throw to reject the write** (the throw propagates out of the
+ * client call, exactly as a real lake rejection would). The release/version
+ * action API (`client.action`, `client.releases.*`, `createVersion`) is **not**
+ * intercepted.
+ *
+ * The client itself has no opinion about *what* a guard is — it only provides
+ * the seam and the before/after/identity context. Callers (e.g. a workflow test
+ * bench) supply the policy: evaluate lake mutation guards, enforce field locks,
+ * etc. Keeping the policy in the caller avoids duplicating guard-evaluation
+ * logic the client has no business owning.
+ */
+export declare type MutationGuard = (
+  context: MutationGuardContext,
+) => void | Promise<void>;
+
+/** The kind of write a {@link MutationGuard} is asked to vet. */
+export declare type MutationGuardAction = "create" | "update" | "delete";
+
+/**
+ * The before/after image of a single document write, handed to a
+ * {@link MutationGuard} before it is applied.
+ *
+ * - `before` is null on create; `after` is null on delete.
+ * - `identity` is the acting user — the id bound to the client's token
+ *   (its `accessControl.currentUser`), or undefined when the client has no
+ *   identity configured.
+ *
+ * Treat `before`/`after` as read-only — they are the live store images, not
+ * copies; a guard that mutates them corrupts the store.
+ */
+export declare interface MutationGuardContext {
+  action: MutationGuardAction;
+  before:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  after:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  identity: string | undefined;
+}
+
 /** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
 export declare interface MutationLogEntry {
   transactionId: string;
@@ -706,6 +769,12 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /**
+       * Rebind the acting identity (and its grants) on a sibling that shares
+       * the same store — the test analogue of a token-scoped client. Lets two
+       * actors write the same dataset, e.g. for `identity()`-based guards.
+       */
+      accessControl: TestClientAccessControl;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -718,6 +787,15 @@ export declare interface TestClient {
   snapshot: () => readonly SanityDocument[];
   /** Direct store access for the current dataset. */
   store: () => TestStore;
+  /**
+   * Simulate `count` concurrent edits to `id` in the current dataset: the
+   * next `count` revision-guarded mutations (those passing `ifRevisionId`)
+   * to that document throw a 409-shaped conflict, as if another client
+   * committed between the caller's read and write. Lets a test exercise
+   * optimistic-locking retry paths deterministically, without timing or
+   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
+   */
+  simulateConcurrentEdit: (id: string, count?: number) => void;
   /** List `(projectId, dataset)` pairs known in this registry. */
   datasets: () => {
     projectId: string;

package/dist/index.js

@@ -859,7 +859,13 @@ const RECORDED_METHODS = /* @__PURE__ */ new Set([
   return { projectId, dataset };
 };
 function createTestClient(options = {}) {
-  const defaultProjectId = options.projectId ?? DEFAULT_PROJECT_ID, defaultDataset = options.dataset ?? DEFAULT_DATASET, backend = { registry: /* @__PURE__ */ new Map(), log: [], stubs: /* @__PURE__ */ new Map(), calls: [] }, registry = backend.registry, ensureStore = (projectId, dataset) => {
+  const defaultProjectId = options.projectId ?? DEFAULT_PROJECT_ID, defaultDataset = options.dataset ?? DEFAULT_DATASET, backend = {
+    registry: /* @__PURE__ */ new Map(),
+    log: [],
+    stubs: /* @__PURE__ */ new Map(),
+    calls: [],
+    concurrentEdits: /* @__PURE__ */ new Map()
+  }, registry = backend.registry, ensureStore = (projectId, dataset) => {
     const key = registryKey(projectId, dataset);
     let store = registry.get(key);
     return store === void 0 && (store = createTestStore(), registry.set(key, store)), store;
@@ -874,7 +880,8 @@ function createTestClient(options = {}) {
     defaultProjectId,
     defaultDataset,
     options.accessControl,
-    options.perspective ?? "raw"
+    options.perspective ?? "raw",
+    options.mutationGuard
   );
 }
 function dedupeIds(results) {
@@ -927,12 +934,12 @@ function toTxnMutations(operations) {
     }
   ];
 }
-function makeHandle(backend, projectId, dataset, accessControl, perspective) {
+function makeHandle(backend, projectId, dataset, accessControl, perspective, mutationGuard) {
   const { registry } = backend, store = (() => {
     const key = registryKey(projectId, dataset);
     let s = registry.get(key);
     return s === void 0 && (s = createTestStore(), registry.set(key, s)), s;
-  })(), record = (transactionId, mutations) => {
+  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations) => {
     backend.log.push({ transactionId, projectId, dataset, mutations });
   }, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
     documents,
@@ -960,6 +967,11 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
     };
   }, checkRevision = (id, ifRevisionId) => {
     if (ifRevisionId === void 0) return;
+    const editKey = concurrentEditKey(id), pendingEdits = backend.concurrentEdits.get(editKey) ?? 0;
+    if (pendingEdits > 0)
+      throw backend.concurrentEdits.set(editKey, pendingEdits - 1), fakeError(
+        `ifRevisionId check failed: document "${id}" was concurrently edited (simulated via simulateConcurrentEdit) \u2014 the revision-guarded mutation lost the race; re-read and retry. (This mirrors Sanity's optimistic-locking 409.)`
+      );
     const existing = store.get(id);
     if (existing === void 0)
       throw fakeError(
@@ -976,6 +988,8 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
       permission,
       userId: accessControl.currentUser.id
     });
+  }, guardGate = async (action, before, after) => {
+    mutationGuard !== void 0 && await mutationGuard({ action, before, after, identity: accessControl?.currentUser.id });
   }, canRead = async (document) => accessControl === void 0 ? !0 : canAccess({
     document,
     grants: accessControl.grants,
@@ -993,7 +1007,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
       _rev: cryptoRandomKey(),
       _updatedAt: now
     };
-    return store.put(next), next;
+    return await guardGate("update", existing, next), store.put(next), next;
   }, applyTransaction = async (mutations, txnOptions) => {
     const transactionId = txnOptions?.transactionId ?? cryptoRandomKey(), snapshot = /* @__PURE__ */ new Map(), touchedIds = [], operations = [], remember = (id) => {
       snapshot.has(id) || snapshot.set(id, store.get(id));
@@ -1008,13 +1022,17 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
               throw fakeError(
                 `create() failed: a document with _id "${promoted._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
               );
-            await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
+            await gate(promoted, "create"), await guardGate("create", null, promoted), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
             break;
           }
           case "createOrReplace": {
             remember(mut.doc._id);
             const promoted = promote2(mut.doc), existing = store.get(promoted._id);
-            await gate(existing ?? promoted, existing !== void 0 ? "update" : "create");
+            await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardGate(
+              existing !== void 0 ? "update" : "create",
+              existing ?? null,
+              promoted
+            );
             const wasPresent = existing !== void 0;
             store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: wasPresent ? "update" : "create" });
             break;
@@ -1022,14 +1040,14 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
           case "createIfNotExists": {
             if (remember(mut.doc._id), store.get(mut.doc._id) === void 0) {
               const promoted = promote2(mut.doc);
-              await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
+              await gate(promoted, "create"), await guardGate("create", null, promoted), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
             }
             break;
           }
           case "delete": {
             remember(mut.id);
             const existing = store.get(mut.id);
-            existing !== void 0 && await gate(existing, "update"), store.remove(mut.id) && (touchedIds.push(mut.id), operations.push({ id: mut.id, operation: "delete" }));
+            existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardGate("delete", existing, null), store.remove(mut.id) && (touchedIds.push(mut.id), operations.push({ id: mut.id, operation: "delete" }));
             break;
           }
           case "patch": {
@@ -1101,7 +1119,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
           `create() failed: a document with _id "${doc._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
         );
       const promoted = promote2(doc);
-      await gate(promoted, "create");
+      await gate(promoted, "create"), await guardGate("create", null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       return opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "create", doc }])), writeResult(
         [promoted],
@@ -1113,7 +1131,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
     createOrReplace: async (doc, opts) => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const promoted = promote2(doc), existing = store.get(doc._id);
-      await gate(existing ?? promoted, existing !== void 0 ? "update" : "create");
+      await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardGate(existing !== void 0 ? "update" : "create", existing ?? null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createOrReplace", doc }]));
       const operation = existing !== void 0 ? "update" : "create";
@@ -1135,7 +1153,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
           opts
         );
       const promoted = promote2(doc);
-      return await gate(promoted, "create"), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }])), writeResult(
+      return await gate(promoted, "create"), await guardGate("create", null, promoted), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }])), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
@@ -1145,7 +1163,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
     delete: async (id, opts) => {
       checkRevision(id, opts?.ifRevisionId);
       const existing = store.get(id);
-      existing !== void 0 && await gate(existing, "update");
+      existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardGate("delete", existing, null);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       let removed = existing;
       return opts?.dryRun !== !0 && (removed = store.remove(id), removed !== void 0 && record(transactionId, [{ kind: "delete", id }])), opts?.returnDocuments === void 0 && opts?.returnFirst === void 0 ? removed !== void 0 ? { _id: id } : null : formatMutationResult(
@@ -1214,14 +1232,19 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective) {
       backend,
       config.projectId ?? projectId,
       config.dataset ?? dataset,
-      accessControl,
-      config.perspective ?? perspective
+      config.accessControl ?? accessControl,
+      config.perspective ?? perspective,
+      mutationGuard
     ),
     seed: (documents) => store.seed(documents),
     add: (documents) => store.add(documents),
     reset: () => store.reset(),
     snapshot: () => store.snapshot(),
     store: () => store,
+    simulateConcurrentEdit: (id, count = 1) => {
+      const editKey = concurrentEditKey(id);
+      backend.concurrentEdits.set(editKey, (backend.concurrentEdits.get(editKey) ?? 0) + count);
+    },
     datasets: () => [...registry.keys()].map(parseRegistryKey),
     stub: (name, handler) => {
       backend.stubs.set(name, handler);