@sanity/client 6.4.10 → 6.4.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "6.4.10",
+  "version": "6.4.12",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -72,7 +72,7 @@
     "test": "vitest",
     "type-check": "tsc --noEmit",
     "test:browser": "npm test -- --config ./vitest.browser.config.ts",
-    "test:bun": "(cd runtimes/bun && bun wiptest)",
+    "test:bun": "bun test runtimes/bun",
     "test:deno": "deno test --allow-read --allow-net --allow-env --fail-fast --import-map=runtimes/deno/import_map.json runtimes/deno",
     "test:deno:update_import_map": "deno run --allow-read --allow-write runtimes/deno/update_import_map.ts",
     "posttest:deno:update_import_map": "npx prettier --write runtimes/deno/import_map.json",
@@ -95,39 +95,34 @@
     "rxjs": "^7.0.0"
   },
   "devDependencies": {
-    "@edge-runtime/types": "^2.2.1",
-    "@edge-runtime/vm": "^3.1.1",
+    "@edge-runtime/types": "^2.2.3",
+    "@edge-runtime/vm": "^3.1.3",
     "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-node-resolve": "^15.2.1",
     "@sanity/pkg-utils": "^2.4.8",
-    "@sanity/semantic-release-preset": "^4.1.4",
-    "@types/node": "^20.5.9",
-    "@typescript-eslint/eslint-plugin": "^6.6.0",
-    "@typescript-eslint/parser": "^6.6.0",
-    "@vitest/coverage-v8": "^0.34.3",
-    "eslint": "^8.48.0",
+    "@types/node": "^20.6.0",
+    "@typescript-eslint/eslint-plugin": "^6.7.0",
+    "@typescript-eslint/parser": "^6.7.0",
+    "@vitest/coverage-v8": "^0.34.4",
+    "eslint": "^8.49.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "faucet": "^0.0.4",
-    "happy-dom": "^10.11.2",
+    "happy-dom": "^11.0.5",
     "ls-engines": "^0.9.0",
     "nock": "^13.3.3",
     "prettier": "^3.0.3",
     "prettier-plugin-packagejson": "^2.4.5",
     "rimraf": "^5.0.1",
-    "rollup": "^3.28.1",
+    "rollup": "^3.29.1",
     "sse-channel": "^4.0.0",
     "terser": "^5.19.4",
     "typescript": "^5.2.2",
-    "vitest": "^0.34.3",
+    "vitest": "^0.34.4",
     "vitest-github-actions-reporter": "^0.10.0"
   },
   "engines": {
     "node": ">=14.18"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
   }
 }

package/src/SanityClient.ts

