arthron 1.0.0 → 1.0.1

package/README.md

@@ -16,7 +16,7 @@ const user = await api.get("/me").json<User>();
 - **Plain `Response` in, plain `Response` out.** No wrapper type to learn. `.json<T>()` and friends are there when you want the body.
 - **Two kinds of plugin, kept apart by the types.** Middleware wraps the request and controls the flow — it can call `next` again to retry. Interceptors transform one value and return it; they cannot retry, skip, or swallow. Auth refresh, retry, timeouts, logging, and anything that reacts to how a call ended (error pages, domain errors) are middleware. Headers, trace ids and per-attempt error details are interceptors.
 - **One error type, two causes.** `ArthronError` means the server said no (`!response.ok`) or the network failed (`status: 0`). Everything else — cancellation, a bug in a plugin — is rethrown as-is.
-- Zero dependencies. ESM and CJS. TypeScript types included. Node 22+ and browsers.
+- Zero dependencies. ESM and CJS. TypeScript types included, for TypeScript 5.0+. Node 22+ and browsers.
 
 ## Install
 
@@ -355,6 +355,7 @@ class ArthronError extends Error {
 - **Redirects follow fetch's rules.** On a redirect to another origin, fetch drops `Authorization` but keeps other headers such as `x-api-key`. Pass `redirect: "error"` (or `"manual"`) for calls that carry such keys if the server could redirect off-origin.
 - **Bodies.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams` and `ReadableStream` go through untouched — recognised by type tag, so polyfill and cross-realm instances count too. A `ReadableStream` is sent with `duplex: "half"`, which fetch requires. Anything else — including `null` — becomes JSON with `content-type: application/json`; a content type you set must be a JSON one. Bodies JSON would mangle — a `Map`, `Set`, generator, Node stream or function — are rejected with a `TypeError` that says what to pass instead. A `FormData` body is always sent without a `content-type` header, even with a JSON default, so the runtime can add the multipart boundary. `GET`/`HEAD` with a body is rejected with a `TypeError`.
 - **Fetch defaults are flat and only sent when set.** Config takes the same fetch options per-call calls do (`credentials`, `cache`, `redirect`, …) as defaults; a per-call value wins and `extend` overrides. Nothing is sent that you did not set — cross-origin cookies need `credentials: "include"`. `signal`, `body` and `method` are per call: a client-wide signal would fail every call once aborted.
+- **In browsers, CORS and the engine have the last word.** CI runs the built package in Chromium, Firefox and WebKit against a server on another origin. A JSON body, a custom header and `query()`'s QUERY method each make the browser send a preflight, so the API must allow them (`Access-Control-Allow-Methods: QUERY`, `Access-Control-Allow-Headers`). `retry()` reads `Retry-After` only if the API exposes it (`Access-Control-Expose-Headers: retry-after`); otherwise it waits its own delay. `redirect: "manual"` gives an opaque redirect (`status` 0, `type` `"opaqueredirect"`), returned rather than thrown. A `ReadableStream` body streams only over HTTP/2 (Chromium, WebKit), and the `ArthronError` for one sent to an HTTP/1.1 server says so. Where the browser cannot stream a request body at all (Firefox would send the text `"[object ReadableStream]"`), the call rejects with a `TypeError` before anything is sent. Either way, send a `Blob` or `ArrayBuffer` there.
 - **Response bodies are single-use.** A response interceptor that wants to inspect the body must `res.clone()`; one that changes it returns a new `Response`.
 - **Argument errors reject, they don't throw.** No `baseURL` with a relative path, a URL the global fetch cannot parse (`baseURL: "api.example.com"` without `https://`), a `BigInt` in a JSON body, a missing `method` in `request` — all surface as a rejected `TypeError` before anything is sent, never as a retried `status: 0`. An injected `fetch` is the judge of its own URLs: arthron does not pre-check them, so one that accepts relative URLs (SvelteKit's server-side `fetch`) works with `baseURL: "/api"`.
 
@@ -365,6 +366,10 @@ class ArthronError extends Error {
 - `examples/` holds type-checked, runnable recipes: LLM streaming, auth refresh, an error page, upload/download. `examples/recipes.test.ts` keeps the auth and error-page recipes honest.
 - Error messages state the fix (`… — pass baseURL in arthron({ baseURL }) or use an absolute URL`).
 
+## Security
+
+Report vulnerabilities privately through GitHub — see [SECURITY.md](SECURITY.md) for supported versions, response times and disclosure.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -288,6 +288,35 @@ function isReadableStream(value) {
 	return tagOf(value) === "ReadableStream";
 }
 /**
+* Whether `RequestCtor` can send a ReadableStream body. Node and Chromium
+* read `duplex` and leave the stream alone; Firefox ignores `duplex` and
+* would send the text "[object ReadableStream]"; older Safari refuses it.
+* The check from
+* https://developer.chrome.com/docs/capabilities/web-apis/fetch-streaming-requests
+*/
+function canStreamRequestBody(RequestCtor) {
+	let duplexRead = false;
+	try {
+		const request = new RequestCtor("https://stream.test", {
+			method: "POST",
+			body: new ReadableStream(),
+			get duplex() {
+				duplexRead = true;
+				return "half";
+			}
+		});
+		return duplexRead && !request.headers.has("content-type");
+	} catch {
+		return false;
+	}
+}
+let runtimeStreams;
+/** `canStreamRequestBody` for the global `Request`, checked once. */
+function runtimeStreamsRequestBody() {
+	runtimeStreams ??= typeof Request !== "function" || canStreamRequestBody(Request);
+	return runtimeStreams;
+}
+/**
 * What JSON.stringify would turn into `{}`, `undefined` or internal state
 * instead of the data — with the fix, so it reads as an error message.
 */
@@ -339,6 +368,146 @@ function serializeBody(body, headers) {
 	};
 }
 //#endregion
+//#region src/response/rebuild-response.ts
+/**
+* A new Response with `body` but everything else taken from `original`. The
+* constructor resets `url`, `redirected` and `type`, so those are copied over
+* as own properties — callers that resolve relative links or detect
+* redirects keep working.
+*/
+function rebuildResponse(original, body) {
+	return withFetchedFields(new Response(body, {
+		status: original.status,
+		statusText: original.statusText,
+		headers: original.headers
+	}), original);
+}
+/** Copy the fields the constructor resets — onto `clone()`s as well. */
+function withFetchedFields(target, from) {
+	const clone = target.clone.bind(target);
+	return Object.defineProperties(target, {
+		url: { value: from.url },
+		redirected: { value: from.redirected },
+		type: { value: from.type },
+		clone: { value: () => withFetchedFields(clone(), from) }
+	});
+}
+//#endregion
+//#region src/error/create-error.ts
+/**
+* Cancellation is not an HTTP failure. Matched by name so it works across
+* realms — or by the request's own `signal`, since `abort(reason)` rejects
+* with whatever reason the caller chose.
+*/
+function isCancellation(error, signal) {
+	if (signal?.aborted) return true;
+	const name = error?.name;
+	return name === "AbortError" || name === "TimeoutError";
+}
+/**
+* What a cancelled call rejects with: its signal's reason. WebKit's fetch
+* rejects, and errors a half-read body, with a generic AbortError instead,
+* dropping a TimeoutError or the caller's own reason.
+*/
+function cancellationError(error, signal) {
+	return signal?.aborted ? signal.reason : error;
+}
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** `message` → `error` (string) → `error.message` → `detail`. */
+function defaultErrorDetail(data) {
+	if (!isRecord(data)) return void 0;
+	if (typeof data.message === "string") return data.message;
+	if (typeof data.error === "string") return data.error;
+	if (isRecord(data.error) && typeof data.error.message === "string") return data.error.message;
+	if (typeof data.detail === "string") return data.detail;
+}
+/** How much of an error body arthron reads. Error bodies are for diagnosis; a hostile or broken server must not be able to fill memory with one. */
+const MAX_ERROR_BODY_BYTES = 65536;
+/** Up to `limit` bytes of the body; the rest is cancelled unread. `undefined` when there is no body or reading it failed. */
+async function readCapped(response, limit) {
+	if (!response.body) return void 0;
+	let reader;
+	const chunks = [];
+	let size = 0;
+	try {
+		reader = response.body.getReader();
+		while (size <= limit) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+			size += value.byteLength;
+		}
+	} catch {
+		return;
+	} finally {
+		await reader?.cancel().catch(() => {});
+		reader?.releaseLock();
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return size > limit ? {
+		bytes: bytes.subarray(0, limit),
+		truncated: true
+	} : {
+		bytes,
+		truncated: false
+	};
+}
+/** JSON if the whole body parses, else the text (cut at the limit), else `undefined` when empty. */
+function parseBody(read) {
+	const text = new TextDecoder().decode(read.bytes);
+	if (text === "") return void 0;
+	if (read.truncated) return text;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+/** The request as error messages name it: method and URL, no query or userinfo. */
+function describeRequest(request) {
+	return `${request.init.method ?? "GET"} ${redactUrl(request.url)}`;
+}
+async function responseError(response, request, resolve = defaultErrorDetail) {
+	const read = await readCapped(response, MAX_ERROR_BODY_BYTES);
+	const data = read && parseBody(read);
+	if (read) response = rebuildResponse(response, read.bytes);
+	const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+	return new ArthronError({
+		message: `${describeRequest(request)} failed with ${status}`,
+		detail: resolve(data, response) || void 0,
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+		data,
+		request,
+		response
+	});
+}
+/**
+* Browsers that stream a request body (Chromium, current WebKit) do it only
+* over HTTP/2, and fail one sent to an HTTP/1.1 server with the same bare
+* "Failed to fetch" / "Load failed" as a dead server, so name the likely cause.
+*/
+const STREAM_BODY_HINT = " — in a browser, a ReadableStream body streams only over HTTP/2; send a Blob or ArrayBuffer to an HTTP/1.1 server";
+function networkError(cause, request) {
+	const reason = cause instanceof Error && cause.message ? cause.message : "network error";
+	const hint = isReadableStream(request.init.body) ? STREAM_BODY_HINT : "";
+	return new ArthronError({
+		message: `${describeRequest(request)} failed: ${reason}${hint}`,
+		status: 0,
+		statusText: "",
+		headers: new Headers(),
+		data: void 0,
+		request,
+		cause
+	});
+}
+//#endregion
 //#region src/response/schema-validation.ts
 const pathOf = (issue) => (issue.path ?? []).map((part) => String(typeof part === "object" && part !== null ? part.key : part)).join(".");
 /**
@@ -472,28 +641,35 @@ async function* parseNdjson(response, { maxLineLength = DEFAULT_LIMIT } = {}) {
 //#endregion
 //#region src/response/arthron-promise.ts
 /** Defer the Response until iteration starts, so the helper itself never rejects. */
-function iterate(promise, parse) {
+function iterate(promise, parse, signal) {
 	promise.catch(() => {});
 	return { async *[Symbol.asyncIterator]() {
-		yield* parse(await promise);
+		try {
+			yield* parse(await promise);
+		} catch (error) {
+			throw cancellationError(error, signal);
+		}
 	} };
 }
 /**
 * Sugar over `Promise<Response>`: `.json()` is `(await p).json()`. Awaiting
 * without a helper still yields the untouched `Response`.
 */
-function toArthronPromise(promise) {
+function toArthronPromise(promise, signal) {
+	const read = (body) => promise.then(body).catch((error) => {
+		throw cancellationError(error, signal);
+	});
 	return Object.assign(promise, {
-		json: ((schema) => promise.then(async (res) => {
+		json: ((schema) => read(async (res) => {
 			const data = await res.json();
 			return schema ? validate(schema, data) : data;
 		})),
-		text: () => promise.then((res) => res.text()),
-		blob: () => promise.then((res) => res.blob()),
-		arrayBuffer: () => promise.then((res) => res.arrayBuffer()),
-		formData: () => promise.then((res) => res.formData()),
-		sse: (options) => iterate(promise, (res) => parseSse(res, options)),
-		ndjson: (options) => iterate(promise, (res) => parseNdjson(res, options))
+		text: () => read((res) => res.text()),
+		blob: () => read((res) => res.blob()),
+		arrayBuffer: () => read((res) => res.arrayBuffer()),
+		formData: () => read((res) => res.formData()),
+		sse: (options) => iterate(promise, (res) => parseSse(res, options), signal),
+		ndjson: (options) => iterate(promise, (res) => parseNdjson(res, options), signal)
 	});
 }
 //#endregion
@@ -548,130 +724,6 @@ function resolveConfig(config) {
 	};
 }
 //#endregion
-//#region src/response/rebuild-response.ts
-/**
-* A new Response with `body` but everything else taken from `original`. The
-* constructor resets `url`, `redirected` and `type`, so those are copied over
-* as own properties — callers that resolve relative links or detect
-* redirects keep working.
-*/
-function rebuildResponse(original, body) {
-	return withFetchedFields(new Response(body, {
-		status: original.status,
-		statusText: original.statusText,
-		headers: original.headers
-	}), original);
-}
-/** Copy the fields the constructor resets — onto `clone()`s as well. */
-function withFetchedFields(target, from) {
-	const clone = target.clone.bind(target);
-	return Object.defineProperties(target, {
-		url: { value: from.url },
-		redirected: { value: from.redirected },
-		type: { value: from.type },
-		clone: { value: () => withFetchedFields(clone(), from) }
-	});
-}
-//#endregion
-//#region src/error/create-error.ts
-/**
-* Cancellation is not an HTTP failure. Matched by name so it works across
-* realms — or by the request's own `signal`, since `abort(reason)` rejects
-* with whatever reason the caller chose.
-*/
-function isCancellation(error, signal) {
-	if (signal?.aborted) return true;
-	const name = error?.name;
-	return name === "AbortError" || name === "TimeoutError";
-}
-const isRecord = (value) => typeof value === "object" && value !== null;
-/** `message` → `error` (string) → `error.message` → `detail`. */
-function defaultErrorDetail(data) {
-	if (!isRecord(data)) return void 0;
-	if (typeof data.message === "string") return data.message;
-	if (typeof data.error === "string") return data.error;
-	if (isRecord(data.error) && typeof data.error.message === "string") return data.error.message;
-	if (typeof data.detail === "string") return data.detail;
-}
-/** How much of an error body arthron reads. Error bodies are for diagnosis; a hostile or broken server must not be able to fill memory with one. */
-const MAX_ERROR_BODY_BYTES = 65536;
-/** Up to `limit` bytes of the body; the rest is cancelled unread. `undefined` when there is no body or reading it failed. */
-async function readCapped(response, limit) {
-	if (!response.body) return void 0;
-	let reader;
-	const chunks = [];
-	let size = 0;
-	try {
-		reader = response.body.getReader();
-		while (size <= limit) {
-			const { value, done } = await reader.read();
-			if (done) break;
-			chunks.push(value);
-			size += value.byteLength;
-		}
-	} catch {
-		return;
-	} finally {
-		await reader?.cancel().catch(() => {});
-		reader?.releaseLock();
-	}
-	const bytes = new Uint8Array(size);
-	let offset = 0;
-	for (const chunk of chunks) {
-		bytes.set(chunk, offset);
-		offset += chunk.byteLength;
-	}
-	return size > limit ? {
-		bytes: bytes.subarray(0, limit),
-		truncated: true
-	} : {
-		bytes,
-		truncated: false
-	};
-}
-/** JSON if the whole body parses, else the text (cut at the limit), else `undefined` when empty. */
-function parseBody(read) {
-	const text = new TextDecoder().decode(read.bytes);
-	if (text === "") return void 0;
-	if (read.truncated) return text;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
-}
-/** The request as error messages name it: method and URL, no query or userinfo. */
-function describeRequest(request) {
-	return `${request.init.method ?? "GET"} ${redactUrl(request.url)}`;
-}
-async function responseError(response, request, resolve = defaultErrorDetail) {
-	const read = await readCapped(response, MAX_ERROR_BODY_BYTES);
-	const data = read && parseBody(read);
-	if (read) response = rebuildResponse(response, read.bytes);
-	const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
-	return new ArthronError({
-		message: `${describeRequest(request)} failed with ${status}`,
-		detail: resolve(data, response) || void 0,
-		status: response.status,
-		statusText: response.statusText,
-		headers: response.headers,
-		data,
-		request,
-		response
-	});
-}
-function networkError(cause, request) {
-	return new ArthronError({
-		message: `${describeRequest(request)} failed: ${cause instanceof Error && cause.message ? cause.message : "network error"}`,
-		status: 0,
-		statusText: "",
-		headers: new Headers(),
-		data: void 0,
-		request,
-		cause
-	});
-}
-//#endregion
 //#region src/client/send.ts
 /**
 * The global fetch rejects a malformed URL or method with a TypeError that
@@ -691,6 +743,16 @@ function assertSendable(url, method) {
 	}
 }
 /**
+* A ReadableStream body the browser cannot stream is rejected before it is
+* sent: Firefox would send the text "[object ReadableStream]", older Safari
+* fails with a bare network error. Only for the global fetch, like
+* assertSendable.
+*/
+function assertStreamable(url, method, body) {
+	if (!isReadableStream(body) || runtimeStreamsRequestBody()) return;
+	throw new TypeError(`arthron: cannot send ${method} ${redactUrl(url)} with a ReadableStream body — this browser cannot stream a request body and would send it garbled or not at all; pass a Blob or ArrayBuffer instead`);
+}
+/**
 * Non-ok responses the caller asked for are not failures: an opaque one
 * (`mode: "no-cors"`) and the 3xx of `redirect: "manual"`.
 */
@@ -701,13 +763,17 @@ function failedByDefault(res, init) {
 /** The one place a failure becomes an ArthronError. Cancellation passes through. */
 async function send(resolved, ctx, throwOn) {
 	const fetchImpl = resolved.fetch ?? globalThis.fetch;
-	if (resolved.fetch === void 0) assertSendable(ctx.url, ctx.init.method ?? "GET");
+	if (resolved.fetch === void 0) {
+		const method = ctx.init.method ?? "GET";
+		assertSendable(ctx.url, method);
+		assertStreamable(ctx.url, method, ctx.init.body);
+	}
 	const { signal } = ctx.init;
 	let res;
 	try {
 		res = await fetchImpl(ctx.url, ctx.init);
 	} catch (thrown) {
-		if (isCancellation(thrown, signal)) throw thrown;
+		if (isCancellation(thrown, signal)) throw cancellationError(thrown, signal);
 		throw networkError(thrown, ctx);
 	}
 	if (res.ok) return res;
@@ -757,7 +823,7 @@ function arthron(config = {}) {
 				url,
 				init: requestInit,
 				meta: { ...meta }
-			}, (ctx) => send(resolved, ctx, throwOn)));
+			}, (ctx) => send(resolved, ctx, throwOn)), init.signal);
 		} catch (thrown) {
 			return toArthronPromise(Promise.reject(thrown));
 		}