@sanity-labs/client-fake-for-test 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,9 @@
+export declare type Action = ReleaseAction | VersionAction;
+
+export declare interface ActionResult {
+  transactionId: string;
+}
+
 /**
  * Apply an ordered list of patch ops to a document, returning the new doc.
  *
@@ -16,6 +22,45 @@ export declare function applyPatchOps(
   ops: PatchOp[],
 ): SanityDocument;
 
+/**
+ * Apply a perspective to a raw set of documents and return the view
+ * groq-js should evaluate against.
+ *
+ * For non-raw perspectives, each output document for a non-system id
+ * gets `_id` projected to its published id and `_originalId` carrying
+ * the source id (matching the wire shape of the real Content Lake).
+ */
+export declare function applyPerspective(
+  docs: readonly SanityDocument[],
+  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,
@@ -65,6 +110,13 @@ export declare interface CreateTestClientOptions {
    * unconditionally — the legacy behavior.
    */
   accessControl?: TestClientAccessControl;
+  /**
+   * Default perspective applied to reads. Per-fetch `options.perspective`
+   * overrides this. `withConfig({ perspective })` returns a sibling
+   * handle with a different default. Defaults to `"raw"` so existing
+   * tests stay green.
+   */
+  perspective?: Perspective;
 }
 
 /**
@@ -102,8 +154,33 @@ export declare function defaultAclPath(
   dataset: string,
 ): string;
 
+/**
+ * Document body accepted by `version.create` / `createVersion`. The id
+ * is derived from `releaseId + publishedId` so callers may omit `_id`
+ * here. `version.replace` requires `_id` since it identifies the doc
+ * to replace.
+ */
+export declare interface DocumentBody {
+  _id?: string;
+  _type: string;
+  [field: string]: unknown;
+}
+
 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`
@@ -125,13 +202,168 @@ 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.
+ *
+ * One `createTestClient()` call creates a registry of stores keyed by
+ * `(projectId, dataset)`. The returned client points at one of them.
+ * `withConfig({ projectId, dataset })` returns a new handle into the same
+ * registry but pointing at a different store — useful for workflows where
+ * definitions live in one dataset and instances live in another.
+ *
+ * Two separate `createTestClient()` calls have separate registries, so
+ * tests stay isolated from each other.
+ *
+ * Methods not on the real client:
+ *
+ * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
+ *   scoped to the current dataset.
+ * - `datasets()` — lists known dataset keys in this registry.
+ *
+ * Methods deliberately omitted:
+ *
+ * - Project / agent / asset / live / listen APIs.
+ */
+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 {
   filter: string;
   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;
+
+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;
+  }[];
+}
+
+/** 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 {
@@ -197,6 +429,118 @@ export declare type PatchOp =
       items: unknown[];
     };
 
+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";
+      releaseId: string;
+      metadata?: Partial<ReleaseMetadata>;
+    }
+  | {
+      actionType: "sanity.action.release.edit";
+      releaseId: string;
+      patch: {
+        set?: Record<string, unknown>;
+        unset?: string[];
+      };
+    }
+  | {
+      actionType: "sanity.action.release.schedule";
+      releaseId: string;
+      publishAt: string;
+    }
+  | {
+      actionType: "sanity.action.release.unschedule";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.publish";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.archive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.unarchive";
+      releaseId: string;
+    }
+  | {
+      actionType: "sanity.action.release.delete";
+      releaseId: string;
+    };
+
+export declare interface ReleaseDocument extends SanityDocument {
+  _type: "system.release";
+  name: string;
+  state: ReleaseState;
+  metadata: ReleaseMetadata;
+  publishAt?: string;
+}
+
+export declare interface ReleaseMetadata {
+  title?: string;
+  description?: string;
+  releaseType?: ReleaseType;
+  intendedPublishAt?: string;
+}
+
+/** Extract the release name from a `versions.<name>.<id>` id, else undefined. */
+export declare function releaseNameOf(id: string): string | undefined;
+
+export declare interface ReleasesHandle {
+  create: (params: {
+    releaseId: string;
+    metadata?: Partial<ReleaseMetadata>;
+  }) => Promise<
+    ActionResult & {
+      releaseId: string;
+      metadata: ReleaseMetadata;
+    }
+  >;
+  edit: (params: {
+    releaseId: string;
+    patch: {
+      set?: Record<string, unknown>;
+      unset?: string[];
+    };
+  }) => Promise<ActionResult>;
+  get: (params: { releaseId: string }) => Promise<ReleaseDocument | undefined>;
+  fetchDocuments: (params: { releaseId: string }) => Promise<SanityDocument[]>;
+  schedule: (params: {
+    releaseId: string;
+    publishAt: string;
+  }) => Promise<ActionResult>;
+  unschedule: (params: { releaseId: string }) => Promise<ActionResult>;
+  publish: (params: { releaseId: string }) => Promise<ActionResult>;
+  archive: (params: { releaseId: string }) => Promise<ActionResult>;
+  unarchive: (params: { releaseId: string }) => Promise<ActionResult>;
+  delete: (params: { releaseId: string }) => Promise<ActionResult>;
+}
+
+export declare type ReleaseState =
+  | "active"
+  | "scheduled"
+  | "published"
+  | "archived";
+
+export declare type ReleaseType = "asap" | "scheduled" | "undecided";
+
 /** @public */
 declare interface SanityDocument {
   _id: string;
@@ -226,42 +570,57 @@ 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;
   _updatedAt: string;
 }
 
-/**
- * Data-plane subset of `@sanity/client`'s surface, with multi-dataset support.
- *
- * One `createTestClient()` call creates a registry of stores keyed by
- * `(projectId, dataset)`. The returned client points at one of them.
- * `withConfig({ projectId, dataset })` returns a new handle into the same
- * registry but pointing at a different store — useful for workflows where
- * definitions live in one dataset and instances live in another.
- *
- * Two separate `createTestClient()` calls have separate registries, so
- * tests stay isolated from each other.
- *
- * Methods not on the real client:
- *
- * - `seed`, `add`, `reset`, `snapshot`, `store` — bulk-load helpers,
- *   scoped to the current dataset.
- * - `datasets()` — lists known dataset keys in this registry.
- *
- * Methods deliberately omitted:
- *
- * - Project / agent / asset / live / listen APIs.
- * - Perspective handling.
- */
 export declare interface TestClient {
   fetch: <T = unknown>(
     query: string,
     params?: Record<string, unknown>,
+    options?: FetchOptions,
   ) => Promise<T>;
-  getDocument: <T = SanityDocument>(id: string) => Promise<T | null>;
-  getDocuments: <T = SanityDocument>(ids: string[]) => Promise<(T | null)[]>;
+  getDocument: <T = SanityDocument>(
+    id: string,
+    options?: FetchOptions,
+  ) => Promise<T | undefined>;
+  getDocuments: <T = SanityDocument>(
+    ids: string[],
+    options?: FetchOptions,
+  ) => Promise<(T | null)[]>;
   /**
    * Sanity-style HTTP request hook. Present iff the client was
    * created with `accessControl`. The engine's access resolver pokes
@@ -300,10 +659,41 @@ export declare interface TestClient {
   } | null>;
   patch: (documentId: string) => PatchHandle;
   transaction: () => TransactionHandle;
-  /** Current `(projectId, dataset)`. */
+  /**
+   * 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
+   * atomically — any failure rolls back the batch.
+   */
+  action: (action: Action | Action[]) => Promise<ActionResult>;
+  /** Helpers mirroring `@sanity/client`'s `client.releases.*` surface. */
+  releases: ReleasesHandle;
+  /** Helper for `sanity.action.document.version.create`. */
+  createVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+    document: DocumentBody;
+  }) => Promise<ActionResult>;
+  /** Helper for `sanity.action.document.version.unpublish`. */
+  unpublishVersion: (params: {
+    releaseId: string;
+    publishedId: string;
+  }) => Promise<ActionResult>;
+  /** Current `(projectId, dataset)` and active perspective. */
   config: () => {
     projectId: string;
     dataset: string;
+    perspective: Perspective;
   };
   /**
    * Return a new client handle pointing at a different `(projectId, dataset)`
@@ -315,6 +705,7 @@ export declare interface TestClient {
     config: Partial<{
       projectId: string;
       dataset: string;
+      perspective: Perspective;
     }>,
   ) => TestClient;
   /** Replace the current dataset with the given documents. */
@@ -332,6 +723,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 {
@@ -390,20 +821,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[];
 
@@ -445,6 +878,53 @@ 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";
+      publishedId: string;
+      document: DocumentBody;
+      releaseId?: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.replace";
+      document: SanityDocumentLike;
+    }
+  | {
+      actionType: "sanity.action.document.version.discard";
+      versionId: string;
+    }
+  | {
+      actionType: "sanity.action.document.version.unpublish";
+      versionId: string;
+      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