@sanity/client 5.0.0-esm.7 → 5.0.0-esm.9

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 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.
 
 ## 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/)
 
@@ -90,7 +136,7 @@ const client = createClient({
 export default client
 ```
 
-#### [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules)
+#### [CommonJS]
 
 ```js
 const {createClient} = require('@sanity/client')
@@ -106,7 +152,7 @@ const client = createClient({
 module.exports = client
 ```
 
-#### [TypeScript](https://www.typescriptlang.org/)
+#### [TypeScript]
 
 ```ts
 import {createClient, type ClientConfig} from '@sanity/client'
@@ -302,8 +348,8 @@ The `require-unpkg` library lets you consume `npm` packages from `unpkg.com` sim
       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
+      token: 'sanity-secret-auth-token', // leave blank for unauthenticated usage
     })
 
     const data = await client.fetch(`count(*[])`)
@@ -314,7 +360,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 +456,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 +478,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 +498,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 +607,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
@@ -1105,3 +1151,10 @@ 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

package/dist/index.browser.cjs

@@ -341,7 +341,7 @@ class BasePatch {
    * @param selector - Attribute or JSONPath expression for array
    * @param start - Index at which to start changing the array (with origin 0). If greater than the length of the array, actual starting index will be set to the length of the array. If negative, will begin that many elements from the end of the array (with origin -1) and will be set to 0 if absolute value is greater than the length of the array.x
    * @param deleteCount - An integer indicating the number of old array elements to remove.
-   * @param items - The elements to add to the array, beginning at the start index. If you don't specify any elements, splice() will only remove elements from the array.
+   * @param items - The elements to add to the array, beginning at the start index. If you don't specify FIXME elements, splice() will only remove elements from the array.
    */
   splice(selector, start, deleteCount, items) {
     const delAll = typeof deleteCount === "undefined" || deleteCount === -1;
@@ -807,7 +807,9 @@ function _requestObservable(client, httpRequest, options) {
   const reqOptions = getRequestOptions(config, Object.assign({}, options, {
     url: _getUrl(client, uri, useCdn)
   }));
-  return new rxjs.Observable(subscriber => httpRequest(reqOptions, config.requester).subscribe(subscriber));
+  return new rxjs.Observable(subscriber =>
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the typings thinks it's optional because it's not required to specify it when calling createClient, but it's always defined in practice since SanityClient provides a default
+  httpRequest(reqOptions, config.requester).subscribe(subscriber));
 }
 function _request(client, httpRequest, options) {
   const observable = _requestObservable(client, httpRequest, options).pipe(operators.filter(event => event.type === "response"), operators.map(event => event.body));
@@ -1553,7 +1555,7 @@ const _ObservableSanityClient = class {
    * Fetch multiple documents in one request.
    * Should be used sparingly - performing a query is usually a better option.
    * The order/position of documents is preserved based on the original array of IDs.
-   * If a any of the documents are missing, they will be replaced by a `null` entry in the returned array
+   * If a FIXME of the documents are missing, they will be replaced by a `null` entry in the returned array
    *
    * @param ids - Document IDs to fetch
    * @param options - Request options
@@ -1676,7 +1678,7 @@ const _SanityClient = class {
    * Fetch multiple documents in one request.
    * Should be used sparingly - performing a query is usually a better option.
    * The order/position of documents is preserved based on the original array of IDs.
-   * If a any of the documents are missing, they will be replaced by a `null` entry in the returned array
+   * If a FIXME of the documents are missing, they will be replaced by a `null` entry in the returned array
    *
    * @param ids - Document IDs to fetch
    * @param options - Request options