@askrjs/fetch 0.0.5 → 0.0.6

package/README.md

@@ -108,6 +108,10 @@ get("/search")
   .returns(json());
 ```
 
+Query serialization treats `null` as the literal `null` and `NaN` as the literal `NaN`, whether
+the value is scalar or array-wrapped. `undefined` is omitted in both positions. This avoids
+silently turning scalar `null` into an empty string or array-wrapped `undefined` into text.
+
 ## Middleware
 
 Import middleware from the dedicated subpath:
@@ -119,21 +123,32 @@ import { bearerAuth, logging, retry, telemetry } from "@askrjs/fetch/middleware"
 const client = createClient(api, {
   baseUrl: "https://api.example.com",
   middleware: [
+    retry({ attempts: 3 }),
     bearerAuth({ token: () => session.accessToken }),
     logging(),
     telemetry(hooks),
-    retry({ attempts: 3 }),
   ],
 });
 ```
 
-Middleware runs outward in declaration order. The package includes bearer and API-key auth,
-idempotent-method retries, redacted structured logging, and telemetry hooks. Logging redacts common
-credential names as well as arbitrary header or query names added by `apiKeyAuth()`.
+Middleware is a linear onion and runs outward in declaration order. Middleware after `retry()`
+runs once per attempt; middleware before it runs once around the complete retry sequence. Put
+token-refreshing authentication, per-attempt logging, and per-attempt telemetry after `retry()` as
+shown above. Put aggregate timing or logging before `retry()` when one observation for the complete
+sequence is intentional. Logging redacts common credential names as well as arbitrary header or
+query names added by `apiKeyAuth()`.
 
 Retries default to `GET`, `HEAD`, `PUT`, `DELETE`, and `OPTIONS`, and to statuses `408`, `425`,
-`429`, `500`, `502`, `503`, and `504`. `Retry-After` is honored when present. Requests with bodies
-are not retried automatically.
+`429`, `500`, `502`, `503`, and `504`. `Retry-After` is honored when present. Cloneable request
+bodies are replayed with the original bytes and headers. `ReadableStream` bodies are explicitly
+single-attempt so retry does not buffer an unbounded stream. If an earlier middleware has already
+consumed any body, retry also sends it once and does not surface an incidental cloning error.
+
+Do not include a status such as `401` in `retry()` when an upstream authentication middleware
+already handles that status. The outer authentication layer cannot react until retry's complete
+inner attempt loop returns, so including `401` would spend the retry budget on the same upstream
+credentials. Prefer the order above so credentials resolve per attempt, or let the authentication
+middleware own `401` without adding it to retry's statuses.
 
 ## Cancellation and timeouts
 

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { AnyEndpointDescriptor, ApiDefinition, ClientOptions, Codec, EndpointDescriptor, FailureResult, FetchResult, HttpResult, InferCodec, ParameterMap, SuccessResult } from "./types.js";
 //#region src/client.d.ts
