arthron 0.0.1 → 1.0.0

package/dist/index.mjs

@@ -1,156 +1,227 @@
-//#region src/body.ts
-const RAW_CTORS = [
-	"FormData",
-	"Blob",
-	"ArrayBuffer",
-	"URLSearchParams",
-	"ReadableStream"
-];
-/** Bodies fetch already knows how to send. Content-Type is left to the caller / runtime. */
-function isRawBody(body) {
-	if (typeof body === "string") return true;
-	if (ArrayBuffer.isView(body)) return true;
-	return RAW_CTORS.some((name) => {
-		const ctor = globalThis[name];
-		return typeof ctor === "function" && body instanceof ctor;
+//#region src/request/url.ts
+const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const HTTP_URL = /^https?:\/\//i;
+function isAbsoluteUrl(path) {
+	return ABSOLUTE_URL.test(path);
+}
+/**
+* Origin + pathname only — the query and userinfo tend to carry secrets.
+* For anything printed: log lines, error messages, `ArthronError.toJSON`.
+*/
+function redactUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return url.split(/[?#]/)[0] ?? url;
+	}
+}
+/**
+* `undefined` when `url` has no origin of its own. A relative baseURL takes
+* the page's origin in a browser and has none elsewhere.
+*/
+function originOf(url) {
+	const page = globalThis.location?.href;
+	try {
+		return new URL(url, page).origin;
+	} catch {
+		return;
+	}
+}
+/** `path` is absolute and points away from `baseURL`'s origin. */
+function leavesBase(baseURL, path) {
+	if (baseURL === void 0 || !isAbsoluteUrl(path)) return false;
+	const base = originOf(baseURL);
+	return base === void 0 || originOf(path) !== base;
+}
+function toQueryString(params) {
+	if (!params) return "";
+	if (Object.prototype.toString.call(params) === "[object URLSearchParams]") return params.toString();
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) for (const item of Array.isArray(value) ? value : [value]) {
+		if (item === null || item === void 0) continue;
+		if (typeof item === "object" || typeof item === "function") throw new TypeError(`arthron: params.${key} is not a string, number or boolean — pass one of those or an array of them (dates: date.toISOString())`);
+		search.append(key, String(item));
+	}
+	return search.toString();
+}
+/**
+* Fill `{name}` placeholders with encoded values, so each one stays inside
+* its segment: "/", "?" and "#" are encoded, and the values WHATWG URL would
+* turn into a different path — "", "." and ".." — are refused. A placeholder
+* without a value, or a value without a placeholder, is a mistake too.
+*/
+function fillPath(template, values) {
+	const used = /* @__PURE__ */ new Set();
+	const filled = template.replace(/\{([^{}/]+)\}/g, (_, name) => {
+		if (!Object.hasOwn(values, name)) throw new TypeError(`arthron: path "${template}" has {${name}} but no value for it — pass path: { ${name}: … }`);
+		used.add(name);
+		const value = String(values[name]);
+		if (value === "" || value === "." || value === "..") throw new TypeError(`arthron: path value ${name}=${JSON.stringify(value)} would change the path, not fill a segment — pass a real id`);
+		return encodeURIComponent(value);
 	});
+	const unused = Object.keys(values).find((name) => !used.has(name));
+	if (unused !== void 0) throw new TypeError(`arthron: path "${template}" has no {${unused}} — add the placeholder or drop the value`);
+	return filled;
 }
 /**
-* Turn a caller-supplied body into something fetch accepts. Raw bodies pass
-* through untouched; anything else is JSON with `content-type` set — unless
-* the caller already set one (headers arrive lowercased, so a plain lookup is
-* enough).
+* Join `baseURL` and `path` by plain string concatenation so a path prefix in
+* the base (`/v1`) survives a leading slash in the path. WHATWG `new URL()`
+* would drop it. An absolute path replaces the base only when it stays on the
+* base's origin, or when `allowAbsoluteUrls` says other origins are fine — a
+* path built from user input or an API response must not carry the client's
+* credentials somewhere else.
 */
-function serializeBody(body, headers) {
-	if (body === void 0) return {
-		body: void 0,
-		headers
-	};
-	if (isRawBody(body)) return {
-		body,
-		headers
-	};
-	const withType = "content-type" in headers ? headers : {
-		...headers,
-		"content-type": "application/json"
-	};
-	return {
-		body: JSON.stringify(body),
-		headers: withType
-	};
+function resolveUrl(baseURL, path, params, allowAbsoluteUrls = false) {
+	let url;
+	if (isAbsoluteUrl(path)) {
+		if (!HTTP_URL.test(path)) {
+			const scheme = path.slice(0, path.indexOf(":") + 1);
+			throw new TypeError(`arthron: only http(s) URLs can be requested, got a "${scheme}" URL — use an http:// or https:// URL`);
+		}
+		if (!allowAbsoluteUrls && leavesBase(baseURL, path)) throw new TypeError(`arthron: ${originOf(path)} is outside baseURL ${(baseURL && originOf(baseURL)) ?? baseURL} — pass a path relative to baseURL, or set arthron({ allowAbsoluteUrls: true }) to allow other origins (config headers are not sent to them)`);
+		url = path;
+	} else {
+		if (baseURL === void 0) throw new TypeError(`arthron: relative path "${redactUrl(path)}" needs a baseURL — pass baseURL in arthron({ baseURL }) or use an absolute URL`);
+		url = `${baseURL.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+	}
+	const query = toQueryString(params);
+	if (!query) return url;
+	const hash = url.indexOf("#");
+	const [base, fragment] = hash === -1 ? [url, ""] : [url.slice(0, hash), url.slice(hash)];
+	return `${base}${base.includes("?") ? "&" : "?"}${query}${fragment}`;
 }
 //#endregion
-//#region src/error.ts
+//#region src/error/arthron-error.ts
+/**
+* Marks an ArthronError across copies of this package. The ESM and CJS
+* builds can both end up loaded (a CJS dependency creates the client, ESM
+* app code catches), each with its own class — `Symbol.for` is shared.
+*/
+const BRAND = Symbol.for("arthron.ArthronError");
 /**
 * 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.
 */
-var ArthronError = class extends Error {
+var ArthronError = class ArthronError extends Error {
 	name = "ArthronError";
+	/** HTTP status of the failed response; `0` when fetch itself failed (network). */
 	status;
 	statusText;
-	headers;
+	/** Parsed body: JSON if it parses, else the text, else `undefined`. */
 	data;
-	request;
-	response;
+	/**
+	* 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.
+	*/
+	detail;
+	/** The underlying error for network failures. */
 	cause;
 	constructor(init) {
 		super(init.message);
 		this.status = init.status;
 		this.statusText = init.statusText;
-		this.headers = init.headers;
 		this.data = init.data;
-		this.request = init.request;
-		this.response = init.response;
+		this.detail = init.detail;
 		this.cause = init.cause;
+		Object.defineProperties(this, {
+			headers: { value: init.headers },
+			request: { value: init.request },
+			response: { value: init.response },
+			[BRAND]: { value: true }
+		});
+	}
+	/** `instanceof ArthronError` holds for an error from any copy of the package. */
+	static [Symbol.hasInstance](value) {
+		return this === ArthronError ? isArthronError(value) : Function.prototype[Symbol.hasInstance].call(this, value);
+	}
+	/** What serializers see: no headers, no body, no query or userinfo. */
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			detail: this.detail,
+			status: this.status,
+			statusText: this.statusText,
+			method: this.request.init.method ?? "GET",
+			url: redactUrl(this.request.url),
+			data: this.data
+		};
 	}
 };
+/** `true` for errors arthron produced: a `!ok` response or a network failure. Cancellations and plugin bugs are not ArthronErrors. */
 function isArthronError(error) {
-	return error instanceof ArthronError;
-}
-/** Cancellation is not an HTTP failure. Matched by name so it works across realms. */
-function isCancellation(error) {
-	const name = error?.name;
-	return name === "AbortError" || name === "TimeoutError";
-}
-const isRecord = (value) => typeof value === "object" && value !== null;
-/** `message` → `error` (string) → `error.message` → `detail`. */
-function defaultErrorMessage(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;
-}
-/** Body as JSON if it parses, else as text, else `undefined` when empty. */
-async function readBody(response) {
-	const text = await response.text().catch(() => "");
-	if (text === "") return void 0;
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
-}
-async function responseError(response, request, resolve = defaultErrorMessage) {
-	const data = await readBody(response);
-	return new ArthronError({
-		message: resolve(data, response) ?? `Request failed with status ${response.status}`,
-		status: response.status,
-		statusText: response.statusText,
-		headers: response.headers,
-		data,
-		request,
-		response
-	});
-}
-function networkError(cause, request) {
-	return new ArthronError({
-		message: cause instanceof Error ? cause.message : "Network error",
-		status: 0,
-		statusText: "",
-		headers: new Headers(),
-		data: void 0,
-		request,
-		cause
-	});
+	return typeof error === "object" && error !== null && error[BRAND] === true;
 }
 //#endregion
-//#region src/headers.ts
+//#region src/request/headers.ts
+const isPlainRecord = (headers) => !Array.isArray(headers) && Object.prototype.toString.call(headers) !== "[object Headers]";
 /**
-* Normalize any `HeadersInit` (plain object, `Headers`, tuple array) into a
-* plain record. Keys come back lowercased — `Headers` does that for us.
+* Layer header sets left to right into one plain record. Names are compared
+* case-insensitively and come back lowercased; a later layer wins, so a
+* caller's `content-type` replaces a default `Content-Type` instead of fetch
+* sending both values joined. `Headers` validates every value it sets.
 */
+function mergeHeaders(...layers) {
+	const merged = new Headers();
+	for (const layer of layers) {
+		if (!layer) continue;
+		if (isPlainRecord(layer)) for (const [name, value] of Object.entries(layer)) if (value == null) merged.delete(name);
+		else merged.set(name, value);
+		else for (const [name, value] of new Headers(layer)) merged.set(name, value);
+	}
+	return Object.fromEntries(merged);
+}
+/** Normalize any header shape into a plain record with lowercased names. */
 function toHeaderRecord(headers) {
-	if (!headers) return {};
-	return Object.fromEntries(new Headers(headers).entries());
+	return mergeHeaders(headers);
+}
+//#endregion
+//#region src/pipeline/pipeline.ts
+/** The mutable body kinds an interceptor can `append` to; anything else is shared as is. */
+function cloneBody(body) {
+	if (typeof FormData !== "undefined" && body instanceof FormData) {
+		const copy = new FormData();
+		for (const [name, value] of body) copy.append(name, value);
+		return copy;
+	}
+	if (body instanceof URLSearchParams) return new URLSearchParams(body);
+	return body;
 }
 /**
-* Layer `override` on top of `base`. Names are compared case-insensitively and
-* the override wins, so a caller's `content-type` replaces a default
-* `Content-Type` instead of fetch sending both values joined.
+* Interceptors mutate the context in place. A middleware that calls `next`
+* again (retry) must not see the previous attempt's changes, so every attempt
+* starts from a fresh copy of the headers and of a FormData/URLSearchParams body.
 */
-function mergeHeaders(base, override) {
+function cloneContext({ url, init, meta }) {
+	const copy = {
+		...init,
+		headers: toHeaderRecord(init.headers)
+	};
+	if (init.body) copy.body = cloneBody(init.body);
 	return {
-		...toHeaderRecord(base),
-		...toHeaderRecord(override)
+		url,
+		init: copy,
+		meta: { ...meta }
 	};
 }
-//#endregion
-//#region src/pipeline.ts
 /**
-* Interceptors mutate the context in place. A middleware that calls `next`
-* again (retry) must not see the previous attempt's changes, so every attempt
-* starts from a fresh copy.
+* Put headers back into a plain lowercase record. A plugin written in JS (or
+* with a cast) may hand back a `Headers` object, and the next plugin's
+* `{ ...ctx.init.headers }` would otherwise drop every header.
 */
-function cloneContext({ url, init }) {
+function normalize(ctx, previous) {
 	return {
-		url,
+		...ctx,
 		init: {
-			...init,
-			headers: toHeaderRecord(init.headers)
-		}
+			...ctx.init,
+			headers: toHeaderRecord(ctx.init.headers)
+		},
+		meta: ctx.meta ?? previous.meta
 	};
 }
 /**
@@ -176,7 +247,7 @@ async function runPipeline(plugins, ctx, send) {
 	const attempt = async (input) => {
 		let current = cloneContext(input);
 		try {
-			for (const interceptor of request) current = await interceptor(current);
+			for (const interceptor of request) current = normalize(await interceptor(current), current);
 			let res = await send(current);
 			for (const interceptor of response) res = await interceptor(res, current);
 			return res;
@@ -190,101 +261,502 @@ async function runPipeline(plugins, ctx, send) {
 	const dispatch = (index, input) => {
 		const middleware = middlewares[index];
 		if (!middleware) return attempt(input);
-		return middleware(input, (next) => dispatch(index + 1, next));
+		return middleware(input, (next) => dispatch(index + 1, {
+			...next,
+			meta: next.meta ?? input.meta
+		}));
 	};
 	return dispatch(0, ctx);
 }
 //#endregion
-//#region src/promise.ts
+//#region src/request/body.ts
+const RAW_TAGS = /* @__PURE__ */ new Set([
+	"FormData",
+	"Blob",
+	"File",
+	"ArrayBuffer",
+	"URLSearchParams",
+	"ReadableStream"
+]);
+/**
+* `Symbol.toStringTag`, not `instanceof`: a body from another realm or a
+* polyfill (formdata-node, fetch-blob) must not be JSON-encoded into `{}`.
+*/
+const tagOf = (value) => Object.prototype.toString.call(value).slice(8, -1);
+function isReadableStream(value) {
+	return tagOf(value) === "ReadableStream";
+}
+/**
+* What JSON.stringify would turn into `{}`, `undefined` or internal state
+* instead of the data — with the fix, so it reads as an error message.
+*/
+function mangledByJson(body) {
+	if (typeof body === "function" || typeof body === "symbol") return `a ${typeof body}, which JSON cannot carry — send its data instead`;
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return;
+	if (Symbol.asyncIterator in body) return "an async iterable (a Node stream?) — pass a ReadableStream (Readable.toWeb(stream)) or collect it first";
+	if (Symbol.iterator in body) return "an iterable such as a Map, Set or generator — convert it to an array or plain object first";
+}
+/** Bodies fetch already knows how to send. Content-Type is left to the caller / runtime. */
+function isRawBody(body) {
+	if (typeof body === "string") return true;
+	if (ArrayBuffer.isView(body)) return true;
+	return RAW_TAGS.has(tagOf(body));
+}
+/**
+* Turn a caller-supplied body into something fetch accepts. Raw bodies pass
+* through untouched; anything else is JSON with `content-type` set — unless
+* the caller already set one (headers arrive lowercased, so a plain lookup is
+* enough).
+*/
+function serializeBody(body, headers) {
+	if (body === void 0) return {
+		body: void 0,
+		headers
+	};
+	if (tagOf(body) === "FormData") {
+		const { "content-type": _dropped, ...rest } = headers;
+		return {
+			body,
+			headers: rest
+		};
+	}
+	if (isRawBody(body)) return {
+		body,
+		headers
+	};
+	const mangled = mangledByJson(body);
+	if (mangled) throw new TypeError(`arthron: the body is ${mangled}`);
+	const type = headers["content-type"];
+	if (type !== void 0 && !/\bjson\b/i.test(type)) throw new TypeError(`arthron: a ${typeof body} body is sent as JSON, but content-type is "${type}" — pass a string, URLSearchParams or FormData for that content type, or drop the header`);
+	const withType = "content-type" in headers ? headers : {
+		...headers,
+		"content-type": "application/json"
+	};
+	return {
+		body: JSON.stringify(body),
+		headers: withType
+	};
+}
+//#endregion
+//#region src/response/schema-validation.ts
+const pathOf = (issue) => (issue.path ?? []).map((part) => String(typeof part === "object" && part !== null ? part.key : part)).join(".");
+/**
+* `.json(schema)` got a body that does not match. Not an ArthronError: the
+* request succeeded — the data is what is wrong.
+*/
+var SchemaError = class extends Error {
+	name = "SchemaError";
+	/** Every problem the validator reported, with the path to it. */
+	issues;
+	constructor(issues) {
+		const [first] = issues;
+		const where = first ? pathOf(first) : "";
+		const more = issues.length > 1 ? ` (+${issues.length - 1} more)` : "";
+		super(`arthron: the response body does not match the schema — ${where ? `${where}: ` : ""}${first?.message ?? "invalid"}${more}. See error.issues`);
+		this.issues = issues;
+	}
+};
+/** Validate `data`; resolve with the schema's output or reject with a SchemaError. */
+async function validate(schema, data) {
+	const result = await schema["~standard"].validate(data);
+	if (result.issues) throw new SchemaError(result.issues);
+	return result.value;
+}
+//#endregion
+//#region src/response/stream-parser.ts
+const DEFAULT_LIMIT = 8388608;
+/**
+* Yield the body line by line, reassembling lines split across chunks. Only
+* the newly arrived text is scanned, so a long line costs linear time; a line
+* past `maxLineLength` stops the stream instead of growing without bound.
+*/
+async function* lines(response, maxLineLength) {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const breaks = /\r\n|\r|\n/g;
+	let pending = "";
+	let afterCR = false;
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			let text = decoder.decode(value, { stream: !done });
+			if (afterCR && text.startsWith("\n")) {
+				text = text.slice(1);
+				afterCR = false;
+			}
+			if (text) afterCR = text.endsWith("\r");
+			let start = 0;
+			breaks.lastIndex = 0;
+			for (let m = breaks.exec(text); m; m = breaks.exec(text)) {
+				yield pending + text.slice(start, m.index);
+				pending = "";
+				start = breaks.lastIndex;
+			}
+			pending += text.slice(start);
+			if (pending.length > maxLineLength) throw new RangeError(`arthron: a stream line is longer than ${maxLineLength} characters — pass a larger maxLineLength to .sse() / .ndjson() if that is expected`);
+			if (done) break;
+		}
+		if (pending) yield pending;
+	} finally {
+		await reader.cancel().catch(() => {});
+		reader.releaseLock();
+	}
+}
+/**
+* Parse a `text/event-stream` body into events. Follows the spec: a blank
+* line dispatches, `data:` lines are joined with `\n`, one leading space
+* after the colon is dropped, lines starting with `:` are comments, and a
+* block without `data` — or one the stream ends inside — is not dispatched.
+* Provider sentinels like
+* `[DONE]` are passed through untouched — they are not part of the spec.
+*/
+async function* parseSse(response, { maxLineLength = DEFAULT_LIMIT, maxEventSize = DEFAULT_LIMIT } = {}) {
+	let data = [];
+	let size = 0;
+	let event;
+	let id;
+	let lastEventId = "";
+	let retry;
+	const flush = () => {
+		const out = data.length === 0 ? void 0 : {
+			data: data.join("\n"),
+			lastEventId
+		};
+		if (out && event !== void 0) out.event = event;
+		if (out && id !== void 0) out.id = id;
+		if (out && retry !== void 0) out.retry = retry;
+		data = [];
+		size = 0;
+		event = id = void 0;
+		return out;
+	};
+	for await (const line of lines(response, maxLineLength)) {
+		if (line === "") {
+			const out = flush();
+			if (out) yield out;
+			continue;
+		}
+		if (line.startsWith(":")) continue;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		switch (field) {
+			case "data":
+				size += value.length + 1;
+				if (size > maxEventSize + 1) throw new RangeError(`arthron: an SSE event's data is longer than ${maxEventSize} characters — pass a larger maxEventSize to .sse() if that is expected`);
+				data.push(value);
+				break;
+			case "event":
+				event = value;
+				break;
+			case "id":
+				if (!value.includes("\0")) id = lastEventId = value;
+				break;
+			case "retry": if (/^\d+$/.test(value)) retry = Number(value);
+		}
+	}
+}
+/**
+* Parse newline-delimited JSON. Blank lines are skipped; a malformed line
+* rejects the iteration with the `SyntaxError` from `JSON.parse`.
+*/
+async function* parseNdjson(response, { maxLineLength = DEFAULT_LIMIT } = {}) {
+	for await (const line of lines(response, maxLineLength)) {
+		if (line.trim() === "") continue;
+		yield JSON.parse(line);
+	}
+}
+//#endregion
+//#region src/response/arthron-promise.ts
+/** Defer the Response until iteration starts, so the helper itself never rejects. */
+function iterate(promise, parse) {
+	promise.catch(() => {});
+	return { async *[Symbol.asyncIterator]() {
+		yield* parse(await promise);
+	} };
+}
 /**
 * Sugar over `Promise<Response>`: `.json()` is `(await p).json()`. Awaiting
 * without a helper still yields the untouched `Response`.
 */
 function toArthronPromise(promise) {
 	return Object.assign(promise, {
-		json: () => promise.then((res) => res.json()),
+		json: ((schema) => promise.then(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())
+		formData: () => promise.then((res) => res.formData()),
+		sse: (options) => iterate(promise, (res) => parseSse(res, options)),
+		ndjson: (options) => iterate(promise, (res) => parseNdjson(res, options))
 	});
 }
 //#endregion
-//#region src/url.ts
-const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
-function isAbsoluteUrl(path) {
-	return ABSOLUTE_URL.test(path);
-}
-function toQueryString(params) {
-	if (!params) return "";
-	const search = new URLSearchParams();
-	for (const [key, value] of Object.entries(params)) {
-		if (value === null || value === void 0) continue;
-		search.append(key, String(value));
-	}
-	return search.toString();
-}
+//#region src/client/resolve-config.ts
 /**
-* Join `baseURL` and `path` by plain string concatenation so a path prefix in
-* the base (`/v1`) survives a leading slash in the path. WHATWG `new URL()`
-* would drop it. Absolute paths skip the base entirely.
+* Config keys that configure arthron itself; every other key is a fetch
+* default. Typed so that a new config key fails to compile until it is
+* listed here — otherwise it would be sent to fetch.
 */
-function resolveUrl(baseURL, path, params) {
-	let url;
-	if (isAbsoluteUrl(path)) url = path;
-	else {
-		if (baseURL === void 0) throw new TypeError(`arthron: relative path "${path}" requires a baseURL`);
-		url = `${baseURL.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+const OWN_KEYS = {
+	baseURL: true,
+	allowAbsoluteUrls: true,
+	headers: true,
+	fetch: true,
+	use: true,
+	errorDetail: true,
+	throwOn: true
+};
+/** Fields that belong to one request, refused as client defaults. */
+const PER_CALL_ONLY = [
+	"signal",
+	"body",
+	"method"
+];
+/**
+* Add plugins to a list. A named plugin takes the place of the one already
+* there with that name — same position, so a replaced `logging()` stays
+* outermost and a second `retry()` does not multiply attempts. Unnamed
+* plugins append.
+*/
+function addPlugins(base, added) {
+	const out = [...base];
+	for (const plugin of added) {
+		const at = plugin.name === void 0 ? -1 : out.findIndex((p) => p.name === plugin.name);
+		if (at === -1) out.push(plugin);
+		else out[at] = plugin;
 	}
-	const query = toQueryString(params);
-	if (!query) return url;
-	return `${url}${url.includes("?") ? "&" : "?"}${query}`;
+	return out;
 }
-//#endregion
-//#region src/client.ts
-/** Normalize once so `extend` can merge headers and append plugins cheaply. */
+/** The fetch defaults in a config: every set key that is not arthron's own. */
+function fetchDefaults(config) {
+	return Object.fromEntries(Object.entries(config).filter(([key, value]) => value !== void 0 && !(key in OWN_KEYS)));
+}
+/** Normalize once so `extend` can merge headers and add plugins cheaply. */
 function resolveConfig(config) {
+	for (const key of PER_CALL_ONLY) if (config[key] !== void 0) throw new TypeError(`arthron: ${key} cannot be a client default, it belongs to one request — pass it per call (api.get(path, { signal }), api.post(path, body), api.request(path, { method }))`);
 	const { headers, use, ...rest } = config;
 	return {
 		...rest,
 		headers: toHeaderRecord(headers),
-		use: use ?? []
+		use: addPlugins([], use ?? [])
 	};
 }
+//#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
+* looks just like a network failure (status 0, retried). A bodiless `Request`
+* runs the same checks first, so those become argument errors instead. Only
+* for the global fetch: an injected one owns its URL rules (SvelteKit's
+* server-side `fetch` accepts relative URLs, for one).
+*/
+function assertSendable(url, method) {
+	if (typeof Request !== "function") return;
+	try {
+		new Request(url, { method });
+	} catch (cause) {
+		const shown = redactUrl(url);
+		const reason = (cause instanceof Error ? cause.message : String(cause)).split(url).join(shown);
+		throw new TypeError(`arthron: cannot send ${method} ${shown} (${reason}) — use an absolute URL or a baseURL with a scheme (https://…), and a valid HTTP method`, { cause });
+	}
+}
+/**
+* Non-ok responses the caller asked for are not failures: an opaque one
+* (`mode: "no-cors"`) and the 3xx of `redirect: "manual"`.
+*/
+function failedByDefault(res, init) {
+	if (res.type === "opaque" || res.type === "opaqueredirect") return false;
+	return !(init.redirect === "manual" && res.status >= 300 && res.status < 400);
+}
+/** 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");
+	const { signal } = ctx.init;
+	let res;
+	try {
+		res = await fetchImpl(ctx.url, ctx.init);
+	} catch (thrown) {
+		if (isCancellation(thrown, signal)) throw thrown;
+		throw networkError(thrown, ctx);
+	}
+	if (res.ok) return res;
+	if (!(throwOn ? throwOn(res) : failedByDefault(res, ctx.init))) return res;
+	const error = await responseError(res, ctx, resolved.errorDetail);
+	if (signal?.aborted) throw signal.reason;
+	throw error;
+}
+//#endregion
+//#region src/client/client.ts
+const BODYLESS_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+/** Sent uppercased whatever their case; fetch itself only normalizes six. */
+const STANDARD_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS",
+	"QUERY"
+]);
 /**
 * Build a client from config. The result is immutable — `use` and `extend`
 * return new clients and never touch the one they were called on.
 */
 function arthron(config = {}) {
 	const resolved = resolveConfig(config);
-	const fetchImpl = resolved.fetch ?? globalThis.fetch;
-	/** The one place a failure becomes an ArthronError. Cancellation passes through. */
-	const send = async (ctx) => {
-		let res;
-		try {
-			res = await fetchImpl(ctx.url, ctx.init);
-		} catch (thrown) {
-			if (isCancellation(thrown)) throw thrown;
-			throw networkError(thrown, ctx);
-		}
-		if (!res.ok) throw await responseError(res, ctx, resolved.errorMessage);
-		return res;
-	};
-	const dispatch = (path, method, rawBody, { params, headers: callHeaders, ...init }) => {
+	const initDefaults = fetchDefaults(resolved);
+	const dispatch = (path, method, rawBody, { params, headers: callHeaders, meta, throwOn = resolved.throwOn, path: pathValues, ...init }) => {
 		try {
-			const url = resolveUrl(resolved.baseURL, path, params);
-			const { body, headers } = serializeBody(rawBody, mergeHeaders(resolved.headers, callHeaders));
+			const upper = method.toUpperCase();
+			const verb = STANDARD_METHODS.has(upper) ? upper : method;
+			if (rawBody !== void 0 && BODYLESS_METHODS.has(upper)) throw new TypeError(`arthron: ${upper} requests cannot carry a body — send it as params (query) or switch to POST`);
+			if (pathValues) path = fillPath(path, pathValues);
+			const url = resolveUrl(resolved.baseURL, path, params, resolved.allowAbsoluteUrls);
+			const { body, headers } = serializeBody(rawBody, mergeHeaders(leavesBase(resolved.baseURL, path) ? void 0 : resolved.headers, callHeaders));
 			const requestInit = {
-				...resolved.credentials !== void 0 && { credentials: resolved.credentials },
+				...initDefaults,
 				...init,
-				method,
+				method: verb,
 				headers
 			};
 			if (body !== void 0) requestInit.body = body;
+			if (isReadableStream(body)) Object.assign(requestInit, { duplex: "half" });
 			return toArthronPromise(runPipeline(resolved.use, {
 				url,
-				init: requestInit
-			}, send));
+				init: requestInit,
+				meta: { ...meta }
+			}, (ctx) => send(resolved, ctx, throwOn)));
 		} catch (thrown) {
 			return toArthronPromise(Promise.reject(thrown));
 		}
@@ -294,7 +766,7 @@ function arthron(config = {}) {
 			...resolved,
 			...next,
 			headers: mergeHeaders(resolved.headers, next.headers),
-			use: [...resolved.use, ...next.use ?? []]
+			use: addPlugins(resolved.use, next.use ?? [])
 		});
 	};
 	return {
@@ -304,58 +776,93 @@ function arthron(config = {}) {
 		post: (path, body, init = {}) => dispatch(path, "POST", body, init),
 		put: (path, body, init = {}) => dispatch(path, "PUT", body, init),
 		patch: (path, body, init = {}) => dispatch(path, "PATCH", body, init),
+		query: (path, body, init = {}) => dispatch(path, "QUERY", body, init),
 		request: (path, init) => {
 			const { method, body, ...rest } = init;
-			if (!method) return toArthronPromise(Promise.reject(/* @__PURE__ */ new TypeError("arthron: request() requires init.method")));
+			if (!method) return toArthronPromise(Promise.reject(/* @__PURE__ */ new TypeError("arthron: request() needs init.method — e.g. request(path, { method: \"OPTIONS\" }); use get/post/... for the common verbs")));
 			return dispatch(path, method, body, rest);
 		},
 		use: (...plugins) => derive({ use: plugins }),
-		extend: (next) => derive(next)
+		extend: (next) => derive(next),
+		without: (...names) => arthron({
+			...resolved,
+			use: resolved.use.filter((p) => p.name === void 0 || !names.includes(p.name))
+		})
 	};
 }
 //#endregion
