@sanity/client 7.26.2 → 7.27.0

package/README.md

@@ -62,6 +62,7 @@ export async function updateDocumentTitle(_id, title) {
     - [ESM](#esm)
     - [CommonJS](#commonjs)
     - [TypeScript](#typescript)
+    - [Typed query results with Sanity TypeGen](#typed-query-results-with-sanity-typegen)
     - [Next.js App Router](#nextjs-app-router)
     - [Bun](#bun)
     - [Deno](#deno)
@@ -266,6 +267,52 @@ console.log(`Number of documents: ${data}`)
 
 Another alternative is [groqd].
 
+#### Typed query results with [Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen)
+
+`client.fetch` looks the query string up in the global `SanityQueries` interface and returns the registered result type when it finds one. `sanity typegen generate` writes these registrations for you, one per query it finds in your code, but the mechanism is plain interface merging:
+
+```ts
+import {createClient} from '@sanity/client'
+
+// Generated by `sanity typegen`, or written by hand
+declare global {
+  interface SanityQueries {
+    '*[_type == "post"]': {_id: string; title: string}[]
+  }
+}
+
+const client = createClient({
+  projectId: 'your-project-id',
+  dataset: 'your-dataset-name',
+  apiVersion: '2025-02-06',
+})
+
+const posts = await client.fetch('*[_type == "post"]')
+// posts is typed as `{_id: string; title: string}[]`, no generic needed
+```
+
+The registry is a global interface rather than a module augmentation of `@sanity/client`, so it does not depend on module resolution: a registration is seen whether or not `@sanity/client` is a direct dependency of the file that makes it, however many copies of the client are installed (a copy nested inside another package reads the same registry), and from every entry point, `@sanity/client/stega` included.
+
+Two more forms are accepted:
+
+- The module augmentation that earlier TypeGen releases generated keeps working. It registers on the `SanityQueries` interface exported from `@sanity/client`, which inherits the global one:
+
+  ```ts
+  declare module '@sanity/client' {
+    interface SanityQueries {
+      '*[_type == "post"]': {_id: string; title: string}[]
+    }
+  }
+  ```
+
+- Releases of `@sanity/client` that predate the global registry only read that exported interface. A generated file that registers queries globally can still reach them with an augmentation that adds nothing but a base type, which is what `sanity typegen` emits alongside the global registry. It is a harmless duplicate on releases that already inherit the global, so the same generated file works with either:
+
+  ```ts
+  declare module '@sanity/client' {
+    interface SanityQueries extends globalThis.SanityQueries {}
+  }
+  ```
+
 #### [Next.js App Router](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#fetching-data-on-the-server-with-fetch)
 
 ```tsx
@@ -897,7 +944,7 @@ const videoAsset = stegaClean(result.videoAsset)
 
 Strings with stega payloads contain invisible characters, so comparing them against string literals fails in surprising ways: `imageLocation === 'left'` is `false` even though `imageLocation` looks exactly like `'left'` when logged. The branded types available on `@sanity/client/stega` turn these bugs into compile errors.
 
-If you use [Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen), pass `ClientReturnStega` as the first generic to `client.fetch` and every string in the result that may contain stega payloads is branded as `StegaString`:
+If you use [Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen), pass `ClientReturnStega` as the first generic to `client.fetch` and every string in the result that may contain stega payloads is branded as `StegaString`. It looks the query up in the same `SanityQueries` registry as `client.fetch` does (see [Typed query results with Sanity TypeGen](#typed-query-results-with-sanity-typegen)):
 
 ```ts
 import {createClient} from '@sanity/client'