@askrjs/fetch 0.2.0 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@
 
 Function-first HTTP contracts, typed clients, codecs, and middleware for Askr. The package is
 ESM-only, has no runtime dependencies, and works with the standard Fetch APIs in modern browsers
-and Node.js 20.19 or newer.
+and Node.js 24 or newer.
 
 ## Install
 
@@ -46,6 +46,12 @@ if (result.ok) {
 Paths use OpenAPI-style `{name}` parameters. Colon parameters and wildcards are rejected. A path
 parameter declaration must exactly match the names in the path.
 
+Path values are runtime-validated or transformed only when their `.params()` entry includes a
+validator. The generic in `.params<T>()` is a compile-time contract and is erased at runtime; using
+`.params<T>()` without validators, or relying on auto-derived path parameters, only checks that
+required names are present. Supply a validator for every path value when runtime safety or coercion
+is required.
+
 Every call returns a discriminated result instead of throwing for request, transport, HTTP, or
 decode failures. Use `unwrap(result)` when exception-based control flow is more convenient.
 
@@ -63,6 +69,20 @@ The built-in codecs are:
 - `empty()`
 - `content({ mediaType: codec })`
 
+For outbound bodies with more than one `content()` variant, pass
+`bodyMediaType` explicitly. Single-variant codecs select their only variant
+automatically:
+
+```ts
+await client.createDocument({
+  body: "plain text",
+  bodyMediaType: "text/plain",
+});
+```
+
+An omitted or unknown media type produces a `request` failure, so declaration
+order never selects a multi-variant request format.
+
 A validator only needs a `safeParse(value)` method, so schema libraries with that contract can be
 used without an adapter. Validators run for request bodies, path parameters, query parameters,
 headers, and decoded response bodies. Successful validator transformations are used for
@@ -139,10 +159,12 @@ sequence is intentional. Logging redacts common credential names as well as arbi
 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. 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.
+`429`, `500`, `502`, `503`, and `504`. Valid `Retry-After` values are honored up to
+`maxRetryAfter` (60 seconds by default); malformed values use the normal backoff. 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

package/dist/client.d.ts

@@ -9,6 +9,8 @@ interface AdHocCall {
   querySpec?: ParameterMap;
   body?: unknown;
   bodyCodec?: Codec;
+  /** Explicit media type used to encode a request body with a multi-variant `content()` codec. */
+  bodyMediaType?: string;
   response?: Codec;
   responses?: Readonly<Record<number, Codec>>;
   errors?: Partial<Record<number | "default", Codec>>;
@@ -33,6 +35,7 @@ type InputParts<D> = D extends EndpointDescriptor<infer P, infer Q, infer H, inf
 type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K; }[keyof T];
 type Container<K extends string, T, Always extends boolean = false> = [T] extends [undefined] ? {} : Always extends true ? { [P in K]: T; } : RequiredKeys<T> extends never ? { [P in K]?: T; } : { [P in K]: T; };
 type EndpointInput<D extends AnyEndpointDescriptor> = Container<"params", InputParts<D>["params"], true> & Container<"query", InputParts<D>["query"]> & Container<"headers", InputParts<D>["headers"]> & Container<"body", InputParts<D>["body"], true> & {
+  bodyMediaType?: string;
   signal?: AbortSignal;
   timeout?: number;
 };

package/dist/client.js

@@ -38,7 +38,7 @@ async function decode(response, codec) {
 	}
 	return value;
 }
