arthron 1.2.0 → 2.1.0

package/dist/shared.d.cts

@@ -0,0 +1,239 @@
+//#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 function this attempt is sent with — the client's `fetchFn` at first,
+   * else the global `fetch`. A plugin may replace it for this attempt
+   * (`uploadProgress()` sends over XMLHttpRequest) or wrap it to observe.
+   * Always set on contexts arthron creates; optional so a context you build
+   * yourself stays valid.
+   */
+  fetchFn?: typeof fetch;
+}
+/**
+ * Per-call settings for plugins, passed as `api.get(path, { meta })` and
+ * carried next to `init` — never sent to fetch. Each built-in plugin with a
+ * per-call setting reads the key named after it — `bearerAuth`, `retry`,
+ * `timeout`, `uploadProgress`; 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:
+   * `{ onProgress: ({ loaded, total, fraction }) => … }`. `onProgress` is
+   * never called without that plugin or without a body, nor where progress
+   * cannot be had: a client with its own `fetchFn`, another plugin's
+   * `fetchFn`, Deno, Bun, Cloudflare Workers, a service worker, or a
+   * `ReadableStream` body in a browser — those calls are sent as usual.
+   */
+  uploadProgress?: {
+    /** Called for each step of the upload, from 0 again on each attempt. */
+    onProgress: (event: UploadProgressEvent) => void;
+  };
+  /** `false` turns `retry()` off for this call; an object overrides its options. */
+  retry?: false | RetryOptions;
+  /**
+   * `false` lifts `timeout()`'s deadlines for this call; a number replaces
+   * its `total` (ms); an object overrides the parts it sets, `total` or
+   * `idle`: `{ idle: 30_000 }` keeps the configured total.
+   */
+  timeout?: false | number | TimeoutOptions;
+}
+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;
+};
+/** One step of an upload, as `meta.uploadProgress` 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`, a fraction from 0 to 1 — not a percentage: multiply
+   * by 100 for one. `undefined` when `total` is.
+   */
+  fraction: number | undefined;
+};
+type RetryOptions = {
+  /** Number of retries after the first attempt. Default 2 (3 requests total). */
+  retries?: number;
+  /** Statuses worth retrying. Default 408, 429, 500, 502, 503, 504; network errors (status 0) always are. */
+  statuses?: readonly number[];
+  /**
+   * Methods safe to repeat (QUERY is, per RFC 10008). Compared
+   * case-insensitively. Default GET, HEAD, OPTIONS, QUERY, PUT, DELETE.
+   */
+  methods?: readonly string[];
+  /**
+   * Returns the wait in ms before the next attempt. `attempt` is 0-based: 0
+   * after the first request failed. Default "full jitter": a random share
+   * of 300 · 2^attempt, so clients that failed together do not retry
+   * together. A `Retry-After` header wins over it. Must return a finite
+   * number ≥ 0, or the call rejects with a TypeError.
+   */
+  delayFn?: (attempt: number, error: unknown) => number;
+  /**
+   * Your own verdict on one failure (`attempt` 0-based, as for `delayFn`):
+   * `true` retries, `false` stops, `undefined` leaves it to
+   * `statuses`/`methods`. It sees every error — a TimeoutError from a
+   * `timeout()` placed after `retry()` included — but cannot exceed
+   * `retries`, resend a `ReadableStream` body, retry a call the caller
+   * aborted, or wait out a `Retry-After` longer than `maxRetryAfter`.
+   */
+  shouldRetry?: (error: unknown, attempt: number, requestContext: RequestContext) => boolean | undefined;
+  /**
+   * Called before each wait, for logs and metrics, with the same 0-based
+   * `attempt` and the `delay` in ms about to be waited.
+   */
+  onRetry?: (error: unknown, attempt: number, delay: number) => void;
+  /**
+   * Longest `Retry-After` (ms) worth honouring. Beyond it the request is not
+   * retried at all. Default 60 000.
+   */
+  maxRetryAfter?: number;
+};
+/**
+ * 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, string | number | boolean | null | undefined | readonly (string | number | boolean | null | undefined)[]> | URLSearchParams;
+//#endregion
+//#region src/error/arthron-error.d.ts
+/**
+ * What `new ArthronError(options)` takes — for a test or a plugin that
+ * builds one by hand. Each field becomes the error's field of that name.
+ */
+type ArthronErrorOptions = {
+  message: string;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  payload: unknown;
+  description?: string | undefined;
+  requestContext: 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;
+  /**
+   * The failed response's payload, parsed: JSON if it parses, else the text;
+   * `undefined` for a network failure, which has no response. At most 64 KiB
+   * is read (text if cut). `response.body`, by contrast, is the stream.
+   */
+  readonly payload: unknown;
+  /**
+   * For people: the server's description of the failure, extracted from
+   * `payload` (by default its `message` → `error` → `error.message` →
+   * `detail`; see the `extractDescription` option). `undefined` when there was
+   * none, and for a network failure. Untrusted server text: show it as text,
+   * never as HTML. `message`, by contrast, is arthron's — method, URL
+   * without query, status — for logs, not for people.
+   */
+  readonly description: string | undefined;
+  /**
+   * The `RequestContext` that was sent — what plugins get as
+   * `requestContext`, after request interceptors: `url`, `init` (method,
+   * headers as a lowercase record, body), `meta`. Not a fetch `Request`: the
+   * method and headers are at `requestContext.init.method` and
+   * `.init.headers`. Not enumerable: it holds credentials, so
+   * `JSON.stringify`, `console.error` and error trackers leave it out. Read
+   * it directly when you need it.
+   */
+  readonly requestContext: 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, with the URL's query and userinfo taken out of its message, stack and causes. */
+  readonly cause: unknown;
+  constructor(options: ArthronErrorOptions);
+  /** `instanceof ArthronError` holds for an error from any copy of the package. */
+  static [Symbol.hasInstance](value: unknown): boolean;
+  /** What serializers see: no headers, no request body, no query or userinfo. */
+  toJSON(): {
+    name: string;
+    message: string;
+    description: string | undefined;
+    status: number;
+    statusText: string;
+    method: string;
+    url: string;
+    payload: 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 = (requestContext: RequestContext) => RequestContext | Promise<RequestContext>;
+/** Runs after a successful attempt. The body is single-use — `clone()` to peek. */
+type ResponseInterceptor = (response: Response, requestContext: RequestContext) => Response | Promise<Response>;
+/** Runs after a failed attempt. Returns the error to throw; it is always thrown. */
+type ErrorInterceptor = (error: ArthronError, requestContext: 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 = (requestContext: RequestContext, next: (requestContext: RequestContext) => Promise<Response>) => Promise<Response>;
+interface Plugin {
+  /**
+   * Identity within a client, required: `use`/`extend` replace the plugin of
+   * the same pluginName in place, `without(pluginName)` removes it. The
+   * built-ins are "bearerAuth", "logging", "retry", "timeout" and
+   * "uploadProgress". Not `name`: a function has one, so a bare middleware
+   * would pass for a plugin.
+   */
+  pluginName: string;
+  /** Wraps the whole call and controls its flow: may call `next` again, or not at all. */
+  middleware?: Middleware;
+  /** Transforms each attempt's context before it is sent; returns the context to send. */
+  requestInterceptor?: RequestInterceptor;
+  /** Transforms each successful attempt's Response; returns the Response to pass on. */
+  responseInterceptor?: ResponseInterceptor;
+  /** Transforms each failed attempt's ArthronError; returns the error to throw. */
+  errorInterceptor?: ErrorInterceptor;
+}
+//#endregion
+export { ResponseInterceptor as a, isArthronError as c, RequestContext as d, RetryOptions as f, RequestInterceptor as i, ArthronMeta as l, UploadProgressEvent as m, Middleware as n, ArthronError as o, TimeoutOptions as p, Plugin as r, ArthronErrorOptions as s, ErrorInterceptor as t, QueryParams as u };

package/dist/shared.d.mts

@@ -0,0 +1,239 @@
+//#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 function this attempt is sent with — the client's `fetchFn` at first,
+   * else the global `fetch`. A plugin may replace it for this attempt
+   * (`uploadProgress()` sends over XMLHttpRequest) or wrap it to observe.
+   * Always set on contexts arthron creates; optional so a context you build
+   * yourself stays valid.
+   */
+  fetchFn?: typeof fetch;
+}
+/**
+ * Per-call settings for plugins, passed as `api.get(path, { meta })` and
+ * carried next to `init` — never sent to fetch. Each built-in plugin with a
+ * per-call setting reads the key named after it — `bearerAuth`, `retry`,
+ * `timeout`, `uploadProgress`; 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:
+   * `{ onProgress: ({ loaded, total, fraction }) => … }`. `onProgress` is
+   * never called without that plugin or without a body, nor where progress
+   * cannot be had: a client with its own `fetchFn`, another plugin's
+   * `fetchFn`, Deno, Bun, Cloudflare Workers, a service worker, or a
+   * `ReadableStream` body in a browser — those calls are sent as usual.
+   */
+  uploadProgress?: {
+    /** Called for each step of the upload, from 0 again on each attempt. */
+    onProgress: (event: UploadProgressEvent) => void;
+  };
+  /** `false` turns `retry()` off for this call; an object overrides its options. */
+  retry?: false | RetryOptions;
+  /**
+   * `false` lifts `timeout()`'s deadlines for this call; a number replaces
+   * its `total` (ms); an object overrides the parts it sets, `total` or
+   * `idle`: `{ idle: 30_000 }` keeps the configured total.
+   */
+  timeout?: false | number | TimeoutOptions;
+}
+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;
+};
+/** One step of an upload, as `meta.uploadProgress` 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`, a fraction from 0 to 1 — not a percentage: multiply
+   * by 100 for one. `undefined` when `total` is.
+   */
+  fraction: number | undefined;
+};
+type RetryOptions = {
+  /** Number of retries after the first attempt. Default 2 (3 requests total). */
+  retries?: number;
+  /** Statuses worth retrying. Default 408, 429, 500, 502, 503, 504; network errors (status 0) always are. */
+  statuses?: readonly number[];
+  /**
+   * Methods safe to repeat (QUERY is, per RFC 10008). Compared
+   * case-insensitively. Default GET, HEAD, OPTIONS, QUERY, PUT, DELETE.
+   */
+  methods?: readonly string[];
+  /**
+   * Returns the wait in ms before the next attempt. `attempt` is 0-based: 0
+   * after the first request failed. Default "full jitter": a random share
+   * of 300 · 2^attempt, so clients that failed together do not retry
+   * together. A `Retry-After` header wins over it. Must return a finite
+   * number ≥ 0, or the call rejects with a TypeError.
+   */
+  delayFn?: (attempt: number, error: unknown) => number;
+  /**
+   * Your own verdict on one failure (`attempt` 0-based, as for `delayFn`):
+   * `true` retries, `false` stops, `undefined` leaves it to
+   * `statuses`/`methods`. It sees every error — a TimeoutError from a
+   * `timeout()` placed after `retry()` included — but cannot exceed
+   * `retries`, resend a `ReadableStream` body, retry a call the caller
+   * aborted, or wait out a `Retry-After` longer than `maxRetryAfter`.
+   */
+  shouldRetry?: (error: unknown, attempt: number, requestContext: RequestContext) => boolean | undefined;
+  /**
+   * Called before each wait, for logs and metrics, with the same 0-based
+   * `attempt` and the `delay` in ms about to be waited.
+   */
+  onRetry?: (error: unknown, attempt: number, delay: number) => void;
+  /**
+   * Longest `Retry-After` (ms) worth honouring. Beyond it the request is not
+   * retried at all. Default 60 000.
+   */
+  maxRetryAfter?: number;
+};
+/**
+ * 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, string | number | boolean | null | undefined | readonly (string | number | boolean | null | undefined)[]> | URLSearchParams;
+//#endregion
+//#region src/error/arthron-error.d.ts
+/**
+ * What `new ArthronError(options)` takes — for a test or a plugin that
+ * builds one by hand. Each field becomes the error's field of that name.
+ */
+type ArthronErrorOptions = {
+  message: string;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  payload: unknown;
+  description?: string | undefined;
+  requestContext: 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;
+  /**
+   * The failed response's payload, parsed: JSON if it parses, else the text;
+   * `undefined` for a network failure, which has no response. At most 64 KiB
+   * is read (text if cut). `response.body`, by contrast, is the stream.
+   */
+  readonly payload: unknown;
+  /**
+   * For people: the server's description of the failure, extracted from
+   * `payload` (by default its `message` → `error` → `error.message` →
+   * `detail`; see the `extractDescription` option). `undefined` when there was
+   * none, and for a network failure. Untrusted server text: show it as text,
+   * never as HTML. `message`, by contrast, is arthron's — method, URL
+   * without query, status — for logs, not for people.
+   */
+  readonly description: string | undefined;
+  /**
+   * The `RequestContext` that was sent — what plugins get as
+   * `requestContext`, after request interceptors: `url`, `init` (method,
+   * headers as a lowercase record, body), `meta`. Not a fetch `Request`: the
+   * method and headers are at `requestContext.init.method` and
+   * `.init.headers`. Not enumerable: it holds credentials, so
+   * `JSON.stringify`, `console.error` and error trackers leave it out. Read
+   * it directly when you need it.
+   */
+  readonly requestContext: 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, with the URL's query and userinfo taken out of its message, stack and causes. */
+  readonly cause: unknown;
+  constructor(options: ArthronErrorOptions);
+  /** `instanceof ArthronError` holds for an error from any copy of the package. */
+  static [Symbol.hasInstance](value: unknown): boolean;
+  /** What serializers see: no headers, no request body, no query or userinfo. */
+  toJSON(): {
+    name: string;
+    message: string;
+    description: string | undefined;
+    status: number;
+    statusText: string;
+    method: string;
+    url: string;
+    payload: 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 = (requestContext: RequestContext) => RequestContext | Promise<RequestContext>;
+/** Runs after a successful attempt. The body is single-use — `clone()` to peek. */
+type ResponseInterceptor = (response: Response, requestContext: RequestContext) => Response | Promise<Response>;
+/** Runs after a failed attempt. Returns the error to throw; it is always thrown. */
+type ErrorInterceptor = (error: ArthronError, requestContext: 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 = (requestContext: RequestContext, next: (requestContext: RequestContext) => Promise<Response>) => Promise<Response>;
+interface Plugin {
+  /**
+   * Identity within a client, required: `use`/`extend` replace the plugin of
+   * the same pluginName in place, `without(pluginName)` removes it. The
+   * built-ins are "bearerAuth", "logging", "retry", "timeout" and
+   * "uploadProgress". Not `name`: a function has one, so a bare middleware
+   * would pass for a plugin.
+   */
+  pluginName: string;
+  /** Wraps the whole call and controls its flow: may call `next` again, or not at all. */
+  middleware?: Middleware;
+  /** Transforms each attempt's context before it is sent; returns the context to send. */
+  requestInterceptor?: RequestInterceptor;
+  /** Transforms each successful attempt's Response; returns the Response to pass on. */
+  responseInterceptor?: ResponseInterceptor;
+  /** Transforms each failed attempt's ArthronError; returns the error to throw. */
+  errorInterceptor?: ErrorInterceptor;
+}
+//#endregion
+export { ResponseInterceptor as a, isArthronError as c, RequestContext as d, RetryOptions as f, RequestInterceptor as i, ArthronMeta as l, UploadProgressEvent as m, Middleware as n, ArthronError as o, TimeoutOptions as p, Plugin as r, ArthronErrorOptions as s, ErrorInterceptor as t, QueryParams as u };