@algolia/client-common 5.8.1 → 5.9.1

package/src/transporter/createTransporter.ts

@@ -1,315 +0,0 @@
-import type {
-  EndRequest,
-  Host,
-  QueryParameters,
-  Request,
-  RequestOptions,
-  Response,
-  StackFrame,
-  Transporter,
-  TransporterOptions,
-} from '../types';
-import { createStatefulHost } from './createStatefulHost';
-import { RetryError } from './errors';
-import { deserializeFailure, deserializeSuccess, serializeData, serializeHeaders, serializeUrl } from './helpers';
-import { isRetryable, isSuccess } from './responses';
-import { stackFrameWithoutCredentials, stackTraceWithoutCredentials } from './stackTrace';
-
-type RetryableOptions = {
-  hosts: Host[];
-  getTimeout: (retryCount: number, timeout: number) => number;
-};
-
-export function createTransporter({
-  hosts,
-  hostsCache,
-  baseHeaders,
-  logger,
-  baseQueryParameters,
-  algoliaAgent,
-  timeouts,
-  requester,
-  requestsCache,
-  responsesCache,
-}: TransporterOptions): Transporter {
-  async function createRetryableOptions(compatibleHosts: Host[]): Promise<RetryableOptions> {
-    const statefulHosts = await Promise.all(
-      compatibleHosts.map((compatibleHost) => {
-        return hostsCache.get(compatibleHost, () => {
-          return Promise.resolve(createStatefulHost(compatibleHost));
-        });
-      }),
-    );
-    const hostsUp = statefulHosts.filter((host) => host.isUp());
-    const hostsTimedOut = statefulHosts.filter((host) => host.isTimedOut());
-
-    // Note, we put the hosts that previously timed out on the end of the list.
-    const hostsAvailable = [...hostsUp, ...hostsTimedOut];
-    const compatibleHostsAvailable = hostsAvailable.length > 0 ? hostsAvailable : compatibleHosts;
-
-    return {
-      hosts: compatibleHostsAvailable,
-      getTimeout(timeoutsCount: number, baseTimeout: number): number {
-        /**
-         * Imagine that you have 4 hosts, if timeouts will increase
-         * on the following way: 1 (timed out) > 4 (timed out) > 5 (200).
-         *
-         * Note that, the very next request, we start from the previous timeout.
-         *
-         *  5 (timed out) > 6 (timed out) > 7 ...
-         *
-         * This strategy may need to be reviewed, but is the strategy on the our
-         * current v3 version.
-         */
-        const timeoutMultiplier =
-          hostsTimedOut.length === 0 && timeoutsCount === 0 ? 1 : hostsTimedOut.length + 3 + timeoutsCount;
-
-        return timeoutMultiplier * baseTimeout;
-      },
-    };
-  }
-
-  async function retryableRequest<TResponse>(
-    request: Request,
-    requestOptions: RequestOptions,
-    isRead = true,
-  ): Promise<TResponse> {
-    const stackTrace: StackFrame[] = [];
-
-    /**
-     * First we prepare the payload that do not depend from hosts.
-     */
-    const data = serializeData(request, requestOptions);
-    const headers = serializeHeaders(baseHeaders, request.headers, requestOptions.headers);
-
-    // On `GET`, the data is proxied to query parameters.
-    const dataQueryParameters: QueryParameters =
-      request.method === 'GET'
-        ? {
-            ...request.data,
-            ...requestOptions.data,
-          }
-        : {};
-
-    const queryParameters: QueryParameters = {
-      ...baseQueryParameters,
-      ...request.queryParameters,
-      ...dataQueryParameters,
-    };
-
-    if (algoliaAgent.value) {
-      queryParameters['x-algolia-agent'] = algoliaAgent.value;
-    }
-
-    if (requestOptions && requestOptions.queryParameters) {
-      for (const key of Object.keys(requestOptions.queryParameters)) {
-        // We want to keep `undefined` and `null` values,
-        // but also avoid stringifying `object`s, as they are
-        // handled in the `serializeUrl` step right after.
-        if (
-          !requestOptions.queryParameters[key] ||
-          Object.prototype.toString.call(requestOptions.queryParameters[key]) === '[object Object]'
-        ) {
-          queryParameters[key] = requestOptions.queryParameters[key];
-        } else {
-          queryParameters[key] = requestOptions.queryParameters[key].toString();
-        }
-      }
-    }
-
-    let timeoutsCount = 0;
-
-    const retry = async (
-      retryableHosts: Host[],
-      getTimeout: (timeoutsCount: number, timeout: number) => number,
-    ): Promise<TResponse> => {
-      /**
-       * We iterate on each host, until there is no host left.
-       */
-      const host = retryableHosts.pop();
-      if (host === undefined) {
-        throw new RetryError(stackTraceWithoutCredentials(stackTrace));
-      }
-
-      const timeout = { ...timeouts, ...requestOptions.timeouts };
-
-      const payload: EndRequest = {
-        data,
-        headers,
-        method: request.method,
-        url: serializeUrl(host, request.path, queryParameters),
-        connectTimeout: getTimeout(timeoutsCount, timeout.connect),
-        responseTimeout: getTimeout(timeoutsCount, isRead ? timeout.read : timeout.write),
-      };
-
-      /**
-       * The stackFrame is pushed to the stackTrace so we
-       * can have information about onRetry and onFailure
-       * decisions.
-       */
-      const pushToStackTrace = (response: Response): StackFrame => {
-        const stackFrame: StackFrame = {
-          request: payload,
-          response,
-          host,
-          triesLeft: retryableHosts.length,
-        };
-
-        stackTrace.push(stackFrame);
-
-        return stackFrame;
-      };
-
-      const response = await requester.send(payload);
-
-      if (isRetryable(response)) {
-        const stackFrame = pushToStackTrace(response);
-
-        // If response is a timeout, we increase the number of timeouts so we can increase the timeout later.
-        if (response.isTimedOut) {
-          timeoutsCount++;
-        }
-        /**
-         * Failures are individually sent to the logger, allowing
-         * the end user to debug / store stack frames even
-         * when a retry error does not happen.
-         */
-        logger.info('Retryable failure', stackFrameWithoutCredentials(stackFrame));
-
-        /**
-         * We also store the state of the host in failure cases. If the host, is
-         * down it will remain down for the next 2 minutes. In a timeout situation,
-         * this host will be added end of the list of hosts on the next request.
-         */
-        await hostsCache.set(host, createStatefulHost(host, response.isTimedOut ? 'timed out' : 'down'));
-
-        return retry(retryableHosts, getTimeout);
-      }
-
-      if (isSuccess(response)) {
-        return deserializeSuccess(response);
-      }
-
-      pushToStackTrace(response);
-      throw deserializeFailure(response, stackTrace);
-    };
-
-    /**
-     * Finally, for each retryable host perform request until we got a non
-     * retryable response. Some notes here:
-     *
-     * 1. The reverse here is applied so we can apply a `pop` later on => more performant.
-     * 2. We also get from the retryable options a timeout multiplier that is tailored
-     * for the current context.
-     */
-    const compatibleHosts = hosts.filter(
-      (host) => host.accept === 'readWrite' || (isRead ? host.accept === 'read' : host.accept === 'write'),
-    );
-    const options = await createRetryableOptions(compatibleHosts);
-
-    return retry([...options.hosts].reverse(), options.getTimeout);
-  }
-
-  function createRequest<TResponse>(request: Request, requestOptions: RequestOptions = {}): Promise<TResponse> {
-    /**
-     * A read request is either a `GET` request, or a request that we make
-     * via the `read` transporter (e.g. `search`).
-     */
-    const isRead = request.useReadTransporter || request.method === 'GET';
-    if (!isRead) {
-      /**
-       * On write requests, no cache mechanisms are applied, and we
-       * proxy the request immediately to the requester.
-       */
-      return retryableRequest<TResponse>(request, requestOptions, isRead);
-    }
-
-    const createRetryableRequest = (): Promise<TResponse> => {
-      /**
-       * Then, we prepare a function factory that contains the construction of
-       * the retryable request. At this point, we may *not* perform the actual
-       * request. But we want to have the function factory ready.
-       */
-      return retryableRequest<TResponse>(request, requestOptions);
-    };
-
-    /**
-     * Once we have the function factory ready, we need to determine of the
-     * request is "cacheable" - should be cached. Note that, once again,
-     * the user can force this option.
-     */
-    const cacheable = requestOptions.cacheable || request.cacheable;
-
-    /**
-     * If is not "cacheable", we immediately trigger the retryable request, no
-     * need to check cache implementations.
-     */
-    if (cacheable !== true) {
-      return createRetryableRequest();
-    }
-
-    /**
-     * If the request is "cacheable", we need to first compute the key to ask
-     * the cache implementations if this request is on progress or if the
-     * response already exists on the cache.
-     */
-    const key = {
-      request,
-      requestOptions,
-      transporter: {
-        queryParameters: baseQueryParameters,
-        headers: baseHeaders,
-      },
-    };
-
-    /**
-     * With the computed key, we first ask the responses cache
-     * implementation if this request was been resolved before.
-     */
-    return responsesCache.get(
-      key,
-      () => {
-        /**
-         * If the request has never resolved before, we actually ask if there
-         * is a current request with the same key on progress.
-         */
-        return requestsCache.get(key, () =>
-          /**
-           * Finally, if there is no request in progress with the same key,
-           * this `createRetryableRequest()` will actually trigger the
-           * retryable request.
-           */
-          requestsCache
-            .set(key, createRetryableRequest())
-            .then(
-              (response) => Promise.all([requestsCache.delete(key), response]),
-              (err) => Promise.all([requestsCache.delete(key), Promise.reject(err)]),
-            )
-            .then(([_, response]) => response),
-        );
-      },
-      {
-        /**
-         * Of course, once we get this response back from the server, we
-         * tell response cache to actually store the received response
-         * to be used later.
-         */
-        miss: (response) => responsesCache.set(key, response),
-      },
-    );
-  }
-
-  return {
-    hostsCache,
-    requester,
-    timeouts,
-    logger,
-    algoliaAgent,
-    baseHeaders,
-    baseQueryParameters,
-    hosts,
-    request: createRequest,
-    requestsCache,
-    responsesCache,
-  };
-}

