@sanity/client 5.0.0-esm.9 → 5.1.0

package/README.md

@@ -19,7 +19,7 @@ Import and create a new client instance, and use its methods to interact with yo
 
 ```js
 // sanity.js
-import {createClient} from '@sanity/client'
+import {createClient} from '@sanity/client'
 // Import using ESM URL imports in environments that supports it:
 // import {createClient} from 'https://esm.sh/@sanity/client'
 
@@ -98,7 +98,7 @@ export async function updateDocumentTitle(_id, title) {
 
 Sanity Client transpiles syntax for [modern browsers]. The JavaScript runtime must support ES6 features such as [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), [rest parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), [spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) and more. Most modern web frameworks, [browsers][modern browsers], and developer tooling supports ES6 today.
 
-For legacy ES5 environments you'll need to transpile `@sanity/client` and its `dependencies` with your own bundler, and have a global ES6-compliant `Promise` available. If your runtime environment doesn't provide a spec compliant `Promise` implementation, we recommend using [native-promise-only](https://www.npmjs.com/package/native-promise-only), [es6-promise](https://www.npmjs.com/package/es6-promise) or another [spec-compliant](https://promisesaplus.com/implementations) implementation. See [this article](https://www.sanity.io/help/js-client-promise-polyfill) for more information.
+[For legacy ES5 environments we recommend v4.](https://github.com/sanity-io/client/tree/v4.0.0#sanityclient)
 
 ## Installation
 
@@ -127,13 +127,13 @@ import {createClient} from '@sanity/client'
 
 const client = createClient({
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
-export default client
+const data = await client.fetch(`count(*)`)
+console.log(`Number of documents: ${data}`)
 ```
 
 #### [CommonJS]
