@sanity/client 7.22.1 → 7.23.1

package/dist/stega.browser.d.cts

@@ -906,11 +906,26 @@ export declare function connectEventSource<EventName extends string>(
 
 /**
  * @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.
+ * Thrown when the EventSource connection could not be established, or was rejected by the server.
+ * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
+ * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
+ * stream with this class so consumers can react — check `status` for the rejection code.
  */
 export declare class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
+  /**
+   * HTTP status code of the rejected connection attempt, if known.
+   * Only set when the EventSource implementation exposes it — the polyfill used in
+   * Node.js and when custom headers (eg authorization) are required does, while
+   * native EventSource implementations (browser and Node.js) do not.
+   */
+  readonly status?: number
+  constructor(
+    message?: string,
+    options?: ErrorOptions & {
+      status?: number
+    },
+  )
 }
 
 /**
@@ -3363,6 +3378,20 @@ export declare class ObservableSanityClient {
       tag?: string
     },
   ): Observable<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Observable<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -5286,6 +5315,20 @@ export declare class SanityClient {
       tag?: string
     },
   ): Promise<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Promise<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.

package/dist/stega.browser.d.ts

@@ -906,11 +906,26 @@ export declare function connectEventSource<EventName extends string>(
 
 /**
  * @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.
+ * Thrown when the EventSource connection could not be established, or was rejected by the server.
+ * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
+ * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
+ * stream with this class so consumers can react — check `status` for the rejection code.
  */
 export declare class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
+  /**
+   * HTTP status code of the rejected connection attempt, if known.
+   * Only set when the EventSource implementation exposes it — the polyfill used in
+   * Node.js and when custom headers (eg authorization) are required does, while
+   * native EventSource implementations (browser and Node.js) do not.
+   */
+  readonly status?: number
+  constructor(
+    message?: string,
+    options?: ErrorOptions & {
+      status?: number
+    },
+  )
 }
 
 /**
@@ -3363,6 +3378,20 @@ export declare class ObservableSanityClient {
       tag?: string
     },
   ): Observable<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Observable<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -5286,6 +5315,20 @@ export declare class SanityClient {
       tag?: string
     },
   ): Promise<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Promise<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.

package/dist/stega.d.cts

@@ -906,11 +906,26 @@ export declare function connectEventSource<EventName extends string>(
 
 /**
  * @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.
+ * Thrown when the EventSource connection could not be established, or was rejected by the server.
+ * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
+ * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
+ * stream with this class so consumers can react — check `status` for the rejection code.
  */
 export declare class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
+  /**
+   * HTTP status code of the rejected connection attempt, if known.
+   * Only set when the EventSource implementation exposes it — the polyfill used in
+   * Node.js and when custom headers (eg authorization) are required does, while
+   * native EventSource implementations (browser and Node.js) do not.
+   */
+  readonly status?: number
+  constructor(
+    message?: string,
+    options?: ErrorOptions & {
+      status?: number
+    },
+  )
 }
 
 /**
@@ -3363,6 +3378,20 @@ export declare class ObservableSanityClient {
       tag?: string
     },
   ): Observable<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Observable<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -5286,6 +5315,20 @@ export declare class SanityClient {
       tag?: string
     },
   ): Promise<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Promise<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.

package/dist/stega.d.ts

@@ -906,11 +906,26 @@ export declare function connectEventSource<EventName extends string>(
 
 /**
  * @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.
+ * Thrown when the EventSource connection could not be established, or was rejected by the server.
+ * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
+ * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
+ * stream with this class so consumers can react — check `status` for the rejection code.
  */
 export declare class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
