@sanity/workflow-engine-test 0.1.0 → 0.2.0

package/README.md

@@ -13,6 +13,45 @@ boilerplate.
 npm install -D @sanity/workflow-engine-test
 ```
 
+## Mutation guards
+
+A workflow stage can deploy **mutation guards** — `temp.system.guard` documents
+that lock the documents it governs while the stage is active, and lift when it
+exits. There are two distinct things you test, and the bench gives you a helper
+for each:
+
+- **Write-time enforcement** — `bench.editDocument(id, patch)` writes through the
+  bench client, which **simulates the lake's server-side guard rejection**: a
+  write a deployed guard denies throws `MutationGuardDeniedError`. In production
+  the lake enforces this for _any_ client; the bench reproduces it on the
+  client it mints.
+- **Read-time preflight** — `bench.activeGuardsForDocument(id)` answers "_would_
+  a write be denied right now?" _without_ writing. This is the check a UI uses
+  to disable a button or show a lock ahead of time. It's a pure read over the
+  same evaluation path as enforcement, so its verdict matches what a write would
+  actually do — and it works against any client.
+
+`bench.listGuards()` returns the deployed guard docs for inspection.
+
+```ts
+const bench = createBench({documents: [{_id: 'doc-1', _type: 'article', body: 'b'}]})
+// …deploy a definition whose current stage locks `doc-1`, start an instance…
+
+// Preflight: is the doc locked for this user right now?
+const active = await bench.activeGuardsForDocument('doc-1')
+
+// Enforcement: a guard-violating write is rejected.
+await expect(bench.editDocument('doc-1', {body: 'edited'})).rejects.toThrow(
+  MutationGuardDeniedError,
+)
+```
+
+> To share one store across benches with enforcement intact, pass another
+> bench's already-wired client: `createBench({client: other.client, tags})`. The
+> `mutationGuard` rides along, so the second bench enforces the same locks. Only
+> a bare hand-built `createTestClient()` opts out of write rejection — the
+> read-time preflight needs no wiring either way.
+
 ## License
 
 [MIT](./LICENSE)