@torthu/jacketui-bring 0.0.1

package/dist/pipe-helpers/timeout.d.ts

@@ -0,0 +1,16 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+/** timeout(number): BringInitDecorator
+ *
+ * Sets in-flight timeout for request.
+ * Used to configure AbortSignal.timeout().
+ *
+ * If retry is set, timeout will be applied to each retry.
+ * Total time for request will be (timeout + jitter + backoff) * retry.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static
+ *
+ * @param timeout The time to wait before aborting the request.
+ * @returns BringInitDecorator
+ */
+export declare const timeout: (timeout: BringInit["timeout"]) => BringInitDecorator;

package/dist/pipe-helpers/timeout.js

@@ -0,0 +1,14 @@
+/** timeout(number): BringInitDecorator
+ *
+ * Sets in-flight timeout for request.
+ * Used to configure AbortSignal.timeout().
+ *
+ * If retry is set, timeout will be applied to each retry.
+ * Total time for request will be (timeout + jitter + backoff) * retry.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static
+ *
+ * @param timeout The time to wait before aborting the request.
+ * @returns BringInitDecorator
+ */
+export const timeout = (timeout) => (init) => ({ ...init, timeout });

package/dist/tryFetch.d.ts

@@ -0,0 +1,3 @@
+import { JuiError, Result } from "@torthu/jacketui-core";
+import { BringInit } from "./types/BringInit";
+export declare const tryFetch: (url: string | URL, requestInit: RequestInit, init: BringInit, retryCount?: number) => Promise<Result<Response, JuiError>>;

package/dist/tryFetch.js

@@ -0,0 +1,19 @@
+import { failure, sleep, success, tryAwait, } from "@torthu/jacketui-core";
+export const tryFetch = async (url, requestInit, init, retryCount = 0) => {
+    const { error, value } = await tryAwait(fetch(url, requestInit));
+    if (error && retryCount < (init.retry ?? 0)) {
+        init.onRetry?.(retryCount);
+        const backoff = init.backoff?.(retryCount) ?? 0;
+        const jitter = init.jitter?.() ?? 0;
+        if (backoff + jitter > 0) {
+            await sleep(backoff + jitter);
+        }
+        return await tryFetch(url, requestInit, init, retryCount + 1);
+    }
+    else if (error) {
+        return failure(error);
+    }
+    else {
+        return success(value);
+    }
+};

package/dist/types/BringDecorator.d.ts

@@ -0,0 +1,4 @@
+import { BringInit } from "./BringInit";
+export interface BringInitDecorator {
+    (init: BringInit): BringInit;
+}

package/dist/types/BringDecorator.js

@@ -0,0 +1 @@
+export {};

package/dist/types/BringInit.d.ts

@@ -0,0 +1,37 @@
+import { AbortError, BringError, TimeoutError } from "../errors";
+type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export interface BringCallbacks {
+    onAbort?: (error: AbortError) => void;
+    onError?: (error: BringError) => void;
+    onRetry?: (retryNum: number) => void;
+    onSuccess?: (response: Response) => void;
+    onTimeout?: (error: TimeoutError) => void;
+    onClientError?: (response: Response) => void;
+    onServerError?: (response: Response) => void;
+}
+export interface RequestInit {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+    body?: string | ArrayBuffer | Blob | DataView | File | FormData | TypedArray | URLSearchParams | ReadableStream;
+    cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached";
+    credentials?: "omit" | "same-origin" | "include";
+    headers?: Record<string, string> | Headers;
+    integrity?: string;
+    keepalive?: boolean;
+    mode?: "cors" | "no-cors" | "same-origin";
+    priority?: "low" | "high" | "auto";
+    redirect?: "follow" | "error" | "manual";
+    referrer?: string | "" | "about:client";
+    referrerPolicy?: "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url";
+}
+export interface RetryBackoff {
+    retry?: number;
+    timeout?: number;
+    shouldRetry?: (response: Response, retryNum: number) => boolean;
+    backoff?: (retryNum: number) => number;
+    jitter?: () => number;
+}
+export type BringInit = RequestInit & RetryBackoff & BringCallbacks & {
+    url: string | URL;
+    abortController?: AbortController;
+};
+export {};

package/dist/types/BringInit.js

@@ -0,0 +1 @@
+export {};

package/dist/types/ClientErrorResponse.d.ts

@@ -0,0 +1,6 @@
+type ClientErrorStatus = 400 | 401 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451;
+export interface ClientErrorResponse extends Response {
+    status: ClientErrorStatus;
+}
+export declare const isClientErrorResponse: (res: Response) => res is ClientErrorResponse;
+export {};

