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

package/README.md

@@ -65,18 +65,36 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 
 | Area | Method | Notes |
 | --- | --- | --- |
-| Read | `fetch<T>(query, params?)` | GROQ via groq-js against the in-memory store |
-| Read | `getDocument<T>(id)` | Returns `null` if missing (or hidden by ACL) |
-| Read | `getDocuments<T>(ids)` | Element-wise null for missing |
-| Write | `create(doc, { ifRevisionId? })` | Throws if `_id` already exists |
-| Write | `createOrReplace(doc, { ifRevisionId? })` | Upsert |
-| Write | `createIfNotExists(doc, { ifRevisionId? })` | No-op if `_id` exists |
-| Write | `delete(id, { ifRevisionId? })` | Returns `{ _id }` or `null` |
+| Read | `fetch<T>(query, params?, { filterResponse?, returnQuery? })` | GROQ via groq-js. `filterResponse: false` → `{ result, ms, query }` (`RawQueryResponse`), like the real client |
+| Read | `getDocument<T>(id)` | Returns `undefined` if missing (or hidden by ACL) — matches `@sanity/client` |
+| Read | `getDocuments<T>(ids)` | Element-wise `null` for missing |
+| Write | `create(doc, options?)` | Throws if `_id` already exists |
+| Write | `createOrReplace(doc, options?)` | Upsert |
+| Write | `createIfNotExists(doc, options?)` | No-op if `_id` exists |
+| Write | `delete(id, options?)` | Default `{ _id }` or `null`; id/array shapes via options |
+| Mutate | `mutate(operations, options?)` | Raw mutation array (`{create}`/`{patch}`/`{delete}`/…), or a `patch()` / `transaction()` builder. Atomic |
 | Patch | `patch(id)` chain → `.commit()` | Ops: `.set`, `.setIfMissing`, `.unset`, `.inc`, `.dec`, `.insert(position, anchor, items)`, `.ifRevisionId` |
-| Transaction | `transaction()` chain → `.commit()` | Mutations: `.create`, `.createOrReplace`, `.createIfNotExists`, `.delete`, `.patch(id, recipe)`. Atomic — any throw rolls back the whole batch |
-| Config | `config()` | Returns `{ projectId, dataset }` |
-| Config | `withConfig({ projectId?, dataset? })` | Sibling handle into the same multi-dataset registry |
-| HTTP | `request({ url? \| uri? })` | Present **only** when the client is created with `accessControl`. Serves `/users/me` + the configured ACL path. Absent otherwise. |
+| 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? })` | Sibling handle into the same multi-dataset registry |
+| 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. |
+
+#### Mutation return shapes
+
+`create` / `createOrReplace` / `createIfNotExists` / `delete` / `mutate` / `transaction().commit()` honor `returnDocuments` / `returnFirst`, mirroring `@sanity/client`:
+
+| `returnDocuments` | `returnFirst` | Resolves to |
+| --- | --- | --- |
+| (default for create-family) | | the mutated document |
+| `true` | `false` | `SanityDocument[]` |
+| `false` | `true` (or default) | `SingleMutationResult` `{ transactionId, documentId, results }` |
+| `false` | `false` (default for `transaction` / `mutate`) | `MultipleMutationResult` `{ transactionId, documentIds, results }` |
+
+> [!NOTE]
+> The static return type of `create` / `delete` reflects the **default** shape (the document / `{ _id } | null`). When you pass `returnDocuments: false` to get an id-shaped result, supply a type argument or cast — the runtime value is correct either way.
 
 ### Test-only helpers (not on real `SanityClient`)
 
@@ -90,29 +108,88 @@ Useful in test bodies, but a giveaway that the code under test isn't using the r
 | `client.reset()` | Drop everything in the current dataset |
 | `client.store()` | Direct access to the underlying `TestStore` |
 | `client.datasets()` | `{ projectId, dataset }[]` known to the registry |
+| `client.mutations()` | Every committed mutation, flattened and in order — assert exactly what writes your code submitted |
+| `client.transactions()` | Every committed transaction (a direct mutation is a one-mutation transaction), each tagged with `transactionId` + `(projectId, dataset)` |
+| `client.clearLog()` | Reset the mutation / transaction log |
+| `client.calls(method?)` | Every recorded method call, with args + result — a framework-agnostic spy (like `vi.fn().mock.calls`) |
+| `client.callCount(method?)` | Number of recorded calls, optionally filtered by method |
+| `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 |
 | `createTestClient({ datasets: { "p:d": [...] } })` | Seed multiple `(projectId, dataset)` stores up front |
 
