arthron 1.2.0 → 2.1.0

package/dist/index.d.cts

@@ -1,13 +1,14 @@
-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.cjs";
+import { a as ResponseInterceptor, c as isArthronError, d as RequestContext, i as RequestInterceptor, l as ArthronMeta, n as Middleware, o as ArthronError, r as Plugin, s as ArthronErrorOptions, t as ErrorInterceptor, u as QueryParams } from "./shared.cjs";
 //#region src/types/response.types.d.ts
-interface ArthronPromise extends Promise<Response> {
+interface ResponsePromise 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`.
+   * The body as JSON, checked by a schema from Zod, Valibot, ArkType or any
+   * other Standard Schema library — passed as is — and typed by it. A body
+   * that does not match rejects with a `SchemaMismatchError`.
    */
-  json<S extends StandardSchemaV1>(schema: S): Promise<InferOutput<S>>;
+  json<S extends ArthronSchema>(schema: S): Promise<ArthronSchema.Infer<S>>;
   text(): Promise<string>;
   blob(): Promise<Blob>;
   arrayBuffer(): Promise<ArrayBuffer>;
@@ -17,10 +18,17 @@ interface ArthronPromise extends Promise<Response> {
   /** 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. */
+/**
+ * One server-sent event, as described by the WHATWG EventSource spec, with
+ * the names a browser `MessageEvent` uses (`type`, `data`, `lastEventId`).
+ */
 type SseEvent = {
-  /** The `event:` field, when the server sent one. */
-  event?: string;
+  /**
+   * The `event:` field; `"message"` when the server sent none, as in a
+   * browser. Any other value is the server's own name (`"update"`,
+   * `"content_block_delta"`, …).
+   */
+  type: "message" | (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. */
@@ -31,8 +39,12 @@ type SseEvent = {
    * 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;
+  /**
+   * How long in ms the server asked a client to wait before reconnecting,
+   * from its last `retry:` field (the spec's "reconnection time"); carried
+   * on every event after it.
+   */
+  reconnectionTime?: number;
 };
 type NdjsonOptions = {
   /**
@@ -41,45 +53,60 @@ type NdjsonOptions = {
    */
   maxLineLength?: number;
 };
-type SseOptions = NdjsonOptions & {
+type SseOptions = {
+  /**
+   * Longest line accepted, in characters. A longer one rejects the iteration
+   * with a RangeError and cancels the body. Default 8 Mi.
+   */
+  maxLineLength?: number;
   /**
-   * 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.
+   * Longest `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;
+  maxDataLength?: 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)`.
+ * A schema `.json(schema)` checks the body against. It is `StandardSchemaV1`
+ * from `@standard-schema/spec` (https://standardschema.dev) under arthron's
+ * name, copied as types so arthron keeps zero dependencies: pass a Zod,
+ * Valibot, ArkType or any other Standard Schema as is — there is no
+ * arthron-specific format.
  */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
+interface ArthronSchema<Input = unknown, Output = Input> {
   readonly "~standard": {
     readonly version: 1;
     readonly vendor: string;
-    readonly validate: (value: unknown) => SchemaResult<Output> | Promise<SchemaResult<Output>>;
+    readonly validate: (value: unknown) => ArthronSchema.ValidationResult<Output> | Promise<ArthronSchema.ValidationResult<Output>>;
     readonly types?: {
       readonly input: Input;
       readonly output: Output;
     } | undefined;
   };
 }
-type SchemaResult<Output> = {
-  readonly value: Output;
-  readonly issues?: undefined;
-} | {
-  readonly issues: readonly SchemaIssue[];
-};
-interface SchemaIssue {
-  readonly message: string;
-  readonly path?: readonly (PropertyKey | {
-    readonly key: PropertyKey;
-  })[] | undefined;
+declare namespace ArthronSchema {
+  /** The type a schema produces — what `.json(schema)` resolves with. */
+  type Infer<S extends ArthronSchema> = NonNullable<S["~standard"]["types"]>["output"];
+  /** One way the body does not match, with the path to it (`StandardSchemaV1.Issue`). */
+  interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+      readonly key: PropertyKey;
+    })[] | undefined;
+  }
+  /** What a schema's `validate` returns: the value, or the issues (`StandardSchemaV1.Result`). */
+  type ValidationResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+  } | {
+    readonly issues: readonly Issue[];
+  };
 }
-/** The type a schema produces. */
-type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
-type ErrorDetailResolver = (data: unknown, response: Response) => string | undefined;
+/**
+ * Extracts `ArthronError.description` from a failed response's payload
+ * (parsed: JSON if it parses, else the text).
+ */
+type DescriptionExtractor = (payload: unknown, response: Response) => string | undefined;
 //#endregion
 //#region src/client/client.types.d.ts
 /**
@@ -93,128 +120,144 @@ type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTION
  * 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;
+  /**
+   * Per-call headers: anything fetch's `headers` takes, or a record whose
+   * `null`/`undefined` values drop a client default. Not typed with
+   * `HeadersInit`: that name exists only in the DOM lib, and a Node project
+   * typed with `@types/node` alone does not have it.
+   */
+  headers?: RequestInit["headers"] | Record<string, string | null | undefined>;
+  /**
+   * The query string: `null`/`undefined` values are skipped, an array becomes
+   * repeated keys (`ids=1&ids=2`), and a `URLSearchParams` is used as is.
+   */
+  queryParams?: 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.
+   * segment: `get("/users/{id}", { pathParams: { id } })`. Interpolating ids
+   * into the path string yourself lets "../" or "?" escape the segment.
    */
-  path?: Record<string, string | number>;
+  pathParams?: 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;
+  throwOn?: (response: Response) => boolean;
 }
 /** `request()`'s options: any method, with the same body rules as `post`. */
-interface RequestInitWithBody extends RequestOptions {
+interface RequestOptionsWithMethod 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 —
+ * Client options. 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. Left out: 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 {
+interface ArthronClientOptions extends Omit<RequestInit, "body" | "method" | "headers" | "signal" | "window"> {
   /** Prefix for relative paths. Without it only absolute URLs are accepted. */
   baseURL?: string;
   /**
-   * 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.
+   * Origins an absolute URL may go to besides `baseURL`'s, as URLs of which
+   * only the origin counts: `["https://cdn.example.com"]`. Any other origin
+   * is a TypeError, so a path from user input or an API response cannot send
+   * requests elsewhere. Config `headers` go to `baseURL`'s origin only, never
+   * to these — calls there carry per-call headers alone. Without a
+   * `baseURL` this list alone limits absolute URLs, and config `headers`
+   * are refused (they would have nowhere to go); with neither, any http(s)
+   * URL goes, config headers included.
+   */
+  allowedOrigins?: readonly string[];
+  /**
+   * Default headers, sent to baseURL's origin only: anything fetch's
+   * `headers` takes, or a record. Per-call headers win, compared
+   * case-insensitively; `extend` can drop one with `null`.
+   */
+  headers?: RequestInit["headers"] | Record<string, string | null | undefined>;
+  /**
+   * The function requests are sent with: anything with fetch's signature,
+   * `(input, init) => Promise<Response>`. Default: the global `fetch`, read
+   * per call. Pass a fake in tests, a polyfill, or a framework's fetch
+   * (SvelteKit's `event.fetch`). Plugins see it as `requestContext.fetchFn`.
    */
-  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. */
-  errorDetail?: ErrorDetailResolver;
+  fetchFn?: typeof fetch;
+  /**
+   * Plugins, outermost first. One with the pluginName of an earlier one
+   * replaces it in place.
+   */
+  plugins?: readonly Plugin[];
+  /**
+   * Extracts `ArthronError.description` from a failed response's payload, for
+   * an API that puts it somewhere else:
+   * `(payload) => (payload as { errors?: { msg?: string }[] }).errors?.[0]?.msg`.
+   * Called only for failed responses; if it throws, the error simply has no
+   * description. Default: the payload's `message`, else `error` (a string),
+   * else `error.message`, else `detail`.
+   */
+  extractDescription?: DescriptionExtractor;
   /**
    * 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;
+  throwOn?: (response: 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;
+interface ArthronClient {
+  get(path: string, requestOptions?: RequestOptions): ResponsePromise;
+  delete(path: string, requestOptions?: RequestOptions): ResponsePromise;
+  head(path: string, requestOptions?: RequestOptions): ResponsePromise;
+  post(path: string, body?: unknown, requestOptions?: RequestOptions): ResponsePromise;
+  put(path: string, body?: unknown, requestOptions?: RequestOptions): ResponsePromise;
+  patch(path: string, body?: unknown, requestOptions?: RequestOptions): ResponsePromise;
   /** RFC 10008 QUERY: safe and idempotent like GET, but the query travels in the body. */
-  query(path: string, body?: unknown, init?: RequestOptions): ArthronPromise;
+  query(path: string, body?: unknown, requestOptions?: RequestOptions): ResponsePromise;
   /** Any method — the extension point for verbs without their own helper. */
-  request(path: string, init: RequestInitWithBody): ArthronPromise;
+  request(path: string, requestOptions: RequestOptionsWithMethod): ResponsePromise;
   /**
-   * 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.
+   * New client with these plugins added: a plugin replaces the one with its
+   * pluginName in place; other names append. The receiver is untouched.
    */
-  use(...plugins: Plugin[]): Arthron;
-  /** 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;
+  use(...plugins: Plugin[]): ArthronClient;
+  /** New client with these options shallow-merged, headers merged, plugins added as `use` adds them. */
+  extend(clientOptions: Partial<ArthronClientOptions>): ArthronClient;
+  /** New client without the plugins of these pluginNames. The receiver is untouched. */
+  without(...pluginNames: string[]): ArthronClient;
 }
 //#endregion
 //#region src/client/client.d.ts
 /**
- * Build a client from config. The result is immutable — `use` and `extend`
+ * Build a client from its options. 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;
+export declare function arthron(clientOptions?: ArthronClientOptions): ArthronClient;
 //#endregion
-//#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. */
-export declare const defineInterceptor: {
-  request: (interceptor: RequestInterceptor) => RequestInterceptor;
-  response: (interceptor: ResponseInterceptor) => ResponseInterceptor;
-  error: (interceptor: ErrorInterceptor) => ErrorInterceptor;
-};
-/** Identity helper: type-checks a plugin object literal without an annotation. */
-export declare const definePlugin: (plugin: Plugin) => Plugin;
+//#region src/pipeline/create-plugin.d.ts
+/**
+ * A plugin, checked where it is written and typed without annotations:
+ * `createPlugin({ pluginName: "trace", requestInterceptor: (requestContext) => … })`.
+ */
+export declare function createPlugin(plugin: Plugin): Plugin;
+/** A middleware written on its own, typed without annotations. */
+export declare const createMiddleware: (middleware: Middleware) => Middleware;
+/** A request interceptor written on its own, typed without annotations. */
+export declare const createRequestInterceptor: (interceptor: RequestInterceptor) => RequestInterceptor;
+/** A response interceptor written on its own, typed without annotations. */
+export declare const createResponseInterceptor: (interceptor: ResponseInterceptor) => ResponseInterceptor;
+/** An error interceptor written on its own, typed without annotations. */
+export declare const createErrorInterceptor: (interceptor: ErrorInterceptor) => ErrorInterceptor;
 //#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.
+ * `.json(schema)` got a body that does not match the schema. Not an
+ * ArthronError: the request succeeded — the data is what is wrong.
  */
-export declare class SchemaError extends Error {
-  readonly name = "SchemaError";
+export declare class SchemaMismatchError extends Error {
+  readonly name = "SchemaMismatchError";
   /** Every problem the validator reported, with the path to it. */
-  readonly issues: readonly SchemaIssue[];
-  constructor(issues: readonly SchemaIssue[]);
+  readonly issues: readonly ArthronSchema.Issue[];
+  constructor(issues: readonly ArthronSchema.Issue[]);
 }
 //#endregion
-//#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.cts.map
+export { type ArthronClient, type ArthronClientOptions, ArthronError, type ArthronErrorOptions, type ArthronMeta, type ArthronSchema, type DescriptionExtractor, type ErrorInterceptor, type HttpMethod, type Middleware, type NdjsonOptions, type Plugin, type QueryParams, type RequestContext, type RequestInterceptor, type RequestOptions, type RequestOptionsWithMethod, type ResponseInterceptor, type ResponsePromise, type SseEvent, type SseOptions, isArthronError };