@sanity/client 7.14.1 → 7.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "7.14.1",
+  "version": "7.15.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",

package/src/data/listen.ts

@@ -11,6 +11,10 @@ import {
   type MutationEvent,
   type OpenEvent,
   type ReconnectEvent,
+  type ResetEvent,
+  type ResumableListenEventNames,
+  type ResumableListenOptions,
+  type WelcomeBackEvent,
   type WelcomeEvent,
 } from '../types'
 import defaults from '../util/defaults'
@@ -33,6 +37,7 @@ const possibleOptions = [
   'includeAllVersions',
   'visibility',
   'effectFormat',
+  'enableResume',
   'tag',
 ]
 
@@ -51,7 +56,10 @@ const defaultOptions = {
  */
 export 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
@@ -59,9 +67,13 @@ export 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
 
 /**
@@ -75,9 +87,9 @@ export type MapListenEventNamesToListenEvents<
  */
 export 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']>
     : // fall back to ListenEvent if opts events is present, but we can't infer the literal event names
       ListenEvent<R>
@@ -106,7 +118,7 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
  */
 export 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,
@@ -116,7 +128,7 @@ export function _listen<
 /** @public */
 export 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,

package/src/types.ts

@@ -1151,8 +1151,14 @@ export type OpenEvent = {
 }
 
 /**
- * The listener has been established, and will start receiving events.
- * Note that this is also emitted upon _reconnection_.
+ * 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
  */
@@ -1161,10 +1167,44 @@ export type WelcomeEvent = {
   listenerName: string
 }
 
+/**
+ * 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 type WelcomeBackEvent = {
+  type: 'welcomeback'
+  listenerName: string
+}
+
+/**
+ * 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 type ResetEvent = {
+  type: 'reset'
+}
+
 /** @public */
-export type ListenEvent<R extends Record<string, Any>> =
+export type ListenEvent<R extends Record<string, Any> = Record<string, Any>> =
   | MutationEvent<R>
   | ReconnectEvent
+  | WelcomeBackEvent
+  | ResetEvent
   | WelcomeEvent
   | OpenEvent
 
@@ -1182,6 +1222,14 @@ export type ListenEventName =
    */
   | 'open'
 
+/** @public */
+export 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 type ListenParams = {[key: string]: Any}
 
@@ -1233,7 +1281,7 @@ export interface ListenOptions {
 
   /**
    * 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[]
@@ -1255,6 +1303,32 @@ export 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 */
+export 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[]
 }
 
 /** @public */

package/umd/sanityClient.js

@@ -3346,6 +3346,7 @@ ${selectionOpts}`);
     "includeAllVersions",
     "visibility",
     "effectFormat",
+    "enableResume",
     "tag"
   ], defaultOptions = {
     includeResult: true