package/dist/types/ClientErrorResponse.js

@@ -0,0 +1,32 @@
+const clientStatusErrorMap = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Entity",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+};
+const clientStatusErrorSet = new Set(Object.keys(clientStatusErrorMap).map((s) => parseInt(s, 10)));
+export const isClientErrorResponse = (res) => clientStatusErrorSet.has(res.status);

package/dist/types/InformationalResponse.d.ts

@@ -0,0 +1,6 @@
+type InformationalResponseStatus = 100 | 101 | 102 | 103;
+export interface InformationalResponse extends Response {
+    status: InformationalResponseStatus;
+}
+export declare const isInformationalResponse: (res: Response) => res is InformationalResponse;
+export {};

package/dist/types/InformationalResponse.js

@@ -0,0 +1,8 @@
+const informationalResponseMap = {
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+};
+const informationalResponseSet = new Set(Object.keys(informationalResponseMap).map((s) => parseInt(s, 10)));
+export const isInformationalResponse = (res) => informationalResponseSet.has(res.status);

package/dist/types/RedirectResponse.d.ts

@@ -0,0 +1,6 @@
+type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+export interface RedirectResponse extends Response {
+    status: RedirectStatus;
+}
+export declare const isRedirectResponse: (res: Response) => res is RedirectResponse;
+export {};

package/dist/types/RedirectResponse.js

@@ -0,0 +1,9 @@
+const redirectMap = {
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+};
+const redirectSet = new Set(Object.keys(redirectMap).map((s) => parseInt(s, 10)));
+export const isRedirectResponse = (res) => redirectSet.has(res.status);

package/dist/types/ServerErrorResponse.d.ts

@@ -0,0 +1,6 @@
+type ServerErrorStatus = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | 520 | 521 | 522 | 523 | 524 | 525 | 526 | 527 | 530;
+export interface ServerErrorResponse extends Response {
+    status: ServerErrorStatus;
+}
+export declare const isServerErrorResponse: (res: Response) => res is ServerErrorResponse;
+export {};

package/dist/types/ServerErrorResponse.js

@@ -0,0 +1,24 @@
+const serverStatusErrorMap = {
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+    520: "Unknown Error",
+    521: "Web Server Is Down",
+    522: "Connection Timed Out",
+    523: "Origin Is Unreachable",
+    524: "A Timeout Occurred",
+    525: "SSL Handshake Failed",
+    526: "Invalid SSL Certificate",
+    527: "Railgun Error",
+    530: "Site Is Frozen",
+};
+const serverStatusErrorSet = new Set(Object.keys(serverStatusErrorMap).map((s) => parseInt(s, 10)));
+export const isServerErrorResponse = (res) => serverStatusErrorSet.has(res.status);

package/dist/types/SuccessResponse.d.ts

@@ -0,0 +1,13 @@
+type KnownSuccessStatus = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226;
+export interface KnownSuccessResponse extends Response {
+    status: KnownSuccessStatus;
+}
+export declare const isKnownSuccessResponse: (res: Response) => res is KnownSuccessResponse;
+export interface UnknownSuccessResponse extends Response {
+    status: number;
+}
+export declare const isUnknownSuccessResponse: (res: Response) => res is UnknownSuccessResponse;
+export type SuccessResponse = KnownSuccessResponse | UnknownSuccessResponse;
+export declare const isSuccessResponse: (res: Response) => res is SuccessResponse;
+export declare const getSuccessStatusText: (res: SuccessResponse) => string;
+export {};

package/dist/types/SuccessResponse.js

@@ -0,0 +1,20 @@
+const knownSuccessStatusMap = {
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+};
+const unknownSuccessStatusText = "Unknown Success";
+const knownSuccessStatusSet = new Set(Object.keys(knownSuccessStatusMap).map((s) => parseInt(s, 10)));
+export const isKnownSuccessResponse = (res) => knownSuccessStatusSet.has(res.status);
+export const isUnknownSuccessResponse = (res) => res.status >= 200 && res.status < 300 && !isKnownSuccessResponse(res);
+export const isSuccessResponse = (res) => res.status >= 200 && res.status < 300;
+export const getSuccessStatusText = (res) => isKnownSuccessResponse(res)
+    ? knownSuccessStatusMap[res.status]
+    : unknownSuccessStatusText;

package/dist/types/statusCodes.d.ts

