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

package/dist/index.js

@@ -1,4 +1,8 @@
 import { parse, evaluate } from "groq-js";
+const ERR_PREFIX = "[client-fake-for-test]";
+function fakeError(message) {
+  return new Error(`${ERR_PREFIX} ${message}`);
+}
 class WriteAccessDeniedError extends Error {
   documentId;
   permission;
@@ -63,17 +67,21 @@ function makeRequestImpl(accessControl, projectId, dataset) {
       return accessControl.currentUser;
     if (path === aclPath)
       return accessControl.grants;
-    throw new Error(
-      `TestClient.request: no handler for path "${path}". The TestClient only serves "/users/me" and "${aclPath}". Configure additional endpoints via createTestClient({ accessControl }).`
+    throw fakeError(
+      `request(): no handler for path "${path}". With accessControl configured, the fake only serves "/users/me" and "${aclPath}". For any other endpoint, register a stub (client.stub("request", fn)) or intercept the HTTP call with a tool like MSW.`
     );
   };
 }
 function createTestStore(initial) {
   const docs = /* @__PURE__ */ new Map(), promote2 = (doc) => {
     if (typeof doc._id != "string" || doc._id.length === 0)
-      throw new Error(`document is missing _id: ${JSON.stringify(doc)}`);
+      throw fakeError(
+        `Cannot seed/store a document without a non-empty string \`_id\` (got ${JSON.stringify(doc._id)}). This fake never auto-generates ids \u2014 give every document an explicit _id. Document: ${JSON.stringify(doc)}`
+      );
     if (typeof doc._type != "string" || doc._type.length === 0)
-      throw new Error(`document ${doc._id} is missing _type`);
+      throw fakeError(
+        `Document "${doc._id}" is missing a non-empty string \`_type\` (got ${JSON.stringify(doc._type)}). Every Sanity document needs a _type.`
+      );
     const now = (/* @__PURE__ */ new Date()).toISOString();
     return {
       ...doc,
@@ -115,6 +123,9 @@ function cryptoRandomKey(length = 12) {
   const bytes = new Uint8Array(length);
   return globalThis.crypto.getRandomValues(bytes), [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, length);
 }
+function describeType(value) {
+  return value === null ? "null" : Array.isArray(value) ? "an array" : `a ${typeof value}`;
+}
 function createPatch(documentId, executor) {
   const ops = [];
   let ifRev;
@@ -175,7 +186,10 @@ function parsePath(path) {
   const segments = [];
   for (const raw of path.split(".")) {
     const match = /^([A-Za-z_$][\w$]*)(?:\[(.+)\])?$/.exec(raw);
-    if (!match) throw new Error(`Unsupported patch path segment: ${raw}`);
+    if (!match)
+      throw fakeError(
+        `Unsupported patch path segment "${raw}" (in path "${path}"). This fake supports dotted field access ("a.b.c"), array index ("items[0]"), and keyed lookup (\`items[_key=="x"]\`). Recursive descent ("..") and GROQ filter expressions are not supported.`
+      );
     const key = match[1], selectorRaw = match[2];
     if (selectorRaw === void 0) {
       segments.push({ key });
@@ -194,7 +208,9 @@ function parsePath(path) {
       });
       continue;
     }
-    throw new Error(`Unsupported array selector in patch path: ${selectorRaw}`);
+    throw fakeError(
+      `Unsupported array selector "[${selectorRaw}]" in patch path "${path}". Supported selectors are a numeric index (e.g. "[0]") and a single keyed match (e.g. \`[_key=="abc"]\`). Multi-key matches and arbitrary GROQ filters are not supported.`
+    );
   }
   return segments;
 }
@@ -204,7 +220,9 @@ function resolveSelector(array, selector) {
     (entry) => typeof entry == "object" && entry !== null && entry[selector.field] === selector.value
   );
   if (idx === -1)
-    throw new Error(`No array entry matched ${selector.field}=="${selector.value}" in patch path`);
+    throw fakeError(
+      `Patch path matched no array entry where ${selector.field}=="${selector.value}". The array has ${array.length} item(s); check the key exists (and that you're patching the right document).`
+    );
   return idx;
 }
 function getAtPath(doc, path) {
@@ -222,14 +240,17 @@ function getAtPath(doc, path) {
 }
 function setAtPath(doc, path, value) {
   const segments = parsePath(path);
-  if (segments.length === 0) throw new Error("Empty patch path");
+  if (segments.length === 0)
+    throw fakeError("Empty patch path \u2014 a set/setIfMissing op needs a target field.");
   let cursor = doc;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i];
     let next = cursor[seg.key];
     if (next === void 0 && (next = seg.selector?.kind === "index" || seg.selector?.kind === "keyed" ? [] : {}, cursor[seg.key] = next), seg.selector !== void 0) {
       if (!Array.isArray(next))
-        throw new Error(`Patch path crosses non-array at segment ${seg.key}`);
+        throw fakeError(
+          `Patch path "${path}" applies an array selector to field "${seg.key}", but that field holds ${describeType(next)}, not an array.`
+        );
       const idx = resolveSelector(next, seg.selector);
       cursor = next[idx];
     } else
@@ -239,7 +260,9 @@ function setAtPath(doc, path, value) {
   if (last.selector !== void 0) {
     const arr = cursor[last.key];
     if (!Array.isArray(arr))
-      throw new Error(`Patch path crosses non-array at segment ${last.key}`);
+      throw fakeError(
+        `Patch path "${path}" applies an array selector to field "${last.key}", but that field holds ${describeType(arr)}, not an array.`
+      );
     const idx = resolveSelector(arr, last.selector);
     arr[idx] = value;
   } else
@@ -271,41 +294,56 @@ function unsetAtPath(doc, path) {
 }
 function insertIntoArray(doc, position, anchor, items) {
   const segments = parsePath(anchor);
-  if (segments.length === 0) throw new Error("Empty insert anchor");
+  if (segments.length === 0)
+    throw fakeError("Empty insert anchor \u2014 insert() needs an array path to anchor against.");
   const last = segments[segments.length - 1];
   if (last.selector === void 0)
-    throw new Error(`Insert anchor must end with an array selector: ${anchor}`);
+    throw fakeError(
+      `Insert anchor "${anchor}" must end with an array selector (an index like "[0]" or a keyed match like \`[_key=="x"]\`) so the fake knows where in the array to insert.`
+    );
   let cursor = doc;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i], next = cursor[seg.key];
     if (next == null)
-      throw new Error(`Insert anchor traverses missing field: ${seg.key}`);
+      throw fakeError(
+        `Insert anchor "${anchor}" traverses field "${seg.key}", which is missing on the document. setIfMissing the parent first, or anchor against an existing array.`
+      );
     if (seg.selector !== void 0) {
       if (!Array.isArray(next))
-        throw new Error(`Insert anchor traverses non-array at: ${seg.key}`);
+        throw fakeError(
+          `Insert anchor "${anchor}" applies an array selector to field "${seg.key}", but it holds ${describeType(next)}, not an array.`
+        );
       cursor = next[resolveSelector(next, seg.selector)];
     } else
       cursor = next;
   }
   const arr = cursor[last.key];
   if (!Array.isArray(arr))
-    throw new Error(`Insert anchor target is not an array: ${last.key}`);
+    throw fakeError(
+      `Insert anchor "${anchor}" targets field "${last.key}", but it holds ${describeType(arr)}, not an array.`
+    );
   const idx = resolveSelector(arr, last.selector);
   position === "replace" ? arr.splice(idx, 1, ...items) : position === "before" ? arr.splice(idx, 0, ...items) : arr.splice(idx + 1, 0, ...items);
 }
 const RELEASE_DOC_PREFIX$1 = "_.releases.", VERSIONS_PREFIX$1 = "versions.", releaseDocId = (releaseId) => `${RELEASE_DOC_PREFIX$1}${releaseId}`, versionDocId = (releaseId, publishedId) => `${VERSIONS_PREFIX$1}${releaseId}.${publishedId}`;
 function parseVersionId(versionId) {
   if (!versionId.startsWith(VERSIONS_PREFIX$1))
-    throw new Error(`Not a version id: ${versionId}`);
+    throw fakeError(
+      `"${versionId}" is not a version document id. Version ids look like "versions.<releaseId>.<publishedId>" (e.g. "versions.summer-drop.product-1").`
+    );
   const rest = versionId.slice(VERSIONS_PREFIX$1.length), dot = rest.indexOf(".");
   if (dot === -1)
-    throw new Error(`Not a version id: ${versionId}`);
+    throw fakeError(
+      `"${versionId}" is not a version document id. Version ids look like "versions.<releaseId>.<publishedId>" (e.g. "versions.summer-drop.product-1").`
+    );
   return { releaseId: rest.slice(0, dot), publishedId: rest.slice(dot + 1) };
 }
 function getRelease(store, releaseId) {
   const doc = store.get(releaseDocId(releaseId));
   if (doc === void 0)
-    throw new Error(`Release not found: ${releaseId}`);
+    throw fakeError(
+      `Release "${releaseId}" not found. Create it first with client.releases.create({ releaseId: "${releaseId}" }) (or a "sanity.action.release.create" action) before editing, scheduling, or adding versions to it.`
+    );
   return doc;
 }
 function maybeRelease(store, releaseId) {
@@ -335,15 +373,17 @@ function bumpRev(doc, patch) {
 }
 function requireActive(release) {
   if (release.state !== "active")
-    throw new Error(
-      `Release ${release.name} is ${release.state}; only active releases accept version writes`
+    throw fakeError(
+      `Release "${release.name}" is "${release.state}", but only "active" releases accept version writes (create / replace / discard / unpublish). Unschedule or unarchive it back to "active" first, or target a different release.`
     );
 }
 function applyAction(store, action) {
   switch (action.actionType) {
     case "sanity.action.release.create": {
       if (maybeRelease(store, action.releaseId) !== void 0)
-        throw new Error(`Release ${action.releaseId} already exists`);
+        throw fakeError(
+          `Release "${action.releaseId}" already exists. release.create expects a new releaseId; use release.edit to change its metadata, or pick a different releaseId.`
+        );
       const now = nowIso(), metadata = {
         releaseType: "undecided",
         ...action.metadata
@@ -368,7 +408,9 @@ function applyAction(store, action) {
     case "sanity.action.release.schedule": {
       const release = getRelease(store, action.releaseId);
       if (release.state !== "active")
-        throw new Error(`Cannot schedule release in state ${release.state}`);
+        throw fakeError(
+          `Cannot schedule release "${action.releaseId}": it is "${release.state}", and only "active" releases can be scheduled.`
+        );
       return store.put(
         bumpRev(release, {
           state: "scheduled",
@@ -379,7 +421,9 @@ function applyAction(store, action) {
     case "sanity.action.release.unschedule": {
       const release = getRelease(store, action.releaseId);
       if (release.state !== "scheduled")
-        throw new Error(`Cannot unschedule release in state ${release.state}`);
+        throw fakeError(
+          `Cannot unschedule release "${action.releaseId}": it is "${release.state}", and only "scheduled" releases can be unscheduled.`
+        );
       const next = { ...release, state: "active" };
       return delete next.publishAt, store.put(bumpRev(next, {})), { transactionId: cryptoRandomKey() };
     }
@@ -388,7 +432,9 @@ function applyAction(store, action) {
       if (release.state === "published")
         return { transactionId: cryptoRandomKey() };
       if (release.state !== "active" && release.state !== "scheduled")
-        throw new Error(`Cannot publish release in state ${release.state}`);
+        throw fakeError(
+          `Cannot publish release "${action.releaseId}": it is "${release.state}", and only "active" or "scheduled" releases can be published.`
+        );
       const prefix = `${VERSIONS_PREFIX$1}${action.releaseId}.`, sources = store.all().filter((d) => d._id.startsWith(prefix));
       for (const v of sources) {
         const pubId = v._id.slice(prefix.length);
@@ -410,20 +456,24 @@ function applyAction(store, action) {
     case "sanity.action.release.archive": {
       const release = getRelease(store, action.releaseId);
       if (release.state !== "active" && release.state !== "scheduled")
-        throw new Error(`Cannot archive release in state ${release.state}`);
+        throw fakeError(
+          `Cannot archive release "${action.releaseId}": it is "${release.state}", and only "active" or "scheduled" releases can be archived.`
+        );
       return store.put(bumpRev(release, { state: "archived" })), { transactionId: cryptoRandomKey() };
     }
     case "sanity.action.release.unarchive": {
       const release = getRelease(store, action.releaseId);
       if (release.state !== "archived")
-        throw new Error(`Cannot unarchive release in state ${release.state}`);
+        throw fakeError(
+          `Cannot unarchive release "${action.releaseId}": it is "${release.state}", and only "archived" releases can be unarchived.`
+        );
       return store.put(bumpRev(release, { state: "active" })), { transactionId: cryptoRandomKey() };
     }
     case "sanity.action.release.delete": {
       const release = getRelease(store, action.releaseId);
       if (release.state !== "archived" && release.state !== "published")
-        throw new Error(
-          `Cannot delete release in state ${release.state}; archive or publish it first`
+        throw fakeError(
+          `Cannot delete release "${action.releaseId}": it is "${release.state}", and only "archived" or "published" releases can be deleted. Archive it first (sanity.action.release.archive) or publish it.`
         );
       const prefix = `${VERSIONS_PREFIX$1}${action.releaseId}.`;
       for (const v of store.all())
@@ -433,7 +483,9 @@ function applyAction(store, action) {
     case "sanity.action.document.version.create": {
       const releaseId = action.releaseId ?? (action.document._id !== void 0 ? parseVersionId(action.document._id).releaseId : void 0);
       if (releaseId === void 0)
-        throw new Error("version.create needs releaseId or a document._id that encodes it");
+        throw fakeError(
+          'version.create needs a release to attach to: pass `releaseId`, or a `document._id` shaped "versions.<releaseId>.<publishedId>" so the release can be inferred.'
+        );
       const release = getRelease(store, releaseId);
       requireActive(release);
       const vid = versionDocId(releaseId, action.publishedId), doc = {
@@ -445,7 +497,9 @@ function applyAction(store, action) {
     case "sanity.action.document.version.replace": {
       const id = action.document._id;
       if (typeof id != "string")
-        throw new Error("version.replace needs document._id");
+        throw fakeError(
+          'version.replace needs `document._id` (a version id like "versions.<releaseId>.<publishedId>") to identify which version document to replace.'
+        );
       const { releaseId } = parseVersionId(id), release = getRelease(store, releaseId);
       requireActive(release);
       const existing = store.get(id), promoted = promote(action.document);
@@ -619,12 +673,193 @@ function createTransaction(executor) {
   };
   return handle;
 }
-const DEFAULT_PROJECT_ID = "test", DEFAULT_DATASET = "test", registryKey = (projectId, dataset) => `${projectId}:${dataset}`, parseRegistryKey = (key) => {
+const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues", SUPPORTED_SURFACE = [
+  "fetch",
+  "getDocument",
+  "getDocuments",
+  "create",
+  "createOrReplace",
+  "createIfNotExists",
+  "delete",
+  "patch",
+  "transaction",
+  "mutate",
+  "action",
+  "releases",
+  "createVersion",
+  "unpublishVersion",
+  "request (only with accessControl)",
+  "config",
+  "withConfig"
+], UNSUPPORTED_MEMBERS = {
+  listen: {
+    what: "real-time listener (returns an RxJS Observable of mutation events)",
+    workaround: 'Test your subscription logic in isolation, or register a fake: client.stub("listen", () => myFakeObservable).'
+  },
+  observable: {
+    what: "the RxJS-flavoured mirror of the client API",
+    workaround: "Use the Promise-based methods and wrap them with `from()` if you need an Observable."
+  },
+  clone: {
+    what: "clone the client with the same config",
+    workaround: "Use `withConfig({})` \u2014 it returns a sibling handle into the same store."
+  },
+  getUrl: {
+    what: "build an absolute API URL for a path",
+    workaround: "Hard-code the expected URL in your test, or stub it."
+  },
+  getDataUrl: {
+    what: "build an absolute data-API URL",
+    workaround: "Hard-code the expected URL in your test, or stub it."
+  },
+  assets: {
+    what: "asset upload / metadata namespace",
+    workaround: "Seed asset documents into the store directly with `seed()` / `add()`."
+  },
+  agent: {
+    what: "Agent Actions namespace (generate / transform / \u2026)",
+    workaround: 'Stub the call site: client.stub("agent", myFakeAgent).'
+  },
+  projects: {
+    what: "project-management namespace",
+    workaround: "Out of scope for a data-plane fake \u2014 stub the call site."
+  },
+  users: {
+    what: "user-management namespace",
+    workaround: "Out of scope for a data-plane fake \u2014 stub the call site."
+  },
+  live: {
+    what: "Live Content API namespace",
+    workaround: "Out of scope \u2014 stub the call site or test the consumer separately."
+  },
+  mediaLibrary: {
+    what: "Media Library namespace",
+    workaround: "Out of scope \u2014 seed documents directly or stub the call site."
+  },
+  request: {
+    what: "generic HTTP request hook \u2014 only wired up when accessControl is configured",
+    workaround: "Create the client with `accessControl` to enable request() (it serves /users/me + the ACL path), or register a stub."
+  },
+  dryRun: {
+    what: "not a method \u2014 did you mean the `{ dryRun }` mutation option?",
+    workaround: "Pass `{ dryRun: true }` as the second arg to create / mutate / delete."
+  }
+}, PROBE_NAMES = /* @__PURE__ */ new Set([
+  "then",
+  "catch",
+  "finally",
+  "toJSON",
+  "asymmetricMatch",
+  "$$typeof",
+  "nodeType",
+  "_isMockFunction"
+]);
+function guardMessage(path, detail, workaround) {
+  return [
+    `[client-fake-for-test] \`client.${path}\` ${detail}`,
+    "",
+    "This is an in-memory fake of @sanity/client. It implements:",
+    `  ${SUPPORTED_SURFACE.join(", ")}.`,
+    "",
+    `\u2192 ${workaround}`,
+    "",
+    `Register a stub to fill any gap:  client.stub(${JSON.stringify(path.split(".")[0])}, handler)`,
+    `If this should be supported, open an issue: ${ISSUES_URL}`
+  ].join(`
+`);
+}
+function makeGuard(path, message) {
+  const thrower = () => {
+    throw new Error(message);
+  };
+  return new Proxy(thrower, {
+    apply: () => thrower(),
+    get: (_t, prop) => {
+      if (typeof prop == "symbol" || PROBE_NAMES.has(prop)) return;
+      const childPath = `${path}.${String(prop)}`, top = path.split(".")[0], entry = UNSUPPORTED_MEMBERS[top], detail = entry ? `is not implemented (${entry.what}).` : "is not implemented.", workaround = entry?.workaround ?? "Register a stub or use a different test strategy.";
+      return makeGuard(childPath, guardMessage(childPath, detail, workaround));
+    }
+  });
+}
+function wrapRecorded(method, fn, onCall) {
+  return (...args) => {
+    const settle = onCall(method, args);
+    try {
+      const out = fn(...args);
+      return out !== null && typeof out == "object" && typeof out.then == "function" ? out.then(
+        (result) => (settle({ result }), result),
+        (error) => {
+          throw settle({ error }), error;
+        }
+      ) : (settle({ result: out }), out);
+    } catch (error) {
+      throw settle({ error }), error;
+    }
+  };
+}
+function wrapNamespace(ns, prefix, onCall) {
+  return new Proxy(ns, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      return typeof prop == "string" && typeof value == "function" ? wrapRecorded(`${prefix}.${prop}`, value, onCall) : value;
+    }
+  });
+}
+function wrapWithGuards(client, config) {
+  const { getStub, onCall, recorded } = config;
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      if (typeof prop == "symbol") return Reflect.get(target, prop, receiver);
+      if (prop in target) {
+        const value = Reflect.get(target, prop, receiver);
+        if (onCall !== void 0 && recorded?.has(prop) === !0) {
+          if (typeof value == "function")
+            return wrapRecorded(prop, value, onCall);
+          if (value !== null && typeof value == "object")
+            return wrapNamespace(value, prop, onCall);
+        }
+        return value;
+      }
+      if (PROBE_NAMES.has(prop)) return;
+      const stub = getStub(prop);
+      if (stub !== void 0) return stub;
+      const entry = UNSUPPORTED_MEMBERS[prop];
+      return entry !== void 0 ? makeGuard(
+        prop,
+        guardMessage(prop, `is not implemented (${entry.what}).`, entry.workaround)
+      ) : makeGuard(
+        prop,
+        guardMessage(
+          prop,
+          "is not a method on this fake (unknown member or unimplemented @sanity/client API).",
+          "Check for a typo, register a stub, or use a different test strategy."
+        )
+      );
+    }
+  });
+}
+const RECORDED_METHODS = /* @__PURE__ */ new Set([
+  "fetch",
+  "getDocument",
+  "getDocuments",
+  "create",
+  "createOrReplace",
+  "createIfNotExists",
+  "delete",
+  "patch",
+  "transaction",
+  "mutate",
+  "action",
+  "releases",
+  "createVersion",
+  "unpublishVersion",
+  "request"
+]), DEFAULT_PROJECT_ID = "test", DEFAULT_DATASET = "test", registryKey = (projectId, dataset) => `${projectId}:${dataset}`, parseRegistryKey = (key) => {
   const [projectId, dataset] = key.split(":");
   return { projectId, dataset };
 };
 function createTestClient(options = {}) {
-  const defaultProjectId = options.projectId ?? DEFAULT_PROJECT_ID, defaultDataset = options.dataset ?? DEFAULT_DATASET, registry = /* @__PURE__ */ new Map(), 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: [] }, 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;
@@ -635,24 +870,87 @@ function createTestClient(options = {}) {
       ensureStore(projectId, dataset).seed(docs);
     }
   return makeHandle(
-    registry,
+    backend,
     defaultProjectId,
     defaultDataset,
     options.accessControl,
-    options.perspective ?? "raw"
+    options.perspective ?? "raw",
+    options.mutationGuard
   );
 }
-function makeHandle(registry, projectId, dataset, accessControl, perspective) {
-  const store = (() => {
+function dedupeIds(results) {
+  const seen = /* @__PURE__ */ new Set(), out = [];
+  for (const r of results)
+    seen.has(r.id) || (seen.add(r.id), out.push(r.id));
+  return out;
+}
+function formatMutationResult(documents, results, transactionId, returnDocuments, returnFirst) {
+  return returnDocuments ? returnFirst ? documents[0] : documents : returnFirst ? {
+    transactionId,
+    documentId: results[0]?.id,
+    results
+  } : {
+    transactionId,
+    documentIds: dedupeIds(results),
+    results
+  };
+}
+function toSingleTxnMutation(op) {
+  if ("create" in op) return { kind: "create", doc: op.create };
+  if ("createOrReplace" in op) return { kind: "createOrReplace", doc: op.createOrReplace };
+  if ("createIfNotExists" in op) return { kind: "createIfNotExists", doc: op.createIfNotExists };
+  if ("delete" in op) return { kind: "delete", id: op.delete.id };
+  const p = op.patch, ops = [];
+  if (p.set !== void 0 && ops.push({ kind: "set", props: p.set }), p.setIfMissing !== void 0 && ops.push({ kind: "setIfMissing", props: p.setIfMissing }), p.unset !== void 0 && ops.push({ kind: "unset", paths: p.unset }), p.inc !== void 0 && ops.push({ kind: "inc", props: p.inc }), p.dec !== void 0 && ops.push({ kind: "dec", props: p.dec }), p.insert !== void 0) {
+    const { before, after, replace, items } = p.insert, position = before !== void 0 ? "before" : after !== void 0 ? "after" : "replace", anchor = before ?? after ?? replace;
+    if (anchor === void 0)
+      throw fakeError(
+        'mutate(): a `patch.insert` operation must name exactly one anchor \u2014 `before`, `after`, or `replace` \u2014 pointing at an array path (e.g. "tags[-1]" or `tags[_key=="x"]`), alongside `items`. None was set.'
+      );
+    ops.push({ kind: "insert", position, anchor, items });
+  }
+  return {
+    kind: "patch",
+    documentId: p.id,
+    ops,
+    ...p.ifRevisionID !== void 0 ? { ifRev: p.ifRevisionID } : {}
+  };
+}
+function toTxnMutations(operations) {
+  if (Array.isArray(operations)) return operations.map(toSingleTxnMutation);
+  const json = operations.toJSON();
+  return Array.isArray(json) ? json : [
+    {
+      kind: "patch",
+      documentId: json.id,
+      ops: json.ops,
+      ...json.ifRev !== void 0 ? { ifRev: json.ifRev } : {}
+    }
+  ];
+}
+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;
-  })(), promote2 = (doc) => {
+  })(), record = (transactionId, mutations) => {
+    backend.log.push({ transactionId, projectId, dataset, mutations });
+  }, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
+    documents,
+    results,
+    transactionId,
+    opts?.returnDocuments ?? !0,
+    opts?.returnFirst ?? !0
+  ), promote2 = (doc) => {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     if (typeof doc._id != "string" || doc._id.length === 0)
-      throw new Error("document is missing _id");
+      throw fakeError(
+        `Cannot store a document without a non-empty string \`_id\` (got ${JSON.stringify(doc._id)}). Unlike @sanity/client, this fake never auto-generates ids \u2014 give every document an explicit _id.`
+      );
     if (typeof doc._type != "string" || doc._type.length === 0)
-      throw new Error(`document ${doc._id} is missing _type`);
+      throw fakeError(
+        `Document "${doc._id}" is missing a non-empty string \`_type\` (got ${JSON.stringify(doc._type)}). Every Sanity document needs a _type.`
+      );
     return {
       ...doc,
       _id: doc._id,
@@ -665,10 +963,12 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
     if (ifRevisionId === void 0) return;
     const existing = store.get(id);
     if (existing === void 0)
-      throw new Error(`ifRevisionId check failed: document ${id} does not exist`);
+      throw fakeError(
+        `ifRevisionId check failed: document "${id}" does not exist, so its revision cannot match the expected _rev="${ifRevisionId}". Drop ifRevisionId when creating a new document, or seed/create the document before guarding on its revision.`
+      );
     if (existing._rev !== ifRevisionId)
-      throw new Error(
-        `ifRevisionId check failed: document ${id} has _rev=${existing._rev}, expected ${ifRevisionId}`
+      throw fakeError(
+        `ifRevisionId check failed: document "${id}" is at _rev="${existing._rev}" but the mutation required _rev="${ifRevisionId}". The document changed since you read it \u2014 re-read it and retry. (This mirrors Sanity's optimistic-locking 409.)`
       );
   }, gate = async (document, permission) => {
     accessControl !== void 0 && await enforceWriteAccess({
@@ -677,6 +977,8 @@ function makeHandle(registry, 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,
@@ -685,16 +987,18 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
   }), applyPatch = async (documentId, ops, ifRev) => {
     const existing = store.get(documentId);
     if (existing === void 0)
-      throw new Error(`Cannot patch document ${documentId}: not found`);
+      throw fakeError(
+        `Cannot patch document "${documentId}": not found \u2014 no document with that _id exists in dataset "${projectId}:${dataset}". patch() requires the target to already exist; use createOrReplace() / createIfNotExists() to upsert, or seed the document first.`
+      );
     checkRevision(documentId, ifRev), await gate(existing, "update");
     const patched = applyPatchOps(existing, ops), now = (/* @__PURE__ */ new Date()).toISOString(), next = {
       ...patched,
       _rev: cryptoRandomKey(),
       _updatedAt: now
     };
-    return store.put(next), next;
+    return await guardGate("update", existing, next), store.put(next), next;
   }, applyTransaction = async (mutations, txnOptions) => {
-    const snapshot = /* @__PURE__ */ new Map(), touchedIds = [], operations = [], remember = (id) => {
+    const transactionId = txnOptions?.transactionId ?? cryptoRandomKey(), snapshot = /* @__PURE__ */ new Map(), touchedIds = [], operations = [], remember = (id) => {
       snapshot.has(id) || snapshot.set(id, store.get(id));
     };
     try {
@@ -704,14 +1008,20 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
             remember(mut.doc._id);
             const promoted = promote2(mut.doc);
             if (store.get(promoted._id) !== void 0)
-              throw new Error(`create failed: document ${promoted._id} already exists`);
-            await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
+              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"), 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;
@@ -719,14 +1029,14 @@ function makeHandle(registry, 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": {
@@ -739,14 +1049,15 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
         doc === void 0 ? store.remove(id) : store.put(doc);
       throw error;
     }
-    if (txnOptions?.returnDocuments) {
-      const docs = touchedIds.map((id) => store.get(id)).filter((d) => d !== void 0);
-      return txnOptions.returnFirst ? docs[0] : docs;
-    }
-    return {
-      transactionId: cryptoRandomKey(),
-      results: operations
-    };
+    record(transactionId, mutations);
+    const documents = touchedIds.map((id) => store.get(id)).filter((d) => d !== void 0);
+    return formatMutationResult(
+      documents,
+      operations,
+      transactionId,
+      txnOptions?.returnDocuments ?? !1,
+      txnOptions?.returnFirst ?? !1
+    );
   }, accessVisibleDocs = async () => {
     const all = store.all();
     if (accessControl === void 0) return all;
@@ -757,23 +1068,26 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
   }, visibleDocs = async (override) => {
     const accessible = await accessVisibleDocs();
     return applyPerspective(accessible, override ?? perspective);
-  };
-  return {
+  }, client = {
     fetch: async (query, params, opts) => {
-      const tree = parse(query, params ? { params } : void 0);
-      return await (await evaluate(tree, {
+      const start = Date.now(), tree = parse(query, params ? { params } : void 0), result = await (await evaluate(tree, {
         dataset: await visibleDocs(opts?.perspective),
         ...params !== void 0 ? { params } : {}
       })).get();
+      if (opts?.filterResponse === !1) {
+        const ms = Date.now() - start;
+        return opts.returnQuery === !1 ? { ms, result } : { query, ms, result };
+      }
+      return result;
     },
     getDocument: async (id, opts) => {
       const effective = opts?.perspective ?? perspective;
       if (effective === "raw") {
         const doc = store.get(id);
-        return doc === void 0 || !await canRead(doc) ? null : doc;
+        return doc === void 0 || !await canRead(doc) ? void 0 : doc;
       }
       const view = await visibleDocs(effective);
-      return resolveDocument(view, id, effective) ?? null;
+      return resolveDocument(view, id, effective) ?? void 0;
     },
     getDocuments: async (ids, opts) => {
       const effective = opts?.perspective ?? perspective;
@@ -790,29 +1104,75 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
     },
     create: async (doc, opts) => {
       if (checkRevision(doc._id, opts?.ifRevisionId), store.get(doc._id) !== void 0)
-        throw new Error(`create failed: document ${doc._id} already exists`);
+        throw fakeError(
+          `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);
-      return await gate(promoted, "create"), store.put(promoted), promoted;
+      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],
+        [{ id: promoted._id, operation: "create" }],
+        transactionId,
+        opts
+      );
     },
     createOrReplace: async (doc, opts) => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const promoted = promote2(doc), existing = store.get(doc._id);
-      return await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), store.put(promoted), promoted;
+      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";
+      return writeResult(
+        [promoted],
+        [{ id: promoted._id, operation }],
+        transactionId,
+        opts
+      );
     },
     createIfNotExists: async (doc, opts) => {
       checkRevision(doc._id, opts?.ifRevisionId);
-      const existing = store.get(doc._id);
-      if (existing !== void 0) return existing;
+      const existing = store.get(doc._id), transactionId = opts?.transactionId ?? cryptoRandomKey();
+      if (existing !== void 0)
+        return writeResult(
+          [existing],
+          [{ id: existing._id, operation: "none" }],
+          transactionId,
+          opts
+        );
       const promoted = promote2(doc);
-      return await gate(promoted, "create"), store.put(promoted), promoted;
+      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,
+        opts
+      );
     },
     delete: async (id, opts) => {
       checkRevision(id, opts?.ifRevisionId);
       const existing = store.get(id);
-      return existing !== void 0 && await gate(existing, "update"), store.remove(id) ? { _id: id } : null;
+      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(
+        removed !== void 0 ? [removed] : [],
+        removed !== void 0 ? [{ id, operation: "delete" }] : [],
+        transactionId,
+        opts.returnDocuments ?? !0,
+        opts.returnFirst ?? !0
+      );
     },
-    patch: (documentId) => createPatch(documentId, { apply: applyPatch }),
+    patch: (documentId) => createPatch(documentId, {
+      apply: async (docId, ops, ifRev) => {
+        const doc = await applyPatch(docId, ops, ifRev);
+        return record(cryptoRandomKey(), [
+          { kind: "patch", documentId: docId, ops, ...ifRev !== void 0 ? { ifRev } : {} }
+        ]), doc;
+      }
+    }),
     transaction: () => createTransaction({ apply: applyTransaction }),
+    mutate: async (operations, options) => applyTransaction(toTxnMutations(operations), options),
     action: async (action) => applyActions(store, action),
     releases: {
       create: async ({ releaseId, metadata }) => {
@@ -858,21 +1218,49 @@ function makeHandle(registry, projectId, dataset, accessControl, perspective) {
     ...accessControl !== void 0 ? { request: makeRequestImpl(accessControl, projectId, dataset) } : {},
     config: () => ({ projectId, dataset, perspective }),
     withConfig: (config) => makeHandle(
-      registry,
+      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,
-    datasets: () => [...registry.keys()].map(parseRegistryKey)
+    datasets: () => [...registry.keys()].map(parseRegistryKey),
+    stub: (name, handler) => {
+      backend.stubs.set(name, handler);
+    },
+    stubs: () => Object.fromEntries(backend.stubs),
+    mutations: () => backend.log.flatMap((entry) => entry.mutations),
+    transactions: () => [...backend.log],
+    clearLog: () => {
+      backend.log.length = 0;
+    },
+    calls: (method) => method === void 0 ? [...backend.calls] : backend.calls.filter((c) => c.method === method),
+    callCount: (method) => method === void 0 ? backend.calls.length : backend.calls.filter((c) => c.method === method).length,
+    clearCalls: () => {
+      backend.calls.length = 0;
+    }
   };
+  return wrapWithGuards(client, {
+    getStub: (name) => backend.stubs.get(name),
+    onCall: (method, args) => {
+      const rec = { method, args, projectId, dataset };
+      return backend.calls.push(rec), (outcome) => {
+        "error" in outcome ? rec.error = outcome.error : rec.result = outcome.result;
+      };
+    },
+    recorded: RECORDED_METHODS
+  });
 }
 export {
+  ERR_PREFIX,
+  SUPPORTED_SURFACE,
+  UNSUPPORTED_MEMBERS,
   WriteAccessDeniedError,
   applyPatchOps,
   applyPerspective,
@@ -882,11 +1270,13 @@ export {
   createTransaction,
   defaultAclPath,
   evaluateWriteAccess,
+  fakeError,
   isDraftId,
   isReleaseDocId,
   isSystemId,
   isVersionId,
   publishedIdOf,
-  releaseNameOf
+  releaseNameOf,
+  wrapWithGuards
 };
 //# sourceMappingURL=index.js.map