@sanity/client 6.4.10-dev.0 → 6.4.11

package/dist/index.d.ts

@@ -270,7 +270,12 @@ export declare class BaseTransaction {
   protected _add(mut: Mutation): this
 }
 
-/** @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 declare type ChannelErrorEvent = {
   type: 'channelError'
   message: string
@@ -485,7 +490,15 @@ export declare type DatasetsResponse = {
 declare function deprecatedCreateClient(config: ClientConfig): SanityClient
 export default deprecatedCreateClient
 
-/** @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 declare type DisconnectEvent = {
   type: 'disconnect'
   reason: string
@@ -575,8 +588,8 @@ export declare type InsertPatch =
  *
  * @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 declare function _listen<R extends Record<string, Any> = Record<string, Any>>(
   this: SanityClient | ObservableSanityClient,
@@ -589,8 +602,8 @@ export declare function _listen<R extends Record<string, Any> = Record<string, A
  *
  * @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 declare function _listen<R extends Record<string, Any> = Record<string, Any>>(
   this: SanityClient | ObservableSanityClient,
@@ -608,15 +621,60 @@ export declare type ListenEvent<R extends Record<string, Any>> =
   | WelcomeEvent
 
 /** @public */
-export declare type ListenEventName = 'mutation' | 'welcome' | 'reconnect'
+export declare 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 declare 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
 }
 
@@ -666,25 +724,100 @@ export declare interface MutationErrorItem {
   }
 }
 
-/** @public */
+/**
+ * A mutation was performed. Note that when updating multiple documents in a transaction,
+ * each document affected will get a separate mutation event.
+ *
+ * @public
+ */
 declare type MutationEvent_2<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
 }
 export {MutationEvent_2 as MutationEvent}
 
@@ -1291,10 +1424,27 @@ export declare 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
+  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 transaction of mutations
    *
@@ -1304,9 +1454,8 @@ export declare class ObservableSanityClient {
     operations?: Mutation<R>[],
   ): ObservableTransaction
   /**
-   * 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>
@@ -1542,7 +1691,11 @@ export declare interface RawRequestOptions {
   maxRedirects?: number
 }
 
-/** @public */
+/**
+ * The listener has been disconnected, and a reconnect attempt is scheduled.
+ *
+ * @public
+ */
 export declare type ReconnectEvent = {
   type: 'reconnect'
 }
@@ -2038,10 +2191,27 @@ export declare 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(documentId: PatchSelection, operations?: PatchOperations): Patch
+  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 transaction of mutations
    *
@@ -2215,81 +2385,6 @@ export declare interface SingleMutationResult {
   }[]
 }
 
-/**
- * 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 declare type StrictUnknownQueryResponseResult =
-  | string
-  | number
-  | boolean
-  | null
-  | {
-      [key: string]: StrictUnknownQueryResponseResult | undefined
-    }
-  | StrictUnknownQueryResponseResult[]
-
 /** @public */
 export declare class Transaction extends BaseTransaction {
   #private
@@ -2465,7 +2560,12 @@ export declare class UsersClient {
   getById<T extends 'me' | string>(id: T): Promise<T extends 'me' ? CurrentSanityUser : SanityUser>
 }
 
-/** @public */
+/**
+ * The listener has been established, and will start receiving events.
+ * Note that this is also emitted upon _reconnection_.
+ *
+ * @public
+ */
 export declare type WelcomeEvent = {
   type: 'welcome'
 }

package/dist/index.js

@@ -4,7 +4,7 @@ export { adapter as unstable__adapter, environment as unstable__environment } fr
 import { Observable, lastValueFrom } from 'rxjs';
 import { map, filter } from 'rxjs/operators';
 var name = "@sanity/client";
-var version = "6.4.10-dev.0";
+var version = "6.4.11";
 const middleware = [debug({
   verbose: true,
   namespace: "sanity:client"
@@ -1718,11 +1718,12 @@ const _ObservableSanityClient = class _ObservableSanityClient {
   /**
    * 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
@@ -1733,9 +1734,8 @@ const _ObservableSanityClient = class _ObservableSanityClient {
     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) {
@@ -1866,8 +1866,9 @@ const _SanityClient = class _SanityClient {
   /**
    * 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);