-### Not supported (by design)
+#### Two layers of observability
+
+The fake records at two levels, so you can assert on either *what your code did to the data* or *how it called the client*:
+
+- **Write effects** — `client.mutations()` / `client.transactions()`: the create/patch/delete/mutate operations that actually landed (rolled-back and `dryRun` writes excluded).
+- **API calls** — `client.calls()` / `client.callCount()`: every invocation of a `@sanity/client`-surface method (`fetch`, `getDocument`, `create`, `patch`, `mutate`, `releases.*`, …) with its `args`, resolved `result`, or thrown `error`. This is the spy layer — reach for it to assert read patterns (`fetch` called once, with these params) that the write log can't show.
 
-The whole-client surface listed below throws / returns `undefined` / is simply absent. Code that depends on these needs a different test strategy (real client against an ephemeral dataset, MSW for HTTP intercepts, or a hand-rolled stub).
+```ts
+const client = createTestClient({ documents: [{ _id: "a", _type: "article" }] });
+await myLoader(client);
+
+expect(client.callCount("fetch")).toBe(1);
+expect(client.calls("fetch")[0]?.args).toEqual([`*[_type=="article"]`, {}]);
+expect(client.calls("getDocument")[0]?.result).toMatchObject({ _id: "a" });
+```
+
+> [!NOTE]
+> Builder-returning methods (`patch`, `transaction`) record the call at builder-creation time (`patch("a")` → `args: ["a"]`); the chained ops/commit show up in the mutation log, not as extra calls. Test-only helpers (`snapshot`, `mutations`, `calls`, …) are never recorded.
+
+#### Inspecting what your code wrote
+
+```ts
+const client = createTestClient();
+await myFeature(client); // code under test issues some writes
+
+expect(client.mutations()).toEqual([
+  { kind: "create", doc: { _id: "draft.x", _type: "article" } },
+  { kind: "patch", documentId: "draft.x", ops: [{ kind: "set", props: { status: "ready" } }] },
+]);
+// or assert on whole transactions:
+expect(client.transactions()).toHaveLength(1);
+```
+
+### Not supported — but fails gracefully
+
+The client is wrapped in a `Proxy`. Reaching for a member the fake doesn't implement doesn't give you a bare `undefined is not a function` — it throws an actionable error naming the member, what it is on the real client, and what to do instead:
+
+```
+[client-fake-for-test] `client.listen()` is not implemented (real-time listener …).
+
+This is an in-memory fake of @sanity/client. It implements:
+  fetch, getDocument, getDocuments, create, createOrReplace, …
+
+→ Test your subscription logic in isolation, or register a fake: client.stub("listen", () => myFakeObservable).
+
+Register a stub to fill any gap:  client.stub("listen", handler)
+If this should be supported, open an issue: …
+```
+
+Nested access reports the full path (`client.assets.upload(...)` → `client.assets.upload`). If you type the test variable as `TestClient`, TypeScript also catches the misuse at compile time.
 
 | Area | Status | Workaround |
 | --- | --- | --- |
-| `listen(query, params, options)` — real-time | ❌ Absent | Test the subscription logic separately, mock the observable |
-| `mutate(mutations, options)` — bulk array form | ❌ Absent | Use `transaction()` chain instead |
-| `action(actions, options)` — releases / Content Lake actions | ❌ Absent | Stub the call site, or use MSW |
-| `clone()` | ❌ Absent | `withConfig({})` returns a sibling handle |
-| `getUrl(uri)` / `getDataUrl(...)` — URL builders | ❌ Absent | Hard-code in tests |
-| `request(...)` — generic HTTP | ⚠️ Only with `accessControl` | Use [MSW](https://mswjs.io) for arbitrary HTTP |
-| `agent.*` — Agent Actions | ❌ Absent | Stub the namespace |
-| `assets.*` — uploads, metadata | ❌ Absent | Seed asset docs manually |
-| `users.*` / `projects.*` / `datasets.*` / `releases.*` | ❌ Absent | Stub per call site |
-| `observable.*` — RxJS API | ❌ Absent | Wrap the Promise API with `from()` if needed |
-| Perspectives (`drafts.*` / `published.*` / `raw` config) | ❌ All docs visible | Treat IDs literally; no draft/published split |
+| `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) |
+| `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 |
 
-> [!IMPORTANT]
-> Unsupported methods aren't silently no-op'd — calling one throws (`...is not a function` for the absent ones, `accessControl required` for `request` without setup). If you type the test variable as `TestClient`, TypeScript catches misuse at compile time; if you cast through `SanityClient`, you'll see the error at runtime instead.
+#### Registering stubs
+
+Fill any gap without forking — `client.stub(name, handler)` makes that member resolve to your handler (shared across `withConfig` siblings):
+
+```ts
+const client = createTestClient();
+client.stub("listen", () => fakeObservable);
+client.stub("assets", { upload: vi.fn() });
+```
+
+Stubs fill gaps only — they don't shadow implemented methods like `fetch` or `patch`.
 
 ## Design constraints