@@ -0,0 +1,69 @@
+export declare const statusCodes: {
+    100: string;
+    101: string;
+    102: string;
+    103: string;
+    200: string;
+    201: string;
+    202: string;
+    203: string;
+    204: string;
+    205: string;
+    206: string;
+    207: string;
+    208: string;
+    226: string;
+    301: string;
+    302: string;
+    303: string;
+    307: string;
+    308: string;
+    400: string;
+    401: string;
+    403: string;
+    404: string;
+    405: string;
+    406: string;
+    407: string;
+    408: string;
+    409: string;
+    410: string;
+    411: string;
+    412: string;
+    413: string;
+    414: string;
+    415: string;
+    416: string;
+    417: string;
+    418: string;
+    421: string;
+    422: string;
+    423: string;
+    424: string;
+    425: string;
+    426: string;
+    428: string;
+    429: string;
+    431: string;
+    451: string;
+    500: string;
+    501: string;
+    502: string;
+    503: string;
+    504: string;
+    505: string;
+    506: string;
+    507: string;
+    508: string;
+    510: string;
+    511: string;
+    520: string;
+    521: string;
+    522: string;
+    523: string;
+    524: string;
+    525: string;
+    526: string;
+    527: string;
+    530: string;
+};

package/dist/types/statusCodes.js

@@ -0,0 +1,69 @@
+export const statusCodes = {
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Payload Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Entity",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+    520: "Unknown Error",
+    521: "Web Server Is Down",
+    522: "Connection Timed Out",
+    523: "Origin Is Unreachable",
+    524: "A Timeout Occurred",
+    525: "SSL Handshake Failed",
+    526: "Invalid SSL Certificate",
+    527: "Railgun Error",
+    530: "Site Is Frozen",
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@torthu/jacketui-bring",
+  "version": "0.0.1",
+  "description": "Improved fetch API with retry, timeout, and more.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": {
+    "name": "Torstein Thune",
+    "email": "torstein@thune.io",
+    "url": "https://thune.io"
+  },
+  "peerDependencies": {},
+  "devDependencies": {},
+  "dependencies": {
+    "@torthu/jacketui-core": "latest"
+  },
+  "scripts": {
+    "prepublish": "npm run build",
+    "build": "rimraf ./dist && tsc",
+    "test": "vitest run"
+  },
+  "license": "GPL-3.0-only"
+}

package/src/bring.ts

