arthron 1.2.0 → 2.0.1

package/dist/shared.mjs

@@ -0,0 +1,498 @@
+//#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;
+	}
+}
+/**
+* `url` as written, without its query, fragment and userinfo — for a value
+* that may not parse, or whose origin would print as "null" (ftp://…).
+*/
+function withoutSecrets(url) {
+	return (url.split(/[?#]/)[0] ?? url).replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/\\]*@/i, "$1");
+}
+/**
+* `text` with `url` redacted wherever it appears, as given or as the URL
+* parser normalizes it — for a runtime's own message that repeats the URL.
+*/
+function redactUrlIn(text, url) {
+	const shown = redactUrl(url);
+	let href;
+	try {
+		href = new URL(url).href;
+	} catch {}
+	let out = text.split(url).join(shown);
+	if (href && href !== url) out = out.split(href).join(shown);
+	return out;
+}
+/**
+* `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;
+	}
+}
+/** The origin of an absolute http(s) URL; `undefined` for anything else. */
+function httpOrigin(url) {
+	try {
+		const { protocol, origin } = new URL(url);
+		return protocol === "http:" || protocol === "https:" ? origin : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* The origins of a list of http(s) URLs, for an option that names where
+* requests may go. An empty list or another kind of entry is a TypeError in
+* the option's own words.
+*/
+function httpOrigins(urls, errors) {
+	if (urls.length === 0) throw new TypeError(errors.empty);
+	return new Set(urls.map((url) => {
+		const origin = httpOrigin(url);
+		if (origin) return origin;
+		throw new TypeError(errors.invalid(JSON.stringify(withoutSecrets(url))));
+	}));
+}
+/** `allowedOrigins` as origins, checked once when the client is created. */
+function originSet(urls) {
+	return httpOrigins(urls, {
+		empty: "arthron: allowedOrigins needs at least one URL — leave it out to stay on baseURL's origin",
+		invalid: (url) => `arthron: allowedOrigins needs http(s) URLs, got ${url} — e.g. allowedOrigins: ["https://cdn.example.com"]`
+	});
+}
+/** `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(queryParams) {
+	if (!queryParams) return "";
+	if (Object.prototype.toString.call(queryParams) === "[object URLSearchParams]") return queryParams.toString();
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(queryParams)) 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: queryParams.${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 pathParams: { ${name}: … }`);
+		used.add(name);
+		const value = String(values[name]);
+		if (value === "" || value === "." || value === "..") throw new TypeError(`arthron: pathParams.${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;
+}
+/**
+* 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 goes to one in `allowed` (`allowedOrigins`) — a path built
+* from user input or an API response must not carry the client's
+* credentials somewhere else. Without a baseURL, `allowed` alone limits it.
+*/
+function resolveUrl(baseURL, path, queryParams, allowed) {
+	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`);
+		}
+		const target = originOf(path);
+		if (target === void 0 && (baseURL !== void 0 || allowed)) throw new TypeError(`arthron: "${withoutSecrets(path)}" is not a valid URL — check it, or pass a path relative to baseURL`);
+		const listed = target !== void 0 && allowed?.has(target) === true;
+		if (!listed && leavesBase(baseURL, path)) {
+			const base = (baseURL && originOf(baseURL)) ?? withoutSecrets(baseURL ?? "");
+			throw new TypeError(`arthron: ${target} is outside baseURL ${base} — pass a path relative to baseURL, or add ${target} to arthron({ allowedOrigins }) (config headers are not sent there)`);
+		}
+		if (!listed && baseURL === void 0 && allowed) throw new TypeError(`arthron: ${target} is not in allowedOrigins — add it to arthron({ allowedOrigins }) or request a listed origin`);
+		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(queryParams);
+	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/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 ArthronError extends Error {
+	name = "ArthronError";
+	/** HTTP status of the failed response; `0` when fetch itself failed (network). */
+	status;
+	statusText;
+	/**
+	* The failed response's payload, parsed: JSON if it parses, else the text;
+	* `undefined` for a network failure, which has no response. At most 64 KiB
+	* is read (text if cut). `response.body`, by contrast, is the stream.
+	*/
+	payload;
+	/**
+	* For people: the server's description of the failure, extracted from
+	* `payload` (by default its `message` → `error` → `error.message` →
+	* `detail`; see the `extractDescription` option). `undefined` when there was
+	* none, and for a network failure. Untrusted server text: show it as text,
+	* never as HTML. `message`, by contrast, is arthron's — method, URL
+	* without query, status — for logs, not for people.
+	*/
+	description;
+	/** The underlying error for network failures, with the URL's query and userinfo taken out of its message, stack and causes. */
+	cause;
+	constructor(options) {
+		super(options.message);
+		this.status = options.status;
+		this.statusText = options.statusText;
+		this.payload = options.payload;
+		this.description = options.description;
+		this.cause = options.cause;
+		Object.defineProperties(this, {
+			headers: { value: options.headers },
+			requestContext: { value: options.requestContext },
+			response: { value: options.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 request body, no query or userinfo. */
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			description: this.description,
+			status: this.status,
+			statusText: this.statusText,
+			method: this.requestContext.init.method ?? "GET",
+			url: redactUrl(this.requestContext.url),
+			payload: this.payload
+		};
+	}
+};
+/** `true` for errors arthron produced: a `!ok` response or a network failure. Cancellations and plugin bugs are not ArthronErrors. */
+function isArthronError(error) {
+	return typeof error === "object" && error !== null && error[BRAND] === true;
+}
+//#endregion
+//#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";
+}
+/**
+* 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.
+*/
+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/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) {
+	const rebuilt = new Response(body, {
+		status: original.status,
+		statusText: original.statusText,
+		headers: original.headers
+	});
+	const { url, redirected, type } = original;
+	return withFields(rebuilt, {
+		url,
+		redirected,
+		type
+	});
+}
+/** Set those fields on `target` — and on its `clone()`s as well. */
+function withFields(target, fields) {
+	const clone = target.clone.bind(target);
+	return Object.defineProperties(target, {
+		url: { value: fields.url },
+		redirected: { value: fields.redirected },
+		type: { value: fields.type },
+		clone: { value: () => withFields(clone(), fields) }
+	});
+}
+//#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 defaultDescription(payload) {
+	if (!isRecord(payload)) return void 0;
+	if (typeof payload.message === "string") return payload.message;
+	if (typeof payload.error === "string") return payload.error;
+	if (isRecord(payload.error) && typeof payload.error.message === "string") return payload.error.message;
+	if (typeof payload.detail === "string") return payload.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(requestContext) {
+	return `${requestContext.init.method ?? "GET"} ${redactUrl(requestContext.url)}`;
+}
+async function responseError(response, requestContext, extractDescription = defaultDescription) {
+	const read = await readCapped(response, MAX_ERROR_BODY_BYTES);
+	const payload = read && parseBody(read);
+	if (read) response = rebuildResponse(response, read.bytes);
+	const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+	let description;
+	try {
+		description = extractDescription(payload, response) || void 0;
+	} catch {}
+	return new ArthronError({
+		message: `${describeRequest(requestContext)} failed with ${status}`,
+		description,
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+		payload,
+		requestContext,
+		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";
+/**
+* Take `url`'s query and userinfo out of an error the runtime threw, in
+* place: its message and stack, string fields (Node's `input`), and its
+* causes. `console.error` and error trackers print that chain, not
+* `toJSON()`. It stays the same object, so `cause.code` and `instanceof`
+* still work; a field that cannot be redefined (a frozen error) is left.
+*/
+function redactErrorUrl(error, url, seen = /* @__PURE__ */ new Set()) {
+	if (typeof error !== "object" || error === null || seen.has(error)) return;
+	seen.add(error);
+	const fields = error;
+	for (const key of /* @__PURE__ */ new Set([
+		"message",
+		"stack",
+		...Object.keys(error)
+	])) {
+		const value = fields[key];
+		if (typeof value !== "string") continue;
+		const redacted = redactUrlIn(value, url);
+		if (redacted === value) continue;
+		try {
+			Object.defineProperty(error, key, { value: redacted });
+		} catch {}
+	}
+	redactErrorUrl(fields.cause, url, seen);
+}
+function networkError(cause, requestContext) {
+	redactErrorUrl(cause, requestContext.url);
+	const reason = cause instanceof Error && cause.message ? cause.message : "network error";
+	const hint = isReadableStream(requestContext.init.body) ? STREAM_BODY_HINT : "";
+	return new ArthronError({
+		message: `${describeRequest(requestContext)} failed: ${reason}${hint}`,
+		status: 0,
+		statusText: "",
+		headers: new Headers(),
+		payload: void 0,
+		requestContext,
+		cause
+	});
+}
+//#endregion
+export { withoutSecrets as C, resolveUrl as S, leavesBase as _, responseError as a, redactUrl as b, isReadableStream as c, tagOf as d, ArthronError as f, httpOrigins as g, httpOrigin as h, redactErrorUrl as i, runtimeStreamsRequestBody as l, fillPath as m, isCancellation as n, rebuildResponse as o, isArthronError as p, networkError as r, withFields as s, cancellationError as t, serializeBody as u, originOf as v, redactUrlIn as x, originSet as y };