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

package/dist/index.d.cts

@@ -1,5 +1,11 @@
 export declare type Action = ReleaseAction | VersionAction;
 
+/** Options for `action()`. Only `tag` is meaningful to the fake. */
+export declare interface ActionOptions {
+  /** Request tag, recorded on the {@link CallRecord} (`null` = explicit suppression). */
+  tag?: string | null;
+}
+
 export declare interface ActionResult {
   transactionId: string;
 }
@@ -51,6 +57,8 @@ export declare interface CallRecord {
   result?: unknown;
   /** Thrown or rejected value, set if the call failed. */
   error?: unknown;
+  /** Request tag from the call's options, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
   projectId: string;
   dataset: string;
 }
@@ -110,6 +118,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
@@ -290,8 +329,12 @@ export declare interface FetchOptions {
    * raw response. Ignored when `filterResponse` is not `false`.
    */
   returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  /**
+   * Request tag, recorded on the {@link CallRecord} for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
   signal?: AbortSignal;
 }
@@ -398,6 +441,8 @@ export declare interface MutationLogEntry {
   projectId: string;
   dataset: string;
   mutations: TxnMutation[];
+  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
 }
 
 /** The operation recorded per affected document, matching `@sanity/client`. */
@@ -425,8 +470,21 @@ export declare interface MutationOptions {
   visibility?: "sync" | "async" | "deferred";
   /** Accepted for signature parity; not simulated. */
   autoGenerateArrayKeys?: boolean;
+  /**
+   * Request tag, recorded on the {@link CallRecord} and the
+   * {@link MutationLogEntry} for assertions. `null` mirrors
+   * `@sanity/client`'s explicit-suppression form and is recorded as-is.
+   * No other behavior is simulated.
+   */
+  tag?: string | null;
+}
+
+/** Options for `PatchHandle.commit()`. Only `tag` is meaningful to the fake. */
+export declare interface PatchCommitOptions {
+  /** Request tag, recorded on the mutation log entry (`null` = explicit suppression). */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  visibility?: "sync" | "async" | "deferred";
 }
 
 export declare interface PatchExecutor {
@@ -434,6 +492,7 @@ export declare interface PatchExecutor {
     documentId: string,
     ops: PatchOp[],
     ifRev: string | undefined,
+    options: PatchCommitOptions | undefined,
   ) => Promise<SanityDocument>;
 }
 
@@ -449,7 +508,7 @@ export declare interface PatchHandle {
     items: unknown[],
   ) => PatchHandle;
   ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: PatchCommitOptions) => Promise<SanityDocument>;
   /** Test-only introspection — not on real Patch */
   toJSON: () => {
     id: string;
@@ -659,7 +718,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,22 +744,18 @@ 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;
     uri?: string;
     signal?: AbortSignal;
-    tag?: string;
+    tag?: string | null;
   }) => Promise<T>;
   create: <T extends SanityDocumentLike>(
     doc: T,
@@ -738,7 +793,10 @@ export declare interface TestClient {
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
    * atomically — any failure rolls back the batch.
    */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
+  action: (
+    action: Action | Action[],
+    options?: ActionOptions,
+  ) => Promise<ActionResult>;
   /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
   releases: ReleasesHandle;
   /** Helper for `sanity.action.document.version.create`. */
@@ -752,11 +810,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 +835,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 +863,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 +895,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 +949,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.
@@ -910,6 +1018,12 @@ export declare interface TxnCommitOptions {
   returnFirst?: boolean;
   /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
   transactionId?: string;
+  /**
+   * Request tag, recorded on the mutation log entry for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
 }
 
 export declare type TxnCommitResult =

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export declare type Action = ReleaseAction | VersionAction;
 
+/** Options for `action()`. Only `tag` is meaningful to the fake. */
+export declare interface ActionOptions {
+  /** Request tag, recorded on the {@link CallRecord} (`null` = explicit suppression). */
+  tag?: string | null;
+}
+
 export declare interface ActionResult {
   transactionId: string;
 }
@@ -51,6 +57,8 @@ export declare interface CallRecord {
   result?: unknown;
   /** Thrown or rejected value, set if the call failed. */
   error?: unknown;
+  /** Request tag from the call's options, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
   projectId: string;
   dataset: string;
 }
@@ -110,6 +118,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
@@ -290,8 +329,12 @@ export declare interface FetchOptions {
    * raw response. Ignored when `filterResponse` is not `false`.
    */
   returnQuery?: boolean;
-  /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  /**
+   * Request tag, recorded on the {@link CallRecord} for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
   signal?: AbortSignal;
 }
@@ -398,6 +441,8 @@ export declare interface MutationLogEntry {
   projectId: string;
   dataset: string;
   mutations: TxnMutation[];
+  /** Request tag the commit carried, when one was passed (`null` = explicit suppression). */
+  tag?: string | null;
 }
 
 /** The operation recorded per affected document, matching `@sanity/client`. */
@@ -425,8 +470,21 @@ export declare interface MutationOptions {
   visibility?: "sync" | "async" | "deferred";
   /** Accepted for signature parity; not simulated. */
   autoGenerateArrayKeys?: boolean;
+  /**
+   * Request tag, recorded on the {@link CallRecord} and the
+   * {@link MutationLogEntry} for assertions. `null` mirrors
+   * `@sanity/client`'s explicit-suppression form and is recorded as-is.
+   * No other behavior is simulated.
+   */
+  tag?: string | null;
+}
+
+/** Options for `PatchHandle.commit()`. Only `tag` is meaningful to the fake. */
+export declare interface PatchCommitOptions {
+  /** Request tag, recorded on the mutation log entry (`null` = explicit suppression). */
+  tag?: string | null;
   /** Accepted for signature parity; not simulated. */
-  tag?: string;
+  visibility?: "sync" | "async" | "deferred";
 }
 
 export declare interface PatchExecutor {
@@ -434,6 +492,7 @@ export declare interface PatchExecutor {
     documentId: string,
     ops: PatchOp[],
     ifRev: string | undefined,
+    options: PatchCommitOptions | undefined,
   ) => Promise<SanityDocument>;
 }
 
@@ -449,7 +508,7 @@ export declare interface PatchHandle {
     items: unknown[],
   ) => PatchHandle;
   ifRevisionId: (rev: string) => PatchHandle;
-  commit: () => Promise<SanityDocument>;
+  commit: (options?: PatchCommitOptions) => Promise<SanityDocument>;
   /** Test-only introspection — not on real Patch */
   toJSON: () => {
     id: string;
@@ -659,7 +718,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,22 +744,18 @@ 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;
     uri?: string;
     signal?: AbortSignal;
-    tag?: string;
+    tag?: string | null;
   }) => Promise<T>;
   create: <T extends SanityDocumentLike>(
     doc: T,
@@ -738,7 +793,10 @@ export declare interface TestClient {
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
    * atomically — any failure rolls back the batch.
    */
-  action: (action: Action | Action[]) => Promise<ActionResult>;
+  action: (
+    action: Action | Action[],
+    options?: ActionOptions,
+  ) => Promise<ActionResult>;
   /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
   releases: ReleasesHandle;
   /** Helper for `sanity.action.document.version.create`. */
@@ -752,11 +810,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 +835,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 +863,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 +895,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 +949,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.
@@ -910,6 +1018,12 @@ export declare interface TxnCommitOptions {
   returnFirst?: boolean;
   /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
   transactionId?: string;
+  /**
+   * Request tag, recorded on the mutation log entry for assertions.
+   * `null` mirrors `@sanity/client`'s explicit-suppression form and is
+   * recorded as-is. No other behavior is simulated.
+   */
+  tag?: string | null;
 }
 
 export declare type TxnCommitResult =