arthron 1.0.1 → 1.2.0

package/dist/index-C3lylSNd.d.mts

@@ -0,0 +1,333 @@
+//#region src/types/request.types.d.ts
+/**
+ * What plugins see and return. `init.headers` is always a plain record with
+ * lowercased names — spread it, read it, add to it — and the pipeline puts
+ * it back into that shape after every request interceptor.
+ */
+interface RequestContext {
+  url: string;
+  init: Omit<RequestInit, "headers"> & {
+    headers: Record<string, string>;
+  };
+  /** Per-call settings for plugins (`RequestOptions.meta`); never sent. */
+  meta: ArthronMeta;
+  /**
+   * The fetch this attempt is sent with — the client's `fetch`, else the
+   * global one. Always set on contexts arthron creates; replace it to change
+   * the transport for this attempt, wrap it to observe. Optional so a
+   * context you build yourself stays valid.
+   */
+  fetch?: typeof fetch;
+}
+/**
+ * Per-call settings for plugins, passed as `api.get(path, { meta })` and
+ * carried next to `init` — never sent to fetch. The built-in plugins read
+ * `bearerAuth`, `onUploadProgress`, `retry` and `timeout`; your own add keys
+ * by augmentation:
+ *
+ * ```ts
+ * declare module "arthron" {
+ *   interface ArthronMeta { skipTrace?: boolean }
+ * }
+ * ```
+ */
+interface ArthronMeta {
+  /**
+   * `false` sends this call without the `bearerAuth()` token and never refreshes
+   * on its 401 — for the login and token-refresh endpoints.
+   */
+  bearerAuth?: false;
+  /**
+   * Upload progress for this call, with `uploadProgress()` on the client.
+   * Never called without that plugin or without a body, nor where progress
+   * cannot be had: a client with an injected `fetch`, another plugin's
+   * transport, Deno, Bun, Cloudflare Workers, a service worker, or a
+   * `ReadableStream` body in a browser — those calls are sent as usual.
+   */
+  onUploadProgress?: (event: UploadProgressEvent) => void;
+  /** `false` turns `retry()` off for this call; an object overrides its options. */
+  retry?: false | Omit<RetryOptions, "sleep">;
+  /** Deadline for this call in ms, overriding `timeout(ms)`. `Infinity` lifts it. */
+  timeout?: number;
+}
+/** One step of an upload, as `meta.onUploadProgress` receives it. */
+type UploadProgressEvent = {
+  /** Bytes sent so far. */
+  loaded: number;
+  /** Bytes in the whole body; `undefined` when it cannot be known (a stream without content-length). */
+  total: number | undefined;
+  /** `loaded / total`, from 0 to 1; `undefined` when `total` is. */
+  progress: number | undefined;
+};
+type RetryOptions = {
+  /** Number of retries after the first attempt. Default 2 (3 requests total). */
+  retries?: number;
+  /** Statuses worth retrying. Network errors (status 0) always are. */
+  retryOn?: readonly number[];
+  /** Methods safe to repeat (QUERY is, per RFC 10008). Compared case-insensitively. */
+  methods?: readonly string[];
+  /**
+   * Backoff in ms for retry number `retry` (0-based). Default "full jitter":
+   * a random share of 300 · 2^retry, so clients that failed together do not
+   * retry together.
+   */
+  delay?: (retry: number, error: unknown) => number;
+  /**
+   * Your own verdict on one failure: `true` retries, `false` stops,
+   * `undefined` leaves it to `retryOn`/`methods`. It sees every error — a
+   * TimeoutError from a `timeout()` placed after `retry()` included — but
+   * cannot exceed `retries`, resend a `ReadableStream` body, or retry a call
+   * the caller aborted.
+   */
+  shouldRetry?: (error: unknown, attempt: number, ctx: RequestContext) => boolean | undefined;
+  /** Called before each wait, for logs and metrics. */
+  onRetry?: (error: unknown, attempt: number, waitMs: number) => void;
+  /** Injectable for tests. Default `setTimeout`; rejects with the abort reason. */
+  sleep?: (ms: number, signal?: AbortSignal | null) => Promise<void>;
+  /**
+   * Longest `Retry-After` (ms) worth honouring. Beyond it the request is not
+   * retried at all. Default 60 000.
+   */
+  maxRetryAfter?: number;
+};
+type QueryValue = string | number | boolean | null | undefined;
+/**
+ * Query parameters. `null`/`undefined` values are skipped, an array becomes
+ * repeated keys (`ids=1&ids=2`), and a `URLSearchParams` is used as is.
+ */
+type QueryParams = Record<string, QueryValue | readonly QueryValue[]> | URLSearchParams;
+/**
+ * Headers as config and per-call options accept them: anything fetch's
+ * `headers` takes, or a plain object whose `null`/`undefined` values delete
+ * that header from the layer underneath (a client default, an inherited
+ * header). Not spelled `HeadersInit`: that name exists only in the DOM lib,
+ * and a Node project typed with `@types/node` alone does not have it.
+ */
+type HeadersOption = NonNullable<RequestInit["headers"]> | Record<string, string | null | undefined>;
+//#endregion
+//#region src/error/arthron-error.d.ts
+type ArthronErrorInit = {
+  message: string;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  data: unknown;
+  detail?: string | undefined;
+  request: RequestContext;
+  response?: Response;
+  cause?: unknown;
+};
+/**
+ * The only error arthron itself produces. Two sources: a response with
+ * `ok === false`, or fetch rejecting outright (network failure, `status` 0).
+ * Everything else — cancellation, interceptor bugs — is rethrown untouched.
+ */
+declare class ArthronError extends Error {
+  readonly name = "ArthronError";
+  /** HTTP status of the failed response; `0` when fetch itself failed (network). */
+  readonly status: number;
+  readonly statusText: string;
+  /** Response headers; empty for network failures. Not enumerable — kept out of logs. */
+  readonly headers: Headers;
+  /** Parsed body: JSON if it parses, else the text, else `undefined`. */
+  readonly data: unknown;
+  /**
+   * The server's own explanation, picked out of `data` (by default
+   * `message` → `error` → `error.message` → `detail`; see the `errorDetail`
+   * config). `undefined` when the body had none. Untrusted server text: show
+   * it to users as text, never as HTML. `message`, by contrast, is written by
+   * arthron — method, URL without query, status — and is meant for logs.
+   */
+  readonly detail: string | undefined;
+  /**
+   * The context that was sent — url and init after request interceptors.
+   * Not enumerable: it holds credentials, so `JSON.stringify`, `console.error`
+   * and error trackers leave it out. Read it directly when you need it.
+   */
+  readonly request: RequestContext;
+  /** The failed Response, still readable — its body holds what arthron read (at most 64 KiB). Absent for network failures. Not enumerable. */
+  readonly response: Response | undefined;
+  /** The underlying error for network failures. */
+  readonly cause: unknown;
+  constructor(init: ArthronErrorInit);
+  /** `instanceof ArthronError` holds for an error from any copy of the package. */
+  static [Symbol.hasInstance](value: unknown): boolean;
+  /** What serializers see: no headers, no body, no query or userinfo. */
+  toJSON(): {
+    name: string;
+    message: string;
+    detail: string | undefined;
+    status: number;
+    statusText: string;
+    method: string;
+    url: string;
+    data: unknown;
+  };
+}
+/** `true` for errors arthron produced: a `!ok` response or a network failure. Cancellations and plugin bugs are not ArthronErrors. */
+declare function isArthronError(error: unknown): error is ArthronError;
+//#endregion
+//#region src/types/plugin.types.d.ts
+/** Runs before each attempt. Returns the context to send (may be a new object). */
+type RequestInterceptor = (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
+/** Runs after a successful attempt. The body is single-use — `clone()` to peek. */
+type ResponseInterceptor = (res: Response, ctx: RequestContext) => Response | Promise<Response>;
+/** Runs after a failed attempt. Returns the error to throw; it is always thrown. */
+type ErrorInterceptor = (err: ArthronError, ctx: RequestContext) => ArthronError | Promise<ArthronError>;
+/**
+ * Wraps the whole call. `next` runs everything below it (request interceptors →
+ * fetch → response/error interceptors) and may be called again to retry.
+ * `next` rejects with an `ArthronError`, or with the untouched original when the
+ * failure was a cancellation or a bug in a plugin.
+ */
+type Middleware = (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+interface Plugin {
+  /**
+   * Identity within a client: `use`/`extend` replace the plugin of the same
+   * name in place, `without(name)` removes it. The built-ins are named
+   * "bearerAuth", "logging", "retry", "timeout" and "uploadProgress". Leave it out to always
+   * append.
+   */
+  name?: string;
+  middleware?: Middleware;
+  request?: RequestInterceptor;
+  response?: ResponseInterceptor;
+  error?: ErrorInterceptor;
+}
+//#endregion
+//#region src/plugins/bearer-auth/bearer-auth.types.d.ts
+type BearerAuthOptions = {
+  /**
+   * Where the token may go: a URL, or several. Only their origins count, so
+   * your `baseURL` works as is. A request anywhere else — a CDN, a URL taken
+   * from a response body — is sent without the token.
+   */
+  origin: string | readonly string[];
+  /**
+   * The current access token, read on every attempt. `null`, `undefined` or
+   * `""` sends no `authorization` header.
+   */
+  token: () => string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Get a new token after a 401; the call is then redone once. Concurrent
+   * 401s share one refresh, and a call whose token was already replaced
+   * retries without one. Throw when the refresh fails — every waiting call
+   * rejects with that error. Requests the refresh makes through the same
+   * client need `meta: { bearerAuth: false }`. Without `refresh`, or for a
+   * `ReadableStream` body (already read, so it cannot be resent), a 401 is
+   * thrown as is.
+   */
+  refresh?: () => Promise<void>;
+};
+//#endregion
+//#region src/plugins/bearer-auth/bearer-auth.d.ts
+/**
+ * Bearer-token auth. A request interceptor sets `authorization: Bearer
+ * <token>` on every attempt to `origin`; with `refresh`, a middleware turns a
+ * 401 into one refresh and one more try. Concurrent 401s share the refresh
+ * (with refresh-token rotation, parallel refreshes revoke each other), and a
+ * call whose token was replaced meanwhile just retries. A call opts out with
+ * `meta: { bearerAuth: false }`.
+ */
+declare function bearerAuth(options: BearerAuthOptions): Plugin;
+//#endregion
+//#region src/plugins/logging/logging.types.d.ts
+type LogEventBase = {
+  method: string;
+  path: string;
+};
+type LogEvent = ({
+  phase: "start";
+} & LogEventBase) | ({
+  phase: "success";
+  status: number;
+  ms: number;
+} & LogEventBase) | ({
+  phase: "error";
+  /** HTTP status for an ArthronError (0 = network); undefined for anything else. */
+  status: number | undefined;
+  ms: number;
+  error: unknown;
+} & LogEventBase);
+type LoggingOptions = {
+  /** Default `true`. The library never reads `NODE_ENV` — pass `isDev` yourself. */
+  enabled?: boolean;
+  logger?: Pick<Console, "log" | "error">;
+  /** Receive structured events instead of the default console lines. */
+  onEvent?: (event: LogEvent) => void;
+  /** Clock in ms. Injectable for tests. */
+  now?: () => number;
+};
+//#endregion
+//#region src/plugins/logging/logging.d.ts
+/**
+ * One event when a request starts, one when it settles, with status and
+ * elapsed time. Wraps the whole call, so retries are included in the time.
+ * Default output is a console line per event; pass `onEvent` to get the
+ * structured event instead. Cancellations are not reported.
+ */
+declare function logging(options?: LoggingOptions): Plugin;
+//#endregion
+//#region src/plugins/retry/retry.d.ts
+/**
+ * Retry on network errors and the configured statuses by calling `next`
+ * again — the whole attempt (request interceptors included) is re-run.
+ * Only `ArthronError` is considered; cancellation and plugin bugs pass through.
+ * A call can turn it off or override its options with `meta.retry`.
+ */
+declare function retry(options?: RetryOptions): Plugin;
+//#endregion
+//#region src/plugins/timeout/timeout.types.d.ts
+type TimeoutOptions = {
+  /**
+   * Abort after this many ms in all, counted until the body has been fully
+   * read — the same deadline as `timeout(ms)`. Default: none.
+   */
+  total?: number;
+  /**
+   * Abort when no data has arrived for this many ms — while waiting for the
+   * headers and between body chunks. Unlike `total`, a stream that keeps
+   * flowing is never cut off: `timeout({ idle: 30_000 })`.
+   */
+  idle?: number;
+};
+//#endregion
+//#region src/plugins/timeout/timeout.d.ts
+/**
+ * Abort the request when it takes longer than `ms` — counted from the start
+ * of the attempt until the body has been fully read, so a server that sends
+ * headers and then stalls still trips it. `timeout({ idle })` instead aborts
+ * once no data has arrived for that long, and never cuts off a stream that
+ * keeps flowing; `timeout({ total, idle })` does both. Rejects with a
+ * `TimeoutError` (a `DOMException`, like `AbortSignal.timeout()` would give);
+ * it is not an `ArthronError`, so error interceptors and `retry` leave it
+ * alone.
+ *
+ * A call can change the total deadline with `meta.timeout`.
+ *
+ * Deadlines are timers on an AbortController — not `AbortSignal.timeout`,
+ * since the idle one restarts — joined to the caller's signal with
+ * `AbortSignal.any`.
+ */
+declare function timeout(ms: number): Plugin;
+declare function timeout(options: TimeoutOptions): Plugin;
+/** @deprecated Use `timeout({ total: ms, idle })`; this form goes in the next major. */
+declare function timeout(ms: number, options: Pick<TimeoutOptions, "idle">): Plugin;
+//#endregion
+//#region src/plugins/upload-progress/upload-progress.d.ts
+/**
+ * Does nothing by itself — only a call that passes `meta.onUploadProgress`
+ * reports upload progress. On such a call it changes how that one attempt
+ * is sent: over XMLHttpRequest in a browser, with a counted body in Node.
+ * Every other call, on this client too, goes out exactly as before.
+ *
+ * Progress needs the runtime's own fetch: with an injected `fetch`, another
+ * plugin's transport, or a runtime that is neither (Deno, Bun, Cloudflare
+ * Workers, a service worker), the call is sent as usual without progress.
+ * Put it last in `use`: the call's signal carries a throwing callback's
+ * error, and an interceptor after it that replaces the signal would cut it.
+ */
+declare function uploadProgress(): Plugin;
+//#endregion
+export { UploadProgressEvent as S, ArthronMeta as _, logging as a, RequestContext as b, bearerAuth as c, Middleware as d, Plugin as f, isArthronError as g, ArthronError as h, retry as i, BearerAuthOptions as l, ResponseInterceptor as m, timeout as n, LogEvent as o, RequestInterceptor as p, TimeoutOptions as r, LoggingOptions as s, uploadProgress as t, ErrorInterceptor as u, HeadersOption as v, RetryOptions as x, QueryParams as y };
+//# sourceMappingURL=index-C3lylSNd.d.mts.map