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

package/dist/index.d.cts

@@ -35,6 +35,32 @@ export declare function applyPerspective(
   perspective: Perspective,
 ): SanityDocument[];
 
+/**
+ * One recorded invocation of a client method — the spy layer behind
+ * `client.calls()` / `client.callCount()`. `result` holds the resolved
+ * value (awaited, for async methods); `error` holds the thrown/rejected
+ * value. Builder-returning methods (`patch`, `transaction`) record the
+ * builder as `result`; their eventual writes show up in the mutation log.
+ */
+export declare interface CallRecord {
+  /** Method name; namespace methods are dotted, e.g. `releases.create`. */
+  method: string;
+  /** Arguments as passed (stored by reference, like `vi.fn`). */
+  args: unknown[];
+  /** Resolved/returned value, set once the call settles successfully. */
+  result?: unknown;
+  /** Thrown or rejected value, set if the call failed. */
+  error?: unknown;
+  projectId: string;
+  dataset: string;
+}
+
+/** Outcome of a recorded call, reported once a (possibly async) result is known. */
+export declare type CallSettler = (outcome: {
+  result?: unknown;
+  error?: unknown;
+}) => void;
+
 export declare function createPatch(
   documentId: string,
   executor: PatchExecutor,
@@ -84,6 +110,15 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Pluggable write interceptor — runs on each write through the document
+   * mutation API (create/patch/delete/transaction; not the release/version
+   * action API) before the store changes, and may throw to reject it. The
+   * client has no opinion about the policy; callers (e.g. a workflow test bench
+   * enforcing lake mutation guards) supply it. Inherited by `withConfig`
+   * siblings. See {@link MutationGuard}.
+   */
+  mutationGuard?: MutationGuard;
   /**
    * Default perspective applied to reads. Per-fetch `options.perspective`
    * overrides this. `withConfig({ perspective })` returns a sibling
@@ -142,6 +177,19 @@ export declare interface DocumentBody {
 
 export declare type DocumentValuePermission = "create" | "read" | "update";
 
+/**
+ * Error helpers shared across the fake.
+ *
+ * Every error the fake throws is prefixed with {@link ERR_PREFIX} so it's
+ * unmistakably attributable to *this fake* — not to `@sanity/client`,
+ * groq-js, or the code under test — and carries enough context to fix
+ * the problem without reading the fake's source. Short, bare messages
+ * ("not found", "invalid id") are a poor developer experience in a test
+ * double: prefer stating what happened, the offending value, and what to
+ * do about it.
+ */
+export declare const ERR_PREFIX = "[client-fake-for-test]";
+
 /**
  * Resolve whether `grants` allow `permission` on `document` for the
  * given user. Same logic the engine uses in `permissions.grantsPermissionOn`
@@ -163,6 +211,47 @@ export declare function evaluateWriteAccess(args: {
   matchingGrants: number;
 }>;
 
+/** Build a prefixed Error. Pass a fully-formed, dev-facing message. */
+export declare function fakeError(message: string): Error;
+
+/**
+ * A single mutation in the raw array form accepted by `mutate()` — the
+ * same shape `@sanity/client` accepts. The inline `patch` form mirrors
+ * the real client's keyed patch object.
+ */
+export declare type FakeMutation =
+  | {
+      create: SanityDocumentLike;
+    }
+  | {
+      createOrReplace: SanityDocumentLike;
+    }
+  | {
+      createIfNotExists: SanityDocumentLike;
+    }
+  | {
+      delete: {
+        id: string;
+      };
+    }
+  | {
+      patch: {
+        id: string;
+        ifRevisionID?: string;
+        set?: Record<string, unknown>;
+        setIfMissing?: Record<string, unknown>;
+        unset?: string[];
+        inc?: Record<string, number>;
+        dec?: Record<string, number>;
+        insert?: {
+          before?: string;
+          after?: string;
+          replace?: string;
+          items: unknown[];
+        };
+      };
+    };
+
 /**
  * Data-plane subset of `@sanity/client`'s surface, with multi-dataset support.
  *
@@ -188,6 +277,21 @@ export declare function evaluateWriteAccess(args: {
 export declare interface FetchOptions {
   /** Override the client's configured perspective for this read. */
   perspective?: Perspective;
+  /**
+   * When `false`, resolve to a {@link RawQueryResponse} (`{ query, ms,
+   * result }`) instead of the bare result — mirrors `@sanity/client`.
+   * Defaults to `true`.
+   */
+  filterResponse?: boolean;
+  /**
+   * With `filterResponse: false`, set to `false` to omit `query` from the
+   * raw response. Ignored when `filterResponse` is not `false`.
+   */
+  returnQuery?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  tag?: string;
+  /** Accepted for signature parity; not simulated. */
+  signal?: AbortSignal;
 }
 
 export declare interface Grant {
@@ -195,6 +299,27 @@ export declare interface Grant {
   permissions: DocumentValuePermission[];
 }
 
+export declare interface GuardConfig {
+  /**
+   * Resolve a registered stub for an unimplemented member, or `undefined`.
+   * Checked only for members the client doesn't already implement, so
+   * stubs fill gaps without shadowing core behaviour.
+   */
+  getStub: (name: string) => unknown;
+  /**
+   * Called synchronously when a recorded method is invoked, with the
+   * method name and its arguments. Returns a settler the wrapper invokes
+   * once the result (or rejection) is known. Omit to disable recording.
+   */
+  onCall?: (method: string, args: unknown[]) => CallSettler;
+  /**
+   * Top-level member names whose calls are recorded via `onCall`. A
+   * recorded member that resolves to a namespace object (e.g. `releases`)
+   * has each of its methods recorded as `name.method`.
+   */
+  recorded?: Set<string>;
+}
+
 export declare const isDraftId: (id: string) => boolean;
 
 export declare const isReleaseDocId: (id: string) => boolean;
@@ -203,8 +328,103 @@ export declare const isSystemId: (id: string) => boolean;
 
 export declare const isVersionId: (id: string) => boolean;
 
+/** Result of a mutation when ids are requested for all affected documents. */
+export declare interface MultipleMutationResult {
+  transactionId: string;
+  documentIds: string[];
+  results: {
+    id: string;
+    operation: MutationOperation;
+  }[];
+}
+
+/**
+ * A pluggable write interceptor, configured via
+ * `createTestClient({ mutationGuard })`. It runs on each write through the
+ * document mutation API — `create` / `createOrReplace` / `createIfNotExists` /
+ * `patch` / `delete` and the equivalent `transaction()` operations — before the
+ * store changes; **throw to reject the write** (the throw propagates out of the
+ * client call, exactly as a real lake rejection would). The release/version
+ * action API (`client.action`, `client.releases.*`, `createVersion`) is **not**
+ * intercepted.
+ *
+ * The client itself has no opinion about *what* a guard is — it only provides
+ * the seam and the before/after/identity context. Callers (e.g. a workflow test
+ * bench) supply the policy: evaluate lake mutation guards, enforce field locks,
+ * etc. Keeping the policy in the caller avoids duplicating guard-evaluation
+ * logic the client has no business owning.
+ */
+export declare type MutationGuard = (
+  context: MutationGuardContext,
+) => void | Promise<void>;
+
+/** The kind of write a {@link MutationGuard} is asked to vet. */
+export declare type MutationGuardAction = "create" | "update" | "delete";
+
+/**
+ * The before/after image of a single document write, handed to a
+ * {@link MutationGuard} before it is applied.
+ *
+ * - `before` is null on create; `after` is null on delete.
+ * - `identity` is the acting user — the id bound to the client's token
+ *   (its `accessControl.currentUser`), or undefined when the client has no
+ *   identity configured.
+ *
+ * Treat `before`/`after` as read-only — they are the live store images, not
+ * copies; a guard that mutates them corrupts the store.
+ */
+export declare interface MutationGuardContext {
+  action: MutationGuardAction;
+  before:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  after:
+    | (SanityDocumentLike & {
+        _id: string;
+        _type: string;
+      })
+    | null;
+  identity: string | undefined;
+}
+
+/** Append-only record of one committed transaction (a single mutation is a 1-entry transaction). */
+export declare interface MutationLogEntry {
+  transactionId: string;
+  projectId: string;
+  dataset: string;
+  mutations: TxnMutation[];
+}
+
+/** The operation recorded per affected document, matching `@sanity/client`. */
+export declare type MutationOperation = "create" | "update" | "delete" | "none";
+
 export declare interface MutationOptions {
   ifRevisionId?: string;
+  /**
+   * Shape the resolved value, mirroring `@sanity/client`:
+   * - default → the mutated document
+   * - `returnDocuments: false` → an id-shaped mutation result
+   *   ({@link SingleMutationResult} / {@link MultipleMutationResult})
+   * - `returnFirst: false` with documents → an array
+   *
+   * The static return type reflects the default (the document); pass a
+   * type argument or cast when requesting an id-shaped result.
+   */
+  returnDocuments?: boolean;
+  returnFirst?: boolean;
+  /** Override the synthetic transaction id used in the result and log. */
+  transactionId?: string;
+  /** When `true`, validate + shape the result but don't persist. */
+  dryRun?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  visibility?: "sync" | "async" | "deferred";
+  /** Accepted for signature parity; not simulated. */
+  autoGenerateArrayKeys?: boolean;
+  /** Accepted for signature parity; not simulated. */
+  tag?: string;
 }
 
 export declare interface PatchExecutor {
@@ -275,6 +495,17 @@ export declare type Perspective = "raw" | "published" | "drafts" | string[];
 /** Strip `drafts.` / `versions.<name>.` prefix to recover the published id. */
 export declare function publishedIdOf(id: string): string;
 
+/**
+ * Shape returned by `fetch` when `filterResponse: false`. Matches
+ * `@sanity/client`'s `RawQueryResponse`. `query` is omitted when the
+ * caller also passes `returnQuery: false`.
+ */
+export declare interface RawQueryResponse<R> {
+  query?: string;
+  ms: number;
+  result: R;
+}
+
 export declare type ReleaseAction =
   | {
       actionType: "sanity.action.release.create";
@@ -400,6 +631,37 @@ declare interface SanityDocumentLike {
   [key: string]: unknown;
 }
 
+/** Result of a mutation when `returnFirst` resolves true and ids are requested. */
+export declare interface SingleMutationResult {
+  transactionId: string;
+  documentId: string;
+  results: {
+    id: string;
+    operation: MutationOperation;
+  }[];
+}
+
+/** Members this fake actually implements — surfaced in error messages. */
+export declare const SUPPORTED_SURFACE: readonly [
+  "fetch",
+  "getDocument",
+  "getDocuments",
+  "create",
+  "createOrReplace",
+  "createIfNotExists",
+  "delete",
+  "patch",
+  "transaction",
+  "mutate",
+  "action",
+  "releases",
+  "createVersion",
+  "unpublishVersion",
+  "request (only with accessControl)",
+  "config",
+  "withConfig",
+];
+
 export declare interface SystemFields {
   _rev: string;
   _createdAt: string;
@@ -415,7 +677,7 @@ export declare interface TestClient {
   getDocument: <T = SanityDocument>(
     id: string,
     options?: FetchOptions,
-  ) => Promise<T | null>;
+  ) => Promise<T | undefined>;
   getDocuments: <T = SanityDocument>(
     ids: string[],
     options?: FetchOptions,
@@ -458,6 +720,17 @@ export declare interface TestClient {
   } | null>;
   patch: (documentId: string) => PatchHandle;
   transaction: () => TransactionHandle;
+  /**
+   * Apply a batch of mutations in the raw array form (or a `patch()` /
+   * `transaction()` builder) — mirrors `@sanity/client`'s `mutate()`.
+   * Atomic: any failure rolls the whole batch back. The resolved shape
+   * follows `options.returnDocuments` / `returnFirst` exactly like the
+   * real client (default → {@link MultipleMutationResult}).
+   */
+  mutate: (
+    operations: FakeMutation[] | PatchHandle | TransactionHandle,
+    options?: TxnCommitOptions,
+  ) => Promise<TxnCommitResult>;
   /**
    * Dispatch one or more release / version actions against the store.
    * Returns a synthetic `transactionId`. Multi-action arrays are applied
@@ -494,6 +767,12 @@ export declare interface TestClient {
       projectId: string;
       dataset: string;
       perspective: Perspective;
+      /**
+       * 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.
+       */
+      accessControl: TestClientAccessControl;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -511,6 +790,46 @@ export declare interface TestClient {
     projectId: string;
     dataset: string;
   }[];
+  /**
+   * Register a handler for a `@sanity/client` member the fake doesn't
+   * implement (e.g. `listen`, `assets`). Accessing that member on the
+   * client then returns the handler instead of throwing the
+   * "not implemented" guard error. Shared across sibling `withConfig`
+   * handles. Stubs fill gaps only — they don't shadow implemented methods.
+   */
+  stub: (name: string, handler: unknown) => void;
+  /** The currently-registered stubs, keyed by member name. */
+  stubs: () => Record<string, unknown>;
+  /**
+   * Every mutation committed through this client's registry, flattened
+   * and in order — `create` / `createOrReplace` / `createIfNotExists` /
+   * `delete` / `patch`, whether issued directly, via `transaction()`, or
+   * via `mutate()`. The spy hook for "assert exactly what writes my code
+   * submitted".
+   */
+  mutations: () => TxnMutation[];
+  /**
+   * Every committed transaction, in order. A direct mutation is recorded
+   * as a one-mutation transaction. Each entry carries its synthetic
+   * `transactionId` and the `(projectId, dataset)` it targeted.
+   */
+  transactions: () => MutationLogEntry[];
+  /** Clear the recorded mutation / transaction log. */
+  clearLog: () => void;
+  /**
+   * Every recorded method call, in order — the spy layer for "was `fetch`
+   * called, how many times, and with what params". Records the
+   * `@sanity/client`-surface methods (`fetch`, `getDocument`, `create`,
+   * `patch`, `mutate`, `releases.*`, …), not the test-only helpers.
+   * Pass a method name to filter (e.g. `calls("fetch")`); namespace
+   * methods are dotted (`calls("releases.create")`). Shared across
+   * `withConfig` siblings.
+   */
+  calls: (method?: string) => CallRecord[];
+  /** Number of recorded calls, optionally filtered by method name. */
+  callCount: (method?: string) => number;
+  /** Clear the recorded call log. */
+  clearCalls: () => void;
 }
 
 export declare interface TestClientAccessControl {
@@ -569,20 +888,22 @@ export declare interface TransactionHandle {
 }
 
 export declare interface TxnCommitOptions {
-  /** If true, returns the resulting documents instead of just ids. */
+  /**
+   * Shape the resolved value (mirrors `@sanity/client`):
+   * - default (both unset) → {@link MultipleMutationResult}
+   * - `returnDocuments: true` → the resulting document(s)
+   * - `returnFirst: true` with `returnDocuments` → a single document
+   * - `returnDocuments: false` → an id-shaped mutation result
+   */
   returnDocuments?: boolean;
-  /** With `returnDocuments`, return only the first updated doc. */
   returnFirst?: boolean;
+  /** Override the synthetic transaction id (mirrors `client.transaction(undefined, { transactionId })`). */
+  transactionId?: string;
 }
 
 export declare type TxnCommitResult =
-  | {
-      transactionId: string;
-      results: {
-        id: string;
-        operation: "create" | "update" | "delete";
-      }[];
-    }
+  | MultipleMutationResult
+  | SingleMutationResult
   | SanityDocument
   | SanityDocument[];
 
@@ -624,6 +945,20 @@ export declare type TxnMutation =
       ifRev?: string;
     };
 
+/**
+ * Curated map of real `@sanity/client` members the fake deliberately omits.
+ * Keyed by the top-level property name; nested access (e.g.
+ * `assets.upload`) is reported with the full dotted path.
+ */
+export declare const UNSUPPORTED_MEMBERS: Record<string, UnsupportedEntry>;
+
+declare interface UnsupportedEntry {
+  /** What the real member is. */
+  what: string;
+  /** What to do instead. */
+  workaround: string;
+}
+
 export declare type VersionAction =
   | {
       actionType: "sanity.action.document.version.create";
@@ -645,6 +980,18 @@ export declare type VersionAction =
       publishedId: string;
     };
 
+/**
+ * Wrap a client object so unimplemented members fail informatively,
+ * registered stubs are served, and recorded methods report their calls.
+ *
+ * @param client - the fully-built client object (plain literal).
+ * @param config - stub resolver plus optional call-recording hooks.
+ */
+export declare function wrapWithGuards<T extends object>(
+  client: T,
+  config: GuardConfig,
+): T;
+
 /**
  * Sanity-style 403 raised when a configured-grants check rejects a
  * write. The thrown object carries the doc id, the attempted