package/src/transporter/errors.ts

@@ -1,77 +0,0 @@
-import type { Response, StackFrame } from '../types';
-
-export class AlgoliaError extends Error {
-  override name: string = 'AlgoliaError';
-
-  constructor(message: string, name: string) {
-    super(message);
-
-    if (name) {
-      this.name = name;
-    }
-  }
-}
-
-export class ErrorWithStackTrace extends AlgoliaError {
-  stackTrace: StackFrame[];
-
-  constructor(message: string, stackTrace: StackFrame[], name: string) {
-    super(message, name);
-    // the array and object should be frozen to reflect the stackTrace at the time of the error
-    this.stackTrace = stackTrace;
-  }
-}
-
-export class RetryError extends ErrorWithStackTrace {
-  constructor(stackTrace: StackFrame[]) {
-    super(
-      'Unreachable hosts - your application id may be incorrect. If the error persists, please reach out to the Algolia Support team: https://alg.li/support.',
-      stackTrace,
-      'RetryError',
-    );
-  }
-}
-
-export class ApiError extends ErrorWithStackTrace {
-  status: number;
-
-  constructor(message: string, status: number, stackTrace: StackFrame[], name = 'ApiError') {
-    super(message, stackTrace, name);
-    this.status = status;
-  }
-}
-
-export class DeserializationError extends AlgoliaError {
-  response: Response;
-
-  constructor(message: string, response: Response) {
-    super(message, 'DeserializationError');
-    this.response = response;
-  }
-}
-
-export type DetailedErrorWithMessage = {
-  message: string;
-  label: string;
-};
-
-export type DetailedErrorWithTypeID = {
-  id: string;
-  type: string;
-  name?: string;
-};
-
-export type DetailedError = {
-  code: string;
-  details?: DetailedErrorWithMessage[] | DetailedErrorWithTypeID[];
-};
-
-// DetailedApiError is only used by the ingestion client to return more informative error, other clients will use ApiClient.
-export class DetailedApiError extends ApiError {
-  error: DetailedError;
-
-  constructor(message: string, status: number, error: DetailedError, stackTrace: StackFrame[]) {
-    super(message, status, stackTrace, 'DetailedApiError');
-    this.error = error;
-  }
-}

