@sanity/client 6.24.2 → 6.24.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "6.24.2",
+  "version": "6.24.4",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -119,7 +119,7 @@
   },
   "dependencies": {
     "@sanity/eventsource": "^5.0.2",
-    "get-it": "^8.6.5",
+    "get-it": "^8.6.6",
     "rxjs": "^7.0.0"
   },
   "devDependencies": {
@@ -128,7 +128,7 @@
     "@rollup/plugin-commonjs": "^28.0.2",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@sanity/client-latest": "npm:@sanity/client@latest",
-    "@sanity/pkg-utils": "^6.13.2",
+    "@sanity/pkg-utils": "^7.0.1",
     "@types/json-diff": "^1.0.3",
     "@types/node": "^22.9.0",
     "@typescript-eslint/eslint-plugin": "^8.19.1",
@@ -152,7 +152,7 @@
     "rollup": "^4.30.1",
     "sse-channel": "^4.0.0",
     "terser": "^5.37.0",
-    "typescript": "5.7.2",
+    "typescript": "5.7.3",
     "vitest": "2.1.8",
     "vitest-github-actions-reporter": "0.11.1"
   },

package/src/data/eventsource.ts

@@ -0,0 +1,255 @@
+import {defer, isObservable, mergeMap, Observable, of} from 'rxjs'
+
+import {type Any} from '../types'
+
+/**
+ * @public
+ * Thrown if the EventSource connection could not be established.
+ * Note that ConnectionFailedErrors are rare, and disconnects will normally be handled by the EventSource instance itself and emitted as `reconnect` events.
+ */
+export class ConnectionFailedError extends Error {
+  readonly name = 'ConnectionFailedError'
+}
+
+/**
+ * The listener has been told to explicitly disconnect.
+ *  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.
+ * @public
+ */
+export class DisconnectError extends Error {
+  readonly name = 'DisconnectError'
+  readonly reason?: string
+  constructor(message: string, reason?: string, options: ErrorOptions = {}) {
+    super(message, options)
+    this.reason = reason
+  }
+}
+
+/**
+ * @public
+ * The server sent a `channelError` message. Usually indicative of a bad or malformed request
+ */
+export class ChannelError extends Error {
+  readonly name = 'ChannelError'
+  readonly data?: unknown
+  constructor(message: string, data: unknown) {
+    super(message)
+    this.data = data
+  }
+}
+
+/**
+ * @public
+ * The server sent an `error`-event to tell the client that an unexpected error has happened.
+ */
+export class MessageError extends Error {
+  readonly name = 'MessageError'
+  readonly data?: unknown
+  constructor(message: string, data: unknown, options: ErrorOptions = {}) {
+    super(message, options)
+    this.data = data
+  }
+}
+
+/**
+ * @public
+ * An error occurred while parsing the message sent by the server as JSON. Should normally not happen.
+ */
+export class MessageParseError extends Error {
+  readonly name = 'MessageParseError'
+}
+
+/**
+ * @public
+ */
+export interface ServerSentEvent<Name extends string> {
+  type: Name
+  id?: string
+  data?: unknown
+}
+
+// Always listen for these events, no matter what
+const REQUIRED_EVENTS = ['channelError', 'disconnect']
+
+/**
+ * @internal
+ */
+export type EventSourceEvent<Name extends string> = ServerSentEvent<Name>
+
+/**
+ * @internal
+ */
+export type EventSourceInstance = InstanceType<typeof globalThis.EventSource>
+
+/**
+ * Sanity API specific EventSource handler shared between the listen and live APIs
+ *
+ * Since the `EventSource` API is not provided by all environments, this function enables custom initialization of the EventSource instance
+ * for runtimes that requires polyfilling or custom setup logic (e.g. custom HTTP headers)
+ * via the passed `initEventSource` function which must return an EventSource instance.
+ *
+ * Possible errors to be thrown on the returned observable are:
+ * - {@link MessageError}
+ * - {@link MessageParseError}
+ * - {@link ChannelError}
+ * - {@link DisconnectError}
+ * - {@link ConnectionFailedError}
+ *
+ * @param initEventSource - A function that returns an EventSource instance or an Observable that resolves to an EventSource instance
+ * @param events - an array of named events from the API to listen for.
+ *
+ * @internal
+ */
+export function connectEventSource<EventName extends string>(
+  initEventSource: () => EventSourceInstance | Observable<EventSourceInstance>,
+  events: EventName[],
+) {
+  return defer(() => {
+    const es = initEventSource()
+    return isObservable(es) ? es : of(es)
+  }).pipe(mergeMap((es) => connectWithESInstance(es, events))) as Observable<
+    ServerSentEvent<EventName>
+  >
+}
+
+/**
+ * Provides an observable from the passed EventSource instance, subscribing to the passed list of names of events types to listen for
+ * Handles connection logic, adding/removing event listeners, payload parsing, error propagation, etc.
+ *
+ * @param es - The EventSource instance
+ * @param events - List of event names to listen for
+ */
+function connectWithESInstance<EventTypeName extends string>(
+  es: EventSourceInstance,
+  events: EventTypeName[],
+) {
+  return new Observable<EventSourceEvent<EventTypeName>>((observer) => {
+    const emitOpen = (events as string[]).includes('open')
+    const emitReconnect = (events as string[]).includes('reconnect')
+
+    // EventSource will emit a regular Event if it fails to connect, however the API may also emit an `error` MessageEvent
+    // So we need to handle both cases
+    function onError(evt: MessageEvent | Event) {
+      // If the event has a `data` property, then it`s a MessageEvent emitted by the API and we should forward the error
+      if ('data' in evt) {
+        const [parseError, event] = parseEvent(evt as MessageEvent)
+        observer.error(
+          parseError
+            ? new MessageParseError('Unable to parse EventSource error message', {cause: event})
+            : new MessageError((event?.data as {message: string}).message, event),
+        )
+        return
+      }
+
+      // We should never be in a disconnected state. By default, EventSource will reconnect
+      // automatically, but in some cases (like when a laptop lid is closed), it will trigger onError
+      // if it can't reconnect.
+      // see https://html.spec.whatwg.org/multipage/server-sent-events.html#sse-processing-model
+      if (es.readyState === es.CLOSED) {
+        // In these cases we'll signal to consumers (via the error path) that a retry/reconnect is needed.
+        observer.error(new ConnectionFailedError('EventSource connection failed'))
+      } else if (emitReconnect) {
+        observer.next({type: 'reconnect' as EventTypeName})
+      }
+    }
+
+    function onOpen() {
+      // The open event of the EventSource API is fired when a connection with an event source is opened.
+      observer.next({type: 'open' as EventTypeName})
+    }
+
+    function onMessage(message: MessageEvent) {
+      const [parseError, event] = parseEvent(message)
+      if (parseError) {
+        observer.error(
+          new MessageParseError('Unable to parse EventSource message', {cause: parseError}),
+        )
+        return
+      }
+      if (message.type === 'channelError') {
+        // 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.
+        observer.error(new ChannelError(extractErrorMessage(event?.data), event.data))
+        return
+      }
+      if (message.type === 'disconnect') {
+        // 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.
+        observer.error(
+          new DisconnectError(
+            `Server disconnected client: ${
+              (event.data as {reason?: string})?.reason || 'unknown error'
+            }`,
+          ),
+        )
+        return
+      }
+      observer.next({
+        type: message.type as EventTypeName,
+        id: message.lastEventId,
+        ...(event.data ? {data: event.data} : {}),
+      })
+    }
+
+    es.addEventListener('error', onError)
+
+    if (emitOpen) {
+      es.addEventListener('open', onOpen)
+    }
+
+    // Make sure we have a unique list of events types to avoid listening multiple times,
+    const cleanedEvents = [...new Set([...REQUIRED_EVENTS, ...events])]
+      // filter out events that are handled separately
+      .filter((type) => type !== 'error' && type !== 'open' && type !== 'reconnect')
+
+    cleanedEvents.forEach((type: string) => es.addEventListener(type, onMessage))
+
+    return () => {
+      es.removeEventListener('error', onError)
+      if (emitOpen) {
+        es.removeEventListener('open', onOpen)
+      }
+      cleanedEvents.forEach((type: string) => es.removeEventListener(type, onMessage))
+      es.close()
+    }
+  })
+}
+
+function parseEvent(
+  message: MessageEvent,
+): [null, {type: string; id: string; data?: unknown}] | [Error, null] {
+  try {
+    const data = typeof message.data === 'string' && JSON.parse(message.data)
+    return [
+      null,
+      {
+        type: message.type,
+        id: message.lastEventId,
+        ...(isEmptyObject(data) ? {} : {data}),
+      },
+    ]
+  } catch (err) {
+    return [err as Error, null]
+  }
+}
+
+function extractErrorMessage(err: Any) {
+  if (!err.error) {
+    return err.message || 'Unknown listener error'
+  }
+
+  if (err.error.description) {
+    return err.error.description
+  }
+
+  return typeof err.error === 'string' ? err.error : JSON.stringify(err.error, null, 2)
+}
+
+function isEmptyObject(data: object) {
+  for (const _ in data) {
+    return false
+  }
+  return true
+}