@@ -586,11 +586,39 @@ export class ObservableSanityClient {
   /**
    * Create a new buildable patch of operations to perform
    *
-   * @param documentId - Document ID(s) to patch
+   * @param documentId - Document ID to patch
    * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
    */
-  patch(documentId: PatchSelection, operations?: PatchOperations): ObservablePatch {
-    return new ObservablePatch(documentId, operations, this)
+  patch(documentId: string, operations?: PatchOperations): ObservablePatch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param documentIds - Array of document IDs to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(documentIds: string[], operations?: PatchOperations): ObservablePatch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param selection - An object with `query` and optional `params`, defining which document(s) to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(selection: MutationSelection, operations?: PatchOperations): ObservablePatch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param selection - Document ID, an array of document IDs, or an object with `query` and optional `params`, defining which document(s) to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(selection: PatchSelection, operations?: PatchOperations): ObservablePatch {
+    return new ObservablePatch(selection, operations, this)
   }
 
   /**
@@ -605,9 +633,8 @@ export class ObservableSanityClient {
   }
 
   /**
-   * DEPRECATED: Perform an HTTP request against the Sanity API
+   * Perform an HTTP request against the Sanity API
    *
-   * @deprecated Use your own request library!
    * @param options - Request options
    */
   request<R = Any>(options: RawRequestOptions): Observable<R> {
@@ -1191,8 +1218,36 @@ export class SanityClient {
   /**
    * Create a new buildable patch of operations to perform
    *
-   * @param documentId - Document ID(s)to patch
+   * @param documentId - Document ID to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(documentId: string, operations?: PatchOperations): Patch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param documentIds - Array of document IDs to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(documentIds: string[], operations?: PatchOperations): Patch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param selection - An object with `query` and optional `params`, defining which document(s) to patch
+   * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
+   */
+  patch(selection: MutationSelection, operations?: PatchOperations): Patch
+
+  /**
+   * Create a new buildable patch of operations to perform
+   *
+   * @param selection - Document ID, an array of document IDs, or an object with `query` and optional `params`, defining which document(s) to patch
    * @param operations - Optional object of patch operations to initialize the patch instance with
+   * @returns Patch instance - call `.commit()` to perform the operations defined
    */
   patch(documentId: PatchSelection, operations?: PatchOperations): Patch {
     return new Patch(documentId, operations, this)

package/src/data/listen.ts

@@ -29,8 +29,8 @@ const defaultOptions = {
  *
  * @param query - GROQ-filter to listen to changes for
  * @param params - Optional query parameters
- * @param options - Listener options
- * @internal
+ * @param options - Optional listener options
+ * @public
  */
 export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   this: SanityClient | ObservableSanityClient,
@@ -42,8 +42,8 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
  *
  * @param query - GROQ-filter to listen to changes for
  * @param params - Optional query parameters
- * @param options - Listener options
- * @internal
+ * @param options - Optional listener options
+ * @public
  */
 export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   this: SanityClient | ObservableSanityClient,
@@ -51,7 +51,7 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   params?: QueryParams,
   options?: ListenOptions,
 ): Observable<ListenEvent<R>>
-/** @internal */
+/** @public */
 export function _listen<R extends Record<string, Any> = Record<string, Any>>(
   this: SanityClient | ObservableSanityClient,
   query: string,

package/src/types.ts

@@ -439,42 +439,154 @@ export type Mutation<R extends Record<string, Any> = Record<string, Any>> =
   | {delete: MutationSelection}
   | {patch: PatchMutationOperation}
 
-/** @public */
+/**
+ * A mutation was performed. Note that when updating multiple documents in a transaction,
+ * each document affected will get a separate mutation event.
+ *
+ * @public
+ */
 export type MutationEvent<R extends Record<string, Any> = Record<string, Any>> = {
   type: 'mutation'
+
+  /**
+   * The ID of the document that was affected
+   */
   documentId: string
+
+  /**
+   * A unique ID for this event
+   */
   eventId: string
+
+  /**
+   * The user ID of the user that performed the mutation
+   */
   identity: string
+
+  /**
+   * An array of mutations that were performed. Note that this can differ slightly from the
+   * mutations sent to the server, as the server may perform some mutations automatically.
+   */
   mutations: Mutation[]
+
+  /**
+   * The revision ID of the document before the mutation was performed
+   */
   previousRev?: string
+
+  /**
+   * The revision ID of the document after the mutation was performed
+   */
   resultRev?: string
+
+  /**
+   * The document as it looked after the mutation was performed. This is only included if
+   * the listener was configured with `includeResult: true`.
+   */
   result?: SanityDocument<R>
+
+  /**
+   * The document as it looked before the mutation was performed. This is only included if
+   * the listener was configured with `includePreviousRevision: true`.
+   */
   previous?: SanityDocument<R> | null
+
+  /**
+   * The effects of the mutation, if the listener was configured with `effectFormat: 'mendoza'`.
+   * Object with `apply` and `revert` arrays, see {@link https://github.com/sanity-io/mendoza}.
+   */
   effects?: {apply: unknown[]; revert: unknown[]}
+
+  /**
+   * A timestamp for when the mutation was performed
+   */
   timestamp: string
+
+  /**
+   * The transaction ID for the mutation
+   */
   transactionId: string
+
+  /**
+   * The type of transition the document went through.
+   *
+   * - `update` means the document was previously part of the subscribed set of documents,
+   *   and still is.
+   * - `appear` means the document was not previously part of the subscribed set of documents,
+   *   but is now. This can happen both on create or if updating to a state where it now matches
+   *   the filter provided to the listener.
+   * - `disappear` means the document was previously part of the subscribed set of documents,
+   *   but is no longer. This can happen both on delete or if updating to a state where it no
+   *   longer matches the filter provided to the listener.
+   */
   transition: 'update' | 'appear' | 'disappear'
+
+  /**
+   * Whether the change that triggered this event is visible to queries (query) or only to
+   * subsequent transactions (transaction). The listener client can specify a preferred visibility
+   * through the `visibility` parameter on the listener, but this is only on a best-effort basis,
+   * and may yet not be accurate.
+   */
   visibility: 'query' | 'transaction'
+
+  /**
+   * The total number of events that will be sent for this transaction.
+   * Note that this may differ from the amount of _documents_ affected by the transaction, as this
+   * number only includes the documents that matches the given filter.
+   *
+   * This can be useful if you need to perform changes to all matched documents atomically,
+   * eg you would wait for `transactionTotalEvents` events with the same `transactionId` before
+   * applying the changes locally.
+   */
+  transactionTotalEvents: number
+
+  /**
+   * The index of this event within the transaction. Note that events may be delivered out of order,
+   * and that the index is zero-based.
+   */
+  transactionCurrentEvent: number
 }
 
-/** @public */
+/**
+ * An error occurred. This is different from a network-level error (which will be emitted as 'error').
+ * Possible causes are things such as malformed filters, non-existant datasets or similar.
+ *
+ * @public
+ */
 export type ChannelErrorEvent = {
   type: 'channelError'
   message: string
 }
 
-/** @public */
+/**
+ * The listener has been told to explicitly disconnect and not reconnect.
+ * This is a rare situation, but may occur if the API knows reconnect attempts will fail,
+ * eg in the case of a deleted dataset, a blocked project or similar events.
+ *
+ * Note that this is not treated as an error on the observable, but will complete the observable.
+ *
+ * @public
+ */
 export type DisconnectEvent = {
   type: 'disconnect'
   reason: string
 }
 
-/** @public */
+/**
+ * The listener has been disconnected, and a reconnect attempt is scheduled.
+ *
+ * @public
+ */
 export type ReconnectEvent = {
   type: 'reconnect'
 }
 
-/** @public */
+/**
+ * The listener has been established, and will start receiving events.
+ * Note that this is also emitted upon _reconnection_.
+ *
+ * @public
+ */
 export type WelcomeEvent = {
   type: 'welcome'
 }
@@ -488,15 +600,65 @@ export type ListenEvent<R extends Record<string, Any>> =
   | WelcomeEvent
 
 /** @public */
-export type ListenEventName = 'mutation' | 'welcome' | 'reconnect'
+export type ListenEventName =
+  /** A mutation was performed */
+  | 'mutation'
+  /** The listener has been (re)established */
+  | 'welcome'
+  /** The listener has been disconnected, and a reconnect attempt is scheduled */
+  | 'reconnect'
 
 /** @public */
 export interface ListenOptions {
+  /**
+   * Whether or not to include the resulting document in addition to the mutations performed.
+   * If you do not need the actual document, set this to `false` to reduce bandwidth usage.
+   * The result will be available on the `.result` property of the events.
+   * @defaultValue `true`
+   */
   includeResult?: boolean
+
+  /**
+   * Whether or not to include the document as it looked before the mutation event.
+   * The previous revision will be available on the `.previous` property of the events,
+   * and may be `null` in the case of a new document.
+   * @defaultValue `false`
+   */
   includePreviousRevision?: boolean
-  visibility?: 'sync' | 'async' | 'query'
+
+  /**
+   * Whether events should be sent as soon as a transaction has been committed (`transaction`, default),
+   * or only after they are available for queries (query). Note that this is on a best-effort basis,
+   * and listeners with `query` may in certain cases (notably with deferred transactions) receive events
+   * that are not yet visible to queries.
+   *
+   * @defaultValue `'transaction'`
+   */
+  visibility?: 'transaction' | 'query'
+
+  /**
+   * Array of event names to include in the observable. By default, only mutation events are included.
+   *
+   * @defaultValue `['mutation']`
+   */
   events?: ListenEventName[]
+
+  /**
+   * Format of "effects", eg the resulting changes of a mutation.
+   * Currently only `mendoza` is supported, and (if set) will include `apply` and `revert` arrays
+   * in the mutation events under the `effects` property.
+   *
+   * See {@link https://github.com/sanity-io/mendoza | The mendoza docs} for more info
+   *
+   * @defaultValue `undefined`
+   */
   effectFormat?: 'mendoza'
+
+  /**
+   * Optional request tag for the listener. Use to identify the request in logs.
+   *
+   * @defaultValue `undefined`
+   */
   tag?: string
 }
 

package/umd/sanityClient.js

@@ -3842,11 +3842,12 @@
     /**
      * Create a new buildable patch of operations to perform
      *
-     * @param documentId - Document ID(s) to patch
+     * @param selection - Document ID, an array of document IDs, or an object with `query` and optional `params`, defining which document(s) to patch
      * @param operations - Optional object of patch operations to initialize the patch instance with
+     * @returns Patch instance - call `.commit()` to perform the operations defined
      */
-    patch(documentId, operations) {
-      return new ObservablePatch(documentId, operations, this);
+    patch(selection, operations) {
+      return new ObservablePatch(selection, operations, this);
     }
     /**
      * Create a new transaction of mutations
@@ -3857,9 +3858,8 @@
       return new ObservableTransaction(operations, this);
     }
     /**
-     * DEPRECATED: Perform an HTTP request against the Sanity API
+     * Perform an HTTP request against the Sanity API
      *
-     * @deprecated Use your own request library!
      * @param options - Request options
      */
     request(options) {
@@ -3990,8 +3990,9 @@
     /**
      * Create a new buildable patch of operations to perform
      *
-     * @param documentId - Document ID(s)to patch
+     * @param selection - Document ID, an array of document IDs, or an object with `query` and optional `params`, defining which document(s) to patch
      * @param operations - Optional object of patch operations to initialize the patch instance with
+     * @returns Patch instance - call `.commit()` to perform the operations defined
      */
     patch(documentId, operations) {
       return new Patch(documentId, operations, this);