@sanity/client 5.4.2 → 5.4.3-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "5.4.2",
+  "version": "5.4.3-dev.1",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -33,6 +33,7 @@
         "import": "./dist/index.browser.js"
       },
       "deno": "./dist/index.browser.js",
+      "edge": "./dist/index.browser.js",
       "edge-light": "./dist/index.browser.js",
       "worker": "./dist/index.browser.js",
       "source": "./src/index.ts",
@@ -103,23 +104,23 @@
     "@types/node": "^18.15.10",
     "@typescript-eslint/eslint-plugin": "^5.57.0",
     "@typescript-eslint/parser": "^5.57.0",
-    "@vitest/coverage-c8": "^0.29.8",
+    "@vitest/coverage-c8": "^0.30.0",
     "eslint": "^8.36.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "faucet": "^0.0.4",
-    "happy-dom": "^8.9.0",
+    "happy-dom": "^9.0.0",
     "ls-engines": "^0.9.0",
     "nock": "^13.3.0",
     "prettier": "^2.8.7",
     "prettier-plugin-packagejson": "^2.4.3",
-    "rimraf": "^4.4.1",
+    "rimraf": "^5.0.0",
     "rollup": "^3.20.2",
     "sse-channel": "^4.0.0",
     "terser": "^5.16.8",
     "typescript": "^5.0.2",
