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

package/dist/index.d.cts

@@ -110,6 +110,37 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Token→identity registry, shared by the whole `withConfig` family:
+   * multiple identities over one store, keyed by the token a handle is
+   * bound to — the token determines identity, exactly like production.
+   *
+   * ```ts
+   * const client = createTestClient({
+   *   token: "t-admin",
+   *   identities: {
+   *     "t-admin": { user: { id: "admin", roles: [{ name: "administrator" }] }, grants: WILDCARD },
+   *     "t-bob": { user: { id: "bob", roles: [{ name: "editor" }] }, grants: READ_ONLY },
+   *   },
+   * });
+   * const bob = client.withConfig({ token: "t-bob" });
+   * // same store; bob's /users/me → bob; bob's ACL path → bob's grants
+   * ```
+   *
+   * A token-bound handle behaves exactly like one configured with
+   * `accessControl` derived from its identity (identity serving + grant
+   * gating; the ACL path defaults per `(projectId, dataset)`). Register
+   * more identities later with `addIdentity`.
+   */
+  identities?: Record<string, TestClientIdentity>;
+  /**
+   * Token the root handle is bound to — must name an entry in
+   * `identities` (unknown tokens throw). Omit to leave the root handle
+   * identity-free (a bare factory for token-bound siblings): its
+   * `request` is undefined and its reads/writes are ungated. Mutually
+   * exclusive with `accessControl`.
+   */
+  token?: string;
   /**
    * Pluggable write interceptor — runs on each write through the document
    * mutation API (create/patch/delete/transaction; not the release/version
@@ -659,7 +690,7 @@ export declare const SUPPORTED_SURFACE: readonly [
   "releases",
   "createVersion",
   "unpublishVersion",
-  "request (only with accessControl)",
+  "request (only with accessControl or a bound token)",
   "config",
   "withConfig",
 ];
@@ -685,16 +716,12 @@ export declare interface TestClient {
     options?: FetchOptions,
   ) => Promise<(T | null)[]>;
   /**
-   * Sanity-style HTTP request hook. Present iff the client was
-   * created with `accessControl`. The engine's access resolver pokes
-   * `/users/me` and the configured ACL path through this — without it
-   * the engine throws on any verb that needs an actor (which is the
-   * cue for the bench to supply an `access` override).
-   *
-   * Test cases that want to exercise the engine's token-resolution
-   * path should configure `accessControl`; cases that want bench-style
-   * always-allow should leave it off and pass `access` through the
-   * bench.
+   * Sanity-style HTTP request hook. Present iff the handle has an
+   * acting identity — created with `accessControl`, or bound to a
+   * registered token (`identities` + `token`). The engine's access
+   * resolver pokes `/users/me` and the configured ACL path through
+   * this — without it the engine throws on any verb that needs an
+   * actor.
    */
   request?: <T>(opts: {
     url?: string;
@@ -752,11 +779,15 @@ export declare interface TestClient {
     releaseId: string;
     publishedId: string;
   }) => Promise<ActionResult>;
-  /** Current `(projectId, dataset)` and active perspective. */
+  /**
+   * Current `(projectId, dataset)` and active perspective. `token` is
+   * present iff the handle is bound to a registered identity.
+   */
   config: () => {
     projectId: string;
     dataset: string;
     perspective: Perspective;
+    token?: string;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -773,8 +804,18 @@ export declare interface TestClient {
        * 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.
+       * Mutually exclusive with `token`.
        */
       accessControl: TestClientAccessControl;
+      /**
+       * Bind the sibling to a token registered in the family's identity
+       * registry (`createTestClient({ identities })` / `addIdentity`): its
+       * `/users/me` serves that identity's user, its ACL path serves that
+       * identity's grants, and reads/writes are gated through them — the
+       * token determines identity, exactly like production. Unknown tokens
+       * throw. Mutually exclusive with `accessControl`.
+       */
+      token: string;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -791,9 +832,21 @@ export declare interface TestClient {
    * Simulate `count` concurrent edits to `id` in the current dataset: the
    * next `count` revision-guarded mutations (those passing `ifRevisionId`)
    * to that document throw a 409-shaped conflict, as if another client
-   * committed between the caller's read and write. Lets a test exercise
-   * optimistic-locking retry paths deterministically, without timing or
-   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
+   * committed between the caller's read and write. Mutations that don't
+   * pass `ifRevisionId` are unaffected.
+   *
+   * Reach for this when the code under test reads a document's `_rev` and
+   * commits with `ifRevisionId` internally — so you can't stage the race
+   * by mutating the document first (the code would just re-read the new
+   * revision and its commit would match). The counter is consumed one per
+   * guarded commit, so `count` lets a test drive a recover-after-N-losses
+   * path or exhaust a retry budget, deterministically and without relying
+   * on promise interleaving.
+   *
+   * Note: this forces the conflict *outcome* — it short-circuits the
+   * revision comparison rather than changing the stored `_rev`. The code
+   * under test sees the identical 409 error a real lost race produces; the
+   * stored revision is left untouched.
    */
   simulateConcurrentEdit: (id: string, count?: number) => void;
   /** List `(projectId, dataset)` pairs known in this registry. */
@@ -811,6 +864,16 @@ export declare interface TestClient {
   stub: (name: string, handler: unknown) => void;
   /** The currently-registered stubs, keyed by member name. */
   stubs: () => Record<string, unknown>;
+  /**
+   * Register (or upsert) a token→identity entry in the family's shared
+   * registry. Siblings already bound to `token` resolve lazily, so a
+   * re-registration takes effect on them immediately. Registering an
+   * identity does not bind it — pass `token` at `createTestClient` or
+   * `withConfig({ token })` to act as it.
+   */
+  addIdentity: (token: string, identity: TestClientIdentity) => void;
+  /** Snapshot of the registered token→identity entries. */
+  identities: () => Record<string, TestClientIdentity>;
   /**
    * Every mutation committed through this client's registry, flattened
    * and in order — `create` / `createOrReplace` / `createIfNotExists` /
@@ -855,6 +918,20 @@ export declare interface TestClientAccessControl {
   aclPath?: string;
 }
 
+/**
+ * One entry in the token→identity registry (`createTestClient({ identities })`).
+ * A handle bound to the entry's token behaves exactly like one configured
+ * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
+ * `user`, the default ACL path serves `grants`, and reads/writes are gated
+ * through them.
+ */
+export declare interface TestClientIdentity {
+  /** What `/users/me` returns for clients bound to this token. */
+  user: CurrentUser;
+  /** Grants served at the ACL path and enforced on reads/writes. */
+  grants: Grant[];
+}
+
 /**
  * In-memory document store backing a TestClient. Closure-scoped — created
  * fresh per test, no global state.

package/dist/index.d.ts

@@ -110,6 +110,37 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Token→identity registry, shared by the whole `withConfig` family:
+   * multiple identities over one store, keyed by the token a handle is
+   * bound to — the token determines identity, exactly like production.
+   *
+   * ```ts
+   * const client = createTestClient({
+   *   token: "t-admin",
+   *   identities: {
+   *     "t-admin": { user: { id: "admin", roles: [{ name: "administrator" }] }, grants: WILDCARD },
+   *     "t-bob": { user: { id: "bob", roles: [{ name: "editor" }] }, grants: READ_ONLY },
+   *   },
+   * });
+   * const bob = client.withConfig({ token: "t-bob" });
+   * // same store; bob's /users/me → bob; bob's ACL path → bob's grants
+   * ```
+   *
+   * A token-bound handle behaves exactly like one configured with
+   * `accessControl` derived from its identity (identity serving + grant
+   * gating; the ACL path defaults per `(projectId, dataset)`). Register
+   * more identities later with `addIdentity`.
+   */
+  identities?: Record<string, TestClientIdentity>;
+  /**
+   * Token the root handle is bound to — must name an entry in
+   * `identities` (unknown tokens throw). Omit to leave the root handle
+   * identity-free (a bare factory for token-bound siblings): its
+   * `request` is undefined and its reads/writes are ungated. Mutually
+   * exclusive with `accessControl`.
+   */
+  token?: string;
   /**
    * Pluggable write interceptor — runs on each write through the document
    * mutation API (create/patch/delete/transaction; not the release/version
@@ -659,7 +690,7 @@ export declare const SUPPORTED_SURFACE: readonly [
   "releases",
   "createVersion",
   "unpublishVersion",
-  "request (only with accessControl)",
+  "request (only with accessControl or a bound token)",
   "config",
   "withConfig",
 ];
@@ -685,16 +716,12 @@ export declare interface TestClient {
     options?: FetchOptions,
   ) => Promise<(T | null)[]>;
   /**
-   * Sanity-style HTTP request hook. Present iff the client was
-   * created with `accessControl`. The engine's access resolver pokes
-   * `/users/me` and the configured ACL path through this — without it
-   * the engine throws on any verb that needs an actor (which is the
-   * cue for the bench to supply an `access` override).
-   *
-   * Test cases that want to exercise the engine's token-resolution
-   * path should configure `accessControl`; cases that want bench-style
-   * always-allow should leave it off and pass `access` through the
-   * bench.
+   * Sanity-style HTTP request hook. Present iff the handle has an
+   * acting identity — created with `accessControl`, or bound to a
+   * registered token (`identities` + `token`). The engine's access
+   * resolver pokes `/users/me` and the configured ACL path through
+   * this — without it the engine throws on any verb that needs an
+   * actor.
    */
   request?: <T>(opts: {
     url?: string;
@@ -752,11 +779,15 @@ export declare interface TestClient {
     releaseId: string;
     publishedId: string;
   }) => Promise<ActionResult>;
-  /** Current `(projectId, dataset)` and active perspective. */
+  /**
+   * Current `(projectId, dataset)` and active perspective. `token` is
+   * present iff the handle is bound to a registered identity.
+   */
   config: () => {
     projectId: string;
     dataset: string;
     perspective: Perspective;
+    token?: string;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -773,8 +804,18 @@ export declare interface TestClient {
        * 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.
+       * Mutually exclusive with `token`.
        */
       accessControl: TestClientAccessControl;
+      /**
+       * Bind the sibling to a token registered in the family's identity
+       * registry (`createTestClient({ identities })` / `addIdentity`): its
+       * `/users/me` serves that identity's user, its ACL path serves that
+       * identity's grants, and reads/writes are gated through them — the
+       * token determines identity, exactly like production. Unknown tokens
+       * throw. Mutually exclusive with `accessControl`.
+       */
+      token: string;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -791,9 +832,21 @@ export declare interface TestClient {
    * Simulate `count` concurrent edits to `id` in the current dataset: the
    * next `count` revision-guarded mutations (those passing `ifRevisionId`)
    * to that document throw a 409-shaped conflict, as if another client
-   * committed between the caller's read and write. Lets a test exercise
-   * optimistic-locking retry paths deterministically, without timing or
-   * interleaving. Mutations that don't pass `ifRevisionId` are unaffected.
+   * committed between the caller's read and write. Mutations that don't
+   * pass `ifRevisionId` are unaffected.
+   *
+   * Reach for this when the code under test reads a document's `_rev` and
+   * commits with `ifRevisionId` internally — so you can't stage the race
+   * by mutating the document first (the code would just re-read the new
+   * revision and its commit would match). The counter is consumed one per
+   * guarded commit, so `count` lets a test drive a recover-after-N-losses
+   * path or exhaust a retry budget, deterministically and without relying
+   * on promise interleaving.
+   *
+   * Note: this forces the conflict *outcome* — it short-circuits the
+   * revision comparison rather than changing the stored `_rev`. The code
+   * under test sees the identical 409 error a real lost race produces; the
+   * stored revision is left untouched.
    */
   simulateConcurrentEdit: (id: string, count?: number) => void;
   /** List `(projectId, dataset)` pairs known in this registry. */
@@ -811,6 +864,16 @@ export declare interface TestClient {
   stub: (name: string, handler: unknown) => void;
   /** The currently-registered stubs, keyed by member name. */
   stubs: () => Record<string, unknown>;
+  /**
+   * Register (or upsert) a token→identity entry in the family's shared
+   * registry. Siblings already bound to `token` resolve lazily, so a
+   * re-registration takes effect on them immediately. Registering an
+   * identity does not bind it — pass `token` at `createTestClient` or
+   * `withConfig({ token })` to act as it.
+   */
+  addIdentity: (token: string, identity: TestClientIdentity) => void;
+  /** Snapshot of the registered token→identity entries. */
+  identities: () => Record<string, TestClientIdentity>;
   /**
    * Every mutation committed through this client's registry, flattened
    * and in order — `create` / `createOrReplace` / `createIfNotExists` /
@@ -855,6 +918,20 @@ export declare interface TestClientAccessControl {
   aclPath?: string;
 }
 
+/**
+ * One entry in the token→identity registry (`createTestClient({ identities })`).
+ * A handle bound to the entry's token behaves exactly like one configured
+ * with `accessControl: { currentUser: user, grants }` — `/users/me` serves
+ * `user`, the default ACL path serves `grants`, and reads/writes are gated
+ * through them.
+ */
+export declare interface TestClientIdentity {
+  /** What `/users/me` returns for clients bound to this token. */
+  user: CurrentUser;
+  /** Grants served at the ACL path and enforced on reads/writes. */
+  grants: Grant[];
+}
+
 /**
  * In-memory document store backing a TestClient. Closure-scoped — created
  * fresh per test, no global state.

package/dist/index.js

@@ -59,16 +59,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.`
     );
   };
 }
@@ -688,7 +687,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 = {
@@ -737,8 +736,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?",
@@ -854,7 +853,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 };
 };
@@ -864,8 +877,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;
@@ -881,7 +897,8 @@ function createTestClient(options = {}) {
     defaultDataset,
     options.accessControl,
     options.perspective ?? "raw",
-    options.mutationGuard
+    options.mutationGuard,
+    options.token
   );
 }
 function dedupeIds(results) {
@@ -934,8 +951,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;
@@ -982,20 +1010,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(
@@ -1071,7 +1103,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);
@@ -1226,16 +1258,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(),
@@ -1250,6 +1287,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: () => {