+  /**
+   * HTTP status code of the rejected connection attempt, if known.
+   * Only set when the EventSource implementation exposes it — the polyfill used in
+   * Node.js and when custom headers (eg authorization) are required does, while
+   * native EventSource implementations (browser and Node.js) do not.
+   */
+  readonly status?: number
+  constructor(
+    message?: string,
+    options?: ErrorOptions & {
+      status?: number
+    },
+  )
 }
 
 /**
@@ -3363,6 +3378,20 @@ export declare class ObservableSanityClient {
       tag?: string
     },
   ): Observable<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Observable<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -5286,6 +5315,20 @@ export declare class SanityClient {
       tag?: string
     },
   ): Promise<(SanityDocument<R> | null)[]>
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {
+      signal?: AbortSignal
+      tag?: string
+    },
+  ): Promise<Set<string>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "7.22.1",
+  "version": "7.23.1",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -130,7 +130,7 @@
   },
   "dependencies": {
     "@sanity/eventsource": "^5.0.2",
-    "get-it": "^8.7.2",
+    "get-it": "^8.8.0",
     "nanoid": "^3.3.11",
     "rxjs": "^7.0.0"
   },

package/src/SanityClient.ts

@@ -324,6 +324,20 @@ export class ObservableSanityClient {
     return dataMethods._getDocuments<R>(this, this.#httpRequest, ids, options)
   }
 
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {signal?: AbortSignal; tag?: string},
+  ): Observable<Set<string>> {
+    return dataMethods._documentsExists(this, this.#httpRequest, ids, options)
+  }
+
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -1390,6 +1404,20 @@ export class SanityClient {
     return lastValueFrom(dataMethods._getDocuments<R>(this, this.#httpRequest, ids, options))
   }
 
+  /**
+   * Convenient and bandwidth efficient method of checking wether a set of document IDs exists.
+   * Returns a set of the IDs that exist.
+   *
+   * @param ids - Document IDs to check
+   * @param options - Request options
+   */
+  documentsExists(
+    ids: string[],
+    options?: {signal?: AbortSignal; tag?: string},
+  ): Promise<Set<string>> {
+    return lastValueFrom(dataMethods._documentsExists(this, this.#httpRequest, ids, options))
+  }
+
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.

package/src/data/dataMethods.ts

@@ -1,6 +1,6 @@
 import {getDraftId, getVersionFromId, getVersionId, isDraftId} from '@sanity/client/csm'
-import {from, type MonoTypeOperatorFunction, Observable} from 'rxjs'
-import {combineLatestWith, filter, map} from 'rxjs/operators'
+import {from, type MonoTypeOperatorFunction, Observable, of} from 'rxjs'
+import {combineLatestWith, concatMap, filter, map, reduce} from 'rxjs/operators'
 
 import {validateApiPerspective} from '../config'
 import {requestOptions} from '../http/requestOptions'
@@ -231,6 +231,51 @@ export function _getDocuments<R extends Record<string, Any>>(
   )
 }
 
+const DOCUMENTS_EXISTS_BATCH_SIZE = 100
+
+/** @internal */
+export function _documentsExists(
+  client: Client,
+  httpRequest: HttpRequest,
+  ids: string[],
+  opts: {signal?: AbortSignal; tag?: string} = {},
+): Observable<Set<string>> {
+  if (ids.length === 0) {
+    return of(new Set<string>())
+  }
+
+  const batches: string[][] = []
+  for (let i = 0; i < ids.length; i += DOCUMENTS_EXISTS_BATCH_SIZE) {
+    batches.push(ids.slice(i, i + DOCUMENTS_EXISTS_BATCH_SIZE))
+  }
+
+  const fetchBatch = (batchIds: string[]) =>
+    _requestObservable<Any>(client, httpRequest, {
+      uri: _getDataUrl(client, 'doc', batchIds.map(encodeURIComponent).join(',')),
+      tag: opts.tag,
+      signal: opts.signal,
+      query: {excludeContent: true},
+    }).pipe(
+      filter(isResponse),
+      map((event: Any) => {
+        const missing = new Set<string>()
+        for (const omitted of event.body.omitted || []) {
+          if (omitted.reason !== 'existence') continue
+          missing.add(omitted.id)
+        }
+        return new Set(batchIds.filter((id) => !missing.has(id)))
+      }),
+    )
+
+  return from(batches).pipe(
+    concatMap(fetchBatch),
+    reduce((acc, set) => {
+      for (const id of set) acc.add(id)
+      return acc
+    }, new Set<string>()),
+  )
+}
+
 /** @internal */
 export function _getReleaseDocuments<R extends Record<string, Any>>(
   client: ObservableSanityClient | SanityClient,
@@ -598,6 +643,11 @@ export function _requestObservable<R>(
   httpRequest: HttpRequest,
   options: RequestObservableOptions,
 ): Observable<HttpRequestEvent<R>> {
+  // Capture the call-site error here, where the caller's code is still
+  // on the synchronous call stack, and pass it through to get-it so errors
+  // include the originating call site rather than just internal plumbing.
+  const callSiteStack = new Error()
+
   const uri = options.url || (options.uri as string)
   const config = client.config()
 
@@ -667,6 +717,7 @@ export function _requestObservable<R>(
     config,
     Object.assign({}, options, {
       url: _getUrl(client, uri, useCdn),
+      callSiteStack,
     }),
   ) as RequestOptions
 

package/src/data/eventsource.ts

@@ -5,11 +5,25 @@ 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.
+ * Thrown when the EventSource connection could not be established, or was rejected by the server.
+ * Transient failures (network drops, 5xx, 408, 429) are reconnected internally and emitted as
+ * `reconnect` events; a permanent rejection (any other 4xx, eg an expired token) errors the
+ * stream with this class so consumers can react — check `status` for the rejection code.
  */
 export class ConnectionFailedError extends Error {
   readonly name = 'ConnectionFailedError'
+  /**
+   * HTTP status code of the rejected connection attempt, if known.
+   * Only set when the EventSource implementation exposes it — the polyfill used in
+   * Node.js and when custom headers (eg authorization) are required does, while
+   * native EventSource implementations (browser and Node.js) do not.
+   */
+  readonly status?: number
+  constructor(message?: string, options: ErrorOptions & {status?: number} = {}) {
+    const {status, ...errorOptions} = options
+    super(message, errorOptions)
+    this.status = status
+  }
 }
 
 /**
@@ -147,6 +161,18 @@ function connectWithESInstance<EventTypeName extends string>(
       // 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
+      // The polyfills expose the HTTP status of a rejected connection on the error event
+      // (native EventSource implementations do not). A status means the server rejected the
+      // connection attempt, so error out regardless of readyState — the polyfills disagree
+      // on whether the connection closes before or after the error event is dispatched —
+      // and let `reconnectOnConnectionFailure` classify it (4xx fatal, otherwise retried).
+      const rawStatus = (evt as {status?: unknown}).status
+      const status = typeof rawStatus === 'number' ? rawStatus : undefined
+      if (status !== undefined) {
+        observer.error(new ConnectionFailedError('EventSource connection failed', {status}))
+        return
+      }
+
       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'))

package/src/data/reconnectOnConnectionFailure.ts

@@ -11,6 +11,8 @@ import {
 
 import {ConnectionFailedError} from './eventsource'
 
+const RETRYABLE_STATUSES = new Set([408, 429])
+
 /**
  * Note: connection failure is not the same as network disconnect which may happen more frequent.
  * The EventSource instance will automatically reconnect in case of a network disconnect, however,
@@ -20,7 +22,19 @@ export function reconnectOnConnectionFailure<T>(): OperatorFunction<T, T | {type
   return function (source: Observable<T>) {
     return source.pipe(
       catchError((err, caught) => {
-        if (err instanceof ConnectionFailedError) {
+        // Only reconnect on transient connection failures. A 4xx response is a
+        // rejection, not a transient failure — the server will keep rejecting
+        // (eg an expired token), so reconnecting would loop forever. The named
+        // exceptions are the explicitly transient 4xx statuses: 408 (request
+        // timeout) and 429 (rate limited). Anything else surfaces to the
+        // consumer instead.
+        if (
+          err instanceof ConnectionFailedError &&
+          (typeof err.status !== 'number' ||
+            err.status < 400 ||
+            err.status >= 500 ||
+            RETRYABLE_STATUSES.has(err.status))
+        ) {
           return concat(of({type: 'reconnect' as const}), timer(1000).pipe(mergeMap(() => caught)))
         }
         return throwError(() => err)