@sanity-labs/client-fake-for-test 0.3.0 → 0.4.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
@@ -329,6 +338,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 +767,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. */

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
@@ -329,6 +338,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 +767,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. */

package/dist/index.js

@@ -874,7 +874,8 @@ function createTestClient(options = {}) {
     defaultProjectId,
     defaultDataset,
     options.accessControl,
-    options.perspective ?? "raw"
+    options.perspective ?? "raw",
+    options.mutationGuard
   );
 }
 function dedupeIds(results) {
@@ -927,7 +928,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);
@@ -976,6 +977,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 +996,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 +1011,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 +1029,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 +1108,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 +1120,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 +1142,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 +1152,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,8 +1221,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),