package/src/transporter/helpers.ts

@@ -1,96 +0,0 @@
-import type { Headers, Host, QueryParameters, Request, RequestOptions, Response, StackFrame } from '../types';
-import { ApiError, DeserializationError, DetailedApiError } from './errors';
-
-export function shuffle<TData>(array: TData[]): TData[] {
-  const shuffledArray = array;
-
-  for (let c = array.length - 1; c > 0; c--) {
-    const b = Math.floor(Math.random() * (c + 1));
-    const a = array[c];
-
-    shuffledArray[c] = array[b];
-    shuffledArray[b] = a;
-  }
-
-  return shuffledArray;
-}
-
-export function serializeUrl(host: Host, path: string, queryParameters: QueryParameters): string {
-  const queryParametersAsString = serializeQueryParameters(queryParameters);
-  let url = `${host.protocol}://${host.url}${host.port ? `:${host.port}` : ''}/${
-    path.charAt(0) === '/' ? path.substring(1) : path
-  }`;
-
-  if (queryParametersAsString.length) {
-    url += `?${queryParametersAsString}`;
-  }
-
-  return url;
-}
-
-export function serializeQueryParameters(parameters: QueryParameters): string {
-  return Object.keys(parameters)
-    .filter((key) => parameters[key] !== undefined)
-    .sort()
-    .map(
-      (key) =>
-        `${key}=${encodeURIComponent(
-          Object.prototype.toString.call(parameters[key]) === '[object Array]'
-            ? parameters[key].join(',')
-            : parameters[key],
-        ).replace(/\+/g, '%20')}`,
-    )
-    .join('&');
-}
-
-export function serializeData(request: Request, requestOptions: RequestOptions): string | undefined {
-  if (request.method === 'GET' || (request.data === undefined && requestOptions.data === undefined)) {
-    return undefined;
-  }
-
-  const data = Array.isArray(request.data) ? request.data : { ...request.data, ...requestOptions.data };
-
-  return JSON.stringify(data);
-}
-
-export function serializeHeaders(
-  baseHeaders: Headers,
-  requestHeaders: Headers,
-  requestOptionsHeaders?: Headers,
-): Headers {
-  const headers: Headers = {
-    Accept: 'application/json',
-    ...baseHeaders,
-    ...requestHeaders,
-    ...requestOptionsHeaders,
-  };
-  const serializedHeaders: Headers = {};
-
-  Object.keys(headers).forEach((header) => {
-    const value = headers[header];
-    serializedHeaders[header.toLowerCase()] = value;
-  });
-
-  return serializedHeaders;
-}
-
-export function deserializeSuccess<TObject>(response: Response): TObject {
-  try {
-    return JSON.parse(response.content);
-  } catch (e) {
-    throw new DeserializationError((e as Error).message, response);
-  }
-}
-
-export function deserializeFailure({ content, status }: Response, stackFrame: StackFrame[]): Error {
-  try {
-    const parsed = JSON.parse(content);
-    if ('error' in parsed) {
-      return new DetailedApiError(parsed.message, status, parsed.error, stackFrame);
-    }
-    return new ApiError(parsed.message, status, stackFrame);
-  } catch {
-    // ..
-  }
-  return new ApiError(content, status, stackFrame);
-}