-function encode(value, codec, headers) {
+function encode(value, codec, headers, requestedMediaType) {
 	if (codec.validator) {
 		const parsed = codec.validator.safeParse(value);
 		if (!parsed.success) throw parsed.error;
@@ -60,10 +60,14 @@ function encode(value, codec, headers) {
 		case "arrayBuffer":
 		case "stream": return value;
 		case "content": {
-			const [type, selected] = Object.entries(codec.variants ?? {})[0] ?? [];
-			if (!selected) throw new TypeError("content() has no variants");
+			const variants = Object.entries(codec.variants ?? {});
+			if (variants.length === 0) throw new TypeError("content() has no variants");
+			const type = requestedMediaType?.split(";", 1)[0]?.trim().toLowerCase();
+			const [selectedType, selected] = type ? [type, codec.variants?.[type]] : variants.length === 1 ? variants[0] : [];
+			if (type && !selected) throw new TypeError(`No content() request variant for media type ${type}`);
+			if (!selected) throw new TypeError("Multi-variant content() request bodies require bodyMediaType");
 			const body = encode(value, selected, headers);
-			if (selected.kind !== "multipart") headers.set("content-type", type);
+			if (selected.kind !== "multipart") headers.set("content-type", selectedType);
 			return body;
 		}
 	}
@@ -163,7 +167,7 @@ function createFetch(options = {}) {
 		}
 		let body;
 		try {
-			if (call.bodyCodec) body = encode(call.body, call.bodyCodec, headers);
+			if (call.bodyCodec) body = encode(call.body, call.bodyCodec, headers, call.bodyMediaType);
 		} catch (error) {
 			return failure("request", error, url);
 		}
@@ -289,6 +293,7 @@ function createClient(api, options = {}) {
 			querySpec: endpoint.query,
 			body: input.body,
 			bodyCodec: endpoint.body,
+			bodyMediaType: input.bodyMediaType,
 			responses: endpoint.responses,
 			errors: endpoint.errors,
 			signal: input.signal,

package/dist/dsl.d.ts

@@ -22,6 +22,10 @@ declare const STATE: unique symbol;
  */
 interface EndpointBuilder<P = undefined, Q = undefined, H = undefined, B = undefined, R extends Responses = {}, E extends Errors = {}> {
   readonly [STATE]: State;
+  /**
+   * Declares path parameter types and optional runtime validators. Generic types are erased;
+   * runtime validation occurs only for entries whose specification includes a validator.
+   */
   params<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<T, Q, H, B, R, E>;
   query<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<P, T, H, B, R, E>;
   headers<T extends Record<string, unknown>>(spec?: ParameterMap): EndpointBuilder<P, Q, T, B, R, E>;

package/dist/middleware.d.ts

@@ -28,6 +28,8 @@ interface RetryOptions {
   statuses?: readonly number[];
   /** Computes the delay (ms) before the given retry attempt, if no `Retry-After` header is present. */
   delay?: (attempt: number) => number;
+  /** Maximum delay (ms) accepted from `Retry-After`. Defaults to 60 seconds. */
+  maxRetryAfter?: number;
 }
 /**
  * Middleware that retries failed requests. Retries eligible methods on network failures

package/dist/middleware.js

@@ -72,6 +72,8 @@ function retry(options = {}) {
 		503,
 		504
 	];
+	const maxRetryAfter = options.maxRetryAfter ?? 6e4;
+	if (!Number.isFinite(maxRetryAfter) || maxRetryAfter < 0) throw new TypeError("maxRetryAfter must be a non-negative finite number");
 	return async (context, next) => {
 		if (!methods.includes(context.request.method)) return next(context);
 		if (context.replayableBody === false) return next(context);
@@ -84,8 +86,10 @@ function retry(options = {}) {
 		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;
-			const wait = retryAfter ? /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1e3 : Math.max(0, Date.parse(retryAfter) - Date.now()) : options.delay?.(attempt) ?? 100 * 2 ** (attempt - 2);
-			if (context.deadline && Date.now() + wait >= context.deadline) break;
+			const fallback = () => options.delay?.(attempt) ?? 100 * 2 ** (attempt - 2);
+			const parsedRetryAfter = retryAfter ? /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1e3 : Math.max(0, Date.parse(retryAfter) - Date.now()) : void 0;
+			const wait = parsedRetryAfter === void 0 || !Number.isFinite(parsedRetryAfter) ? fallback() : Math.min(parsedRetryAfter, maxRetryAfter);
+			if (context.deadline !== void 0 && Date.now() + wait >= context.deadline) break;
 			if (!await new Promise((resolve) => {
 				const onAbort = () => {
 					clearTimeout(timer);

package/package.json

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