@sanity/client 5.0.0-esm.4 → 5.0.0-esm.6

package/README.md

@@ -1,67 +1,58 @@
-# @sanity/client<!-- omit in toc -->
+# @sanity/client
 
 [![npm stat](https://img.shields.io/npm/dm/@sanity/client.svg?style=flat-square)](https://npm-stat.com/charts.html?package=@sanity/client)
 [![npm version](https://img.shields.io/npm/v/@sanity/client.svg?style=flat-square)](https://www.npmjs.com/package/@sanity/client)
-[![gzip size][gzip-badge]][unpkg-dist]
-[![size][size-badge]][unpkg-dist]
+[![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].
 
-## Table of contents<!-- omit in toc -->
-
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [API](#api)
-  - [Creating a client instance](#creating-a-client-instance)
-    - [ESM](#esm)
-    - [CommonJS](#commonjs)
-    - [TypeScript](#typescript)
-    - [Bun](#bun)
-  - [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)
+# 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)
-    - [No longer shipping `ES5`](#no-longer-shipping-es5)
-    - [Node.js `v12` no longer supported](#nodejs-v12-no-longer-supported)
-    - [The `default` export is replaced with the named export `createClient`](#the-default-export-is-replaced-with-the-named-export-createclient)
-    - [`client.assets.delete` is removed](#clientassetsdelete-is-removed)
-    - [`client.assets.getImageUrl` is removed, replace with `@sanity/image-url`](#clientassetsgetimageurl-is-removed-replace-with-sanityimage-url)
-    - [`SanityClient` static properties moved to named exports](#sanityclient-static-properties-moved-to-named-exports)
-    - [`client.clientConfig` is removed, replace with `client.config()`](#clientclientconfig-is-removed-replace-with-clientconfig)
-    - [`client.getUrl()` is removed](#clientgeturl-is-removed)
-    - [`client.getDataUrl()` is removed](#clientgetdataurl-is-removed)
-    - [`client.isPromiseAPI()` is removed, replace with `instanceof` check](#clientispromiseapi-is-removed-replace-with-instanceof-check)
-    - [`client.observable.isObservableAPI()` is removed, replace with `instanceof` check](#clientobservableisobservableapi-is-removed-replace-with-instanceof-check)
-    - [`client._requestObservable` is removed, replace with `client.observable.request`](#client_requestobservable-is-removed-replace-with-clientobservablerequest)
-    - [`client._dataRequest` is removed, replace with `client.dataRequest`](#client_datarequest-is-removed-replace-with-clientdatarequest)
-    - [`client._create_` is removed, replace with one of `client.create`, `client.createIfNotExists` or `client.createOrReplace`](#client_create_-is-removed-replace-with-one-of-clientcreate-clientcreateifnotexists-or-clientcreateorreplace)
-- [Release new version](#release-new-version)
-- [License](#license)
 
 ## Requirements
 
@@ -87,6 +78,7 @@ Initializes a new Sanity Client. Required options are `projectId`, `dataset`, an
 
 ```js
 import {createClient} from '@sanity/client'
+
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'bikeshop',
@@ -102,6 +94,7 @@ export default client
 
 ```js
 const {createClient} = require('@sanity/client')
+
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'bikeshop',
@@ -132,21 +125,191 @@ export default createClient(config)
 #### [Bun]
 
 ```bash
-bun
+bun init
+bun add @sanity/client
+open index.ts
 ```
 
 ```ts
-import {createClient, type ClientConfig} from '@sanity/client'
+// index.ts
+import {createClient} from '@sanity/client'
 
-const client: ClientConfig = {
+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
+})
+
+const data = await client.fetch(`count(*[])`)
+
+console.write(`Number of documents: ${data}`)
+```
+
+```bash
+bun run index.ts
+# Number of documents ${number}
+```
+
+#### [Deno]
+
+```bash
+deno init
+open main.ts
+```
+
+```ts
+// main.ts
+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
+})
+
+const data = await client.fetch(`count(*[])`)
+
+console.log(`Number of documents: ${data}`)
+```
+
+```bash
+deno run --allow-net --allow-env main.ts
+# Number of documents ${number}
+```
+
+#### [Edge Runtime]
+
+```bash
+npm install next
+```
+
+```ts
+// pages/api/total.ts
+import {createClient} from '@sanity/client'
+import type {NextRequest} from 'next/server'
+
+export const config = {
+  runtime: 'edge',
 }
 
-export default createClient(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
+  })
+
+  return new Response(
+    JSON.stringify({
+      count: await client.fetch(`count(*[])`),
+    }),
+    {
+      status: 200,
+      headers: {
+        'content-type': 'application/json',
+      },
+    }
+  )
+}
+```
+
+```bash
+npx next dev
+# Open http://localhost:3000/api/total
+# {"count": number}
+```
+
+#### Browser ESM CDN
+
+Using [esm.sh] you can either load the client using a `<script type="module">` tag:
+
+```html
+<script type="module">
+  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
+  })
+
+  const data = await client.fetch(`count(*[])`)
+  document.getElementById('results').innerText = `Number of documents: ${data}`
+</script>
+<div id="results"></div>
+```
+
+Or from anywhere using a dynamic `import()`:
+
+```js
+// You can run this snippet from your browwser 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
+})
+
+const data = await client.fetch(`count(*[])`)
+console.log(`Number of documents: ${data}`)
+```
+
+#### [UMD][unpkg-dist]
+
+Loading the UMD script creates a `SanityClient` global that have the same exports as `import * as SanityClient from '@sanity/client'`:
+
+```html
+<script src="https://unpkg.com/@sanity/client"></script>
+<!-- Unminified build for debugging -->
+<!--<script src="https://unpkg.com/@sanity/client/umd/sanityClient.js"></script>-->
+<script>
+  const {createClient} = SanityClient
+
+  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
+  })
+
+  client.fetch(`count(*[])`).then((data) => console.log(`Number of documents: ${data}`))
+</script>
+```
+
+The `require-unpkg` library lets you consume `npm` packages from `unpkg.com` similar to how `esm.sh` lets you `import()` anything:
+
+```html
+<div id="results"></div>
+<script src="https://unpkg.com/require-unpkg"></script>
+<script>
+  ;(async () => {
+    // const {createClient} = await require('@sanity/client')
+    const [$, {createClient}] = await require(['jquery', '@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
+    })
+
+    const data = await client.fetch(`count(*[])`)
+    $('#results').text(`Number of documents: ${data}`)
+  })()
+</script>
 ```
 
 ### Specifying API version
@@ -643,23 +806,30 @@ client.config({dataset: 'newDataset'})
 
 Set client configuration. Required options are `projectId` and `dataset`.
 
-## Migrate
+## Release new version
 
-### From `v4`
+Run ["CI & Release" workflow](https://github.com/sanity-io/client/actions/workflows/ci.yml).
+Make sure to select the main branch and check "Release new version".
 
-#### No longer shipping `ES5`
+Semantic release will only release on configured branches, so it is safe to run release on any branch.
 
-The target is changed to [modern browsers] that supports `ES6` `class`, `{...rest}` syntax and more. You may need to update your bundler to a recent major version. Or you could configure your bundler to transpile `@sanity/client`, and `get-it`, which is the engine that powers `@sanity/client` and uses the same output target.
+## License
 
----
+MIT © [Sanity.io](https://www.sanity.io/)
 
-#### Node.js `v12` no longer supported
+# Migrate
 
-Upgrade to the [LTS release, or one of the Maintenance releases](https://github.com/nodejs/release#release-schedule).
+## From `v4`
+
+### No longer shipping `ES5`<!-- omit in toc -->
 
----
+The target is changed to [modern browsers] that supports `ES6` `class`, `{...rest}` syntax and more. You may need to update your bundler to a recent major version. Or you could configure your bundler to transpile `@sanity/client`, and `get-it`, which is the engine that powers `@sanity/client` and uses the same output target.
 
-#### The `default` export is replaced with the named export `createClient`
+### Node.js `v12` no longer supported<!-- omit in toc -->
+
+Upgrade to the [LTS release, or one of the Maintenance releases](https://github.com/nodejs/release#release-schedule).
+
+### The `default` export is replaced with the named export `createClient`<!-- omit in toc -->
 
 Before:
 
@@ -680,9 +850,7 @@ import {createClient} from '@sanity/client'
 const client = createClient()
 ```
 
----
-
-#### `client.assets.delete` is removed
+### `client.assets.delete` is removed<!-- omit in toc -->
 
 Before:
 
@@ -698,9 +866,7 @@ After:
 client.delete('image-abc123_foobar-123x123-png')
 ```
 
----
-
-#### `client.assets.getImageUrl` is removed, replace with [`@sanity/image-url`](https://github.com/sanity-io/image-url)
+### `client.assets.getImageUrl` is removed, replace with [`@sanity/image-url`](https://github.com/sanity-io/image-url)<!-- omit in toc -->
 
 Before:
 
@@ -731,7 +897,7 @@ urlFor({_ref: 'image-abc123_foobar-123x123-png'}).url()
 urlFor({_ref: 'image-abc123_foobar-123x123-png'}).auto('format').url()
 ```
 
-#### `SanityClient` static properties moved to named exports
+### `SanityClient` static properties moved to named exports<!-- omit in toc -->
 
 Before:
 
@@ -747,9 +913,7 @@ After:
 import {Patch, Transaction, ClientError, ServerError, requester} from '@sanity/client'
 ```
 
----
-
-#### `client.clientConfig` is removed, replace with `client.config()`
+### `client.clientConfig` is removed, replace with `client.config()`<!-- omit in toc -->
 
 Before:
 
@@ -769,9 +933,7 @@ const client = createClient()
 console.log(client.config().projectId)
 ```
 
----
-
-#### `client.getUrl()` is removed
+### `client.getUrl()` is removed<!-- omit in toc -->
 
 Before:
 
@@ -799,9 +961,7 @@ console.log(getUrl('/foo/bar') === 'https://abc123.api.sanity.io/v1/foo/bar')
 console.log(getUrl('/foo/bar', true) === 'https://abc123.apicdn.sanity.io/v1/foo/bar')
 ```
 
----
-
-#### `client.getDataUrl()` is removed
+### `client.getDataUrl()` is removed<!-- omit in toc -->
 
 Before:
 
@@ -830,9 +990,7 @@ console.log(getDataUrl('doc') === '/data/doc/bikeshop')
 console.log(getDataUrl('doc', 'bike-123') === '/data/doc/bikeshop/bike-123')
 ```
 
----
-
-#### `client.isPromiseAPI()` is removed, replace with `instanceof` check
+### `client.isPromiseAPI()` is removed, replace with an `instanceof` check<!-- omit in toc -->
 
 Before:
 
@@ -854,9 +1012,7 @@ const client = createClient()
 console.log(client instanceof SanityClient)
 ```
 
----
-
-#### `client.observable.isObservableAPI()` is removed, replace with `instanceof` check
+### `client.observable.isObservableAPI()` is removed, replace with an `instanceof` check<!-- omit in toc -->
 
 Before:
 
@@ -876,9 +1032,7 @@ const client = createClient()
 console.log(client.observable instanceof ObservableSanityClient)
 ```
 
----
-
-#### `client._requestObservable` is removed, replace with `client.observable.request`
+### `client._requestObservable` is removed, replace with `client.observable.request`<!-- omit in toc -->
 
 Before:
 
@@ -898,9 +1052,7 @@ const client = createClient()
 client.observable.request({uri: '/ping'}).subscribe()
 ```
 
----
-
-#### `client._dataRequest` is removed, replace with `client.dataRequest`
+### `client._dataRequest` is removed, replace with `client.dataRequest`<!-- omit in toc -->
 
 Before:
 
@@ -920,9 +1072,7 @@ const client = createClient()
 client.dataRequest(endpoint, body, options)
 ```
 
----
-
-#### `client._create_` is removed, replace with one of `client.create`, `client.createIfNotExists` or `client.createOrReplace`
+### `client._create_` is removed, replace with one of `client.create`, `client.createIfNotExists` or `client.createOrReplace`<!-- omit in toc -->
 
 Before:
 
@@ -946,19 +1096,6 @@ client.createIfNotExists(doc, options)
 client.createOrReplace(doc, options)
 ```
 
----
-
-## Release new version
-
-Run ["CI & Release" workflow](https://github.com/sanity-io/client/actions/workflows/ci.yml).
-Make sure to select the main branch and check "Release new version".
-
-Semantic release will only release on configured branches, so it is safe to run release on any branch.
-
-## License
-
-MIT © [Sanity.io](https://www.sanity.io/)
-
 [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/
@@ -966,3 +1103,5 @@ MIT © [Sanity.io](https://www.sanity.io/)
 [gzip-badge]: https://img.shields.io/bundlephobia/minzip/@sanity/client?label=gzip%20size&style=flat-square
 [size-badge]: https://img.shields.io/bundlephobia/min/@sanity/client?label=size&style=flat-square
 [unpkg-dist]: https://unpkg.com/@sanity/client/umd/
+[bundlephobia]: https://bundlephobia.com/package/@sanity/client
+[esm.sh]: https://esm.sh