package/src/transporter/index.ts

@@ -1,6 +0,0 @@
-export * from './createStatefulHost';
-export * from './createTransporter';
-export * from './errors';
-export * from './helpers';
-export * from './responses';
-export * from './stackTrace';

package/src/transporter/responses.ts

@@ -1,13 +0,0 @@
-import type { Response } from '../types';
-
-export function isNetworkError({ isTimedOut, status }: Omit<Response, 'content'>): boolean {
-  return !isTimedOut && ~~status === 0;
-}
-
-export function isRetryable({ isTimedOut, status }: Omit<Response, 'content'>): boolean {
-  return isTimedOut || isNetworkError({ isTimedOut, status }) || (~~(status / 100) !== 2 && ~~(status / 100) !== 4);
-}
-
-export function isSuccess({ status }: Pick<Response, 'status'>): boolean {
-  return ~~(status / 100) === 2;
-}

package/src/transporter/stackTrace.ts

@@ -1,22 +0,0 @@
-import type { Headers, StackFrame } from '../types';
-
-export function stackTraceWithoutCredentials(stackTrace: StackFrame[]): StackFrame[] {
-  return stackTrace.map((stackFrame) => stackFrameWithoutCredentials(stackFrame));
-}
-
-export function stackFrameWithoutCredentials(stackFrame: StackFrame): StackFrame {
-  const modifiedHeaders: Headers = stackFrame.request.headers['x-algolia-api-key']
-    ? { 'x-algolia-api-key': '*****' }
-    : {};
-
-  return {
-    ...stackFrame,
-    request: {
-      ...stackFrame.request,
-      headers: {
-        ...stackFrame.request.headers,
-        ...modifiedHeaders,
-      },
-    },
-  };
-}

