@sanity/client 6.4.10-dev.0 → 6.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "6.4.10-dev.0",
+  "version": "6.4.11",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -40,10 +40,8 @@
       "source": "./src/index.ts",
       "require": "./dist/index.cjs",
       "node": {
-        "module": "./dist/index.js",
         "import": "./dist/index.cjs.js"
       },
-      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
@@ -72,7 +70,7 @@
     "prepublishOnly": "npm run build",
     "rollup": "NODE_ENV=production rollup -c rollup.config.cjs",
     "test": "vitest",
-    "type-check": "tsc --noEmit && vitest typecheck",
+    "type-check": "tsc --noEmit",
     "test:browser": "npm test -- --config ./vitest.browser.config.ts",
     "test:bun": "(cd runtimes/bun && bun wiptest)",
     "test:deno": "deno test --allow-read --allow-net --allow-env --fail-fast --import-map=runtimes/deno/import_map.json runtimes/deno",
@@ -97,16 +95,16 @@
     "rxjs": "^7.0.0"
   },
   "devDependencies": {
-    "@edge-runtime/types": "^2.2.0",
-    "@edge-runtime/vm": "^3.1.0",
+    "@edge-runtime/types": "^2.2.1",
+    "@edge-runtime/vm": "^3.1.1",
     "@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.5.0",
-    "@typescript-eslint/parser": "^6.5.0",
-    "@vitest/coverage-v8": "0.34.3",
+    "@typescript-eslint/eslint-plugin": "^6.6.0",
+    "@typescript-eslint/parser": "^6.6.0",
+    "@vitest/coverage-v8": "^0.34.3",
     "eslint": "^8.48.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
@@ -118,18 +116,18 @@
     "prettier": "^3.0.3",
     "prettier-plugin-packagejson": "^2.4.5",
     "rimraf": "^5.0.1",
-    "rollup": "^3.28.1",
+    "rollup": "^3.29.0",
     "sse-channel": "^4.0.0",
-    "terser": "^5.19.3",
+    "terser": "^5.19.4",
     "typescript": "^5.2.2",
-    "vitest": "0.34.3",
-    "vitest-github-actions-reporter": "0.10.0"
+    "vitest": "^0.34.3",
+    "vitest-github-actions-reporter": "^0.10.0"
   },
   "engines": {
     "node": ">=14.18"
   },
   "publishConfig": {
     "access": "public",
-    "provenance": false
+    "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
 }
 
@@ -518,79 +680,6 @@ export type UnfilteredResponseQueryOptions = ResponseQueryOptions & {
   filterResponse: false
 }
 
-/**
- * Stricter typing of the response from `client.fetch`, intended to be used by type inference libraries and tooling that
- * delivers runtime safety in production.
- *
- * @example
- * It's not designed to be used directly in application code, in fact that would be the most annoying way to query Content Lake in a runtime safe way:
- * ```ts
- * import type {StrictUnknownQueryResponseResult} from '@sanity/client'
- * const query = '*[_type == "product"]'
- * const response = client.fetch<StrictUnknownQueryResponseResult>(query)
- * // Response is now strictly typed, without any knowledge of the dataset or what the GROQ query might return.
- * // The GROQ query is asking for an array of documents that have `_type` = "product", but TypeScript doesn't know that, 
- * // `query` is `string` and so the type accounts for anything that GROQ supports, which means you might have any JSON valid data in the response.
- * // \@ts-expect-error -- TS doesn't know the api will always return an array, so it errors
- * console.log(response.length)
- * // It needs a runtime check to ensure it's an array
- * if (Array.isArray(response)) console.log(response.length)
- * ```
- * 
- * @example
- * How's it intended to be used? By libraries that delivers end-to-end GROQ runtime type safety.
- * For example in an imaginary TypeScript language service plugin that can look at your `sanity.config.ts`:
- * ```ts
- * import { defineConfig } from 'sanity'
-
-*  export default defineConfig({
-*    projectId: '...',
-*    dataset: '...',
-*    schema: {
-*      types: [
-*        {
-*          name: 'page',
-*          title: 'Page',
-*          type: 'document',
-*          fields: [
-*            {
-*              name: 'title',
-*              title: 'Title',
-*              type: 'string',
-*            },
-*          ],
-*        },
-*      ],
-*    },
-*  })
- * ```
- * And use that to infer typings:
- * ```ts
- * import {createClient} from '@sanity/client'
- * 
- * const client = createClient()
- * const response = client.fetch('*[_type == "page"]')
- * // all is well, if title exists the schema says it's a string
- * response.map(page => page.title?.toUpperCase())
- * // IDE flags an error, the `author` property isn't defined in the schema so it could be any JSON valid value.
- * response.map(page => page.author?.toUpperCase())
- * // Maybe this is by design because `author` is coming from an external source, and not from entering it in the Studio interface,
- * // the IDE plugin returns `StrictUnknownQueryResponseResult` and you have to handle it manually:
- * response.map(page => typeof page.author === 'string' ? page.author.toUpperCase() : 'UNKNOWN')
- * ```
- * If the imaginary IDE extension returned `any` or `unknown` instead of `StrictUnknownQueryResponseResult` it opens up a lot of 
- * possibilities where it would fail silently and instead error at runtime.
- * 
- * @public
- */
-export type StrictUnknownQueryResponseResult =
-  | string
-  | number
-  | boolean
-  | null
-  | {[key: string]: StrictUnknownQueryResponseResult | undefined}
-  | StrictUnknownQueryResponseResult[]
-
 /** @public */
 export interface RawQueryResponse<R> {
   query: string