package/src/data/eventsourcePolyfill.ts

@@ -0,0 +1,7 @@
+import {defer, shareReplay} from 'rxjs'
+import {map} from 'rxjs/operators'
+
+export const eventSourcePolyfill = defer(() => import('@sanity/eventsource')).pipe(
+  map(({default: EventSource}) => EventSource as unknown as typeof globalThis.EventSource),
+  shareReplay(1),
+)

package/src/data/listen.ts

@@ -1,11 +1,21 @@
-import {Observable} from 'rxjs'
+import {Observable, of, throwError} from 'rxjs'
+import {filter, map} from 'rxjs/operators'
 
 import type {ObservableSanityClient, SanityClient} from '../SanityClient'
-import type {Any, ListenEvent, ListenOptions, ListenParams, MutationEvent} from '../types'
+import {
+  type Any,
+  type ListenEvent,
+  type ListenOptions,
+  type ListenParams,
+  type MutationEvent,
+} from '../types'
 import defaults from '../util/defaults'
 import {pick} from '../util/pick'
 import {_getDataUrl} from './dataMethods'
 import {encodeQueryString} from './encodeQueryString'
+import {connectEventSource} from './eventsource'
+import {eventSourcePolyfill} from './eventsourcePolyfill'
+import {reconnectOnConnectionFailure} from './reconnectOnConnectionFailure'
 
 // Limit is 16K for a _request_, eg including headers. Have to account for an
 // unknown range of headers, but an average EventSource request from Chrome seems
