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

package/README.md

@@ -78,7 +78,7 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 | Actions | `action(action \| action[])` | Content Lake release / version actions, applied atomically |
 | Releases | `releases.*`, `createVersion`, `unpublishVersion` | Content Releases lifecycle — create / edit / schedule / publish / archive / delete, plus version create / replace / discard / unpublish |
 | Config | `config()` | Returns `{ projectId, dataset, perspective }` |
-| Config | `withConfig({ projectId?, dataset?, perspective? })` | Sibling handle into the same multi-dataset registry |
+| Config | `withConfig({ projectId?, dataset?, perspective?, accessControl? })` | Sibling handle into the same multi-dataset registry; `accessControl` rebinds the acting identity (a token-scoped sibling sharing the store) |
 | Perspectives | `raw` / `published` / `drafts` / release stacks | Per-client default or per-`fetch` override; draft/version layering with `_originalId` projection |
 | HTTP | `request({ url? \| uri? })` | Present **only** when the client is created with `accessControl`. Serves `/users/me` + the configured ACL path. Calling it without `accessControl` throws a guidance error. |
 
@@ -96,6 +96,44 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 > [!NOTE]
 > The static return type of `create` / `delete` reflects the **default** shape (the document / `{ _id } | null`). When you pass `returnDocuments: false` to get an id-shaped result, supply a type argument or cast — the runtime value is correct either way.
 
+### Gating writes — `mutationGuard`
+
+`createTestClient({ mutationGuard })` installs a pluggable write interceptor. It runs on every write through the document mutation API — `create` / `createOrReplace` / `createIfNotExists` / `patch` / `delete` and the equivalent `transaction()` / `mutate()` operations — _before_ the store changes, and **throws to reject** the write (the throw propagates out of the client call, like a real lake rejection). The release/version action API (`action`, `releases.*`, `createVersion`) is **not** intercepted.
+
+The client owns the _seam_; the caller owns the _policy_. This is the hook a workflow test bench uses to enforce Content Lake **mutation guards** at the write path without re-implementing guard evaluation. Each call receives the before/after image (`before` is `null` on create, `after` is `null` on delete), the `action`, and the acting `identity`.
+
+```ts
+const client = createTestClient({
+  documents: [{ _id: "article-1", _type: "article", body: "draft" }],
+  mutationGuard: ({ action, before, after }) => {
+    // Freeze `body` once an article is locked.
+    if (action === "update" && before?.locked && before.body !== after?.body) {
+      throw new Error("body is locked");
+    }
+  },
+});
+
+await client.patch("article-1").set({ title: "ok" }).commit(); // allowed
+await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toThrow();
+```
+
+#### Identity is the token
+
+`identity` is the id bound to the client's token — its `accessControl.currentUser`. To act as a different user against the **same** store (e.g. to exercise `identity()`-based guards), branch a token-scoped sibling with `withConfig({ accessControl })`:
+
+```ts
+const alice = createTestClient({
+  documents: [article],
+  accessControl: { currentUser: { id: "alice" }, grants },
+  mutationGuard: onlyTheAssignedReviewerMayWrite,
+});
+const bob = alice.withConfig({ accessControl: { currentUser: { id: "bob" }, grants } });
+// alice and bob share one store; each write carries its own identity().
+```
+
+> [!NOTE]
+> Treat `before` / `after` as read-only — they are the live store images, not copies; mutating them corrupts the store.
+
 ### Test-only helpers (not on real `SanityClient`)
 
 Useful in test bodies, but a giveaway that the code under test isn't using the real client. Keep them in the test file, not in the code being tested.

package/dist/index.cjs

@@ -876,7 +876,8 @@ function createTestClient(options = {}) {
     defaultProjectId,
     defaultDataset,
     options.accessControl,
-    options.perspective ?? "raw"
+    options.perspective ?? "raw",
+    options.mutationGuard
   );
 }
 function dedupeIds(results) {
@@ -929,7 +930,7 @@ 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);
@@ -978,6 +979,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,
@@ -995,7 +998,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));
@@ -1010,13 +1013,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;
@@ -1024,14 +1031,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": {
@@ -1103,7 +1110,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],
@@ -1115,7 +1122,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";
@@ -1137,7 +1144,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,
@@ -1147,7 +1154,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(
@@ -1216,8 +1223,9 @@ 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),