@sanity/client 5.0.0-esm.8 → 5.0.0

package/README.md

@@ -5,65 +5,111 @@
 [![gzip size][gzip-badge]][bundlephobia]
 [![size][size-badge]][bundlephobia]
 
-Javascript client for Sanity. Works in [Node.js](https://nodejs.org/en/), [Bun], [Deno], [Edge Runtime] and [modern browsers].
+JavaScript client for Sanity. Works in modern browsers, as well as runtimes like [Node.js], [Bun], [Deno], and [Edge Runtime]
+
+## QuickStart
+
+Install the client with a package manager:
+
+```sh
+npm install @sanity/client
+```
+
+Import and create a new client instance, and use its methods to interact with your project's [Content Lake]. Below are some simple examples in plain JavaScript. Read further for more comprehensive documentation.
+
+```js
+// sanity.js
+import {createClient} from '@sanity/client'
+// Import using ESM URL imports in environments that supports it:
+// import {createClient} from 'https://esm.sh/@sanity/client'
+
+export 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
+  // token: process.env.SANITY_SECRET_TOKEN // Only if you want to update content with the client
+})
+
+// uses GROQ to query content: https://www.sanity.io/docs/groq
+export async function getPosts() {
+  const posts = await client.fetch('*[_type == "post"]')
+  return posts
+}
+
+export async function createPost(post: Post) {
+  const result = client.create(post)
+  return result
+}
+
+export async function updateDocumentTitle(_id, title) {
+  const result = client.patch(_id).set({title})
+  return result
+}
+```
 
 # Table of contents<!-- omit in toc -->
 
-- [@sanity/client](#sanityclient)
-  - [Requirements](#requirements)
-  - [Installation](#installation)
-  - [API](#api)
-    - [Creating a client instance](#creating-a-client-instance)
-      - [ESM](#esm)
-      - [CommonJS](#commonjs)
-      - [TypeScript](#typescript)
-      - [Bun](#bun)
-      - [Deno](#deno)
-      - [Edge Runtime](#edge-runtime)
-      - [Browser ESM CDN](#browser-esm-cdn)
-      - [UMD](#umd)
-    - [Specifying API version](#specifying-api-version)
-    - [Performing queries](#performing-queries)
-    - [Listening to queries](#listening-to-queries)
-    - [Fetch a single document](#fetch-a-single-document)
-    - [Fetch multiple documents in one go](#fetch-multiple-documents-in-one-go)
-    - [Creating documents](#creating-documents)
-    - [Creating/replacing documents](#creatingreplacing-documents)
-    - [Creating if not already present](#creating-if-not-already-present)
-    - [Patch/update a document](#patchupdate-a-document)
-    - [Setting a field only if not already present](#setting-a-field-only-if-not-already-present)
-    - [Removing/unsetting fields](#removingunsetting-fields)
-    - [Incrementing/decrementing numbers](#incrementingdecrementing-numbers)
-    - [Patch a document only if revision matches](#patch-a-document-only-if-revision-matches)
-    - [Adding elements to an array](#adding-elements-to-an-array)
-    - [Appending/prepending elements to an array](#appendingprepending-elements-to-an-array)
-    - [Deleting an element from an array](#deleting-an-element-from-an-array)
-    - [Delete documents](#delete-documents)
-    - [Multiple mutations in a transaction](#multiple-mutations-in-a-transaction)
-    - [Clientless patches \& transactions](#clientless-patches--transactions)
-    - [Uploading assets](#uploading-assets)
-      - [Examples: Uploading assets from Node.js](#examples-uploading-assets-from-nodejs)
-      - [Examples: Uploading assets from the Browser](#examples-uploading-assets-from-the-browser)
-      - [Examples: Specify image metadata to extract](#examples-specify-image-metadata-to-extract)
-    - [Deleting an asset](#deleting-an-asset)
-    - [Mutation options](#mutation-options)
-    - [Get client configuration](#get-client-configuration)
-    - [Set client configuration](#set-client-configuration)
-  - [Release new version](#release-new-version)
-  - [License](#license)
-- [Migrate](#migrate)
-  - [From `v4`](#from-v4)
+- [QuickStart](#quickstart)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [API](#api)
+  - [Creating a client instance](#creating-a-client-instance)
+    - [ESM](#esm)
+    - [CommonJS](#commonjs)
+    - [TypeScript](#typescript)
+    - [Bun](#bun)
+    - [Deno](#deno)
+    - [Edge Runtime](#edge-runtime)
+    - [Browser ESM CDN](#browser-esm-cdn)
+    - [UMD](#umd)
+  - [Specifying API version](#specifying-api-version)
+  - [Performing queries](#performing-queries)
+  - [Listening to queries](#listening-to-queries)
+  - [Fetch a single document](#fetch-a-single-document)
+  - [Fetch multiple documents in one go](#fetch-multiple-documents-in-one-go)
+  - [Creating documents](#creating-documents)
+  - [Creating/replacing documents](#creatingreplacing-documents)
+  - [Creating if not already present](#creating-if-not-already-present)
+  - [Patch/update a document](#patchupdate-a-document)
+  - [Setting a field only if not already present](#setting-a-field-only-if-not-already-present)
+  - [Removing/unsetting fields](#removingunsetting-fields)
+  - [Incrementing/decrementing numbers](#incrementingdecrementing-numbers)
+  - [Patch a document only if revision matches](#patch-a-document-only-if-revision-matches)
+  - [Adding elements to an array](#adding-elements-to-an-array)
+  - [Appending/prepending elements to an array](#appendingprepending-elements-to-an-array)
+  - [Deleting an element from an array](#deleting-an-element-from-an-array)
+  - [Delete documents](#delete-documents)
+  - [Multiple mutations in a transaction](#multiple-mutations-in-a-transaction)
+  - [Clientless patches \& transactions](#clientless-patches--transactions)
+  - [Uploading assets](#uploading-assets)
+    - [Examples: Uploading assets from Node.js](#examples-uploading-assets-from-nodejs)
+    - [Examples: Uploading assets from the Browser](#examples-uploading-assets-from-the-browser)
+    - [Examples: Specify image metadata to extract](#examples-specify-image-metadata-to-extract)
+  - [Deleting an asset](#deleting-an-asset)
+  - [Mutation options](#mutation-options)
+  - [Get client configuration](#get-client-configuration)
+  - [Set client configuration](#set-client-configuration)
+- [Release new version](#release-new-version)
+- [License](#license)
+- [From `v4`](#from-v4)
 
 ## Requirements
 
-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. For 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.
+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 we recommend v4.](https://github.com/sanity-io/client/tree/v4.0.0#sanityclient)
 
 ## Installation
 
-The client can be installed from npm:
+The client can be installed from [npm]:
 
-```
+```sh
 npm install @sanity/client
+
+# Alternative package managers
+yarn add @sanity/client
+pnpm install @sanity/client
 ```
 
 ## API
@@ -72,7 +118,7 @@ npm install @sanity/client
 
 `const client = createClient(options)`
 
-Initializes a new Sanity Client. Required options are `projectId`, `dataset`, and `apiVersion`. Setting a value for `useCdn` is encouraged.
+Initializes a new Sanity Client. Required options are `projectId`, `dataset`, and `apiVersion`. Setting a value for `useCdn` is encouraged. Typically you want to have it as `false` in development to always fetch the freshest content and `true` in production environments so that content is fetched from the distributed cache. [You can learn more about the API CDN here][api-cdn].
 
 #### [ESM](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)
 
@@ -81,47 +127,73 @@ 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](https://nodejs.org/api/modules.html#modules-commonjs-modules)
+#### [CommonJS]
 
 ```js
 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](https://www.typescriptlang.org/)
+#### [TypeScript]
 
 ```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)
+
+const data = await client.fetch<number>(`count(*)`)
+// data is typed as `number`
+console.log(`Number of documents: ${data}`)
+```
 
-export default createClient(config)
+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
@@ -136,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}`)
 ```
@@ -165,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}`)
 ```
@@ -199,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',
+    },
+  })
 }
 ```
 
@@ -235,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>
@@ -250,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}`)
 ```
 
@@ -278,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>
 ```
 
@@ -300,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"!
-      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(*)`)
     $('#results').text(`Number of documents: ${data}`)
   })()
 </script>
@@ -314,7 +375,7 @@ The `require-unpkg` library lets you consume `npm` packages from `unpkg.com` sim
 
 ### Specifying API version
 
-Sanity uses ISO dates (YYYY-MM-DD) in UTC timezone for versioning. The explanation for this can be found [in the documentation](http://sanity.io/docs/api-versioning)
+Sanity uses ISO dates (YYYY-MM-DD) in UTC timezone for versioning. The explanation for this can be found [in the documentation][api-versioning]
 
 In general, unless you know what API version you want to use, you'll want to statically set it to today's UTC date when starting a new project. By doing this, you'll get all the latest bugfixes and features, while locking the API to prevent breaking changes.
 
@@ -410,7 +471,7 @@ client.create(doc).then((res) => {
 })
 ```
 
-`client.create(doc)`  
+`client.create(doc)`
 `client.create(doc, mutationOptions)`
 
 Create a document. Argument is a plain JS object representing the document. It must contain a `_type` attribute. It _may_ contain an `_id`. If an ID is not specified, it will automatically be created.
@@ -432,7 +493,7 @@ client.createOrReplace(doc).then((res) => {
 })
 ```
 
-`client.createOrReplace(doc)`  
+`client.createOrReplace(doc)`
 `client.createOrReplace(doc, mutationOptions)`
 
 If you are not sure whether or not a document exists but want to overwrite it if it does, you can use the `createOrReplace()` method. When using this method, the document must contain an `_id` attribute.
@@ -452,7 +513,7 @@ client.createIfNotExists(doc).then((res) => {
 })
 ```
 
-`client.createIfNotExists(doc)`  
+`client.createIfNotExists(doc)`
 `client.createIfNotExists(doc, mutationOptions)`
 
 If you want to create a document if it does not already exist, but fall back without error if it does, you can use the `createIfNotExists()` method. When using this method, the document must contain an `_id` attribute.
@@ -561,7 +622,7 @@ client.patch('bike-123').unset(reviewsToRemove).commit()
 
 A single document can be deleted by specifying a document ID:
 
-`client.delete(docId)`  
+`client.delete(docId)`
 `client.delete(docId, mutationOptions)`
 
 ```js
@@ -1096,6 +1157,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/
@@ -1105,3 +1225,12 @@ client.createOrReplace(doc, options)
 [unpkg-dist]: https://unpkg.com/@sanity/client/umd/
 [bundlephobia]: https://bundlephobia.com/package/@sanity/client
 [esm.sh]: https://esm.sh
+[Node.js]: https://nodejs.org/en/
+[Content Lake]: https://www.sanity.io/docs/datastore
+[npm]: https://npmjs.com
+[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
+[zod]: https://zod.dev/
+[groqd]: https://github.com/FormidableLabs/groqd#readme