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

package/README.md

@@ -77,10 +77,10 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 | Transaction | `transaction()` chain → `.commit()` | Mutations: `.create`, `.createOrReplace`, `.createIfNotExists`, `.delete`, `.patch(id, recipe)`. Atomic — any throw rolls back the whole batch. Default result is a `MultipleMutationResult` (`{ transactionId, documentIds, results }`) |
 | 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?, accessControl? })` | Sibling handle into the same multi-dataset registry; `accessControl` rebinds the acting identity (a token-scoped sibling sharing the store) |
+| Config | `config()` | Returns `{ projectId, dataset, perspective, token? }` |
+| Config | `withConfig({ projectId?, dataset?, perspective?, accessControl?, token? })` | Sibling handle into the same multi-dataset registry; `token` binds a registered identity (see the token→identity registry below), `accessControl` rebinds it inline — the two are mutually exclusive |
 | 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. |
+| HTTP | `request({ url? \| uri? })` | Present **only** when the handle has an acting identity (`accessControl`, or a bound `token`). Serves `/users/me` + the configured ACL path. Calling it without one throws a guidance error. |
 
 #### Mutation return shapes
 
@@ -119,18 +119,24 @@ await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toT
 
 #### 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 })`:
+`identity` is the id of the handle's acting identity. To act as different users against the **same** store (e.g. to exercise `identity()`-based guards), register a token→identity registry and mint token-scoped siblings — the token determines identity, exactly like production:
 
 ```ts
 const alice = createTestClient({
   documents: [article],
-  accessControl: { currentUser: { id: "alice" }, grants },
+  token: "t-alice",
+  identities: {
+    "t-alice": { user: { id: "alice" }, grants },
+    "t-bob": { user: { id: "bob" }, grants },
+  },
   mutationGuard: onlyTheAssignedReviewerMayWrite,
 });
-const bob = alice.withConfig({ accessControl: { currentUser: { id: "bob" }, grants } });
+const bob = alice.withConfig({ token: "t-bob" });
 // alice and bob share one store; each write carries its own identity().
 ```
 
+Register more identities after creation with `client.addIdentity(token, { user, grants })` — an upsert into the family-shared registry; already-bound siblings resolve lazily and pick the change up immediately. For a one-off identity without a registry, `withConfig({ accessControl })` still works (mutually exclusive with `token` in the same call).
+
 > [!NOTE]
 > Treat `before` / `after` as read-only — they are the live store images, not copies; mutating them corrupts the store.
 
@@ -154,6 +160,8 @@ Useful in test bodies, but a giveaway that the code under test isn't using the r
 | `client.clearCalls()` | Reset the call log |
 | `client.stub(name, handler)` | Register a handler for any unimplemented `@sanity/client` member (see below) |
 | `client.stubs()` | The currently-registered stubs |
+| `client.addIdentity(token, identity)` | Register (upsert) a token→identity entry in the family-shared registry |
+| `client.identities()` | Snapshot of the registered token→identity entries |
 | `createTestClient({ datasets: { "p:d": [...] } })` | Seed multiple `(projectId, dataset)` stores up front |
 
 #### Two layers of observability
@@ -212,7 +220,7 @@ Nested access reports the full path (`client.assets.upload(...)` → `client.ass
 | `listen(...)` — real-time | ❌ Guarded | Test subscription logic separately, or `client.stub("listen", fn)` |
 | `clone()` | ❌ Guarded | `withConfig({})` returns a sibling handle |
 | `getUrl(uri)` / `getDataUrl(...)` — URL builders | ❌ Guarded | Hard-code in tests, or stub |
-| `request(...)` — generic HTTP | ⚠️ Only with `accessControl` | Configure `accessControl`, stub it, or use [MSW](https://mswjs.io) |
+| `request(...)` — generic HTTP | ⚠️ Only with an acting identity | Configure `accessControl` or bind a registered `token`, stub it, or use [MSW](https://mswjs.io) |
 | `agent.*` / `assets.*` / `projects.*` / `users.*` / `live.*` / `mediaLibrary.*` | ❌ Guarded | Seed docs directly, or `client.stub(name, fn)` |
 | `observable.*` — RxJS API | ❌ Guarded | Wrap the Promise API with `from()` if needed |
 | Patch ops: `.diffMatchPatch`, `.merge`, `.append`, `.prepend`, `.replace` | ❌ Absent | `.insert("after", "field[-1]", items)` for append; `.insert("before", "field[0]", items)` for prepend |

package/dist/index.cjs

@@ -61,16 +61,15 @@ async function enforceWriteAccess(args) {
 function defaultAclPath(projectId, dataset) {
   return `/projects/${projectId}/datasets/${dataset}/acl`;
 }
-function makeRequestImpl(accessControl, projectId, dataset) {
-  const aclPath = accessControl.aclPath ?? defaultAclPath(projectId, dataset);
+function makeRequestImpl(getAccess, projectId, dataset) {
   return async (opts) => {
-    const path = opts.uri ?? opts.url;
+    const accessControl = getAccess(), aclPath = accessControl.aclPath ?? defaultAclPath(projectId, dataset), path = opts.uri ?? opts.url;
     if (path === "/users/me")
       return accessControl.currentUser;
     if (path === aclPath)
       return accessControl.grants;
     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.`
+      `request(): no handler for path "${path}". With access control 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.`
     );
   };
 }