@@ -0,0 +1,198 @@
+import {
+  Result,
+  success,
+  failure,
+  AbortablePromise,
+  withResolvers,
+} from "@torthu/jacketui-core";
+import { isClientErrorResponse } from "./types/ClientErrorResponse";
+import { BringInit } from "./types/BringInit";
+import { isInformationalResponse } from "./types/InformationalResponse";
+import { isRedirectResponse } from "./types/RedirectResponse";
+import { isServerErrorResponse } from "./types/ServerErrorResponse";
+import {
+  AbortError,
+  ClientError,
+  BringError,
+  NetworkError,
+  ServerError,
+  TimeoutError,
+} from "./errors";
+import { tryFetch } from "./tryFetch";
+
+/** bring({url: string | URL})
+ *
+ * A wrapper around the fetch API that adds support for timeouts, retries, and aborts.
+ * It also adds support for custom error handling and success handling.
+ * It returns a promise that resolves to a Result object.
+ * The returned promise is extended with an abort method that can be used to abort the fetch request.
+ *
+ * The Result object contains either a Response object or a BringError.
+ *
+ * @param init {BringInit | BringError} RequestInit + retries, timeout, onSuccess, onError, onAbort, onRetry, onTimeout, onClientError, onServerError
+ * @param init.url The URL to fetch.
+ * @param init.abortController (optional) An AbortController object to abort the fetch request. (default: new AbortController())
+ * @param init.timeout (optional) The timeout in milliseconds. (default: 0)
+ * @param init.retry (optional) The number of times to retry the fetch request. (default: 0)
+ * @param init.onSuccess (optional) A callback function that is called when the fetch request is successful.
+ * @param init.onError (optional) A callback function that is called when the fetch request fails.
+ * @param init.onAbort (optional) A callback function that is called when the fetch request is aborted.
+ * @param init.onRetry (optional) A callback function that is called when the fetch request is retried.
+ * @param init.onTimeout (optional) A callback function that is called when the fetch request times out.
+ * @param init.onClientError (optional) A callback function that is called when the fetch request fails with a client error.
+ * @param init.onServerError (optional) A callback function that is called when the fetch request fails with a server error.
+ * @param init.body (optional) The body of the fetch request.
+ * @param init.headers (optional) The headers of the fetch request.
+ * @param init.method (optional) The method of the fetch request.
+ * @param init.mode (optional) The mode of the fetch request.
+ * @param init.credentials (optional) The credentials of the fetch request.
+ * @param init.cache (optional) The cache of the fetch request.
+ * @param init.redirect (optional) The redirect of the fetch request.
+ * @param init.referrer (optional) The referrer of the fetch request.
+ * @param init.referrerPolicy (optional) The referrerPolicy of the fetch request.
+ * @param init.integrity (optional) The integrity of the fetch request.
+ * @param init.keepalive (optional) The keepalive of the fetch request.
+ * @returns AbortablePromise<Result<Response, BringError>>
+ */
+export const bring = (init: BringInit | BringError) => {
+  if (init instanceof BringError) init = init.requestInit;
+
+  const {
+    url,
+    abortController = new AbortController(),
+    timeout = 0,
+    retry = 0,
+    onSuccess,
+    onError,
+    onAbort,
+    onRetry,
+    onTimeout,
+    onClientError,
+    onServerError,
+    ...requestInit
+  } = init;
+
+  // Configure promise
+  const { promise, resolve } = withResolvers();
+  const abortablePromise = promise as AbortablePromise<
+    Result<Response, BringError>
+  >;
+  abortablePromise.abort = abortController.abort;
+
+  // Configure timeout signal
+  const timeoutSignal = timeout > 0 ? AbortSignal.timeout(timeout) : undefined;
+  const signal = AbortSignal.any(
+    [abortController.signal, timeoutSignal].filter((s) => !!s)
+  );
+
+  tryFetch(
+    url,
+    {
+      ...requestInit,
+      signal,
+    },
+    init,
+    0
+  ).then(({ error, value }) => {
+    if (error) {
+      if (abortController.signal.aborted) {
+        const abortError = new AbortError(abortController.signal.reason, {
+          context: {
+            url: url,
+            method: requestInit.method ?? "GET",
+            reason: abortController.signal.reason,
+          },
+          url,
+          requestInit: init,
+        });
+        resolve(failure(abortError));
+        onAbort?.(abortError);
+        onError?.(abortError);
+        return;
+      }
+      if (timeoutSignal?.aborted) {
+        const error = new TimeoutError("Timeout", {
+          context: { reason: timeoutSignal.reason, timeout },
+          url,
+          requestInit: init,
+        });
+        resolve(failure(error));
+        onTimeout?.(error);
+        onError?.(error);
+        return;
+      }
+
+      if (error instanceof Error) {
+        resolve(
+          failure(
+            new BringError(error.message, {
+              cause: error,
+              context: { url, method: requestInit.method ?? "GET" },
+              url,
+              requestInit: init,
+            })
+          )
+        );
+        return;
+      }
+
+      if (typeof error === "string") {
+        resolve(failure(new BringError(error, { url, requestInit: init })));
+        return;
+      }
+
+      resolve(
+        failure(new BringError("Unknown error", { url, requestInit: init }))
+      );
+    } else {
+      const response = value!;
+
+      if (response.ok) {
+        resolve(success(response));
+        onSuccess?.(response);
+      } else {
+        if (isClientErrorResponse(response)) {
+          return failure(
+            new ClientError(response.statusText, {
+              context: {
+                status: response.status,
+                statusText: response.statusText,
+              },
+              response,
+              requestInit: init,
+              url,
+            })
+          );
+        }
+        if (isServerErrorResponse(response)) {
+          return failure(
+            new ServerError(response.statusText, {
+              response,
+              requestInit: init,
+              url,
+              context: {
+                status: response.status,
+                statusText: response.statusText,
+              },
+            })
+          );
+        }
+
+        const error = new BringError("Fetch failed", {
+          context: {
+            url,
+            status: response.status,
+            statusText: response.statusText,
+          },
+          url: url,
+          requestInit: init,
+          response,
+        });
+        resolve(failure(error));
+        onError?.(error);
+      }
+    }
+  });
+
+  return abortablePromise;
+};

package/src/errors/AbortError.ts

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

package/src/errors/BringError.ts

@@ -0,0 +1,24 @@
+import { BringInit } from "../types/BringInit";
+import { JuiError, JuiErrorOptions } from "@torthu/jacketui-core";
+
+export interface BringErrorOptions extends JuiErrorOptions {
+  response?: Response;
+  request?: Request;
+  requestInit: BringInit;
+  url: string | URL;
+}
+
+export class BringError extends JuiError {
+  public readonly response?: BringErrorOptions["response"];
+  public readonly request?: BringErrorOptions["request"];
+  public readonly requestInit: BringErrorOptions["requestInit"];
+  public readonly url: BringErrorOptions["url"];
+
+  constructor(message: string, options: BringErrorOptions) {
+    super(message, options);
+    this.response = options.response;
+    this.request = options.request;
+    this.requestInit = options.requestInit;
+    this.url = options.url;
+  }
+}