@algolia/client-common 4.14.2 → 5.0.0-alpha.3

package/src/transporter/errors.ts

@@ -0,0 +1,51 @@
+import type { Response, StackFrame } from '../types';
+
+export class AlgoliaError extends Error {
+  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, contact support@algolia.com.',
+      stackTrace,
+      'RetryError'
+    );
+  }
+}
+
+export class ApiError extends ErrorWithStackTrace {
+  status: number;
+
+  constructor(message: string, status: number, stackTrace: StackFrame[]) {
+    super(message, stackTrace, 'ApiError');
+    this.status = status;
+  }
+}
+
+export class DeserializationError extends AlgoliaError {
+  response: Response;
+
+  constructor(message: string, response: Response) {
+    super(message, 'DeserializationError');
+    this.response = response;
+  }
+}

package/src/transporter/helpers.ts

@@ -0,0 +1,119 @@
+import type {
+  Headers,
+  Host,
+  QueryParameters,
+  Request,
+  RequestOptions,
+  Response,
+  StackFrame,
+} from '../types';
+
+import { ApiError, DeserializationError } 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}/${
+    path.charAt(0) === '/' ? path.substr(1) : path
+  }`;
+
+  if (queryParametersAsString.length) {
+    url += `?${queryParametersAsString}`;
+  }
+
+  return url;
+}
+
+export function serializeQueryParameters(parameters: QueryParameters): string {
+  const isObjectOrArray = (value: any): boolean =>
+    Object.prototype.toString.call(value) === '[object Object]' ||
+    Object.prototype.toString.call(value) === '[object Array]';
+
+  return Object.keys(parameters)
+    .map(
+      (key) =>
+        `${key}=${
+          isObjectOrArray(parameters[key])
+            ? JSON.stringify(parameters[key])
+            : parameters[key]
+        }`
+    )
+    .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 {
+  let message = content;
+  try {
+    message = JSON.parse(content).message;
+  } catch (e) {
+    // ..
+  }
+  return new ApiError(message, status, stackFrame);
+}

package/src/transporter/index.ts

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

package/src/transporter/responses.ts

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,61 @@
+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 native local storage implementation.
+   */
+  localStorage?: Storage;
+};
+
+export type FallbackableCacheOptions = {
+  /**
+   * List of caches order by priority.
+   */
+  caches: Cache[];
+};

package/src/types/CreateClient.ts

@@ -0,0 +1,23 @@
+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/CreateRetryablePromise.ts

@@ -0,0 +1,21 @@
+export type CreateRetryablePromiseOptions<TResponse> = {
+  /**
+   * The function to run, which returns a promise.
+   */
+  func: () => Promise<TResponse>;
+
+  /**
+   * The validator function. It receives the resolved return of `func`.
+   */
+  validate: (response: TResponse) => boolean;
+
+  /**
+   * The maximum number of retry. 50 by default.
+   */
+  maxRetries?: number;
+
+  /**
+   * The function to decide how long to wait between retries.
+   */
+  timeout?: (retryCount: number) => number;
+};

package/src/types/Host.ts

@@ -0,0 +1,38 @@
+export type Host = {
+  /**
+   * The host URL.
+   */
+  url: string;
+
+  /**
+   * The accepted transporter.
+   */
+  accept: 'read' | 'readWrite' | 'write';
+
+  /**
+   * The protocol of the host URL.
+   */
+  protocol: 'http' | 'https';
+};
+
+export type StatefulHost = Host & {
+  /**
+   * The status of the host.
+   */
+  status: 'down' | 'timed out' | 'up';
+
+  /**
+   * The last update of the host status, used to compare with the expiration delay.
+   */
+  lastUpdate: number;
+
+  /**
+   * Returns whether the host is up or not.
+   */
+  isUp: () => boolean;
+
+  /**
+   * Returns whether the host is timed out or not.
+   */
+  isTimedOut: () => boolean;
+};

package/src/types/Requester.ts

@@ -0,0 +1,72 @@
+import type { Headers, QueryParameters } from './Transporter';
+
+/**
+ * The method of the request.
+ */
+export type Method = 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+
+export type Request = {
+  method: Method;
+  /**
+   * The path of the REST API to send the request to.
+   */
+  path: string;
+  queryParameters: QueryParameters;
+  data?: Array<Record<string, any>> | Record<string, any>;
+  headers: Headers;
+  /**
+   * If the given request should persist on the cache. Keep in mind,
+   * that some methods may have this option enabled by default.
+   */
+  cacheable?: boolean;
+  /**
+   * Some POST methods in the Algolia REST API uses the `read` transporter.
+   * This information is defined at the spec level.
+   */
+  useReadTransporter?: boolean;
+};
+
+export type EndRequest = Pick<Request, 'headers' | 'method'> & {
+  /**
+   * The full URL of the REST API.
+   */
+  url: string;
+  /**
+   * The connection timeout, in milliseconds.
+   */
+  connectTimeout: number;
+  /**
+   * The response timeout, in milliseconds.
+   */
+  responseTimeout: number;
+  data?: string;
+};
+
+export type Response = {
+  /**
+   * The body of the response.
+   */
+  content: string;
+  /**
+   * Whether the API call is timed out or not.
+   */
+  isTimedOut: boolean;
+  /**
+   * The HTTP status code of the response.
+   */
+  status: number;
+};
+
+export type Requester = {
+  /**
+   * Sends the given `request` to the server.
+   */
+  send: (request: EndRequest) => Promise<Response>;
+};
+
+export type EchoResponse = Omit<EndRequest, 'data'> &
+  Pick<Request, 'data' | 'path'> & {
+    host: string;
+    algoliaAgent: string;
+    searchParams?: Record<string, string>;
+  };

package/src/types/Transporter.ts

@@ -0,0 +1,153 @@
+import type { Cache } from './Cache';
+import type { Host } from './Host';
+import type { Request, Requester, EndRequest, Response } from './Requester';
+
+export type Headers = Record<string, string>;
+export type QueryParameters = Record<string, any>;
+
+export type RequestOptions = Pick<Request, 'cacheable'> & {
+  /**
+   * Custom timeout for the request. Note that, in normal situations
+   * the given timeout will be applied. But the transporter layer may
+   * increase this timeout if there is need for it.
+   */
+  timeout?: number;
+
+  /**
+   * Custom headers for the request. This headers are
+   * going to be merged the transporter headers.
+   */
+  headers?: Headers;
+
+  /**
+   * Custom query parameters for the request. This query parameters are
+   * going to be merged the transporter query parameters.
+   */
+  queryParameters?: QueryParameters;
+
+  /**
+   * Custom data for the request. This data is
+   * going to be merged the transporter data.
+   */
+  data?: Array<Record<string, any>> | Record<string, any>;
+};
+
+export type StackFrame = {
+  request: EndRequest;
+  response: Response;
+  host: Host;
+  triesLeft: number;
+};
+
+export type AlgoliaAgentOptions = {
+  /**
+   * The segment. Usually the integration name.
+   */
+  segment: string;
+
+  /**
+   * The version. Usually the integration version.
+   */
+  version?: string;
+};
+
+export type AlgoliaAgent = {
+  /**
+   * The raw value of the user agent.
+   */
+  value: string;
+
+  /**
+   * Mutates the current user agent adding the given user agent options.
+   */
+  add: (options: AlgoliaAgentOptions) => AlgoliaAgent;
+};
+
+export type Timeouts = {
+  /**
+   * Timeout in milliseconds before the connection is established.
+   */
+  connect: number;
+
+  /**
+   * Timeout in milliseconds before reading the response on a read request.
+   */
+  read: number;
+
+  /**
+   * Timeout in milliseconds before reading the response on a write request.
+   */
+  write: number;
+};
+
+export type TransporterOptions = {
+  /**
+   * The cache of the hosts. Usually used to persist
+   * the state of the host when its down.
+   */
+  hostsCache: Cache;
+
+  /**
+   * The underlying requester used. Should differ
+   * depending of the environment where the client
+   * will be used.
+   */
+  requester: Requester;
+
+  /**
+   * The cache of the requests. When requests are
+   * `cacheable`, the returned promised persists
+   * in this cache to shared in similar requests
+   * before being resolved.
+   */
+  requestsCache: Cache;
+
+  /**
+   * The cache of the responses. When requests are
+   * `cacheable`, the returned responses persists
+   * in this cache to shared in similar requests.
+   */
+  responsesCache: Cache;
+
+  /**
+   * The timeouts used by the requester. The transporter
+   * layer may increase this timeouts as defined on the
+   * retry strategy.
+   */
+  timeouts: Timeouts;
+
+  /**
+   * The hosts used by the requester.
+   */
+  hosts: Host[];
+
+  /**
+   * The headers used by the requester. The transporter
+   * layer may add some extra headers during the request
+   * for the user agent, and others.
+   */
+  baseHeaders: Headers;
+
+  /**
+   * The query parameters used by the requester. The transporter
+   * layer may add some extra headers during the request
+   * for the user agent, and others.
+   */
+  baseQueryParameters: QueryParameters;
+
+  /**
+   * The user agent used. Sent on query parameters.
+   */
+  algoliaAgent: AlgoliaAgent;
+};
+
+export type Transporter = TransporterOptions & {
+  /**
+   * Performs a request.
+   * The `baseRequest` and `baseRequestOptions` will be merged accordingly.
+   */
+  request: <TResponse>(
+    baseRequest: Request,
+    baseRequestOptions?: RequestOptions
+  ) => Promise<TResponse>;
+};

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './Cache';
+export * from './CreateClient';
+export * from './CreateRetryablePromise';
+export * from './Host';
+export * from './Requester';
+export * from './Transporter';