@@ -139,7 +138,7 @@ function createPatch(documentId, executor) {
     dec: (props) => (ops.push({ kind: "dec", props }), handle),
     insert: (position, anchor, items) => (ops.push({ kind: "insert", position, anchor, items }), handle),
     ifRevisionId: (rev) => (ifRev = rev, handle),
-    commit: () => executor.apply(documentId, ops, ifRev),
+    commit: (options) => executor.apply(documentId, ops, ifRev, options),
     toJSON: () => ({
       id: documentId,
       ops: [...ops],
@@ -690,7 +689,7 @@ const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues",
   "releases",
   "createVersion",
   "unpublishVersion",
-  "request (only with accessControl)",
+  "request (only with accessControl or a bound token)",
   "config",
   "withConfig"
 ], UNSUPPORTED_MEMBERS = {
@@ -739,8 +738,8 @@ const ISSUES_URL = "https://github.com/sanity-labs/client-fake-for-test/issues",
     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."
+    what: "generic HTTP request hook \u2014 only wired up when the handle has an acting identity",
+    workaround: "Create the client with `accessControl`, or bind a registered token (`identities` + `token` / `withConfig({ token })`), 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?",
@@ -840,6 +839,25 @@ function wrapWithGuards(client, config) {
     }
   });
 }
+const OPTIONS_ARG_POSITION = {
+  fetch: 2,
+  getDocument: 1,
+  getDocuments: 1,
+  create: 1,
+  createOrReplace: 1,
+  createIfNotExists: 1,
+  delete: 1,
+  mutate: 1,
+  action: 1,
+  request: 0
+};
+function tagFromArgs(method, args) {
+  const position = OPTIONS_ARG_POSITION[method];
+  if (position === void 0) return;
+  const options = args[position];
+  if (!(typeof options != "object" || options === null || !("tag" in options)))
+    return options.tag;
+}
 const RECORDED_METHODS = /* @__PURE__ */ new Set([
   "fetch",
   "getDocument",
@@ -856,7 +874,21 @@ const RECORDED_METHODS = /* @__PURE__ */ new Set([
   "createVersion",
   "unpublishVersion",
   "request"
-]), DEFAULT_PROJECT_ID = "test", DEFAULT_DATASET = "test", registryKey = (projectId, dataset) => `${projectId}:${dataset}`, parseRegistryKey = (key) => {
+]), DEFAULT_PROJECT_ID = "test", DEFAULT_DATASET = "test";
+function requireIdentity(backend, token, site) {
+  if (backend.identities.has(token)) return;
+  const known = [...backend.identities.keys()];
+  throw fakeError(
+    `${site}: unknown token "${token}" \u2014 no identity is registered for it. ` + (known.length > 0 ? `Registered tokens: ${known.map((t) => `"${t}"`).join(", ")}. ` : "No identities are registered. ") + "Register identities via createTestClient({ identities }) or client.addIdentity(token, identity)."
+  );
+}
+function rejectAmbiguousIdentity(site, config) {
+  if (config.token !== void 0 && config.accessControl !== void 0)
+    throw fakeError(
+      `${site}: \`token\` and \`accessControl\` are mutually exclusive \u2014 a handle acts either as a registered identity (token) or as an inline accessControl config, not both.`
+    );
+}
+const registryKey = (projectId, dataset) => `${projectId}:${dataset}`, parseRegistryKey = (key) => {
   const [projectId, dataset] = key.split(":");
   return { projectId, dataset };
 };
@@ -866,8 +898,11 @@ function createTestClient(options = {}) {
     log: [],
     stubs: /* @__PURE__ */ new Map(),
     calls: [],
-    concurrentEdits: /* @__PURE__ */ new Map()
-  }, registry = backend.registry, ensureStore = (projectId, dataset) => {
+    concurrentEdits: /* @__PURE__ */ new Map(),
+    identities: new Map(Object.entries(options.identities ?? {}))
+  }, registry = backend.registry;
+  rejectAmbiguousIdentity("createTestClient()", options), options.token !== void 0 && requireIdentity(backend, options.token, "createTestClient()");
+  const ensureStore = (projectId, dataset) => {
     const key = registryKey(projectId, dataset);
     let store = registry.get(key);
     return store === void 0 && (store = createTestStore(), registry.set(key, store)), store;
@@ -883,7 +918,8 @@ function createTestClient(options = {}) {
     defaultDataset,
     options.accessControl,
     options.perspective ?? "raw",
-    options.mutationGuard
+    options.mutationGuard,
+    options.token
   );
 }
 function dedupeIds(results) {
@@ -936,13 +972,30 @@ function toTxnMutations(operations) {
     }
   ];
 }
