@sanity-labs/client-fake-for-test 0.5.0 → 0.6.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.`
     );
   };
 }
@@ -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?",
@@ -856,7 +855,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 +879,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 +899,8 @@ function createTestClient(options = {}) {
     defaultDataset,
     options.accessControl,
     options.perspective ?? "raw",
-    options.mutationGuard
+    options.mutationGuard,
+    options.token
   );
 }
 function dedupeIds(results) {
@@ -936,8 +953,19 @@ 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;
@@ -984,20 +1012,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(
@@ -1073,7 +1105,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);
@@ -1228,16 +1260,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 +1289,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: () => {