package/src/types/cache.ts

@@ -1,75 +0,0 @@
-export type Cache = {
-  /**
-   * Gets the value of the given `key`.
-   */
-  get: <TValue>(
-    key: Record<string, any> | string,
-    defaultValue: () => Promise<TValue>,
-    events?: CacheEvents<TValue>,
-  ) => Promise<TValue>;
-
-  /**
-   * Sets the given value with the given `key`.
-   */
-  set: <TValue>(key: Record<string, any> | string, value: TValue) => Promise<TValue>;
-
-  /**
-   * Deletes the given `key`.
-   */
-  delete: (key: Record<string, any> | string) => Promise<void>;
-
-  /**
-   * Clears the cache.
-   */
-  clear: () => Promise<void>;
-};
-
-export type CacheEvents<TValue> = {
-  /**
-   * The callback when the given `key` is missing from the cache.
-   */
-  miss: (value: TValue) => Promise<any>;
-};
-
-export type MemoryCacheOptions = {
-  /**
-   * If keys and values should be serialized using `JSON.stringify`.
-   */
-  serializable?: boolean;
-};
-
-export type BrowserLocalStorageOptions = {
-  /**
-   * The cache key.
-   */
-  key: string;
-
-  /**
-   * The time to live for each cached item in seconds.
-   */
-  timeToLive?: number;
-
-  /**
-   * The native local storage implementation.
-   */
-  localStorage?: Storage;
-};
-
-export type BrowserLocalStorageCacheItem = {
-  /**
-   * The cache item creation timestamp.
-   */
-  timestamp: number;
-
-  /**
-   * The cache item value.
-   */
-  value: any;
-};
-
-export type FallbackableCacheOptions = {
-  /**
-   * List of caches order by priority.
-   */
-  caches: Cache[];
-};

package/src/types/createClient.ts

@@ -1,15 +0,0 @@
-import type { AlgoliaAgentOptions, TransporterOptions } from './transporter';
-
-export type AuthMode = 'WithinHeaders' | 'WithinQueryParameters';
-
-type OverriddenTransporterOptions = 'baseHeaders' | 'baseQueryParameters' | 'hosts';
-
-export type CreateClientOptions = Omit<TransporterOptions, OverriddenTransporterOptions | 'algoliaAgent'> &
-  Partial<Pick<TransporterOptions, OverriddenTransporterOptions>> & {
-    appId: string;
-    apiKey: string;
-    authMode?: AuthMode;
-    algoliaAgents: AlgoliaAgentOptions[];
-  };
-
-export type ClientOptions = Partial<Omit<CreateClientOptions, 'apiKey' | 'appId'>>;

package/src/types/createIterablePromise.ts

@@ -1,40 +0,0 @@
-export type IterableOptions<TResponse> = Partial<{
-  /**
-   * The function that runs right after the API call has been resolved, allows you to do anything with the response before `validate`.
-   */
-  aggregator: (response: TResponse) => void;
-
-  /**
-   * The `validate` condition to throw an error and its message.
-   */
-  error: {
-    /**
-     * The function to validate the error condition.
-     */
-    validate: (response: TResponse) => boolean;
-
-    /**
-     * The error message to throw.
-     */
-    message: (response: TResponse) => string;
-  };
-
-  /**
-   * The function to decide how long to wait between iterations.
-   */
-  timeout: () => number;
-}>;
-
-export type CreateIterablePromise<TResponse> = IterableOptions<TResponse> & {
-  /**
-   * The function to run, which returns a promise.
-   *
-   * The `previousResponse` parameter (`undefined` on the first call) allows you to build your request with incremental logic, to iterate on `page` or `cursor` for example.
-   */
-  func: (previousResponse?: TResponse) => Promise<TResponse>;
-
-  /**
-   * The validator function. It receive the resolved return of the API call.
-   */
-  validate: (response: TResponse) => boolean;
-};