+/** A one-off, untyped request description accepted by {@link createFetch}'s returned function. */
 interface AdHocCall {
   url: string;
   method?: string;
@@ -16,6 +17,12 @@ interface AdHocCall {
   endpoint?: EndpointDescriptor;
   operationId?: string;
 }
+/**
+ * Creates a low-level fetch function that builds a `Request` from an {@link AdHocCall},
+ * runs it through the configured middleware chain, and decodes the response with the
+ * matching codec. Used internally by {@link createClient}, and usable directly for
+ * requests without a full {@link EndpointDescriptor}.
+ */
 declare function createFetch(options?: ClientOptions): (call: AdHocCall) => Promise<FetchResult>;
 type InputParts<D> = D extends EndpointDescriptor<infer P, infer Q, infer H, infer B, any, any> ? {
   params: P;
@@ -31,10 +38,18 @@ type EndpointInput<D extends AnyEndpointDescriptor> = Container<"params", InputP
 };
 type Successes<D> = D extends EndpointDescriptor<any, any, any, any, infer R, any> ? { [S in keyof R & number]: SuccessResult<InferCodec<R[S]>, S>; }[keyof R & number] : never;
 type Errors<D> = D extends EndpointDescriptor<any, any, any, any, any, infer E> ? { [S in Exclude<keyof E, "default"> & number]: HttpResult<InferCodec<NonNullable<E[S]>>, S>; }[Exclude<keyof E, "default"> & number] | ("default" extends keyof E ? HttpResult<InferCodec<NonNullable<E["default"]>>, number> : never) : never;
+/** The possible results of calling a typed client method for endpoint descriptor `D`. */
 type ClientResult<D extends AnyEndpointDescriptor> = Successes<D> | Errors<D> | FailureResult;
 type ClientMethod<D extends AnyEndpointDescriptor> = RequiredKeys<EndpointInput<D>> extends never ? (input?: EndpointInput<D>) => Promise<ClientResult<D>> : (input: EndpointInput<D>) => Promise<ClientResult<D>>;
+/** A fully-typed client for an {@link ApiDefinition}, with one method per endpoint. */
 type ApiClient<A extends ApiDefinition> = Readonly<{ [K in keyof A["endpoints"]]: ClientMethod<A["endpoints"][K]>; }>;
+/**
+ * Builds a typed {@link ApiClient} from an {@link ApiDefinition}. Each endpoint becomes
+ * a method that fills in the path, query, header, and body parameters, executes the
+ * request via {@link createFetch}, and returns a {@link ClientResult}.
+ */
 declare function createClient<A extends ApiDefinition>(api: A, options?: ClientOptions): ApiClient<A>;
+/** An `Error` thrown by {@link unwrap} that wraps a failed (non-`ok`) {@link FetchResult}. */
 declare class FetchError extends Error {
   readonly result: Exclude<FetchResult, {
     ok: true;
@@ -43,6 +58,10 @@ declare class FetchError extends Error {
     ok: true;
   }>);
 }
+/**
+ * Returns the data of a successful {@link FetchResult}, or throws a {@link FetchError}
+ * wrapping the result if it was not `ok`.
+ */
 declare function unwrap<T>(result: FetchResult<T>): T;
 //#endregion
 export { AdHocCall, ApiClient, ClientResult, FetchError, createClient, createFetch, unwrap };

package/dist/client.js

@@ -98,8 +98,10 @@ function pathParameter(name, value, spec = {}) {
 function queryParameter(output, name, value, spec = {}) {
 	const style = spec.style ?? "form";
 	const explode = spec.explode ?? true;
-	const object = entries(value);
+	const object = entries(value).filter(([, item]) => item !== void 0);
 	const array = Array.isArray(value);
+	const emptyArray = array && value.length === 0;
+	const items = values(value).filter((item) => item !== void 0).map(String);
 	const append = (key, item) => output.append(key, String(item));
 	if (style === "deepObject") {
 		if (!object.length) throw new TypeError(`deepObject query parameter ${name} must be an object`);
@@ -108,17 +110,17 @@ function queryParameter(output, name, value, spec = {}) {
 	}
 	if (style === "spaceDelimited" || style === "pipeDelimited") {
 		if (!array) throw new TypeError(`${style} query parameter ${name} must be an array`);
-		append(name, values(value).join(style === "spaceDelimited" ? " " : "|"));
+		if (items.length || emptyArray) append(name, items.join(style === "spaceDelimited" ? " " : "|"));
 		return;
 	}
 	if (style !== "form") throw new TypeError(`Unsupported query parameter style: ${style}`);
 	if (object.length) {
 		if (explode) for (const [key, item] of object) append(key, item);
-		else append(name, object.flatMap(([key, item]) => [key, item]).join(","));
+		else append(name, object.flatMap(([key, item]) => [key, String(item)]).join(","));
 		return;
 	}
-	if (array && explode) for (const item of values(value)) append(name, item);
-	else append(name, values(value).join(","));
+	if (array && explode) for (const item of items) append(name, item);
+	else if (items.length || emptyArray) append(name, items.join(","));
 }
 function headerParameter(value, spec = {}) {
 	if ((spec.style ?? "simple") !== "simple") throw new TypeError(`Unsupported header parameter style: ${spec.style}`);
@@ -138,6 +140,12 @@ const parameterValue = (map, name, value) => {
 	if (!parsed.success) throw parsed.error;
 	return parsed.data;
 };
+/**
+* Creates a low-level fetch function that builds a `Request` from an {@link AdHocCall},
+* runs it through the configured middleware chain, and decodes the response with the
+* matching codec. Used internally by {@link createClient}, and usable directly for
+* requests without a full {@link EndpointDescriptor}.
+*/
 function createFetch(options = {}) {
 	return async (call) => {
 		let url = `${options.baseUrl?.replace(/\/$/, "") ?? ""}${call.url}`;
@@ -236,6 +244,7 @@ function createFetch(options = {}) {
 				operationId: call.operationId,
 				security: call.endpoint?.security,
 				attempt: 1,
+				...body === void 0 ? {} : { replayableBody: !(body instanceof ReadableStream) },
 				...timeout === void 0 ? {} : { deadline: Date.now() + timeout }
 			}));
 		} finally {
@@ -243,6 +252,11 @@ function createFetch(options = {}) {
 		}
 	};
 }
+/**
+* Builds a typed {@link ApiClient} from an {@link ApiDefinition}. Each endpoint becomes
+* a method that fills in the path, query, header, and body parameters, executes the
+* request via {@link createFetch}, and returns a {@link ClientResult}.
+*/
 function createClient(api, options = {}) {
 	const execute = createFetch(options);
 	const methods = Object.fromEntries(Object.entries(api.endpoints).map(([id, endpoint]) => [id, async (input = {}) => {
@@ -283,6 +297,7 @@ function createClient(api, options = {}) {
 	}]));
 	return Object.freeze(methods);
 }
+/** An `Error` thrown by {@link unwrap} that wraps a failed (non-`ok`) {@link FetchResult}. */
 var FetchError = class extends Error {
 	result;
 	constructor(result) {
@@ -291,6 +306,10 @@ var FetchError = class extends Error {
 		this.name = "FetchError";
 	}
 };
+/**
+* Returns the data of a successful {@link FetchResult}, or throws a {@link FetchError}
+* wrapping the result if it was not `ok`.
+*/
 function unwrap(result) {
 	if (!result.ok) throw new FetchError(result);
 	return result.data;

package/dist/codecs.d.ts

@@ -1,14 +1,27 @@
 import { Codec, Validator } from "./types.js";
 //#region src/codecs.d.ts
+/** Creates a JSON codec, matching `application/json` and `+json` suffixed media types. */
 declare function json<T = unknown>(): Codec<T>;
+/** Creates a JSON codec that validates/parses the decoded value with the given schema. */
 declare function json<V extends Validator>(schema: V): Codec<V extends Validator<infer T> ? T : never>;
+/** Creates a codec for plain text bodies (`text/*`), decoded as a string. */
 declare const text: () => Codec<string>;
+/** Creates a codec for `application/x-www-form-urlencoded` bodies, decoded as `URLSearchParams`. */
 declare const urlEncoded: () => Codec<URLSearchParams>;
+/** Creates a codec for `multipart/form-data` bodies, decoded as `FormData`. */
 declare const multipart: () => Codec<FormData>;
+/** Creates a codec that decodes any response body as a `Blob`. */
 declare const blob: () => Codec<Blob>;
+/** Creates a codec that decodes any response body as an `ArrayBuffer`. */
 declare const arrayBuffer: () => Codec<ArrayBuffer>;
+/** Creates a codec that exposes the raw response body as a `ReadableStream`, without buffering it. */
 declare const stream: () => Codec<ReadableStream<Uint8Array>>;
+/** Creates a codec for bodies expected to be empty (e.g. 204 No Content), decoded as `undefined`. */
 declare const empty: () => Codec<undefined>;
+/**
+ * Creates a content-negotiated codec that selects among `variants` by the response's
+ * media type, decoding with whichever variant matches.
+ */
 declare const content: <T extends Record<string, Codec>>(variants: T) => Codec<{ [K in keyof T]: T[K] extends Codec<infer V> ? V : never; }[keyof T]>;
 //#endregion
 export { arrayBuffer, blob, content, empty, json, multipart, stream, text, urlEncoded };

package/dist/codecs.js

@@ -7,13 +7,24 @@ const codec = (kind, mediaTypes, validator) => Object.freeze({
 function json(schema) {
 	return codec("json", ["application/json", "+json"], schema);
 }
+/** Creates a codec for plain text bodies (`text/*`), decoded as a string. */
 const text = () => codec("text", ["text/*"]);
+/** Creates a codec for `application/x-www-form-urlencoded` bodies, decoded as `URLSearchParams`. */
 const urlEncoded = () => codec("urlEncoded", ["application/x-www-form-urlencoded"]);
+/** Creates a codec for `multipart/form-data` bodies, decoded as `FormData`. */
 const multipart = () => codec("multipart", ["multipart/form-data"]);
+/** Creates a codec that decodes any response body as a `Blob`. */
 const blob = () => codec("blob", ["*/*"]);
+/** Creates a codec that decodes any response body as an `ArrayBuffer`. */
 const arrayBuffer = () => codec("arrayBuffer", ["*/*"]);
+/** Creates a codec that exposes the raw response body as a `ReadableStream`, without buffering it. */
 const stream = () => codec("stream", ["*/*"]);
+/** Creates a codec for bodies expected to be empty (e.g. 204 No Content), decoded as `undefined`. */
 const empty = () => codec("empty", []);
+/**
+* Creates a content-negotiated codec that selects among `variants` by the response's
+* media type, decoding with whichever variant matches.
+*/
 const content = (variants) => Object.freeze({
 	kind: "content",
 	mediaTypes: Object.freeze(Object.keys(variants).sort()),

package/dist/dsl.d.ts

@@ -1,5 +1,11 @@
 import { AnyEndpointDescriptor, ApiDefinition, ApiMetadata, Codec, EndpointDescriptor, ParameterMap } from "./types.js";
 //#region src/dsl.d.ts
+/**
+ * Extracts the ordered list of `{param}` placeholder names from an endpoint path.
+ *
+ * @throws {TypeError} If the path uses colon/wildcard syntax, has malformed
+ * `{...}` placeholders, or contains a duplicate parameter name.
+ */
 declare function pathNames(path: string): string[];
 type Responses = Record<number, Codec>;
 type Errors = Partial<Record<number | "default", Codec>>;
@@ -8,6 +14,12 @@ type State = Omit<EndpointDescriptor, "responses" | "errors"> & {
   errors: Errors;
 };
 declare const STATE: unique symbol;
+/**
+ * Fluent, immutable builder for describing a single endpoint's params, query,
+ * headers, body, responses, errors, and security requirements. Each method
+ * returns a new builder reflecting the added configuration; the accumulated
+ * state is finalized into an {@link EndpointDescriptor} by {@link defineApi}.
+ */
 interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Responses = {}, E extends Errors = {}> {
   readonly [STATE]: State;
   params<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<T, Q, H, B, R, E>;
@@ -19,15 +31,32 @@ interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undef
   errors<T extends Errors>(spec: T): EndpointBuilder<P, Q, H, B, R, E & T>;
   security(requirements: readonly Readonly<Record<string, readonly string[]>>[]): EndpointBuilder<P, Q, H, B, R, E>;
 }
+/** Starts building a GET endpoint at the given path. */
 declare const get: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building a POST endpoint at the given path. */
 declare const post: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building a PUT endpoint at the given path. */
 declare const put: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building a PATCH endpoint at the given path. */
 declare const patch: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building a DELETE endpoint at the given path. */
 declare const del: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building a HEAD endpoint at the given path. */
 declare const head: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
+/** Starts building an OPTIONS endpoint at the given path. */
 declare const options: (path: string) => EndpointBuilder<undefined, undefined, undefined, undefined, {}, {}>;
 type DescriptorOf<T> = T extends EndpointBuilder<infer P, infer Q, infer H, infer B, infer R, infer E> ? EndpointDescriptor<P, Q, H, B, R, E> : T extends AnyEndpointDescriptor ? T : never;
 type Defined<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>> = { [K in keyof E]: DescriptorOf<E[K]>; };
+/**
+ * Finalizes a map of {@link EndpointBuilder}s and/or raw {@link EndpointDescriptor}s into
+ * a frozen {@link ApiDefinition}, stamping each endpoint's `operationId` from its key and
+ * deep-freezing its parameters, security, responses, and errors.
+ *
+ * @example
+ * const api = defineApi({
+ *   getUser: get("/users/{id}").returns(json()),
+ * });
+ */
 declare function defineApi<E extends Record<string, AnyEndpointDescriptor | EndpointBuilder>>(endpoints: E, metadata?: ApiMetadata): ApiDefinition<Defined<E>>;
 //#endregion
 export { EndpointBuilder, defineApi, del, get, head, options, patch, pathNames, post, put };

package/dist/dsl.js

@@ -1,5 +1,11 @@
 //#region src/dsl.ts
 const PATH_NAME = /^[A-Za-z_$][\w$]*$/;
+/**
+* Extracts the ordered list of `{param}` placeholder names from an endpoint path.
+*
+* @throws {TypeError} If the path uses colon/wildcard syntax, has malformed
+* `{...}` placeholders, or contains a duplicate parameter name.
+*/
 function pathNames(path) {
 	if (path.includes(":") || path.includes("*")) throw new TypeError(`Invalid path syntax: ${path}`);
 	const names = [];
@@ -69,12 +75,19 @@ const method = (value) => (path) => {
 		errors: {}
 	});
 };
+/** Starts building a GET endpoint at the given path. */
 const get = method("GET");
+/** Starts building a POST endpoint at the given path. */
 const post = method("POST");
+/** Starts building a PUT endpoint at the given path. */
 const put = method("PUT");
+/** Starts building a PATCH endpoint at the given path. */
 const patch = method("PATCH");
+/** Starts building a DELETE endpoint at the given path. */
 const del = method("DELETE");
+/** Starts building a HEAD endpoint at the given path. */
 const head = method("HEAD");
+/** Starts building an OPTIONS endpoint at the given path. */
 const options = method("OPTIONS");
 const snapshotParameters = (parameters) => parameters ? Object.freeze(Object.fromEntries(Object.entries(parameters).map(([name, definition]) => [name, definition && typeof definition === "object" && !("safeParse" in definition) ? Object.freeze({ ...definition }) : definition]))) : void 0;
 const snapshotSecurity = (security) => security ? Object.freeze(security.map((requirement) => Object.freeze(Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [name, Object.freeze([...scopes])]))))) : void 0;
@@ -84,6 +97,16 @@ const snapshotMetadata = (metadata) => Object.freeze({
 	...metadata.tags ? { tags: Object.freeze([...metadata.tags]) } : {},
 	...metadata.securitySchemes ? { securitySchemes: Object.freeze({ ...metadata.securitySchemes }) } : {}
 });
+/**
+* Finalizes a map of {@link EndpointBuilder}s and/or raw {@link EndpointDescriptor}s into
+* a frozen {@link ApiDefinition}, stamping each endpoint's `operationId` from its key and
+* deep-freezing its parameters, security, responses, and errors.
+*
+* @example
+* const api = defineApi({
+*   getUser: get("/users/{id}").returns(json()),
+* });
+*/
 function defineApi(endpoints, metadata) {
 	const frozen = Object.fromEntries(Object.entries(endpoints).map(([id, value]) => {
 		const endpoint = STATE in value ? value[STATE] : value;

package/dist/middleware.d.ts

@@ -1,28 +1,64 @@
 import { FetchResult, Middleware, RequestContext } from "./types.js";
 //#region src/middleware.d.ts
+/**
+ * Middleware that attaches an `Authorization: Bearer <token>` header to every request.
+ * `token` may be a static string or a (possibly async) function resolved on each request.
+ */
 declare const bearerAuth: ({ token }: {
   token: string | (() => string | Promise<string>);
 }) => Middleware;
+/**
+ * Middleware that attaches an API key to every request, either as a header or a query
+ * parameter (`in`, default `"header"`). `value` may be a static string or a (possibly
+ * async) function resolved on each request. The key is marked sensitive so the
+ * {@link logging} middleware redacts it.
+ */
 declare function apiKeyAuth({ key, value, in: location }: {
   key: string;
   value: string | (() => string | Promise<string>);
   in?: "header" | "query";
 }): Middleware;
+/** Options controlling the {@link retry} middleware's behavior. */
 interface RetryOptions {
+  /** Maximum number of attempts, including the first. Defaults to 3. */
   attempts?: number;
+  /** HTTP methods eligible for retry. Defaults to idempotent-by-convention methods. */
   methods?: readonly string[];
+  /** Response statuses that trigger a retry. Defaults to common transient failure codes. */
   statuses?: readonly number[];
+  /** Computes the delay (ms) before the given retry attempt, if no `Retry-After` header is present. */
   delay?: (attempt: number) => number;
 }
+/**
+ * Middleware that retries failed requests. Retries eligible methods on network failures
+ * or eligible response statuses, honoring a `Retry-After` header when present and
+ * stopping early if the request's deadline would be exceeded. A non-streaming request body
+ * is replayed only when it can be cloned before the first attempt; streaming, already-consumed,
+ * or otherwise non-cloneable bodies are sent once without retrying.
+ */
 declare function retry(options?: RetryOptions): Middleware;
+/**
+ * Middleware that logs a `"request"` event before and a `"response"` event after each
+ * request, via the given logger (defaults to `console`). Headers and query parameters
+ * marked sensitive (e.g. by {@link apiKeyAuth}) or matching common sensitive-name
+ * patterns (authorization, cookie, token, secret, password, api key) are redacted.
+ */
 declare function logging(logger?: {
   log(event: Record<string, unknown>): void;
 }): Middleware;
+/** Hooks invoked by the {@link telemetry} middleware around each request. */
 interface TelemetryHooks {
+  /** Called before the request proceeds; its return value (a "span") is passed to `end`/`error`. */
   start?(context: RequestContext): unknown;
+  /** Called after the request completes successfully (from this middleware's perspective). */
   end?(span: unknown, result: FetchResult): void;
+  /** Called if a downstream middleware or the transport throws. */
   error?(span: unknown, error: unknown): void;
 }
+/**
+ * Middleware that wraps each request with {@link TelemetryHooks}, calling `start` before
+ * the request, `end` after it completes, and `error` (then rethrowing) if it throws.
+ */
 declare function telemetry(hooks: TelemetryHooks): Middleware;
 //#endregion
 export { RetryOptions, TelemetryHooks, apiKeyAuth, bearerAuth, logging, retry, telemetry };

package/dist/middleware.js

@@ -21,10 +21,20 @@ const replaceHeaders = (context, mutate) => {
 		request: new Request(context.request, { headers })
 	});
 };
+/**
+* Middleware that attaches an `Authorization: Bearer <token>` header to every request.
+* `token` may be a static string or a (possibly async) function resolved on each request.
+*/
 const bearerAuth = ({ token }) => async (context, next) => {
 	const resolved = typeof token === "function" ? await token() : token;
 	return next(replaceHeaders(context, (headers) => headers.set("authorization", `Bearer ${resolved}`)));
 };
+/**
+* Middleware that attaches an API key to every request, either as a header or a query
+* parameter (`in`, default `"header"`). `value` may be a static string or a (possibly
+* async) function resolved on each request. The key is marked sensitive so the
+* {@link logging} middleware redacts it.
+*/
 function apiKeyAuth({ key, value, in: location = "header" }) {
 	return async (context, next) => {
 		const resolved = typeof value === "function" ? await value() : value;
@@ -37,6 +47,13 @@ function apiKeyAuth({ key, value, in: location = "header" }) {
 		}), "query", key));
 	};
 }
+/**
+* Middleware that retries failed requests. Retries eligible methods on network failures
+* or eligible response statuses, honoring a `Retry-After` header when present and
+* stopping early if the request's deadline would be exceeded. A non-streaming request body
+* is replayed only when it can be cloned before the first attempt; streaming, already-consumed,
+* or otherwise non-cloneable bodies are sent once without retrying.
+*/
 function retry(options = {}) {
 	const attempts = options.attempts ?? 3;
 	const methods = options.methods ?? [
@@ -56,7 +73,14 @@ function retry(options = {}) {
 		504
 	];
 	return async (context, next) => {
-		if (!methods.includes(context.request.method) || context.request.body) return next(context);
+		if (!methods.includes(context.request.method)) return next(context);
+		if (context.replayableBody === false) return next(context);
+		let replayable;
+		if (context.request.body) try {
+			replayable = context.request.clone();
+		} catch {
+			return next(context);
+		}
 		let result = await next(context);
 		for (let attempt = 2; attempt <= attempts && !result.ok && (result.kind === "network" || result.response !== void 0 && statuses.includes(result.status)); attempt++) {
 			const retryAfter = "response" in result ? result.response?.headers.get("retry-after") : null;
@@ -81,10 +105,16 @@ function retry(options = {}) {
 				headers: new Headers(),
 				url: context.request.url
 			};
+			let request;
+			try {
+				request = (replayable ?? context.request).clone();
+			} catch {
+				break;
+			}
 			result = await next(Object.freeze({
 				...context,
 				attempt,
-				request: context.request.clone()
+				request
 			}));
 		}
 		return result;
@@ -101,6 +131,12 @@ const redactedUrl = (value, names = []) => {
 	}
 	return url.toString();
 };
+/**
+* Middleware that logs a `"request"` event before and a `"response"` event after each
+* request, via the given logger (defaults to `console`). Headers and query parameters
+* marked sensitive (e.g. by {@link apiKeyAuth}) or matching common sensitive-name
+* patterns (authorization, cookie, token, secret, password, api key) are redacted.
+*/
 function logging(logger = console) {
 	return async (context, next) => {
 		const sensitive = context[SENSITIVE];
@@ -123,6 +159,10 @@ function logging(logger = console) {
 		return result;
 	};
 }
+/**
+* Middleware that wraps each request with {@link TelemetryHooks}, calling `start` before
+* the request, `end` after it completes, and `error` (then rethrowing) if it throws.
+*/
 function telemetry(hooks) {
 	return async (context, next) => {
 		const span = hooks.start?.(context);

package/dist/types.d.ts

@@ -1,4 +1,8 @@
 //#region src/types.d.ts
+/**
+ * A minimal schema-validation contract, compatible with libraries such as Zod
+ * that expose a `safeParse` method (e.g. via a thin adapter).
+ */
 interface Validator<T = unknown> {
   safeParse(value: unknown): {
     success: true;
@@ -8,22 +12,38 @@ interface Validator<T = unknown> {
     error: unknown;
   };
 }
+/** Infers the parsed output type `T` from a {@link Validator}. */
 type InferValidator<V> = V extends Validator<infer T> ? T : never;
+/**
+ * Describes how a request or response body is serialized/deserialized:
+ * which wire format (`kind`), which media types it matches, and optionally
+ * a {@link Validator} to parse/validate the decoded value.
+ */
 interface Codec<T = unknown> {
   readonly kind: "json" | "text" | "urlEncoded" | "multipart" | "blob" | "arrayBuffer" | "stream" | "empty" | "content";
   readonly mediaTypes: readonly string[];
   readonly validator?: Validator<T>;
+  /** For `kind: "content"`, the per-media-type codec variants. */
   readonly variants?: Readonly<Record<string, Codec<unknown>>>;
 }
+/** Infers the decoded value type `T` from a {@link Codec}. */
 type InferCodec<C> = C extends Codec<infer T> ? T : never;
+/** The set of HTTP methods supported by endpoint descriptors. */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/** OpenAPI-style serialization styles for path, query, and header parameters. */
 type ParameterStyle = "simple" | "label" | "matrix" | "form" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+/** Serialization and validation settings for a single path, query, or header parameter. */
 interface ParameterSpec<T = unknown> {
   readonly validator?: Validator<T>;
   readonly style?: ParameterStyle;
   readonly explode?: boolean;
 }
+/**
+ * Maps parameter names to either a bare {@link Validator} or a full
+ * {@link ParameterSpec} describing serialization and validation.
+ */
 type ParameterMap = Readonly<Record<string, Validator<unknown> | ParameterSpec | undefined>>;
+/** Describes a single API endpoint: its method, path, parameters, body, and possible responses. */
 interface EndpointDescriptor<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Record<number, Codec> = Record<number, Codec>, E extends Partial<Record<number | "default", Codec>> = Partial<Record<number | "default", Codec>>> {
   readonly method: HttpMethod;
   readonly path: string;
@@ -42,7 +62,9 @@ interface EndpointDescriptor<P = undefined, Q = undefined, H = undefined, B = un
     body: B;
   };
 }
+/** An {@link EndpointDescriptor} with its type parameters erased, for use in generic contexts. */
 type AnyEndpointDescriptor = EndpointDescriptor<any, any, any, any, any, any>;
+/** API-level (rather than per-endpoint) metadata, such as servers and security schemes. */
 interface ApiMetadata {
   readonly servers?: readonly (string | {
     readonly url: string;
@@ -50,10 +72,12 @@ interface ApiMetadata {
   readonly tags?: readonly unknown[];
   readonly securitySchemes?: Readonly<Record<string, unknown>>;
 }
+/** A named collection of endpoints plus optional API metadata, as produced by {@link defineApi}. */
 interface ApiDefinition<E extends Record<string, AnyEndpointDescriptor> = Record<string, AnyEndpointDescriptor>> {
   readonly endpoints: E;
   readonly metadata?: ApiMetadata;
 }
+/** A successful (2xx) fetch outcome, carrying the decoded response data. */
 type SuccessResult<T = unknown, S extends number = number> = {
   ok: true;
   kind: "success";
@@ -64,6 +88,7 @@ type SuccessResult<T = unknown, S extends number = number> = {
   url: string;
   response: Response;
 };
+/** A non-2xx fetch outcome where the server responded with a decodable error body. */
 type HttpResult<T = unknown, S extends number = number> = {
   ok: false;
   kind: "http";
@@ -74,7 +99,9 @@ type HttpResult<T = unknown, S extends number = number> = {
   url: string;
   response: Response;
 };
+/** Categorizes why a fetch could not produce an {@link HttpResult} or {@link SuccessResult}. */
 type FailureKind = "request" | "network" | "timeout" | "abort" | "decode" | "middleware";
+/** A fetch outcome that failed before or independently of receiving a decodable HTTP response. */
 type FailureResult = {
   ok: false;
   kind: FailureKind;
@@ -84,23 +111,35 @@ type FailureResult = {
   url: string;
   response?: Response;
 };
+/** The outcome of a fetch call: success, an HTTP-level error, or another kind of failure. */
 type FetchResult<T = unknown> = SuccessResult<T> | HttpResult<T> | FailureResult;
+/** The mutable-by-replacement state threaded through the middleware chain for a single request. */
 interface RequestContext {
   readonly request: Request;
   readonly endpoint?: AnyEndpointDescriptor;
   readonly operationId?: string;
   readonly security?: AnyEndpointDescriptor["security"];
+  /** 1 on the first attempt, incremented by middleware (e.g. {@link retry}) on subsequent attempts. */
   readonly attempt: number;
+  /** Whether a body was encoded from a replayable value; streaming bodies set this to `false`. */
+  readonly replayableBody?: boolean;
+  /** Absolute timestamp (ms since epoch) by which the request must complete, if a timeout is set. */
   readonly deadline?: number;
 }
+/** Invokes the next middleware in the chain, optionally passing a replacement context. */
 type Next = (context?: RequestContext) => Promise<FetchResult>;
+/** A function that can inspect/replace the request context and/or the result of calling `next`. */
 type Middleware = (context: RequestContext, next: Next) => Promise<FetchResult>;
+/** Options controlling how a {@link createClient} or {@link createFetch} client makes requests. */
 interface ClientOptions {
   baseUrl?: string;
+  /** Custom transport, defaulting to the global `fetch`. */
   fetch?: (request: Request) => Promise<Response>;
   headers?: HeadersInit;
   credentials?: RequestCredentials;
+  /** Request timeout in milliseconds. */
   timeout?: number;
+  /** Middleware chain applied to every request, in order. */
   middleware?: readonly Middleware[];
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/fetch",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Function-first typed HTTP contracts and clients for Askr.",
   "keywords": [
     "askr",