-    "vitest": "^0.29.8",
+    "vitest": "^0.30.0",
     "vitest-github-actions-reporter": "^0.10.0"
   },
   "engines": {

package/src/SanityClient.ts

@@ -1210,22 +1210,25 @@ export class SanityClient {
   }
 
   /**
-   * DEPRECATED: Perform an HTTP request against the Sanity API
+   * Perform a request against the Sanity API
+   * NOTE: Only use this for Sanity API endpoints, not for your own APIs!
    *
-   * @deprecated Use your own request library!
    * @param options - Request options
+   * @returns Promise resolving to the response body
    */
   request<R = Any>(options: RawRequestOptions): Promise<R> {
     return lastValueFrom(dataMethods._request<R>(this, this.#httpRequest, options))
   }
 
   /**
-   * DEPRECATED: Perform an HTTP request a `/data` sub-endpoint
+   * Perform an HTTP request a `/data` sub-endpoint
+   * NOTE: Considered internal, thus marked as deprecated. Use `request` instead.
    *
-   * @deprecated Use your own request library!
+   * @deprecated - Use `request()` or your own HTTP library instead
    * @param endpoint - Endpoint to hit (mutate, query etc)
    * @param body - Request body
    * @param options - Request options
+   * @internal
    */
   dataRequest(endpoint: string, body: unknown, options?: BaseMutationOptions): Promise<Any> {
     return lastValueFrom(dataMethods._dataRequest(this, this.#httpRequest, endpoint, body, options))

package/src/config.ts

@@ -75,7 +75,8 @@ export const initConfig = (
 
   newConfig.apiVersion = `${newConfig.apiVersion}`.replace(/^v/, '')
   newConfig.isDefaultApi = newConfig.apiHost === defaultConfig.apiHost
-  newConfig.useCdn = Boolean(newConfig.useCdn) && !newConfig.withCredentials
+  // If `useCdn` is undefined, we treat it as `true`
+  newConfig.useCdn = newConfig.useCdn !== false && !newConfig.withCredentials
 
   validateApiVersion(newConfig.apiVersion)
 

package/src/data/dataMethods.ts

@@ -302,6 +302,10 @@ export function _requestObservable<R>(
     options.query = {tag: validate.requestTag(tag), ...options.query}
   }
 
+  if (config.resultSourceMap) {
+    options.query = {resultSourceMap: true, ...options.query}
+  }
+
   const reqOptions = requestOptions(
     config,
     Object.assign({}, options, {

package/src/http/nodeMiddleware.ts

@@ -1,11 +1,10 @@
-import {debug, headers, retry} from 'get-it/middleware'
+import {debug, headers} from 'get-it/middleware'
 
 import {name, version} from '../../package.json'
 
 const middleware = [
   debug({verbose: true, namespace: 'sanity:client'}),
   headers({'User-Agent': `${name} ${version}`}),
-  retry({maxRetries: 3}),
 ]
 
 export default middleware

package/src/http/request.ts

@@ -1,5 +1,5 @@
 import {getIt, type Middlewares} from 'get-it'
-import {jsonRequest, jsonResponse, observable, progress} from 'get-it/middleware'
+import {jsonRequest, jsonResponse, observable, progress, retry} from 'get-it/middleware'
 import {Observable} from 'rxjs'
 
 import type {Any, HttpRequest, RequestOptions} from '../types'
@@ -27,8 +27,22 @@ const printWarnings = {
 }
 
 /** @internal */
-export function defineHttpRequest(envMiddleware: Middlewares): HttpRequest {
+export function defineHttpRequest(
+  envMiddleware: Middlewares,
+  {
+    maxRetries = 5,
+    retryDelay,
+  }: {maxRetries?: number; retryDelay?: (attemptNumber: number) => number}
+): HttpRequest {
   const request = getIt([
+    maxRetries > 0
+      ? retry({
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          retryDelay: retryDelay as any, // This option is typed incorrectly in get-it.
+          maxRetries,
+          shouldRetry,
+        })
+      : {},
     ...envMiddleware,
     printWarnings,
     jsonRequest(),
@@ -46,3 +60,29 @@ export function defineHttpRequest(envMiddleware: Middlewares): HttpRequest {
 
   return httpRequest
 }
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function shouldRetry(err: any, attempt: number, options: any) {
+  // By default `retry.shouldRetry` doesn't retry on server errors so we add our own logic.
+
+  const isSafe = options.method === 'GET' || options.method === 'HEAD'
+  const isQuery = options.uri.startsWith('/data/query')
+  const isRetriableResponse =
+    err.response &&
+    (err.response.statusCode === 429 ||
+      err.response.statusCode === 502 ||
+      err.response.statusCode === 503)
+
+  // We retry the following errors:
+  // - 429 means that the request was rate limited. It's a bit difficult
+  //   to know exactly how long it makes sense to wait and/or how many
+  //   attempts we should retry, but the backoff should alleviate the
+  //   additional load.
+  // - 502/503 can occur when certain components struggle to talk to their
+  //   upstream dependencies. This is most likely a temporary problem
+  //   and retrying makes sense.
+
+  if ((isSafe || isQuery) && isRetriableResponse) return true
+
+  return retry.shouldRetry(err, attempt, options)
+}

package/src/index.browser.ts

@@ -11,12 +11,19 @@ export * from './SanityClient'
 export * from './types'
 
 // Set the http client to use for requests, and its environment specific middleware
-const httpRequest = defineHttpRequest(envMiddleware)
+const httpRequest = defineHttpRequest(envMiddleware, {})
 /** @public */
 export const requester = httpRequest.defaultRequester
 
 /** @public */
-export const createClient = (config: ClientConfig) => new SanityClient(httpRequest, config)
+export const createClient = (config: ClientConfig) =>
+  new SanityClient(
+    defineHttpRequest(envMiddleware, {
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+    }),
+    config
+  )
 
 /**
  * @public

package/src/index.ts

@@ -11,12 +11,19 @@ export * from './SanityClient'
 export * from './types'
 
 // Set the http client to use for requests, and its environment specific middleware
-const httpRequest = defineHttpRequest(envMiddleware)
+const httpRequest = defineHttpRequest(envMiddleware, {})
 /** @public */
 export const requester = httpRequest.defaultRequester
 
 /** @public */
-export const createClient = (config: ClientConfig) => new SanityClient(httpRequest, config)
+export const createClient = (config: ClientConfig) =>
+  new SanityClient(
+    defineHttpRequest(envMiddleware, {
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+    }),
+    config
+  )
 
 /**
  * @public

package/src/{types.ts → types/_legacy.ts}

@@ -1,6 +1,9 @@
+// @TODO the types in this file should be split into their own files, that's why the file is named `_legacy`
 // deno-lint-ignore-file no-empty-interface
 import type {Requester} from 'get-it'
 
+import type {ContentSourceMap} from './resultSourceMap'
+
 /**
  * Used to tag types that is set to `any` as a temporary measure, but should be replaced with proper typings in the future
  * @internal
@@ -31,6 +34,7 @@ export interface RequestOptions {
 export interface ClientConfig {
   projectId?: string
   dataset?: string
+  /** @defaultValue true */
   useCdn?: boolean
   token?: string
   apiHost?: string
@@ -42,6 +46,19 @@ export interface ClientConfig {
   allowReconfigure?: boolean
   timeout?: number
 
+  /** Number of retries for requests. Defaults to 5. */
+  maxRetries?: number
+
+  /**
+   * The amount of time, in milliseconds, to wait before retrying, given an attemptNumber (starting at 0).
+   *
+   * Defaults to exponential back-off, starting at 100ms, doubling for each attempt, together with random
+   * jitter between 0 and 100 milliseconds. More specifically the following algorithm is used:
+   *
+   *   Delay = 100 * 2^attemptNumber + randomNumberBetween0and100
+   */
+  retryDelay?: (attemptNumber: number) => number
+
   /**
    * @deprecated Don't use
    */
@@ -51,6 +68,8 @@ export interface ClientConfig {
    * @deprecated Don't use
    */
   requester?: Requester
+
+  resultSourceMap?: boolean
 }
 
 /** @public */
@@ -456,21 +475,22 @@ export interface ListenOptions {
   tag?: string
 }
 
-/** @internal */
+/** @public */
 export type FilteredResponseQueryOptions = RequestOptions & {
   filterResponse?: true
 }
 
-/** @internal */
+/** @public */
 export type UnfilteredResponseQueryOptions = RequestOptions & {
   filterResponse: false
 }
 
-/** @internal */
+/** @public */
 export interface RawQueryResponse<R> {
   q: string
   ms: number
   result: R
+  resultSourceMap: ContentSourceMap
 }
 
 /** @internal */

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export type * from './_legacy'
+export type * from './resultSourceMap'

package/src/types/resultSourceMap.ts

@@ -0,0 +1,60 @@
+import type {SanityDocument} from './_legacy'
+
+/**
+ * DocumentValueSource is a path to a value within a document
+ * @public
+ */
+export type ContentSourceMapDocumentValueSource = {
+  type: 'documentValue'
+  // index location of the document
+  document: number
+  // index location of the path
+  path: number
+}
+/**
+ * When a value is not from a source, its a literal
+ * @public
+ */
+export type ContentSourceMapLiteralSource = {
+  type: 'literal'
+}
+/**
+ * When a field source is unknown
+ * @public
+ */
+export type ContentSourceMapUnknownSource = {
+  type: 'unknown'
+}
+/** @public */
+export type ContentSourceMapSource =
+  | ContentSourceMapDocumentValueSource
+  | ContentSourceMapLiteralSource
+  | ContentSourceMapUnknownSource
+/**
+ * ValueMapping is a mapping when for value that is from a single source value
+ * It may refer to a field within a document or a literal value
+ * @public
+ */
+export type ContentSourceMapValueMapping = {
+  type: 'value'
+  // source of the value
+  source: ContentSourceMapSource
+}
+/** @public */
+export type ContentSourceMapMapping = ContentSourceMapValueMapping
+
+/** @public */
+export type ContentSourceMapMappings = Record<string, ContentSourceMapMapping>
+
+/** @public */
+export type ContentSourceMapDocuments = SanityDocument[]
+
+/** @public */
+export type ContentSourceMapPaths = string[]
+
+/** @public */
+export type ContentSourceMap = {
+  mappings: ContentSourceMapMappings
+  documents: ContentSourceMapDocuments
+  paths: ContentSourceMapPaths
+}

package/src/warnings.ts

@@ -7,10 +7,9 @@ const createWarningPrinter = (message: string[]) =>
   once((...args: Any[]) => console.warn(message.join(' '), ...args))
 
 export const printCdnWarning = createWarningPrinter([
-  'You are not using the Sanity CDN. That means your data is always fresh, but the CDN is faster and',
-  `cheaper. Think about it! For more info, see ${generateHelpUrl('js-client-cdn-configuration')} `,
-  'To hide this warning, please set the `useCdn` option to either `true` or `false` when creating',
-  'the client.',
+  `Since you haven't set a value for \`useCdn\`, we will deliver content using our`,
+  `global, edge-cached API-CDN. If you wish to have content delivered faster, set`,
+  `\`useCdn: false\` to use the Live API. Note: You may incur higher costs using the live API.`,
 ])
 
 export const printBrowserTokenWarning = createWarningPrinter([
@@ -26,5 +25,5 @@ export const printNoApiVersionSpecifiedWarning = createWarningPrinter([
 ])
 
 export const printNoDefaultExport = createWarningPrinter([
-  'The default export of @sanity/client has been deprecated. Use the named export `createClient` instead',
+  'The default export of @sanity/client has been deprecated. Use the named export `createClient` instead.',
 ])

package/umd/sanityClient.js

@@ -4,21 +4,6 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.SanityClient = {}));
 })(this, (function (exports) { 'use strict';
 
-  function _mergeNamespaces(n, m) {
-    m.forEach(function (e) {
-      e && typeof e !== 'string' && !Array.isArray(e) && Object.keys(e).forEach(function (k) {
-        if (k !== 'default' && !(k in n)) {
-          var d = Object.getOwnPropertyDescriptor(e, k);
-          Object.defineProperty(n, k, d.get ? d : {
-            enumerable: true,
-            get: function () { return e[k]; }
-          });
-        }
-      });
-    });
-    return Object.freeze(n);
-  }
-
   const isReactNative = typeof navigator === "undefined" ? false : navigator.product === "ReactNative";
   const defaultOptions$1 = {
     timeout: isReactNative ? 6e4 : 12e4
@@ -1372,6 +1357,50 @@
       cancel
     };
   };
+  var defaultShouldRetry = (err, attempt, options) => {
+    if (options.method !== "GET" && options.method !== "HEAD") {
+      return false;
+    }
+    return err.isNetworkError || false;
+  };
+  const isStream = stream => stream !== null && typeof stream === "object" && typeof stream.pipe === "function";
+  var sharedRetry = opts => {
+    const maxRetries = opts.maxRetries || 5;
+    const retryDelay = opts.retryDelay || getRetryDelay;
+    const allowRetry = opts.shouldRetry;
+    return {
+      onError: (err, context) => {
+        const options = context.options;
+        const max = options.maxRetries || maxRetries;
+        const shouldRetry = options.shouldRetry || allowRetry;
+        const attemptNumber = options.attemptNumber || 0;
+        if (isStream(options.body)) {
+          return err;
+        }
+        if (!shouldRetry(err, attemptNumber, options) || attemptNumber >= max) {
+          return err;
+        }
+        const newContext = Object.assign({}, context, {
+          options: Object.assign({}, options, {
+            attemptNumber: attemptNumber + 1
+          })
+        });
+        setTimeout(() => context.channels.request.publish(newContext), retryDelay(attemptNumber));
+        return null;
+      }
+    };
+  };
+  function getRetryDelay(attemptNum) {
+    return 100 * Math.pow(2, attemptNum) + Math.random() * 100;
+  }
+  const retry = function () {
+    let opts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    return sharedRetry({
+      shouldRetry: defaultShouldRetry,
+      ...opts
+    });
+  };
+  retry.shouldRetry = defaultShouldRetry;
 
   /******************************************************************************
   Copyright (c) Microsoft Corporation.
@@ -2140,8 +2169,18 @@
       return res;
     }
   };
-  function defineHttpRequest(envMiddleware) {
-    const request = getIt([...envMiddleware, printWarnings, jsonRequest(), jsonResponse(), progress(), httpError, observable$1({
+  function defineHttpRequest(envMiddleware, _ref) {
+    let {
+      maxRetries = 5,
+      retryDelay
+    } = _ref;
+    const request = getIt([maxRetries > 0 ? retry({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      retryDelay,
+      // This option is typed incorrectly in get-it.
+      maxRetries,
+      shouldRetry
+    }) : {}, ...envMiddleware, printWarnings, jsonRequest(), jsonResponse(), progress(), httpError, observable$1({
       implementation: Observable
     })]);
     function httpRequest(options) {
@@ -2154,6 +2193,13 @@
     httpRequest.defaultRequester = request;
     return httpRequest;
   }
+  function shouldRetry(err, attempt, options) {
+    const isSafe = options.method === "GET" || options.method === "HEAD";
+    const isQuery = options.uri.startsWith("/data/query");
+    const isRetriableResponse = err.response && (err.response.statusCode === 429 || err.response.statusCode === 502 || err.response.statusCode === 503);
+    if ((isSafe || isQuery) && isRetriableResponse) return true;
+    return retry.shouldRetry(err, attempt, options);
+  }
   const projectHeader = "X-Sanity-Project-ID";
   function requestOptions(config) {
     let overrides = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -2250,12 +2296,12 @@
     }
     return tag;
   };
-  const encodeQueryString = _ref => {
+  const encodeQueryString = _ref2 => {
     let {
       query,
       params = {},
       options = {}
-    } = _ref;
+    } = _ref2;
     const searchParams = new URLSearchParams();
     const {
       tag,
@@ -2864,6 +2910,12 @@
         ...options.query
       };
     }
+    if (config.resultSourceMap) {
+      options.query = {
+        resultSourceMap: true,
+        ...options.query
+      };
+    }
     const reqOptions = requestOptions(config, Object.assign({}, options, {
       url: _getUrl(client, uri, useCdn)
     }));
@@ -3040,10 +3092,10 @@
     }
     return console.warn(message.join(" "), ...args);
   });
-  const printCdnWarning = createWarningPrinter(["You are not using the Sanity CDN. That means your data is always fresh, but the CDN is faster and", "cheaper. Think about it! For more info, see ".concat(generateHelpUrl("js-client-cdn-configuration"), " "), "To hide this warning, please set the `useCdn` option to either `true` or `false` when creating", "the client."]);
+  const printCdnWarning = createWarningPrinter(["Since you haven't set a value for `useCdn`, we will deliver content using our", "global, edge-cached API-CDN. If you wish to have content delivered faster, set", "`useCdn: false` to use the Live API. Note: You may incur higher costs using the live API."]);
   const printBrowserTokenWarning = createWarningPrinter(["You have configured Sanity client to use a token in the browser. This may cause unintentional security issues.", "See ".concat(generateHelpUrl("js-client-browser-token"), " for more information and how to hide this warning.")]);
   const printNoApiVersionSpecifiedWarning = createWarningPrinter(["Using the Sanity client without specifying an API version is deprecated.", "See ".concat(generateHelpUrl("js-client-api-version"))]);
-  const printNoDefaultExport = createWarningPrinter(["The default export of @sanity/client has been deprecated. Use the named export `createClient` instead"]);
+  const printNoDefaultExport = createWarningPrinter(["The default export of @sanity/client has been deprecated. Use the named export `createClient` instead."]);
   const defaultCdnHost = "apicdn.sanity.io";
   const defaultConfig = {
     apiHost: "https://api.sanity.io",
@@ -3094,7 +3146,7 @@
     }
     newConfig.apiVersion = "".concat(newConfig.apiVersion).replace(/^v/, "");
     newConfig.isDefaultApi = newConfig.apiHost === defaultConfig.apiHost;
-    newConfig.useCdn = Boolean(newConfig.useCdn) && !newConfig.withCredentials;
+    newConfig.useCdn = newConfig.useCdn !== false && !newConfig.withCredentials;
     validateApiVersion(newConfig.apiVersion);
     const hostParts = newConfig.apiHost.split("://", 2);
     const protocol = hostParts[0];
@@ -3771,21 +3823,24 @@
       return new Transaction(operations, this);
     }
     /**
-     * DEPRECATED: Perform an HTTP request against the Sanity API
+     * Perform a request against the Sanity API
+     * NOTE: Only use this for Sanity API endpoints, not for your own APIs!
      *
-     * @deprecated Use your own request library!
      * @param options - Request options
+     * @returns Promise resolving to the response body
      */
     request(options) {
       return lastValueFrom(_request(this, __privateGet(this, _httpRequest2), options));
     }
     /**
-     * DEPRECATED: Perform an HTTP request a `/data` sub-endpoint
+     * Perform an HTTP request a `/data` sub-endpoint
+     * NOTE: Considered internal, thus marked as deprecated. Use `request` instead.
      *
-     * @deprecated Use your own request library!
+     * @deprecated - Use `request()` or your own HTTP library instead
      * @param endpoint - Endpoint to hit (mutate, query etc)
      * @param body - Request body
      * @param options - Request options
+     * @internal
      */
     dataRequest(endpoint, body, options) {
       return lastValueFrom(_dataRequest(this, __privateGet(this, _httpRequest2), endpoint, body, options));
@@ -3812,9 +3867,12 @@
   let SanityClient = _SanityClient;
   _clientConfig2 = new WeakMap();
   _httpRequest2 = new WeakMap();
-  const httpRequest = defineHttpRequest(envMiddleware);
+  const httpRequest = defineHttpRequest(envMiddleware, {});
   const requester = httpRequest.defaultRequester;
-  const createClient = config => new SanityClient(httpRequest, config);
+  const createClient = config => new SanityClient(defineHttpRequest(envMiddleware, {
+    maxRetries: config.maxRetries,
+    retryDelay: config.retryDelay
+  }), config);
   function deprecatedCreateClient(config) {
     printNoDefaultExport();
     return new SanityClient(httpRequest, config);
@@ -4872,10 +4930,10 @@
 
   var browser = eventsourceExports.EventSourcePolyfill;
 
-  var browser$1 = /*#__PURE__*/_mergeNamespaces({
+  var browser$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
     default: browser
-  }, [browser]);
+  });
 
   exports.BasePatch = BasePatch;
   exports.BaseTransaction = BaseTransaction;