-//#region src/define.ts
+//#region src/pipeline/define-plugin.ts
+/** Identity helper: gives a middleware written in its own file the right parameter types. */
 const defineMiddleware = (middleware) => middleware;
+/** Identity helpers for each interceptor kind — `defineInterceptor.request(fn)` etc. */
 const defineInterceptor = {
 	request: (interceptor) => interceptor,
 	response: (interceptor) => interceptor,
 	error: (interceptor) => interceptor
 };
+/** Identity helper: type-checks a plugin object literal without an annotation. */
 const definePlugin = (plugin) => plugin;
 //#endregion
-//#region src/plugins/logging.ts
+//#region src/plugins/logging/logging.ts
+function consoleSink(logger) {
+	return (e) => {
+		if (e.phase === "start") logger.log(`[arthron] → ${e.method} ${e.path}`);
+		else if (e.phase === "success") logger.log(`[arthron] ← ${e.method} ${e.path} ${e.status} ${e.ms}ms`);
+		else logger.error(`[arthron] ✕ ${e.method} ${e.path} ${e.status ?? "-"} ${e.ms}ms`);
+	};
+}
 /**
-* One line when a request starts, one when it settles, with status and
+* 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.
-* The query string is dropped — it tends to carry tokens.
+* Default output is a console line per event; pass `onEvent` to get the
+* structured event instead. Cancellations are not reported.
 */
 function logging(options = {}) {
-	const { enabled = true, logger = console, now = () => performance.now() } = options;
+	const { enabled = true, logger = console, onEvent, now = () => performance.now() } = options;
+	const emit = onEvent ?? consoleSink(logger);
 	return {
 		name: "logging",
 		middleware: async (ctx, next) => {
 			if (!enabled) return next(ctx);
 			const method = ctx.init.method ?? "GET";
-			const path = ctx.url.split("?")[0];
+			const path = redactUrl(ctx.url);
 			const started = now();
-			const elapsed = () => `${Math.round(now() - started)}ms`;
-			logger.log(`[arthron] → ${method} ${path}`);
+			const ms = () => Math.round(now() - started);
+			emit({
+				phase: "start",
+				method,
+				path
+			});
+			let res;
 			try {
-				const res = await next(ctx);
-				logger.log(`[arthron] ← ${method} ${path} ${res.status} ${elapsed()}`);
-				return res;
-			} catch (thrown) {
-				if (!isCancellation(thrown)) {
-					const status = isArthronError(thrown) ? thrown.status : "-";
-					logger.error(`[arthron] ✕ ${method} ${path} ${status} ${elapsed()}`);
+				res = await next(ctx);
+			} catch (error) {
+				if (!isCancellation(error, ctx.init.signal)) {
+					const status = isArthronError(error) ? error.status : void 0;
+					emit({
+						phase: "error",
+						method,
+						path,
+						status,
+						ms: ms(),
+						error
+					});
 				}
-				throw thrown;
+				throw error;
 			}
+			emit({
+				phase: "success",
+				method,
+				path,
+				status: res.status,
+				ms: ms()
+			});
+			return res;
 		}
 	};
 }
 //#endregion
-//#region src/plugins/retry.ts
+//#region src/plugins/retry/retry.ts
 const DEFAULT_RETRY_ON = [
 	408,
 	429,
@@ -368,10 +875,13 @@ const DEFAULT_METHODS = [
 	"GET",
 	"HEAD",
 	"OPTIONS",
+	"QUERY",
 	"PUT",
 	"DELETE"
 ];
 const DEFAULT_MAX_RETRY_AFTER = 6e4;
+/** setTimeout fires at once past this, so every wait is capped to it. */
+const MAX_TIMER_MS$1 = 2 ** 31 - 1;
 function defaultSleep(ms, signal) {
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) return reject(signal.reason);
@@ -396,37 +906,168 @@ function retryAfterMs(error) {
 	if (Number.isNaN(at)) return void 0;
 	return Math.max(0, at - Date.now());
 }
-function isStreamBody(ctx) {
-	return typeof ReadableStream !== "undefined" && ctx.init.body instanceof ReadableStream;
+/** The rule without `shouldRetry`: a network error or a `retryOn` status, on a method in `methods`. */
+function byDefault(thrown, method, settings) {
+	if (!settings.allowed.has(method) || !isArthronError(thrown)) return false;
+	return thrown.status === 0 || settings.retryOn.includes(thrown.status);
+}
+/** Defaults filled in and `retries` checked — `attempt >= NaN` is never true, so an unset env var would retry forever. */
+function settle(options, where) {
+	const { retries = 2, retryOn = DEFAULT_RETRY_ON, methods = DEFAULT_METHODS, delay = (retry) => Math.random() * 300 * 2 ** retry, maxRetryAfter = DEFAULT_MAX_RETRY_AFTER, shouldRetry, onRetry } = options;
+	if (!Number.isInteger(retries) || retries < 0) throw new TypeError(`arthron: ${where} retries: ${retries} needs a whole number ≥ 0 — e.g. retries: 2`);
+	return {
+		retries,
+		retryOn,
+		allowed: new Set(methods.map((m) => m.toUpperCase())),
+		delay,
+		maxRetryAfter,
+		shouldRetry,
+		onRetry
+	};
 }
 /**
 * 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`.
 */
 function retry(options = {}) {
-	const { retries = 2, retryOn = DEFAULT_RETRY_ON, methods = DEFAULT_METHODS, delay = (retry) => 300 * 2 ** retry, sleep = defaultSleep, maxRetryAfter = DEFAULT_MAX_RETRY_AFTER } = options;
-	const allowed = new Set(methods.map((m) => m.toUpperCase()));
+	const { sleep = defaultSleep, ...rest } = options;
+	const base = settle(rest, "retry()");
 	return {
 		name: "retry",
 		middleware: async (ctx, next) => {
+			const override = ctx.meta?.retry;
+			if (override === false) return next(ctx);
+			const settings = override ? settle({
+				...rest,
+				...override
+			}, "meta.retry") : base;
 			const method = (ctx.init.method ?? "GET").toUpperCase();
-			const eligible = allowed.has(method) && !isStreamBody(ctx);
+			const resendable = !isReadableStream(ctx.init.body);
 			for (let attempt = 0;; attempt += 1) try {
 				return await next(ctx);
 			} catch (thrown) {
-				if (!eligible || attempt >= retries) throw thrown;
-				if (!isArthronError(thrown)) throw thrown;
-				if (thrown.status !== 0 && !retryOn.includes(thrown.status)) throw thrown;
+				if (!resendable || attempt >= settings.retries) throw thrown;
 				if (ctx.init.signal?.aborted) throw thrown;
-				const retryAfter = retryAfterMs(thrown);
-				if (retryAfter !== void 0 && retryAfter > maxRetryAfter) throw thrown;
-				await sleep(retryAfter ?? delay(attempt, thrown), ctx.init.signal);
+				const verdict = settings.shouldRetry?.(thrown, attempt, ctx);
+				if (verdict === false) throw thrown;
+				if (verdict === void 0 && !byDefault(thrown, method, settings)) throw thrown;
+				const retryAfter = isArthronError(thrown) ? retryAfterMs(thrown) : void 0;
+				if (retryAfter !== void 0 && retryAfter > settings.maxRetryAfter) throw thrown;
+				const wait = Math.min(retryAfter ?? settings.delay(attempt, thrown), MAX_TIMER_MS$1);
+				settings.onRetry?.(thrown, attempt, wait);
+				await sleep(wait, ctx.init.signal);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/timeout/timeout.ts
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+* Wrap `body` so the deadline keeps running until it is fully read, and so an
+* abort while reading surfaces as a stream error instead of a silent stall.
+*/
+function guardBody(body, signal, finish, onChunk) {
+	const reader = body.getReader();
+	return new ReadableStream({
+		start(controller) {
+			signal.addEventListener("abort", () => {
+				controller.error(signal.reason);
+				reader.cancel(signal.reason).catch(() => {});
+			}, { once: true });
+		},
+		async pull(controller) {
+			const { value, done } = await reader.read();
+			if (done) {
+				finish();
+				controller.close();
+				return;
+			}
+			onChunk();
+			controller.enqueue(value);
+		},
+		cancel(reason) {
+			finish();
+			return reader.cancel(reason);
+		}
+	});
+}
+/** setTimeout fires at once for NaN, negatives and anything past 2^31-1. */
+function checkDeadline(ms, where) {
+	if (ms === Number.POSITIVE_INFINITY || ms >= 0 && ms <= MAX_TIMER_MS) return;
+	throw new TypeError(`arthron: ${where} needs 0–${MAX_TIMER_MS} ms — pass Infinity for no deadline`);
+}
+/** A timer that aborts `controller` with a TimeoutError and never keeps Node alive on its own. */
+function deadlineTimer(controller, ms, message) {
+	const timer = setTimeout(() => controller.abort(new DOMException(message, "TimeoutError")), ms);
+	timer.unref?.();
+	return timer;
+}
+/**
+* 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`.
+*/
+function timeout(ms, options = {}) {
+	checkDeadline(ms, `timeout(${ms})`);
+	const { idle } = options;
+	if (idle !== void 0) checkDeadline(idle, `timeout(…, { idle: ${idle} })`);
+	return {
+		name: "timeout",
+		middleware: async (ctx, next) => {
+			const deadline = ctx.meta?.timeout ?? ms;
+			if (deadline !== ms) checkDeadline(deadline, `meta.timeout: ${deadline}`);
+			const idleMs = idle === Number.POSITIVE_INFINITY ? void 0 : idle;
+			if (deadline === Number.POSITIVE_INFINITY && idleMs === void 0) return next(ctx);
+			const controller = new AbortController();
+			const outer = ctx.init.signal;
+			const signal = outer ? AbortSignal.any([outer, controller.signal]) : controller.signal;
+			const total = deadline === Number.POSITIVE_INFINITY ? void 0 : deadlineTimer(controller, deadline, `arthron: request timed out after ${deadline}ms`);
+			let quiet;
+			const stillAlive = () => {
+				if (idleMs === void 0) return;
+				clearTimeout(quiet);
+				quiet = deadlineTimer(controller, idleMs, `arthron: no data for ${idleMs}ms`);
+			};
+			const finish = () => {
+				clearTimeout(total);
+				clearTimeout(quiet);
+			};
+			stillAlive();
+			let res;
+			try {
+				res = await next({
+					...ctx,
+					init: {
+						...ctx.init,
+						signal
+					}
+				});
+			} catch (thrown) {
+				finish();
+				throw thrown;
+			}
+			if (!res.body) {
+				finish();
+				return res;
 			}
+			stillAlive();
+			return rebuildResponse(res, guardBody(res.body, signal, finish, stillAlive));
 		}
 	};
 }
 //#endregion
-export { ArthronError, arthron, defineInterceptor, defineMiddleware, definePlugin, isArthronError, logging, retry };
+export { ArthronError, SchemaError, arthron, defineInterceptor, defineMiddleware, definePlugin, isArthronError, logging, retry, timeout };
 
 //# sourceMappingURL=index.mjs.map