arthron 1.0.1 → 1.2.0

package/dist/index.d.mts

@@ -1,169 +1,4 @@
-//#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;
-};
-/**
- * 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.
- */
-export 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. */
-export 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
-   * "retry", "timeout" and "logging". Leave it out to always append.
-   */
-  name?: string;
-  middleware?: Middleware;
-  request?: RequestInterceptor;
-  response?: ResponseInterceptor;
-  error?: ErrorInterceptor;
-}
-//#endregion
+import { _ as ArthronMeta, a as logging$1, b as RequestContext, d as Middleware, f as Plugin, g as isArthronError, h as ArthronError, i as retry$1, m as ResponseInterceptor, n as timeout$1, o as LogEvent$1, p as RequestInterceptor, r as TimeoutOptions$1, s as LoggingOptions$1, u as ErrorInterceptor, v as HeadersOption, x as RetryOptions, y as QueryParams } from "./index-C3lylSNd.mjs";
 //#region src/types/response.types.d.ts
 interface ArthronPromise extends Promise<Response> {
   /** The body as JSON. `T` is a cast — nothing checks it. */
@@ -355,79 +190,6 @@ 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/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.
- */
-export 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`.
- */
-export declare function retry(options?: RetryOptions): Plugin;
-//#endregion
-//#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. 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.
- *
- * 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, options?: TimeoutOptions): Plugin;
-//#endregion
 //#region src/response/schema-validation.d.ts
 /**
  * `.json(schema)` got a body that does not match. Not an ArthronError: the
@@ -440,5 +202,19 @@ export declare class SchemaError extends Error {
   constructor(issues: readonly SchemaIssue[]);
 }
 //#endregion
-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 };
+//#region src/index.d.ts
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export declare const logging: typeof logging$1;
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export declare const retry: typeof retry$1;
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export declare const timeout: typeof timeout$1;
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export type LogEvent = LogEvent$1;
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export type LoggingOptions = LoggingOptions$1;
+/** @deprecated Import from "arthron/plugins"; this export goes in the next major. */
+export type TimeoutOptions = TimeoutOptions$1;
+//#endregion
+export { type Arthron, type ArthronConfig, ArthronError, type ArthronMeta, type ArthronPromise, type ErrorDetailResolver, type ErrorInterceptor, type HeadersOption, type HttpMethod, type InferOutput, type Middleware, type NdjsonOptions, type Plugin, type QueryParams, type RequestContext, type RequestInitWithBody, type RequestInterceptor, type RequestOptions, type ResponseInterceptor, type RetryOptions, type SchemaIssue, type SseEvent, type SseOptions, type StandardSchemaV1, isArthronError };
 //# sourceMappingURL=index.d.mts.map