arthron 0.1.0 → 1.0.1

package/dist/index.d.cts

@@ -1,11 +1,88 @@
-//#region src/error.d.ts
-type ErrorMessageResolver = (data: unknown, response: Response) => string | undefined;
+//#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;
+}
+/**
+ * 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
+ * `retry` and `timeout`; your own add keys by augmentation:
+ *
+ * ```ts
+ * declare module "arthron" {
+ *   interface ArthronMeta { skipAuth?: boolean }
+ * }
+ * ```
+ */
+interface ArthronMeta {
+  /** `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;
+}
+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;
@@ -20,42 +97,47 @@ export declare class ArthronError extends Error {
   /** HTTP status of the failed response; `0` when fetch itself failed (network). */
   readonly status: number;
   readonly statusText: string;
-  /** Response headers; empty for network failures. */
+  /** 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 context that was sent — url and init after request interceptors. */
+  /**
+   * 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 original Response, still readable (the body was parsed from a clone). Absent for network failures. */
+  /** 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. */
 export declare function isArthronError(error: unknown): error is ArthronError;
 //#endregion
-//#region src/stream.d.ts
-/** One server-sent event, as described by the WHATWG EventSource spec. */
-type SseEvent = {
-  /** The `event:` field, when the server sent one. */
-  event?: string;
-  /** All `data:` lines of the block, joined with `\n`. */
-  data: string;
-  /** The `id:` field, when present. */
-  id?: string;
-  /** The `retry:` field in ms, when present and numeric. */
-  retry?: number;
-};
-//#endregion
-//#region src/url.d.ts
-type QueryParams = Record<string, string | number | boolean | null | undefined>;
-//#endregion
-//#region src/types.d.ts
-type RequestContext = {
-  url: string;
-  init: RequestInit;
-};
+//#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. */
@@ -69,67 +151,199 @@ type ErrorInterceptor = (err: ArthronError, ctx: RequestContext) => ArthronError
  * failure was a cancellation or a bug in a plugin.
  */
 type Middleware = (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
-type Plugin = {
-  /** For logs and debugging only. */
+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
+   * "retry", "timeout" and "logging". Leave it out to always append.
+   */
   name?: string;
   middleware?: Middleware;
   request?: RequestInterceptor;
   response?: ResponseInterceptor;
   error?: ErrorInterceptor;
+}
+//#endregion
+//#region src/types/response.types.d.ts
+interface ArthronPromise extends Promise<Response> {
+  /** The body as JSON. `T` is a cast — nothing checks it. */
+  json<T = unknown>(): Promise<T>;
+  /**
+   * The body as JSON, validated by a Standard Schema (Zod, Valibot, ArkType…)
+   * and typed by it. A mismatch rejects with a `SchemaError`.
+   */
+  json<S extends StandardSchemaV1>(schema: S): Promise<InferOutput<S>>;
+  text(): Promise<string>;
+  blob(): Promise<Blob>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  formData(): Promise<FormData>;
+  /** Iterate a `text/event-stream` body as events. */
+  sse(options?: SseOptions): AsyncIterable<SseEvent>;
+  /** Iterate a newline-delimited JSON body, one parsed value per line. */
+  ndjson<T = unknown>(options?: NdjsonOptions): AsyncIterable<T>;
+}
+/** One server-sent event, as described by the WHATWG EventSource spec. */
+type SseEvent = {
+  /** The `event:` field, when the server sent one. */
+  event?: string;
+  /** All `data:` lines of the block, joined with `\n`. */
+  data: string;
+  /** The `id:` field of this event's own block, when it had one. */
+  id?: string;
+  /**
+   * The last event ID so far, as EventSource's `lastEventId`: it persists
+   * across events (a block with only `id:` updates it too) and is "" until
+   * the server sends one. Send it as `Last-Event-ID` to resume a stream.
+   */
+  lastEventId: string;
+  /** The reconnection time in ms the server last set with `retry:`; carried on every event after it. */
+  retry?: number;
 };
-type RequestOptions = Omit<RequestInit, "body" | "method"> & {
-  params?: QueryParams;
+type NdjsonOptions = {
+  /**
+   * Longest line accepted, in characters. A longer one rejects the iteration
+   * with a RangeError and cancels the body. Default 8 Mi.
+   */
+  maxLineLength?: number;
 };
-type RequestInitWithBody = RequestOptions & {
-  method: string;
-  body?: unknown;
+type SseOptions = NdjsonOptions & {
+  /**
+   * Most `data` one event may collect before its blank line, in characters.
+   * More rejects the iteration with a RangeError and cancels the body.
+   * Default 8 Mi.
+   */
+  maxEventSize?: number;
+};
+/**
+ * The Standard Schema interface (https://standardschema.dev), vendored as
+ * types only so arthron keeps zero dependencies. Zod, Valibot, ArkType and
+ * others implement it, so their schemas can be passed to `.json(schema)`.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => SchemaResult<Output> | Promise<SchemaResult<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
+}
+type SchemaResult<Output> = {
+  readonly value: Output;
+  readonly issues?: undefined;
+} | {
+  readonly issues: readonly SchemaIssue[];
 };
-type ArthronConfig = {
+interface SchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | {
+    readonly key: PropertyKey;
+  })[] | undefined;
+}
+/** The type a schema produces. */
+type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+type ErrorDetailResolver = (data: unknown, response: Response) => string | undefined;
+//#endregion
+//#region src/client/client.types.d.ts
+/**
+ * The methods arthron knows by name; any other string is sent as written.
+ * The standard ones go out uppercased whatever their case — fetch itself
+ * only normalizes six of them, so a lowercase "patch" would draw a 405.
+ */
+type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY" | (string & {});
+/**
+ * Per-call options. Public types are interfaces, so a plugin package can add
+ * its own options by augmentation (`declare module "arthron"`).
+ */
+interface RequestOptions extends Omit<RequestInit, "body" | "method" | "headers"> {
+  /** Per-call headers; a `null`/`undefined` value drops a client default. */
+  headers?: HeadersOption;
+  params?: QueryParams;
+  /**
+   * Values for `{name}` placeholders in the path, each encoded into its own
+   * segment: `get("/users/{id}", { path: { id } })`. Interpolating ids into
+   * the path string yourself lets "../" or "?" escape the segment.
+   */
+  path?: Record<string, string | number>;
+  /** Settings for plugins on this call only (see `ArthronMeta`). Not sent. */
+  meta?: ArthronMeta;
+  /** Which non-ok responses reject on this call; overrides the client's `throwOn`. */
+  throwOn?: (res: Response) => boolean;
+}
+/** `request()`'s options: any method, with the same body rules as `post`. */
+interface RequestInitWithBody extends RequestOptions {
+  method: HttpMethod;
+  body?: unknown;
+}
+/**
+ * The fetch options a client can set as defaults: the same `RequestInit`
+ * fields per-call options take, minus what only makes sense per call —
+ * `body`, `method`, `signal` (one client-wide signal, once aborted, would
+ * fail every later call) and `window`. `headers` has its own merge rules.
+ */
+type FetchDefaults = Omit<RequestInit, "body" | "method" | "headers" | "signal" | "window">;
+/**
+ * Client config. Besides arthron's own keys it takes any fetch option as a
+ * default (`credentials`, `cache`, `redirect`, `mode`, …), flat like per-call
+ * options; a per-call value wins.
+ */
+interface ArthronConfig extends FetchDefaults {
   /** Prefix for relative paths. Without it only absolute URLs are accepted. */
   baseURL?: string;
-  /** Default headers. Per-call headers win, compared case-insensitively. */
-  headers?: HeadersInit;
-  /** Forwarded to fetch as-is. Not set unless you set it. */
-  credentials?: RequestCredentials;
+  /**
+   * Let an absolute URL on another origin than `baseURL` through. Off by
+   * default, so a path from user input or an API response cannot send the
+   * client's headers elsewhere; config `headers` are never sent to another
+   * origin even when this is on.
+   */
+  allowAbsoluteUrls?: boolean;
+  /** Default headers. Per-call headers win, compared case-insensitively; `extend` can drop one with `null`. */
+  headers?: HeadersOption;
   /** Injection point for tests and polyfills. Defaults to `globalThis.fetch`. */
   fetch?: typeof fetch;
   use?: Plugin[];
   /** How to pick a message out of an error body. */
-  errorMessage?: ErrorMessageResolver;
-};
-type ArthronPromise = Promise<Response> & {
-  json<T = unknown>(): Promise<T>;
-  text(): Promise<string>;
-  blob(): Promise<Blob>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  formData(): Promise<FormData>;
-  /** Iterate a `text/event-stream` body as events. */
-  sse(): AsyncIterable<SseEvent>;
-  /** Iterate a newline-delimited JSON body, one parsed value per line. */
-  ndjson<T = unknown>(): AsyncIterable<T>;
-};
-type Arthron = {
+  errorDetail?: ErrorDetailResolver;
+  /**
+   * Which non-ok responses reject with an ArthronError — return `false` to
+   * get the Response instead (a 404 that is data, say). An ok response never
+   * rejects. Default: every non-ok response except an opaque one
+   * (`mode: "no-cors"`) and the 3xx of `redirect: "manual"`.
+   */
+  throwOn?: (res: Response) => boolean;
+}
+interface Arthron {
   get(path: string, init?: RequestOptions): ArthronPromise;
   delete(path: string, init?: RequestOptions): ArthronPromise;
   head(path: string, init?: RequestOptions): ArthronPromise;
   post(path: string, body?: unknown, init?: RequestOptions): ArthronPromise;
   put(path: string, body?: unknown, init?: RequestOptions): ArthronPromise;
   patch(path: string, body?: unknown, init?: RequestOptions): ArthronPromise;
+  /** RFC 10008 QUERY: safe and idempotent like GET, but the query travels in the body. */
+  query(path: string, body?: unknown, init?: RequestOptions): ArthronPromise;
+  /** Any method — the extension point for verbs without their own helper. */
   request(path: string, init: RequestInitWithBody): ArthronPromise;
-  /** New client with these plugins appended. The receiver is untouched. */
+  /**
+   * New client with these plugins added: a named one replaces the plugin of
+   * that name in place, an unnamed one appends. The receiver is untouched.
+   */
   use(...plugins: Plugin[]): Arthron;
-  /** New client with config shallow-merged, headers merged, plugins appended. */
+  /** New client with config shallow-merged, headers merged, plugins added as `use` adds them. */
   extend(config: Partial<ArthronConfig>): Arthron;
-};
+  /** New client without the plugins of these names. The receiver is untouched. */
+  without(...names: string[]): Arthron;
+}
 //#endregion
-//#region src/client.d.ts
+//#region src/client/client.d.ts
 /**
  * Build a client from config. The result is immutable — `use` and `extend`
  * return new clients and never touch the one they were called on.
  */
 export declare function arthron(config?: ArthronConfig): Arthron;
 //#endregion
-//#region src/define.d.ts
+//#region src/pipeline/define-plugin.d.ts
 /** Identity helper: gives a middleware written in its own file the right parameter types. */
 export declare const defineMiddleware: (middleware: Middleware) => Middleware;
 /** Identity helpers for each interceptor kind — `defineInterceptor.request(fn)` etc. */
@@ -141,7 +355,7 @@ export declare const defineInterceptor: {
 /** Identity helper: type-checks a plugin object literal without an annotation. */
 export declare const definePlugin: (plugin: Plugin) => Plugin;
 //#endregion
-//#region src/plugins/logging.d.ts
+//#region src/plugins/logging/logging.types.d.ts
 type LogEventBase = {
   method: string;
   path: string;
@@ -168,6 +382,8 @@ type LoggingOptions = {
   /** 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.
@@ -176,44 +392,53 @@ type LoggingOptions = {
  */
 export declare function logging(options?: LoggingOptions): Plugin;
 //#endregion
-//#region src/plugins/retry.d.ts
-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. Compared case-insensitively. */
-  methods?: readonly string[];
-  /** Backoff in ms for retry number `retry` (0-based). Default 300 · 2^retry. */
-  delay?: (retry: number, error: ArthronError) => number;
-  /** 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. Also guards `setTimeout`'s 2^31-1 ms cap,
-   * past which timers fire immediately.
-   */
-  maxRetryAfter?: number;
-};
+//#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`.
  */
 export declare function retry(options?: RetryOptions): Plugin;
 //#endregion
-//#region src/plugins/timeout.d.ts
+//#region src/plugins/timeout/timeout.types.d.ts
+type TimeoutOptions = {
+  /**
+   * Also abort when no data has arrived for this many ms — while waiting for
+   * the headers and between body chunks. Unlike the total deadline, a stream
+   * that keeps flowing is never cut off: `timeout(Infinity, { 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. Rejects with a `TimeoutError` (a
+ * headers and then stalls still trips it. With `idle`, also abort once no
+ * data has arrived for that long. Rejects with a `TimeoutError` (a
  * `DOMException`, like `AbortSignal.timeout()` would give); it is not an
  * `ArthronError`, so error interceptors and `retry` leave it alone.
  *
- * Built on `AbortController` + `setTimeout` rather than `AbortSignal.any` /
- * `AbortSignal.timeout` so it runs on Node 18.
+ * 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`.
  */
-export declare function timeout(ms: number): Plugin;
+export declare function timeout(ms: number, options?: TimeoutOptions): Plugin;
+//#endregion
+//#region src/response/schema-validation.d.ts
+/**
+ * `.json(schema)` got a body that does not match. Not an ArthronError: the
+ * request succeeded — the data is what is wrong.
+ */
+export declare class SchemaError extends Error {
+  readonly name = "SchemaError";
+  /** Every problem the validator reported, with the path to it. */
+  readonly issues: readonly SchemaIssue[];
+  constructor(issues: readonly SchemaIssue[]);
+}
 //#endregion
-export type { Arthron, ArthronConfig, ArthronPromise, ErrorInterceptor, ErrorMessageResolver, LogEvent, LoggingOptions, Middleware, Plugin, QueryParams, RequestContext, RequestInterceptor, RequestOptions, ResponseInterceptor, RetryOptions, SseEvent };
+export type { Arthron, ArthronConfig, ArthronMeta, ArthronPromise, ErrorDetailResolver, ErrorInterceptor, HeadersOption, HttpMethod, InferOutput, LogEvent, LoggingOptions, Middleware, NdjsonOptions, Plugin, QueryParams, RequestContext, RequestInitWithBody, RequestInterceptor, RequestOptions, ResponseInterceptor, RetryOptions, SchemaIssue, SseEvent, SseOptions, StandardSchemaV1, TimeoutOptions };
 //# sourceMappingURL=index.d.cts.map