@@ -143,13 +143,15 @@ const {createClient} = require('@sanity/client')
 
 const client = createClient({
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
-module.exports = client
+client
+  .fetch(`count(*)`)
+  .then((data) => console.log(`Number of documents: ${data}`))
+  .catch(console.error)
 ```
 
 #### [TypeScript]
@@ -157,17 +159,41 @@ module.exports = client
 ```ts
 import {createClient, type ClientConfig} from '@sanity/client'
 
-const client: ClientConfig = {
+const config: ClientConfig = {
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 }
+const client = createClient(config)
 
-export default createClient(config)
+const data = await client.fetch<number>(`count(*)`)
+// data is typed as `number`
+console.log(`Number of documents: ${data}`)
 ```
 
+We're currently exploring typed GROQ queries that are runtime safe, and will share more when we've landed on a solution we're satisifed with.
+Until then you can achieve this using [Zod]:
+
+```ts
+import {createClient} from '@sanity/client'
+import {z} from 'zod'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+})
+
+const schema = z.number()
+const data = schema.parse(await client.fetch(`count(*)`))
+// data is guaranteed to be `number`, or zod will throw an error
+console.log(`Number of documents: ${data}`)
+```
+
+Another alternative is [groqd].
+
 #### [Bun]
 
 ```bash
@@ -182,13 +208,12 @@ import {createClient} from '@sanity/client'
 
 const client = createClient({
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
-const data = await client.fetch(`count(*[])`)
+const data = await client.fetch<number>(`count(*)`)
 
 console.write(`Number of documents: ${data}`)
 ```
@@ -211,13 +236,12 @@ import {createClient} from 'https://esm.sh/@sanity/client'
 
 const client = createClient({
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
-const data = await client.fetch(`count(*[])`)
+const data = await client.fetch<number>(`count(*)`)
 
 console.log(`Number of documents: ${data}`)
 ```
@@ -245,23 +269,18 @@ export const config = {
 export default async function handler(req: NextRequest) {
   const client = createClient({
     projectId: 'your-project-id',
-    dataset: 'bikeshop',
-    apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-    token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-    useCdn: true, // `false` if you want to ensure fresh data
+    dataset: 'your-dataset-name',
+    useCdn: false, // set to `true` to fetch from edge cache
+    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
-  return new Response(
-    JSON.stringify({
-      count: await client.fetch(`count(*[])`),
-    }),
-    {
-      status: 200,
-      headers: {
-        'content-type': 'application/json',
-      },
-    }
-  )
+  const count = await client.fetch<number>(`count(*)`)
+  return new Response(JSON.stringify({count}), {
+    status: 200,
+    headers: {
+      'content-type': 'application/json',
+    },
+  })
 }
 ```
 
@@ -281,13 +300,12 @@ Using [esm.sh] you can either load the client using a `<script type="module">` t
 
   const client = createClient({
     projectId: 'your-project-id',
-    dataset: 'bikeshop',
-    apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-    token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-    useCdn: true, // `false` if you want to ensure fresh data
+    dataset: 'your-dataset-name',
+    useCdn: false, // set to `true` to fetch from edge cache
+    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
-  const data = await client.fetch(`count(*[])`)
+  const data = await client.fetch(`count(*)`)
   document.getElementById('results').innerText = `Number of documents: ${data}`
 </script>
 <div id="results"></div>
@@ -296,18 +314,17 @@ Using [esm.sh] you can either load the client using a `<script type="module">` t
 Or from anywhere using a dynamic `import()`:
 
 ```js
-// You can run this snippet from your browwser DevTools console.
+// You can run this snippet from your browser DevTools console.
 // Super handy when you're quickly testing out queries.
 const {createClient} = await import('https://esm.sh/@sanity/client')
 const client = createClient({
   projectId: 'your-project-id',
-  dataset: 'bikeshop',
-  apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-  token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-  useCdn: true, // `false` if you want to ensure fresh data
+  dataset: 'your-dataset-name',
+  useCdn: false, // set to `true` to fetch from edge cache
+  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
-const data = await client.fetch(`count(*[])`)
+const data = await client.fetch(`count(*)`)
 console.log(`Number of documents: ${data}`)
 ```
 
@@ -324,13 +341,12 @@ Loading the UMD script creates a `SanityClient` global that have the same export
 
   const client = createClient({
     projectId: 'your-project-id',
-    dataset: 'bikeshop',
-    apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-    token: 'sanity-auth-token', // or leave blank for unauthenticated usage
-    useCdn: true, // `false` if you want to ensure fresh data
+    dataset: 'your-dataset-name',
+    useCdn: false, // set to `true` to fetch from edge cache
+    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
-  client.fetch(`count(*[])`).then((data) => console.log(`Number of documents: ${data}`))
+  client.fetch(`count(*)`).then((data) => console.log(`Number of documents: ${data}`))
 </script>
 ```
 
@@ -346,13 +362,12 @@ The `require-unpkg` library lets you consume `npm` packages from `unpkg.com` sim
 
     const client = createClient({
       projectId: 'your-project-id',
-      dataset: 'bikeshop',
-      apiVersion: '2021-03-25', // use current UTC date - see "specifying API version"!
-      useCdn: true, // `false` if you want to ensure fresh data
-      token: 'sanity-secret-auth-token', // leave blank for unauthenticated usage
+      dataset: 'your-dataset-name',
+      useCdn: false, // set to `true` to fetch from edge cache
+      apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
     })
 
-    const data = await client.fetch(`count(*[])`)
+    const data = await client.fetch(`count(*)`)
     $('#results').text(`Number of documents: ${data}`)
   })()
 </script>
@@ -831,6 +846,49 @@ The following options are available for mutations, and can be applied either as
 - `dryRun` (`true|false`) - default `false`. If true, the mutation will be a dry run - the response will be identical to the one returned had this property been omitted or false (including error responses) but no documents will be affected.
 - `autoGenerateArrayKeys` (`true|false`) - default `false`. If true, the mutation API will automatically add `_key` attributes to objects in arrays that is missing them. This makes array operations more robust by having a unique key within the array available for selections, which helps prevent race conditions in real-time, collaborative editing.
 
+### Aborting a request
+
+Requests can be aborted (or cancelled) in two ways:
+
+#### 1. Abort a request by passing an [AbortSignal] with the request options
+
+Sanity Client supports the [AbortController] API and supports receiving an abort signal that can be used to cancel the request. Here's an example that will abort the request if it takes more than 200ms to complete:
+
+```js
+const abortController = new AbortController()
+
+// note the lack of await here
+const request = getClient().fetch('*[_type == "movie"]', {}, {signal: abortController.signal})
+
+// this will abort the request after 200ms
+setTimeout(() => abortController.abort(), 200)
+
+try {
+  const response = await request
+  //…
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request was aborted')
+  } else {
+    // rethrow in case of other errors
+    throw error
+  }
+}
+```
+
+#### 2. Cancel a request by unsubscribing from the Observable
+
+When using the Observable API (e.g. `client.observable.fetch()`), you can cancel the request by simply `unsubscribe` from the returned observable:
+
+```js
+const subscription = client.observable.fetch('*[_type == "movie"]').subscribe((result) => {
+  /* do something with the result */
+})
+
+// this will cancel the request
+subscription.unsubscribe()
+```
+
 ### Get client configuration
 
 ```js
@@ -1142,6 +1200,65 @@ client.createIfNotExists(doc, options)
 client.createOrReplace(doc, options)
 ```
 
+### `client.patch.replace` is removed, replace with `client.createOrReplace`<!-- omit in toc -->
+
+Before:
+
+```ts
+import createClient from '@sanity/client'
+const client = createClient()
+
+client.patch('tropic-hab').replace({name: 'Tropical Habanero', ingredients: []}).commit()
+```
+
+After:
+
+```ts
+import {createClient} from '@sanity/client'
+const client = createClient()
+
+client.createOrReplace({
+  _id: 'tropic-hab',
+  _type: 'hotsauce',
+  name: 'Tropical Habanero',
+  ingredients: [],
+})
+```
+
+### `client.auth` is removed, replace with `client.request`<!-- omit in toc -->
+
+Before:
+
+```ts
+import createClient from '@sanity/client'
+const client = createClient()
+
+/**
+ * Fetch available login providers
+ */
+const loginProviders = await client.auth.getLoginProviders()
+/**
+ * Revoke the configured session/token
+ */
+await client.auth.logout()
+```
+
+After:
+
+```ts
+import {createclient, type AuthProviderResponse} from '@sanity/client'
+const client = createClient()
+
+/**
+ * Fetch available login providers
+ */
+const loginProviders = await client.request<AuthProviderResponse>({uri: '/auth/providers'})
+/**
+ * Revoke the configured session/token
+ */
+await client.request<void>({uri: '/auth/logout', method: 'POST'})
+```
+
 [modern browsers]: https://browsersl.ist/#q=%3E+0.2%25+and+supports+es6-module+and+supports+es6-module-dynamic-import+and+not+dead+and+not+IE+11
 [Deno]: https://deno.land/
 [Edge Runtime]: https://edge-runtime.vercel.sh/
@@ -1157,4 +1274,8 @@ client.createOrReplace(doc, options)
 [api-cdn]: https://www.sanity.io/docs/api-cdn
 [CommonJS]: https://nodejs.org/api/modules.html#modules-commonjs-modules
 [TypeScript]: https://www.typescriptlang.org/
-[api-versioning]: http://sanity.io/docs/api-versioning
+[api-versioning]: http://sanity.io/docs/api-versioning
+[zod]: https://zod.dev/
+[groqd]: https://github.com/FormidableLabs/groqd#readme
+[AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+[AbortController]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController