@torthu/jacketui-bring 0.0.1

package/src/errors/ClientError.ts

@@ -0,0 +1,24 @@
+import { BringError } from "./BringError";
+
+export class ClientError extends BringError {
+  tag = "ClientError";
+}
+
+/** isClientError
+ *
+ * Checks if error is ClientError.
+ * A ClientError is either an instance of ClientError or a BringError with a status code between 400 and 499.
+ *
+ */
+export const isClientError = (error: unknown): error is ClientError => {
+  if (error instanceof ClientError) {
+    return true;
+  }
+
+  return (
+    error instanceof BringError &&
+    !!error.response &&
+    error.response.status >= 400 &&
+    error.response.status < 500
+  );
+};

package/src/errors/NetworkError.ts

@@ -0,0 +1,23 @@
+import { BringError } from "./BringError";
+
+export class NetworkError extends BringError {
+  tag = "NetworkError";
+}
+
+/** isNetworkError
+ *
+ * Checks if error is NetworkError.
+ * A NetworkError is either an instance of NetworkError or a BringError with status code 0.
+ *
+ */
+export const isNetworkError = (error: unknown): error is NetworkError => {
+  if (error instanceof NetworkError) {
+    return true;
+  }
+
+  return (
+    error instanceof BringError &&
+    !!error.response &&
+    error.response.status === 0
+  );
+};

package/src/errors/ServerError.ts

@@ -0,0 +1,24 @@
+import { BringError } from "./BringError";
+
+export class ServerError extends BringError {
+  tag = "ServerError";
+}
+
+/** isServerError
+ *
+ * Checks if error is ServerError.
+ * A ServerError is either an instance of ServerError or a BringError with status code >= 500 and < 600.
+ *
+ */
+export const isServerError = (error: unknown): error is ServerError => {
+  if (error instanceof ServerError) {
+    return true;
+  }
+
+  return (
+    error instanceof BringError &&
+    !!error.response &&
+    error.response.status >= 500 &&
+    error.response.status < 600
+  );
+};

package/src/errors/TimeoutError.ts

@@ -0,0 +1,18 @@
+import { BringError } from "./BringError";
+
+export class TimeoutError extends BringError {
+  tag = "TimeoutError";
+}
+
+/** isTimeoutError
+ *
+ * Checks if error is TimeoutError.
+ * A TimeoutError is either an instance of TimeoutError or a BringError with tag "TimeoutError".
+ *
+ */
+export const isTimeoutError = (error: unknown): error is TimeoutError => {
+  return (
+    error instanceof TimeoutError ||
+    (error instanceof BringError && error.tag === "TimeoutError")
+  );
+};

package/src/errors/index.ts

@@ -0,0 +1,6 @@
+export * from "./AbortError";
+export * from "./ClientError";
+export * from "./BringError";
+export * from "./NetworkError";
+export * from "./ServerError";
+export * from "./TimeoutError";

package/src/fetch.ts

@@ -0,0 +1,34 @@
+import { bring } from "./bring";
+import { BringInit } from "./types/BringInit";
+
+/** fetch(url: string, init?: Omit<BringInit, "url">): AbortablePromise<Result<Response, BringError>>
+ *
+ * Wraps bring in a fetch-like API.
+ * This is a convenience function for bring.
+ *
+ * Some caveats:
+ * - BringInit expects and AbortController instead of a signal.
+ * - The first argument cannot be a Request object.
+ *
+ * @note This is not a drop-in replacement for the Fetch API.
+ *
+ * @note bring does not throw errors, but will return a Result.
+ *
+ * @example
+ *   const result = await fetch("https://example.com", { method: "GET" });
+ *   if (result.ok) {
+ *     const data = await result.value.json();
+ *     console.log(data);
+ *   } else {
+ *     console.error(result.error);
+ *   }
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ *
+ * @param url string | URL - The URL to fetch.
+ * @param init BringInit - extends RequestInit from the Fetch API.
+ * @returns AbortablePromise<Result<Response, BringError>> - A promise that resolves to a Result object containing either a Response or a BringError.
+ */
+export const fetch = (url: string | URL, init?: Omit<BringInit, "url">) => {
+  return bring({ url, ...init });
+};

package/src/helpers/exponentialBackoff.ts

@@ -0,0 +1,28 @@
+export interface BackoffOptions {
+  base?: number;
+  factor?: number;
+  max?: number;
+  min?: number;
+}
+
+/** backoff(retryNum: number): number
+ *
+ * Backoff is the time to wait before retrying a request. It is calculated using an exponential backoff algorithm.
+ *
+ *  The formula is: base * factor^(retryNum - 1)
+ *
+ * @param retryNum The number of times the request has been retried
+ * @param options
+ * @param options.base Base backoff time in milliseconds
+ * @param options.factor Multiplier for the backoff time
+ * @param options.max Maximum backoff time in milliseconds
+ * @param options.min Minimum backoff time in milliseconds
+ * @returns number
+ */
+export const exponentialBackoff = (
+  retryNum: number,
+  { base = 500, factor = 1.5, max = 10000, min = 500 }: BackoffOptions = {}
+): number => {
+  const calculatedBackoff = base * Math.pow(factor, retryNum - 1);
+  return Math.min(Math.max(calculatedBackoff, min), max);
+};

package/src/helpers/extractCallbacks.ts

@@ -0,0 +1,23 @@
+import { BringCallbacks, BringInit } from "../types/BringInit";
+
+export const extractCallbacks = (init: BringInit): BringCallbacks => {
+  const {
+    onSuccess,
+    onError,
+    onAbort,
+    onRetry,
+    onTimeout,
+    onClientError,
+    onServerError,
+  } = init;
+
+  return {
+    onSuccess,
+    onError,
+    onAbort,
+    onRetry,
+    onTimeout,
+    onClientError,
+    onServerError,
+  };
+};

package/src/helpers/extractRequestInit.ts

@@ -0,0 +1,30 @@
+import { BringInit, RequestInit } from "../types/BringInit";
+
+export const extractRequestInit = (init: BringInit): RequestInit => {
+  const {
+    method,
+    headers,
+    body,
+    mode,
+    credentials,
+    cache,
+    redirect,
+    referrer,
+    referrerPolicy,
+    integrity,
+    keepalive,
+  } = init;
+  return {
+    method,
+    headers,
+    body,
+    mode,
+    credentials,
+    cache,
+    redirect,
+    referrer,
+    referrerPolicy,
+    integrity,
+    keepalive,
+  };
+};

package/src/helpers/randomJitter.ts

@@ -0,0 +1,22 @@
+export interface JitterOptions {
+  min?: number;
+  max?: number;
+}
+
+/** jitter(backoff: number): number
+ *
+ *  Jitter is a random value added to the backoff time to prevent a thundering herd problem (when multiple clients retry at the same time).
+ *
+ * @param backoff The backoff time in milliseconds
+ * @param options
+ * @param options.min (default 0) Minimum jitter time in milliseconds
+ * @param options.max (default 100) Maximum jitter time in milliseconds
+ * @returns number
+ */
+export const randomJitter = ({
+  min = 0,
+  max = 100,
+}: JitterOptions = {}): number => {
+  const jitter = Math.random() * max;
+  return jitter < min ? min : jitter;
+};

package/src/helpers/shouldRetry.ts

@@ -0,0 +1,40 @@
+import { Failure } from "@torthu/jacketui-core";
+import { BringError } from "../errors";
+
+const defaultRetryStatuses = [0, 408, 425, 429, 500, 502, 503, 504];
+
+interface RetryOptions {
+  retryStatuses?: number[];
+}
+
+/** shouldRetry(failure: Failure<BringError>, options?: RetryOptions): boolean
+ *
+ * Determines if a request should be retried based on the failure and options.
+ * By default, it retries on 0, 408, 425, 429, 500, 502, 503, and 504 status codes.
+ *
+ * Additionally if there is no response (i.e the request failed before a response was received),
+ * it will retry.
+ *
+ * You can override this behavior by passing a custom `retryStatuses` array.
+ *
+ * @param failure Failure<BringError>
+ * @param options RetryOptions
+ * @param options.retryStatuses Array of status codes to retry on
+ * @returns boolean
+ */
+export const shouldRetry = (
+  failure: Failure<BringError>,
+  { retryStatuses = defaultRetryStatuses }: RetryOptions = {}
+): boolean => {
+  const error = failure.error;
+
+  if (error.response) {
+    if (retryStatuses.includes(error.response.status)) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  return true;
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./bring";
+export * from "./tryFetch";
+export * from "./errors";
+export * from "./pipe-helpers";

package/src/pipe-helpers/backoff.ts

@@ -0,0 +1,22 @@
+import {
+  BackoffOptions,
+  exponentialBackoff,
+} from "../helpers/exponentialBackoff";
+import { BringInitDecorator } from "../types/BringDecorator";
+
+/** backoff(options?: BackoffOptions): BringInitDecorator
+ *
+ * Sets a exponential backoff function for retrying requests.
+ *
+ * @param options (optional) Backoff options
+ * @param options.base Base backoff time in milliseconds
+ * @param options.factor Multiplier for the backoff time
+ * @param options.max Maximum backoff time in milliseconds
+ * @param options.min Minimum backoff time in milliseconds
+ * @returns BringInitDecorator
+ */
+export const backoff = (options?: BackoffOptions): BringInitDecorator => {
+  const backoffFun = (retryNum: number) =>
+    exponentialBackoff(retryNum, options);
+  return (init) => ({ ...init, backoff: backoffFun });
+};

package/src/pipe-helpers/body.ts

@@ -0,0 +1,17 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** body(body): BringInitDecorator
+ *
+ * Sets the body of the request.
+ *
+ * @note This is a low-level helper. For JSON bodies, use `jsonBody` instead or manually JSON.stringify first.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#body
+ *
+ * @param body
+ * @returns BringInitDecorator
+ */
+export const body =
+  (body: BringInit["body"]): BringInitDecorator =>
+  (init) => ({ ...init, body });

package/src/pipe-helpers/cache.ts

@@ -0,0 +1,23 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** cache(cacheMode): BringInitDecorator
+ *
+ * Sets the cache mode for the request.
+ * Possible values are "default", "no-store", "reload", "no-cache", "force-cache", and "only-if-cached".
+ * The default value is "default".
+ *
+ * @example
+ *   const customGet = (url: string) => pipe(cache("no-cache"), method("GET"), bring)({ url })
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/cache
+ *
+ * @param cacheMode - The cache mode to use for the request. "default", "no-store", "reload", "no-cache", "force-cache", and "only-if-cached"
+ * @returns BringInitDecorator
+ */
+export const cache =
+  (cacheMode: BringInit["cache"] = "default"): BringInitDecorator =>
+  (init) => {
+    init.cache = cacheMode;
+    return init;
+  };

package/src/pipe-helpers/cors.ts

@@ -0,0 +1,39 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** cors(corsMode): BringInitDecorator
+ *
+ * Sets the CORS mode for the request.
+ *
+ * The default value is "cors".
+ *
+ * Possible values are: "cors", "no-cors", "same-origin".
+ * - "cors": CORS mode is enabled. This is the default value.
+ * - "no-cors": CORS mode is disabled.
+ * - "same-origin": CORS mode is enabled only for same-origin requests.
+ *
+ * An origin is the combination of protocol, host, and port.
+ * The path is not included in the origin.
+ *
+ * For example,
+ * - https://example.com is an origin.
+ * - https://example.com/path is the same origin.
+ * - https://example.com:8080 is a different origin.
+ * - https://sub.example.com/path is a different origin.
+ * - http://example.com is a different origin.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/mode
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+ *
+ * @example
+ *   const customGet = (url: string) => pipe(cors("no-cors"), method("GET"), bring)({ url }
+ *
+ * @param corsMode - The mode to use for the request. "cors", "no-cors", "same-origin" (default: "cors").
+ * @returns BringInitDecorator
+ */
+export const cors =
+  (corsMode: BringInit["mode"] = "cors"): BringInitDecorator =>
+  (init) => {
+    init.mode = corsMode;
+    return init;
+  };

package/src/pipe-helpers/credentials.ts

@@ -0,0 +1,33 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** credentials(credentialsMode): BringInitDecorator
+ *
+ * Sets the credentials mode for the request.
+ *
+ * Credentials are cookies, TLS client certificates, or authentication headers containing a username and password.
+ *
+ * Possible values are:
+ * - "omit": Never send cookies.
+ * - "same-origin": Send cookies only if the URL is on the same origin as the calling script. This is the default value.
+ * - "include": Always send cookies, even for cross-origin calls.
+ *
+ * The default value is "same-origin".
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials
+ *
+ * @example
+ *   const customGet = (url: string) => pipe(credentials("include"), method("GET"), bring)({ url })
+ *
+ * @param credentialsMode
+ * @returns
+ */
+export const credentials =
+  (
+    credentialsMode: BringInit["credentials"] = "same-origin"
+  ): BringInitDecorator =>
+  (init) => {
+    init.credentials = credentialsMode;
+    return init;
+  };

package/src/pipe-helpers/header.ts

@@ -0,0 +1,28 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+
+/** header(key: string, val: string): BringInitDecorator
+ *
+ * Sets a header on the request.
+ * If the header already exists, it will be overwritten.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Headers
+ *
+ * @param key The name of the header to set.
+ * @param val The value of the header to set.
+ * @returns BringDecorator
+ */
+export const header = (key: string, val: string): BringInitDecorator => {
+  return (init) => {
+    init.headers ??= new Headers();
+
+    if (init.headers instanceof Headers) {
+      !init.headers.has(key)
+        ? init.headers.append(key, val)
+        : init.headers.set(key, val);
+    } else {
+      init.headers[key] = val;
+    }
+
+    return init;
+  };
+};

package/src/pipe-helpers/index.ts

@@ -0,0 +1,18 @@
+export * from "./cache";
+export * from "./cors";
+export * from "./credentials";
+export * from "./header";
+export * from "./integrity";
+export * from "./keepalive";
+export * from "./method";
+export * from "./redirect";
+export * from "./referrer";
+export * from "./referrerPolicy";
+export * from "./retry";
+export * from "./body";
+export * from "./jsonBody";
+export * from "./priority";
+
+export * from "./backoff";
+export * from "./jitter";
+export * from "./timeout";

package/src/pipe-helpers/integrity.ts

@@ -0,0 +1,23 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** integrity(integrityMode): BringInitDecorator
+ *
+ * Sets the integrity mode of the request.
+ *
+ * The format of this option is <hash-algo>-<hash-source> where:
+ * - <hash-algo> is one of the following values: sha256, sha384, or sha512
+ * - <hash-source> is the Base64-encoding of the result of hashing the resource with the specified hash algorithm.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#integrity
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/integrity
+ *
+ * @param integrityMode
+ * @returns BringDecorator
+ */
+export const integrity =
+  (integrityMode: BringInit["integrity"] = ""): BringInitDecorator =>
+  (init) => {
+    init.integrity = integrityMode;
+    return init;
+  };

package/src/pipe-helpers/jitter.ts

@@ -0,0 +1,17 @@
+import { JitterOptions, randomJitter } from "../helpers/randomJitter";
+import { BringInitDecorator } from "../types/BringDecorator";
+
+/** jitter(options?: JitterOptions): BringInitDecorator
+ *
+ * Sets a jitter function for retrying requests.
+ * Jitter is a random value added to the backoff time to prevent a thundering herd problem (when multiple clients retry at the same time).
+ *
+ * @param options (optional) Jitter options
+ * @param options.max (default 100) Maximum jitter time in milliseconds
+ * @param options.min (default 0) Minimum jitter time in milliseconds
+ * @returns BringInitDecorator
+ */
+export const jitter = (options?: JitterOptions): BringInitDecorator => {
+  const jitterFun = () => randomJitter(options);
+  return (init) => ({ ...init, backoff: jitterFun });
+};

package/src/pipe-helpers/jsonBody.ts

@@ -0,0 +1,13 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** jsonBody(body: BringInit["body"]): BringInitDecorator
+ *
+ * Sets the body of the request to a JSON string.
+ *
+ * @param body Any JSON serializable value
+ * @returns BringInitDecorator
+ */
+export const jsonBody =
+  (body: BringInit["body"]): BringInitDecorator =>
+  (init) => ({ ...init, body: JSON.stringify(body) });

package/src/pipe-helpers/keepalive.ts

@@ -0,0 +1,21 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** keepalive(boolean): BringInitDecorator
+ *
+ * Sets the keepalive mode of the request.
+ *
+ * If set to true, the request will be kept alive until the browser is closed.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#keepalive
+ *
+ * @param keepaliveMode
+ * @returns
+ */
+export const keepalive =
+  (keepaliveMode: BringInit["keepalive"] = false): BringInitDecorator =>
+  (init) => {
+    init.keepalive = keepaliveMode;
+    return init;
+  };

package/src/pipe-helpers/method.ts

@@ -0,0 +1,18 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** method(string): BringInitDecorator
+ *
+ * Sets the HTTP method of the request.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/method
+ *
+ * @param method - The HTTP method to use for the request.
+ * @returns BringDecorator
+ */
+export const method =
+  (method: BringInit["method"] = "GET"): BringInitDecorator =>
+  (init) => ({
+    ...init,
+    method,
+  });

package/src/pipe-helpers/priority.ts

@@ -0,0 +1,20 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** priority("auto" | "high" | "low"): BringInitDecorator
+ *
+ * The priority of the request relative to other requests of the same type.
+ *
+ * Possible values are:
+ * - "auto" (default) No user preference for the fetch priority
+ * - "high" A high priority fetch request relative to other requests of the same type.
+ * - "low" A low priority fetch request relative to other requests of the same type.
+ *
+ * @param priorityMode "auto" | "high" | "low
+ * @returns BringInitDecorator
+ */
+export const priority = (
+  priorityMode: BringInit["priority"] = "auto"
+): BringInitDecorator => {
+  return (init) => ({ ...init, priority: priorityMode });
+};

package/src/pipe-helpers/redirect.ts

@@ -0,0 +1,23 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** redirect(string): BringInitDecorator
+ *
+ * Sets the redirect mode of the request.
+ *
+ * Possible values are:
+ * - "follow": Automatically follow redirects. This is the default value.
+ * - "error": Abort with an error if a redirect occurs.
+ * - "manual": Handle redirects manually.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/redirect
+ *
+ * @param redirectMode - The redirect mode to use. "follow" | "error" | "manual". Defaults to "follow".
+ * @returns BringIntDecorator
+ */
+export const redirect =
+  (redirectMode: BringInit["redirect"] = "follow"): BringInitDecorator =>
+  (init) => {
+    init.redirect = redirectMode;
+    return init;
+  };

package/src/pipe-helpers/referrer.ts

@@ -0,0 +1,21 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** referrer(string): BringInitDecorator
+ *
+ * A string specifying the value to use for the request's Referer header. One of the following:
+ * - A same-origin relative or absolute URL
+ * - An empty string, which indicates that no Referer header should be sent
+ * - "about:client" (default) set the Referer header to the default value for the context of the request (for example, the URL of the page that made the request).
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#referrer
+ *
+ * @param referrerMode
+ * @returns
+ */
+export const referrer =
+  (referrerMode: BringInit["referrer"] = "about:client"): BringInitDecorator =>
+  (init) => {
+    init.referrer = referrerMode;
+    return init;
+  };