@sanity/client 7.14.1 → 7.15.0

package/dist/index.d.cts

@@ -1987,7 +1987,7 @@ export declare function _listen<R extends Record<string, Any> = Record<string, A
  */
 export declare function _listen<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions = ListenOptions,
+  Opts extends ListenOptions | ResumableListenOptions = ListenOptions | ResumableListenOptions,
 >(
   this: SanityClient | ObservableSanityClient,
   query: string,
@@ -1996,9 +1996,11 @@ export declare function _listen<
 ): Observable<ListenEventFromOptions<R, Opts>>
 
 /** @public */
-export declare type ListenEvent<R extends Record<string, Any>> =
+export declare type ListenEvent<R extends Record<string, Any> = Record<string, Any>> =
   | MutationEvent<R>
   | ReconnectEvent
+  | WelcomeBackEvent
+  | ResetEvent
   | WelcomeEvent
   | OpenEvent
 
@@ -2013,9 +2015,9 @@ export declare type ListenEvent<R extends Record<string, Any>> =
  */
 declare type ListenEventFromOptions<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions | undefined = undefined,
-> = Opts extends ListenOptions
-  ? Opts['events'] extends ListenEventName[]
+  Opts extends ListenOptions | ResumableListenOptions | undefined = undefined,
+> = Opts extends ListenOptions | ResumableListenOptions
+  ? Opts['events'] extends (ResumableListenEventNames | ListenEventName)[]
     ? MapListenEventNamesToListenEvents<R, Opts['events']>
     : ListenEvent<R>
   : MutationEvent<R>