@@ -67,11 +77,10 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
 
   const uri = `${url}${_getDataUrl(this, 'listen', qs)}`
   if (uri.length > MAX_URL_LENGTH) {
-    return new Observable((observer) => observer.error(new Error('Query too large for listener')))
+    return throwError(() => new Error('Query too large for listener'))
   }
 
   const listenFor = options.events ? options.events : ['mutation']
-  const shouldEmitReconnect = listenFor.indexOf('reconnect') !== -1
 
   const esOptions: EventSourceInit & {headers?: Record<string, string>} = {}
   if (token || withCredentials) {
@@ -84,142 +93,22 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
     }
   }
 
-  return new Observable((observer) => {
-    let es: InstanceType<typeof import('@sanity/eventsource')>
-    let reconnectTimer: NodeJS.Timeout
-    let stopped = false
-    // Unsubscribe differs from stopped in that we will never reopen.
-    // Once it is`true`, it will never be `false` again.
-    let unsubscribed = false
-
-    open()
-
-    function onError() {
-      if (stopped) {
-        return
-      }
-
-      emitReconnect()
-
-      // Allow event handlers of `emitReconnect` to cancel/close the reconnect attempt
-      if (stopped) {
-        return
-      }
-
-      // Unless we've explicitly stopped the ES (in which case `stopped` should be true),
-      // we should never be in a disconnected state. By default, EventSource will reconnect
-      // automatically, in which case it sets readyState to `CONNECTING`, but in some cases
-      // (like when a laptop lid is closed), it closes the connection. In these cases we need
-      // to explicitly reconnect.
-      if (es.readyState === es.CLOSED) {
-        unsubscribe()
-        clearTimeout(reconnectTimer)
-        reconnectTimer = setTimeout(open, 100)
-      }
-    }
-
-    function onChannelError(err: Any) {
-      observer.error(cooerceError(err))
-    }
-
-    function onMessage(evt: Any) {
-      const event = parseEvent(evt)
-      return event instanceof Error ? observer.error(event) : observer.next(event)
-    }
-
-    function onDisconnect() {
-      stopped = true
-      unsubscribe()
-      observer.complete()
-    }
-
-    function unsubscribe() {
-      if (!es) return
-      es.removeEventListener('error', onError)
-      es.removeEventListener('channelError', onChannelError)
-      es.removeEventListener('disconnect', onDisconnect)
-      listenFor.forEach((type: string) => es.removeEventListener(type, onMessage))
-      es.close()
-    }
-
-    function emitReconnect() {
-      if (shouldEmitReconnect) {
-        observer.next({type: 'reconnect'})
-      }
-    }
-
-    async function getEventSource(): Promise<InstanceType<
-      typeof import('@sanity/eventsource')
-    > | void> {
-      const {default: EventSource} = await import('@sanity/eventsource')
-
-      // If the listener has been unsubscribed from before we managed to load the module,
-      // do not set up the EventSource.
-      if (unsubscribed) {
-        return
-      }
-
-      const evs = new EventSource(uri, esOptions)
-      evs.addEventListener('error', onError)
-      evs.addEventListener('channelError', onChannelError)
-      evs.addEventListener('disconnect', onDisconnect)
-      listenFor.forEach((type: string) => evs.addEventListener(type, onMessage))
-      return evs
-    }
-
-    function open() {
-      getEventSource()
-        .then((eventSource) => {
-          if (eventSource) {
-            es = eventSource
-            // Handle race condition where the observer is unsubscribed before the EventSource is set up
-            if (unsubscribed) {
-              unsubscribe()
-            }
-          }
-        })
-        .catch((reason) => {
-          observer.error(reason)
-          stop()
-        })
-    }
-
-    function stop() {
-      stopped = true
-      unsubscribe()
-      unsubscribed = true
-    }
-
-    return stop
-  })
-}
-
-function parseEvent(event: Any) {
-  try {
-    const data = (event.data && JSON.parse(event.data)) || {}
-    return Object.assign({type: event.type}, data)
-  } catch (err) {
-    return err
-  }
-}
-
-function cooerceError(err: Any) {
-  if (err instanceof Error) {
-    return err
-  }
-
-  const evt = parseEvent(err)
-  return evt instanceof Error ? evt : new Error(extractErrorMessage(evt))
-}
-
-function extractErrorMessage(err: Any) {
-  if (!err.error) {
-    return err.message || 'Unknown listener error'
-  }
-
-  if (err.error.description) {
-    return err.error.description
-  }
-
-  return typeof err.error === 'string' ? err.error : JSON.stringify(err.error, null, 2)
+  const initEventSource = () =>
+    // use polyfill if there is no global EventSource or if we need to set headers
+    (typeof EventSource === 'undefined' || esOptions.headers
+      ? eventSourcePolyfill
+      : of(EventSource)
+    ).pipe(map((EventSource) => new EventSource(uri, esOptions)))
+
+  return connectEventSource(initEventSource, listenFor).pipe(
+    reconnectOnConnectionFailure(),
+    filter((event) => listenFor.includes(event.type)),
+    map(
+      (event) =>
+        ({
+          type: event.type,
+          ...('data' in event ? (event.data as object) : {}),
+        }) as MutationEvent<R> | ListenEvent<R>,
+    ),
+  )
 }