@torthu/jacketui-bring 0.0.1

package/src/pipe-helpers/referrerPolicy.ts

@@ -0,0 +1,33 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** referrerPolicy(string): BringInitDecorator
+ *
+ * A string specifying the value of the referrer-policy header to use for the request.
+ *
+ * Possible values are:
+ * - "no-referrer" The Referer header will not be sent.
+ * - "no-referrer-when-downgrade" Send the origin, path, and query string in Referer when the protocol security level stays the same or improves
+ * - "origin" Send only the origin in the Referer header. For example, a document at https://example.com/page.html will send the referrer https://example.com/.
+ * - "origin-when-cross-origin" When performing a same-origin request to the same protocol level (HTTP→HTTP, HTTPS→HTTPS), send the origin, path, and query string. Send only the origin for cross origin requests and requests to less secure destinations (HTTPS→HTTP).
+ * - "same-origin" Send the origin, path, and query string for same-origin requests. Don't send the Referer header for cross-origin requests.
+ * - "strict-origin" Send only the origin when the protocol security level stays the same (HTTPS→HTTPS). Don't send the Referer header to less secure destinations (HTTPS→HTTP).
+ * - "strict-origin-when-cross-origin" (default) Send the origin, path, and query string when performing a same-origin request. For cross-origin requests send the origin (only) when the protocol security level stays same (HTTPS→HTTPS). Don't send the Referer header to less secure destinations (HTTPS→HTTP).
+ * - "unsafe-url" Send the origin, path, and query string when performing any request, regardless of security.
+ *
+ * Default is "strict-origin-when-cross-origin"
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#referrerpolicy
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy
+ *
+ * @param referrerPolicyMode
+ * @returns BringInitDecorator
+ */
+export const referrerPolicy =
+  (
+    referrerPolicyMode: BringInit["referrerPolicy"] = "strict-origin-when-cross-origin"
+  ): BringInitDecorator =>
+  (init) => {
+    init.referrerPolicy = referrerPolicyMode;
+    return init;
+  };

package/src/pipe-helpers/retry.ts

@@ -0,0 +1,13 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** retry(number): BringInitDecorator
+ *
+ * Sets the number of times to retry the request.
+ *
+ * @param retry The number of times to retry the request.
+ * @returns BringInitDecorator
+ */
+export const retry =
+  (retry: BringInit["retry"]): BringInitDecorator =>
+  (init) => ({ ...init, retry });

package/src/pipe-helpers/shouldRetry.ts

@@ -0,0 +1,11 @@
+import { BringInitDecorator } from "../types/BringDecorator";
+import { BringInit } from "../types/BringInit";
+
+/** shouldRetry((response: Response, retryNum: number) => boolean)): BringInitDecorator
+ *
+ * @param shouldRetry ((response: Response, retryNum: number) => boolean)
+ * @returns BringInitDecorator
+ */
+export const shouldRetry =
+  (shouldRetry: BringInit["shouldRetry"]): BringInitDecorator =>
+  (init) => ({ ...init, shouldRetry });

package/src/pipe-helpers/timeout.ts

@@ -0,0 +1,19 @@
+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 const timeout =
+  (timeout: BringInit["timeout"]): BringInitDecorator =>
+  (init) => ({ ...init, timeout });

package/src/tryFetch.ts

@@ -0,0 +1,32 @@
+import {
+  failure,
+  JuiError,
+  Result,
+  sleep,
+  success,
+  tryAwait,
+} from "@torthu/jacketui-core";
+import { BringInit } from "./types/BringInit";
+
+export const tryFetch = async (
+  url: string | URL,
+  requestInit: RequestInit,
+  init: BringInit,
+  retryCount = 0
+): Promise<Result<Response, JuiError>> => {
+  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/src/types/BringDecorator.ts

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

package/src/types/BringInit.ts

@@ -0,0 +1,78 @@
+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";
+  // signal?: AbortSignal; // Handled by bring() or the AbortController passed in
+}
+
+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;
+  };

package/src/types/ClientErrorResponse.ts

@@ -0,0 +1,72 @@
+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;
+
+const clientStatusErrorMap: Record<ClientErrorStatus, string> = {
+  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 interface ClientErrorResponse extends Response {
+  status: ClientErrorStatus;
+}
+
+export const isClientErrorResponse = (
+  res: Response
+): res is ClientErrorResponse => clientStatusErrorSet.has(res.status);

package/src/types/InformationalResponse.ts

@@ -0,0 +1,20 @@
+type InformationalResponseStatus = 100 | 101 | 102 | 103;
+
+const informationalResponseMap: Record<InformationalResponseStatus, string> = {
+  100: "Continue",
+  101: "Switching Protocols",
+  102: "Processing",
+  103: "Early Hints",
+};
+
+const informationalResponseSet = new Set(
+  Object.keys(informationalResponseMap).map((s) => parseInt(s, 10))
+);
+
+export interface InformationalResponse extends Response {
+  status: InformationalResponseStatus;
+}
+
+export const isInformationalResponse = (
+  res: Response
+): res is InformationalResponse => informationalResponseSet.has(res.status);

package/src/types/RedirectResponse.ts

@@ -0,0 +1,20 @@
+type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+
+const redirectMap: Record<RedirectStatus, string> = {
+  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 interface RedirectResponse extends Response {
+  status: RedirectStatus;
+}
+
+export const isRedirectResponse = (res: Response): res is RedirectResponse =>
+  redirectSet.has(res.status);

package/src/types/ServerErrorResponse.ts

@@ -0,0 +1,56 @@
+type ServerErrorStatus =
+  | 500
+  | 501
+  | 502
+  | 503
+  | 504
+  | 505
+  | 506
+  | 507
+  | 508
+  | 510
+  | 511
+  | 520
+  | 521
+  | 522
+  | 523
+  | 524
+  | 525
+  | 526
+  | 527
+  | 530;
+
+const serverStatusErrorMap: Record<ServerErrorStatus, string> = {
+  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 interface ServerErrorResponse extends Response {
+  status: ServerErrorStatus;
+}
+
+export const isServerErrorResponse = (
+  res: Response
+): res is ServerErrorResponse => serverStatusErrorSet.has(res.status);

package/src/types/SuccessResponse.ts

@@ -0,0 +1,57 @@
+type KnownSuccessStatus =
+  | 200
+  | 201
+  | 202
+  | 203
+  | 204
+  | 205
+  | 206
+  | 207
+  | 208
+  | 226;
+
+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 interface KnownSuccessResponse extends Response {
+  status: KnownSuccessStatus;
+}
+
+export const isKnownSuccessResponse = (
+  res: Response
+): res is KnownSuccessResponse => knownSuccessStatusSet.has(res.status);
+
+export interface UnknownSuccessResponse extends Response {
+  status: number;
+}
+
+export const isUnknownSuccessResponse = (
+  res: Response
+): res is UnknownSuccessResponse =>
+  res.status >= 200 && res.status < 300 && !isKnownSuccessResponse(res);
+
+export type SuccessResponse = KnownSuccessResponse | UnknownSuccessResponse;
+
+export const isSuccessResponse = (res: Response): res is SuccessResponse =>
+  res.status >= 200 && res.status < 300;
+
+export const getSuccessStatusText = (res: SuccessResponse): string =>
+  isKnownSuccessResponse(res)
+    ? knownSuccessStatusMap[res.status]
+    : unknownSuccessStatusText;

package/src/types/statusCodes.ts

@@ -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/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.common.json",
+
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules"]
+}