arthron 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,656 @@
+//#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;
+	});
+}
+/**
+* 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 (isRawBody(body)) return {
+		body,
+		headers
+	};
+	const withType = "content-type" in headers ? headers : {
+		...headers,
+		"content-type": "application/json"
+	};
+	return {
+		body: JSON.stringify(body),
+		headers: withType
+	};
+}
+//#endregion
+//#region src/error.ts
+/**
+* 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 {
+	name = "ArthronError";
+	/** HTTP status of the failed response; `0` when fetch itself failed (network). */
+	status;
+	statusText;
+	/** Response headers; empty for network failures. */
+	headers;
+	/** Parsed body: JSON if it parses, else the text, else `undefined`. */
+	data;
+	/** The context that was sent — url and init after request interceptors. */
+	request;
+	/** The original Response, still readable (the body was parsed from a clone). Absent for network failures. */
+	response;
+	/** 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.cause = init.cause;
+	}
+};
+/** `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.clone());
+	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
+	});
+}
+//#endregion
+//#region src/headers.ts
+/**
+* Normalize any `HeadersInit` (plain object, `Headers`, tuple array) into a
+* plain record. Keys come back lowercased — `Headers` does that for us.
+*/
+function toHeaderRecord(headers) {
+	if (!headers) return {};
+	return Object.fromEntries(new Headers(headers).entries());
+}
+/**
+* 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.
+*/
+function mergeHeaders(base, override) {
+	return {
+		...toHeaderRecord(base),
+		...toHeaderRecord(override)
+	};
+}
+//#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.
+*/
+function cloneContext({ url, init }) {
+	return {
+		url,
+		init: {
+			...init,
+			headers: toHeaderRecord(init.headers)
+		}
+	};
+}
+/**
+* Owns the order of one request.
+*
+* Middleware wraps the whole call, outermost first in registration order.
+* Each attempt below it runs request interceptors → `send` → response
+* interceptors. Only an `ArthronError` reaches the error interceptors; whatever
+* they return is thrown. Anything else that is thrown — cancellation, a bug
+* in a plugin — propagates untouched.
+*/
+async function runPipeline(plugins, ctx, send) {
+	const middlewares = [];
+	const request = [];
+	const response = [];
+	const error = [];
+	for (const plugin of plugins) {
+		if (plugin.middleware) middlewares.push(plugin.middleware);
+		if (plugin.request) request.push(plugin.request);
+		if (plugin.response) response.push(plugin.response);
+		if (plugin.error) error.push(plugin.error);
+	}
+	const attempt = async (input) => {
+		let current = cloneContext(input);
+		try {
+			for (const interceptor of request) current = await interceptor(current);
+			let res = await send(current);
+			for (const interceptor of response) res = await interceptor(res, current);
+			return res;
+		} catch (thrown) {
+			if (!isArthronError(thrown)) throw thrown;
+			let err = thrown;
+			for (const interceptor of error) err = await interceptor(err, current);
+			throw err;
+		}
+	};
+	const dispatch = (index, input) => {
+		const middleware = middlewares[index];
+		if (!middleware) return attempt(input);
+		return middleware(input, (next) => dispatch(index + 1, next));
+	};
+	return dispatch(0, ctx);
+}
+//#endregion
+//#region src/stream.ts
+/** Yield the body line by line, reassembling lines split across chunks. */
+async function* lines(response) {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			buffer += decoder.decode(value, { stream: !done });
+			const parts = buffer.split(/\r\n|\r|\n/);
+			buffer = parts.pop() ?? "";
+			for (const line of parts) yield line;
+			if (done) break;
+		}
+		if (buffer) yield buffer;
+	} finally {
+		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` is not dispatched. Provider sentinels like
+* `[DONE]` are passed through untouched — they are not part of the spec.
+*/
+async function* parseSse(response) {
+	let data = [];
+	let event;
+	let id;
+	let retry;
+	const flush = () => {
+		if (data.length === 0) {
+			event = id = retry = void 0;
+			return;
+		}
+		const out = { data: data.join("\n") };
+		if (event !== void 0) out.event = event;
+		if (id !== void 0) out.id = id;
+		if (retry !== void 0) out.retry = retry;
+		data = [];
+		event = id = retry = void 0;
+		return out;
+	};
+	for await (const line of lines(response)) {
+		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":
+				data.push(value);
+				break;
+			case "event":
+				event = value;
+				break;
+			case "id":
+				id = value;
+				break;
+			case "retry": {
+				const ms = Number(value);
+				if (Number.isInteger(ms) && ms >= 0) retry = ms;
+				break;
+			}
+		}
+	}
+	const out = flush();
+	if (out) yield out;
+}
+/**
+* Parse newline-delimited JSON. Blank lines are skipped; a malformed line
+* rejects the iteration with the `SyntaxError` from `JSON.parse`.
+*/
+async function* parseNdjson(response) {
+	for await (const line of lines(response)) {
+		if (line.trim() === "") continue;
+		yield JSON.parse(line);
+	}
+}
+//#endregion
+//#region src/promise.ts
+/** Defer the Response until iteration starts, so the helper itself never rejects. */
+function iterate(promise, parse) {
+	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()),
+		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: () => iterate(promise, parseSse),
+		ndjson: () => iterate(promise, parseNdjson)
+	});
+}
+//#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();
+}
+/**
+* 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.
+*/
+function resolveUrl(baseURL, path, params) {
+	let url;
+	if (isAbsoluteUrl(path)) url = path;
+	else {
+		if (baseURL === void 0) throw new TypeError(`arthron: relative path "${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/client.ts
+const BODYLESS_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+/** Normalize once so `extend` can merge headers and append plugins cheaply. */
+function resolveConfig(config) {
+	const { headers, use, ...rest } = config;
+	return {
+		...rest,
+		headers: toHeaderRecord(headers),
+		use: use ?? []
+	};
+}
+/**
+* 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);
+	/** The one place a failure becomes an ArthronError. Cancellation passes through. */
+	const send = async (ctx) => {
+		const fetchImpl = resolved.fetch ?? globalThis.fetch;
+		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 }) => {
+		try {
+			if (rawBody !== void 0 && BODYLESS_METHODS.has(method.toUpperCase())) throw new TypeError(`arthron: ${method.toUpperCase()} requests cannot carry a body — send it as params (query) or switch to POST`);
+			const url = resolveUrl(resolved.baseURL, path, params);
+			const { body, headers } = serializeBody(rawBody, mergeHeaders(resolved.headers, callHeaders));
+			const requestInit = {
+				...resolved.credentials !== void 0 && { credentials: resolved.credentials },
+				...init,
+				method,
+				headers
+			};
+			if (body !== void 0) requestInit.body = body;
+			return toArthronPromise(runPipeline(resolved.use, {
+				url,
+				init: requestInit
+			}, send));
+		} catch (thrown) {
+			return toArthronPromise(Promise.reject(thrown));
+		}
+	};
+	const derive = (next) => {
+		return arthron({
+			...resolved,
+			...next,
+			headers: mergeHeaders(resolved.headers, next.headers),
+			use: [...resolved.use, ...next.use ?? []]
+		});
+	};
+	return {
+		get: (path, init = {}) => dispatch(path, "GET", void 0, init),
+		delete: (path, init = {}) => dispatch(path, "DELETE", void 0, init),
+		head: (path, init = {}) => dispatch(path, "HEAD", void 0, init),
+		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),
+		request: (path, init) => {
+			const { method, body, ...rest } = init;
+			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)
+	};
+}
+//#endregion
+//#region src/define.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
+/** Origin + pathname only — the query and userinfo tend to carry secrets. */
+function displayPath(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return url.split("?")[0] ?? url;
+	}
+}
+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 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.
+* 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, 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 = displayPath(ctx.url);
+			const started = now();
+			const ms = () => Math.round(now() - started);
+			emit({
+				phase: "start",
+				method,
+				path
+			});
+			try {
+				const res = await next(ctx);
+				emit({
+					phase: "success",
+					method,
+					path,
+					status: res.status,
+					ms: ms()
+				});
+				return res;
+			} catch (error) {
+				if (!isCancellation(error)) {
+					const status = isArthronError(error) ? error.status : void 0;
+					emit({
+						phase: "error",
+						method,
+						path,
+						status,
+						ms: ms(),
+						error
+					});
+				}
+				throw error;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/retry.ts
+const DEFAULT_RETRY_ON = [
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+];
+const DEFAULT_METHODS = [
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"PUT",
+	"DELETE"
+];
+const DEFAULT_MAX_RETRY_AFTER = 6e4;
+function defaultSleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** `Retry-After` as ms — seconds or an HTTP-date. `undefined` when absent or unparsable. */
+function retryAfterMs(error) {
+	const value = error.headers.get("retry-after")?.trim();
+	if (!value) return void 0;
+	const seconds = Number(value);
+	if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1e3);
+	const at = Date.parse(value);
+	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;
+}
+/**
+* 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.
+*/
+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()));
+	return {
+		name: "retry",
+		middleware: async (ctx, next) => {
+			const method = (ctx.init.method ?? "GET").toUpperCase();
+			const eligible = allowed.has(method) && !isStreamBody(ctx);
+			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 (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);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/timeout.ts
+/**
+* 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) {
+	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;
+			}
+			controller.enqueue(value);
+		},
+		cancel(reason) {
+			finish();
+			return reader.cancel(reason);
+		}
+	});
+}
+/**
+* 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. Rejects with a `TimeoutError` (a
+* `DOMException`, like `AbortSignal.timeout()` would give); it is not an
+* `ArthronError`, so error interceptors and `retry` leave it alone.
+*
+* Built on `AbortController` + `setTimeout` rather than `AbortSignal.any` /
+* `AbortSignal.timeout` so it runs on Node 18.
+*/
+function timeout(ms) {
+	return {
+		name: "timeout",
+		middleware: async (ctx, next) => {
+			const controller = new AbortController();
+			const outer = ctx.init.signal;
+			const forward = () => controller.abort(outer?.reason);
+			if (outer?.aborted) forward();
+			else outer?.addEventListener("abort", forward, { once: true });
+			const timer = setTimeout(() => controller.abort(new DOMException(`arthron: request timed out after ${ms}ms`, "TimeoutError")), ms);
+			const finish = () => {
+				clearTimeout(timer);
+				outer?.removeEventListener("abort", forward);
+			};
+			let res;
+			try {
+				res = await next({
+					...ctx,
+					init: {
+						...ctx.init,
+						signal: controller.signal
+					}
+				});
+			} catch (thrown) {
+				finish();
+				throw thrown;
+			}
+			if (!res.body) {
+				finish();
+				return res;
+			}
+			return new Response(guardBody(res.body, controller.signal, finish), {
+				status: res.status,
+				statusText: res.statusText,
+				headers: res.headers
+			});
+		}
+	};
+}
+//#endregion
+export { ArthronError, arthron, defineInterceptor, defineMiddleware, definePlugin, isArthronError, logging, retry, timeout };
+
+//# sourceMappingURL=index.mjs.map