@@ -2068,7 +2070,7 @@ export declare interface ListenOptions {
   visibility?: 'transaction' | 'query'
   /**
    * Array of event names to include in the observable. By default, only mutation events are included.
-   *
+   * Note: `welcomeback` and `reset` events requires `enableResume: true`
    * @defaultValue `['mutation']`
    */
   events?: ListenEventName[]
@@ -2088,6 +2090,13 @@ export declare interface ListenOptions {
    * @defaultValue `undefined`
    */
   tag?: string
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * When if enabling this, you should also add the `reset` to the events array and handle the case where the backend is unable to resume.
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume?: boolean
 }
 
 /** @public */
@@ -2178,7 +2187,10 @@ export declare type Logger =
  */
 declare type MapListenEventNamesToListenEvents<
   R extends Record<string, Any> = Record<string, Any>,
-  Events extends ListenEventName[] = ListenEventName[],
+  Events extends (ResumableListenEventNames | ListenEventName)[] = (
+    | ResumableListenEventNames
+    | ListenEventName
+  )[],
 > = Events extends (infer E)[]
   ? E extends 'welcome'
     ? WelcomeEvent
@@ -2186,9 +2198,13 @@ declare type MapListenEventNamesToListenEvents<
       ? MutationEvent<R>
       : E extends 'reconnect'
         ? ReconnectEvent
-        : E extends 'open'
-          ? OpenEvent
-          : never
+        : E extends 'welcomeback'
+          ? WelcomeBackEvent
+          : E extends 'reset'
+            ? ResetEvent
+            : E extends 'open'
+              ? OpenEvent
+              : never
   : never
 
 /** @public */
@@ -4730,6 +4746,19 @@ export declare interface RequestOptions {
   signal?: AbortSignal
 }
 
+/**
+ * The listener can't be resumed or otherwise need to reset its local state
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export declare type ResetEvent = {
+  type: 'reset'
+}
+
 export {ResolveStudioUrl}
 
 /** @public */
@@ -4762,6 +4791,32 @@ export declare interface ResponseQueryOptions extends RequestOptions {
   cacheMode?: 'noStale'
 }
 
+/** @public */
+export declare type ResumableListenEventNames =
+  | ListenEventName
+  /** The listener has reconnected and successfully resumed from where it left off */
+  | 'welcomeback'
+  /** The listener can't be resumed or otherwise need to reset its local state */
+  | 'reset'
+
+/** @public */
+export declare interface ResumableListenOptions
+  extends Omit<ListenOptions, 'events' | 'enableResume'> {
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * Note that you should also subscribe to `reset`-events and handle the case where the backend is unable to resume
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume: true
+  /**
+   * Array of event names to include in the observable. By default, only mutation events are included.
+   *
+   * @defaultValue `['mutation']`
+   */
+  events?: ResumableListenEventNames[]
+}
+
 /** @internal */
 export declare interface SanityAssetDocument extends SanityDocument {
   url: string
@@ -6490,8 +6545,33 @@ export declare interface VideoPlaybackTokens {
 }
 
 /**
- * The listener has been established, and will start receiving events.
- * Note that this is also emitted upon _reconnection_.
+ * Emitted when the listener reconnects and successfully resumes from
+ * its previous position.
+ *
+ * Even if the listener is created with `enableResume: true`, resume support
+ * may not be available. In that case, a reconnect will emit `welcome`
+ * instead of `welcomeback`.
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export declare type WelcomeBackEvent = {
+  type: 'welcomeback'
+  listenerName: string
+}
+
+/**
+ * Emitted when the listener connection has been successfully established
+ * and is ready to receive events.
+ *
+ * If the listener was created with `enableResume: true` and resume support
+ * is available, the `welcome` event will only be emitted on the initial
+ * connection. On subsequent reconnects, a `welcomeback` event will be
+ * emitted instead, followed by any events that were missed while the
+ * connection was disconnected.
  *
  * @public
  */

package/dist/index.d.ts

@@ -1987,7 +1987,7 @@ export declare function _listen<R extends Record<string, Any> = Record<string, A
  */
 export declare function _listen<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions = ListenOptions,
+  Opts extends ListenOptions | ResumableListenOptions = ListenOptions | ResumableListenOptions,
 >(
   this: SanityClient | ObservableSanityClient,
   query: string,
@@ -1996,9 +1996,11 @@ export declare function _listen<
 ): Observable<ListenEventFromOptions<R, Opts>>
 
 /** @public */
-export declare type ListenEvent<R extends Record<string, Any>> =
+export declare type ListenEvent<R extends Record<string, Any> = Record<string, Any>> =
   | MutationEvent<R>
   | ReconnectEvent
+  | WelcomeBackEvent
+  | ResetEvent
   | WelcomeEvent
   | OpenEvent
 
@@ -2013,9 +2015,9 @@ export declare type ListenEvent<R extends Record<string, Any>> =
  */
 declare type ListenEventFromOptions<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions | undefined = undefined,
-> = Opts extends ListenOptions
-  ? Opts['events'] extends ListenEventName[]
+  Opts extends ListenOptions | ResumableListenOptions | undefined = undefined,
+> = Opts extends ListenOptions | ResumableListenOptions
+  ? Opts['events'] extends (ResumableListenEventNames | ListenEventName)[]
     ? MapListenEventNamesToListenEvents<R, Opts['events']>
     : ListenEvent<R>
   : MutationEvent<R>
@@ -2068,7 +2070,7 @@ export declare interface ListenOptions {
   visibility?: 'transaction' | 'query'
   /**
    * Array of event names to include in the observable. By default, only mutation events are included.
-   *
+   * Note: `welcomeback` and `reset` events requires `enableResume: true`
    * @defaultValue `['mutation']`
    */
   events?: ListenEventName[]
@@ -2088,6 +2090,13 @@ export declare interface ListenOptions {
    * @defaultValue `undefined`
    */
   tag?: string
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * When if enabling this, you should also add the `reset` to the events array and handle the case where the backend is unable to resume.
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume?: boolean
 }
 
 /** @public */
@@ -2178,7 +2187,10 @@ export declare type Logger =
  */
 declare type MapListenEventNamesToListenEvents<
   R extends Record<string, Any> = Record<string, Any>,
-  Events extends ListenEventName[] = ListenEventName[],
+  Events extends (ResumableListenEventNames | ListenEventName)[] = (
+    | ResumableListenEventNames
+    | ListenEventName
+  )[],
 > = Events extends (infer E)[]
   ? E extends 'welcome'
     ? WelcomeEvent
@@ -2186,9 +2198,13 @@ declare type MapListenEventNamesToListenEvents<
       ? MutationEvent<R>
       : E extends 'reconnect'
         ? ReconnectEvent
-        : E extends 'open'
-          ? OpenEvent
-          : never
+        : E extends 'welcomeback'
+          ? WelcomeBackEvent
+          : E extends 'reset'
+            ? ResetEvent
+            : E extends 'open'
+              ? OpenEvent
+              : never
   : never
 
 /** @public */
@@ -4730,6 +4746,19 @@ export declare interface RequestOptions {
   signal?: AbortSignal
 }
 
+/**
+ * The listener can't be resumed or otherwise need to reset its local state
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export declare type ResetEvent = {
+  type: 'reset'
+}
+
 export {ResolveStudioUrl}
 
 /** @public */
@@ -4762,6 +4791,32 @@ export declare interface ResponseQueryOptions extends RequestOptions {
   cacheMode?: 'noStale'
 }
 
+/** @public */
+export declare type ResumableListenEventNames =
+  | ListenEventName
+  /** The listener has reconnected and successfully resumed from where it left off */
+  | 'welcomeback'
+  /** The listener can't be resumed or otherwise need to reset its local state */
+  | 'reset'
+
+/** @public */
+export declare interface ResumableListenOptions
+  extends Omit<ListenOptions, 'events' | 'enableResume'> {
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * Note that you should also subscribe to `reset`-events and handle the case where the backend is unable to resume
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume: true
+  /**
+   * Array of event names to include in the observable. By default, only mutation events are included.
+   *
+   * @defaultValue `['mutation']`
+   */
+  events?: ResumableListenEventNames[]
+}
+
 /** @internal */
 export declare interface SanityAssetDocument extends SanityDocument {
   url: string
@@ -6490,8 +6545,33 @@ export declare interface VideoPlaybackTokens {
 }
 
 /**
- * The listener has been established, and will start receiving events.
- * Note that this is also emitted upon _reconnection_.
+ * Emitted when the listener reconnects and successfully resumes from
+ * its previous position.
+ *
+ * Even if the listener is created with `enableResume: true`, resume support
+ * may not be available. In that case, a reconnect will emit `welcome`
+ * instead of `welcomeback`.
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export declare type WelcomeBackEvent = {
+  type: 'welcomeback'
+  listenerName: string
+}
+
+/**
+ * Emitted when the listener connection has been successfully established
+ * and is ready to receive events.
+ *
+ * If the listener was created with `enableResume: true` and resume support
+ * is available, the `welcome` event will only be emitted on the initial
+ * connection. On subsequent reconnects, a `welcomeback` event will be
+ * emitted instead, followed by any events that were missed while the
+ * connection was disconnected.
  *
  * @public
  */

package/dist/index.js

@@ -1211,6 +1211,7 @@ const MAX_URL_LENGTH = 14800, possibleOptions = [
   "includeAllVersions",
   "visibility",
   "effectFormat",
+  "enableResume",
   "tag"
 ], defaultOptions = {
   includeResult: !0
@@ -2676,7 +2677,7 @@ function defineDeprecatedCreateClient(createClient2) {
     return printNoDefaultExport(), createClient2(config);
   };
 }
-var name = "@sanity/client", version = "7.14.1";
+var name = "@sanity/client", version = "7.15.0";
 const middleware = [
   debug({ verbose: !0, namespace: "sanity:client" }),
   headers({ "User-Agent": `${name} ${version}` }),