-function makeHandle(backend, projectId, dataset, accessControl, perspective, mutationGuard) {
-  const { registry } = backend, store = (() => {
+function makeHandle(backend, projectId, dataset, accessControl, perspective, mutationGuard, token) {
+  const { registry } = backend, activeAccess = () => {
+    if (token === void 0) return accessControl;
+    const identity = backend.identities.get(token);
+    if (identity === void 0)
+      throw fakeError(`no identity is registered for token "${token}" (was it removed?).`);
+    return { currentUser: identity.user, grants: identity.grants };
+  }, requireActiveAccess = () => {
+    const access = activeAccess();
+    if (access === void 0)
+      throw fakeError("this handle has no acting identity (no token or accessControl bound).");
+    return access;
+  }, store = (() => {
     const key = registryKey(projectId, dataset);
     let s = registry.get(key);
     return s === void 0 && (s = createTestStore(), registry.set(key, s)), s;
-  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations) => {
-    backend.log.push({ transactionId, projectId, dataset, mutations });
+  })(), concurrentEditKey = (id) => registryKey(projectId, dataset) + " " + id, record = (transactionId, mutations, tag) => {
+    backend.log.push({
+      transactionId,
+      projectId,
+      dataset,
+      mutations,
+      ...tag !== void 0 ? { tag } : {}
+    });
   }, writeResult = (documents, results, transactionId, opts) => formatMutationResult(
     documents,
     results,
@@ -984,20 +1037,24 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
         `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({
+    const access = activeAccess();
+    access !== void 0 && await enforceWriteAccess({
       document,
-      grants: accessControl.grants,
+      grants: access.grants,
       permission,
-      userId: accessControl.currentUser.id
+      userId: access.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,
-    permission: "read",
-    userId: accessControl.currentUser.id
-  }), applyPatch = async (documentId, ops, ifRev) => {
+    mutationGuard !== void 0 && await mutationGuard({ action, before, after, identity: activeAccess()?.currentUser.id });
+  }, canRead = async (document) => {
+    const access = activeAccess();
+    return access === void 0 ? !0 : canAccess({
+      document,
+      grants: access.grants,
+      permission: "read",
+      userId: access.currentUser.id
+    });
+  }, applyPatch = async (documentId, ops, ifRev) => {
     const existing = store.get(documentId);
     if (existing === void 0)
       throw fakeError(
@@ -1062,7 +1119,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
         doc === void 0 ? store.remove(id) : store.put(doc);
       throw error;
     }
-    record(transactionId, mutations);
+    record(transactionId, mutations, txnOptions?.tag);
     const documents = touchedIds.map((id) => store.get(id)).filter((d) => d !== void 0);
     return formatMutationResult(
       documents,
@@ -1073,7 +1130,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
     );
   }, accessVisibleDocs = async () => {
     const all = store.all();
-    if (accessControl === void 0) return all;
+    if (activeAccess() === void 0) return all;
     const out = [];
     for (const doc of all)
       await canRead(doc) && out.push(doc);
@@ -1123,7 +1180,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       const promoted = promote2(doc);
       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(
+      return opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "create", doc }], opts?.tag)), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
@@ -1135,7 +1192,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       const promoted = promote2(doc), existing = store.get(doc._id);
       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 }]));
+      opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createOrReplace", doc }], opts?.tag));
       const operation = existing !== void 0 ? "update" : "create";
       return writeResult(
         [promoted],
@@ -1155,7 +1212,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
           opts
         );
       const promoted = promote2(doc);
-      return await gate(promoted, "create"), await guardGate("create", null, promoted), 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 }], opts?.tag)), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
@@ -1168,7 +1225,7 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       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(
+      return opts?.dryRun !== !0 && (removed = store.remove(id), removed !== void 0 && record(transactionId, [{ kind: "delete", id }], opts?.tag)), 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,
@@ -1177,11 +1234,13 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       );
     },
     patch: (documentId) => createPatch(documentId, {
-      apply: async (docId, ops, ifRev) => {
+      apply: async (docId, ops, ifRev, options) => {
         const doc = await applyPatch(docId, ops, ifRev);
-        return record(cryptoRandomKey(), [
-          { kind: "patch", documentId: docId, ops, ...ifRev !== void 0 ? { ifRev } : {} }
-        ]), doc;
+        return record(
+          cryptoRandomKey(),
+          [{ kind: "patch", documentId: docId, ops, ...ifRev !== void 0 ? { ifRev } : {} }],
+          options?.tag
+        ), doc;
       }
     }),
     transaction: () => createTransaction({ apply: applyTransaction }),
@@ -1228,16 +1287,21 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       versionId: `versions.${releaseId}.${publishedId}`,
       publishedId
     }),
-    ...accessControl !== void 0 ? { request: makeRequestImpl(accessControl, projectId, dataset) } : {},
-    config: () => ({ projectId, dataset, perspective }),
-    withConfig: (config) => makeHandle(
-      backend,
-      config.projectId ?? projectId,
-      config.dataset ?? dataset,
-      config.accessControl ?? accessControl,
-      config.perspective ?? perspective,
-      mutationGuard
-    ),
+    ...token !== void 0 || accessControl !== void 0 ? { request: makeRequestImpl(requireActiveAccess, projectId, dataset) } : {},
+    config: () => ({ projectId, dataset, perspective, ...token !== void 0 ? { token } : {} }),
+    withConfig: (config) => {
+      rejectAmbiguousIdentity("withConfig()", config), config.token !== void 0 && requireIdentity(backend, config.token, "withConfig()");
+      const rebinds = config.token !== void 0 || config.accessControl !== void 0;
+      return makeHandle(
+        backend,
+        config.projectId ?? projectId,
+        config.dataset ?? dataset,
+        rebinds ? config.accessControl : accessControl,
+        config.perspective ?? perspective,
+        mutationGuard,
+        rebinds ? config.token : token
+      );
+    },
     seed: (documents) => store.seed(documents),
     add: (documents) => store.add(documents),
     reset: () => store.reset(),
@@ -1252,6 +1316,10 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
       backend.stubs.set(name, handler);
     },
     stubs: () => Object.fromEntries(backend.stubs),
+    addIdentity: (identityToken, identity) => {
+      backend.identities.set(identityToken, identity);
+    },
+    identities: () => Object.fromEntries(backend.identities),
     mutations: () => backend.log.flatMap((entry) => entry.mutations),
     transactions: () => [...backend.log],
     clearLog: () => {
@@ -1266,8 +1334,8 @@ function makeHandle(backend, projectId, dataset, accessControl, perspective, mut
   return wrapWithGuards(client, {
     getStub: (name) => backend.stubs.get(name),
     onCall: (method, args) => {
-      const rec = { method, args, projectId, dataset };
-      return backend.calls.push(rec), (outcome) => {
+      const rec = { method, args, projectId, dataset }, tag = tagFromArgs(method, args);
+      return tag !== void 0 && (rec.tag = tag), backend.calls.push(rec), (outcome) => {
         "error" in outcome ? rec.error = outcome.error : rec.result = outcome.result;
       };
     },