arthron 0.0.1 → 0.1.0

package/README.md

@@ -1,10 +1,22 @@
 # arthron
 
-**Middleware owns the flow — it can call `next` again to retry the whole request. Interceptors only transform values and can never change the flow. arthron keeps the two apart at the type level.**
+A `fetch` client you assemble from plugins.
 
-A composable `fetch` client. Create one from config, plug in interceptors and middleware, get a plain `Response` back. Zero dependencies, TypeScript first, Node 18+ and browsers.
+```ts
+import { arthron, logging, retry, timeout } from "arthron";
+
+const api = arthron({
+  baseURL: "https://api.example.com",
+  use: [logging(), timeout(10_000), retry()],
+});
+
+const user = await api.get("/me").json<User>();
+```
 
-> *arthron* (ἄρθρον) — Greek for "joint": the place where two parts meet and work as one.
+- **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 and timeouts are middleware. Headers, logging and error mapping 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 18+ and browsers.
 
 ## Install
 
@@ -12,176 +24,183 @@ A composable `fetch` client. Create one from config, plug in interceptors and mi
 npm i arthron
 ```
 
-## Quick start
+## Usage
 
-```ts
-import { arthron, logging, retry } from "arthron";
+### Create a client
 
-const base = arthron({
-  baseURL: "https://api.example.com",
-  use: [logging(), retry({ retries: 3 })],
-});
-
-const api = base.extend({
-  use: [auth({ getToken, refresh })], // your own plugin — see "Writing your own plugin"
+```ts
+const api = arthron({
+  baseURL: "https://api.example.com", // prefix for relative paths
+  headers: { accept: "application/json" }, // defaults; per-call headers win
+  credentials: "include", // only if you need cookies cross-origin
+  use: [retry()], // plugins, outermost first
 });
-
-const res = await api.get("/me");                             // Response
-const user = await api.get("/me").json<User>();               // parsed body
-const blob = await api.get("/export").blob();
-const stream = (await api.post("/chat", { prompt })).body;    // ReadableStream
 ```
 
-## Concepts
+Every field is optional. Without `baseURL`, only absolute URLs are accepted.
 
-One request runs like this:
+### Make requests
 
+```ts
+await api.get("/users", { params: { page: 2 } }); // → Response
+await api.post("/users", { name: "kim" }); // object body → JSON
+await api.post("/upload", formData); // FormData/Blob/string/stream → sent as-is
+await api.put("/users/1", { name: "lee" });
+await api.patch("/users/1", { name: "lee" });
+await api.delete("/users/1");
+await api.head("/users/1");
+await api.request("/users", { method: "OPTIONS" });
 ```
-middleware[0] (
-  middleware[1] (
-    ...
-      attempt: request interceptors → fetch → ok ? response interceptors : error interceptors → throw
-  )
-)
-```
-
-- **Middleware** wraps the whole call, outermost first in registration order. `next(ctx)` runs everything beneath it; calling `next` again re-runs the whole attempt — that is how retry, auth refresh and timeouts are built.
-- **Interceptors** run inside each attempt. They receive a value (`RequestContext`, `Response`, or `ArthronError`) and return one. They cannot skip, retry, or swallow — an error interceptor's return value is always thrown.
-- Every attempt starts from a **copy** of the context, so headers an interceptor set on attempt one do not leak into attempt two.
 
-A plugin is just an object bundling any of the four:
+Each call returns `Promise<Response>` with body helpers attached:
 
 ```ts
-type Plugin = {
-  name?: string;
-  middleware?: (ctx, next) => Promise<Response>;
-  request?:    (ctx) => RequestContext | Promise<RequestContext>;
-  response?:   (res, ctx) => Response | Promise<Response>;
-  error?:      (err, ctx) => ArthronError | Promise<ArthronError>;
-};
+const res = await api.get("/me"); // Response — status, headers, body untouched
+const user = await api.get("/me").json<User>(); // body parsed; T is a cast, not validation
+const text = await api.get("/robots.txt").text();
+const blob = await api.get("/export").blob();
+const stream = (await api.post("/chat", prompt)).body; // ReadableStream
+for await (const e of api.post("/chat", prompt).sse()) {} // see "Stream responses"
 ```
 
-## API
+`init` accepts everything `fetch` does (`signal`, `cache`, `headers`, …) plus `params`, a query object whose `null`/`undefined` values are dropped.
 
-### `arthron(config?)`
+### Stream responses
 
 ```ts
-type ArthronConfig = {
-  baseURL?: string;                 // prefix for relative paths; without it only absolute URLs are accepted
-  headers?: HeadersInit;            // defaults; per-call headers win, compared case-insensitively
-  credentials?: RequestCredentials; // forwarded as-is; NOT set unless you set it
-  fetch?: typeof fetch;             // injection point for tests / polyfills
-  use?: Plugin[];
-  errorMessage?: (data: unknown, res: Response) => string | undefined;
-};
+// Server-sent events — one event per `for await` step
+for await (const { event, data } of api.post("/v1/chat/completions", body).sse()) {
+  if (data === "[DONE]") break; // provider sentinel; arthron does not interpret it
+  process.stdout.write(JSON.parse(data).choices[0].delta.content ?? "");
+}
+
+// Newline-delimited JSON (Ollama, many log endpoints)
+for await (const row of api.get("/logs").ndjson<LogRow>()) console.log(row);
 ```
 
-### Instance
+`.sse()` follows the EventSource spec (multi-line `data:` joined with `\n`, comments ignored, dispatch on blank line). Both helpers honour `signal` and `timeout` while the body is being read.
+
+### Handle errors
 
 ```ts
-api.get(path, init?)            api.delete(path, init?)        api.head(path, init?)
-api.post(path, body?, init?)    api.put(path, body?, init?)    api.patch(path, body?, init?)
-api.request(path, { method, body?, ...init })
+import { isArthronError } from "arthron";
 
-api.use(...plugins)   // new client with plugins appended
-api.extend(config)    // new client: config shallow-merged, headers merged, plugins appended
+try {
+  await api.get("/users/404");
+} catch (e) {
+  if (isArthronError(e)) {
+    e.status; // 404, or 0 when the network failed
+    e.data; // parsed body: JSON, else text, else undefined
+    e.message; // from the body (`message` → `error` → `error.message` → `detail`), else "Request failed with status 404"
+    e.response; // the original Response, still readable
+  }
+}
 ```
 
-`init` is `RequestInit` minus `method`/`body`, plus `params` (query object; `null`/`undefined` skipped, appended with `&` if the path already has a query).
-
-Clients are **immutable**. `use` and `extend` return new clients; the receiver — and anything previously derived from it — is untouched.
-
-**Body rules.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams`, `ReadableStream` are sent as-is with no `Content-Type` added. Anything else is `JSON.stringify`-ed with `content-type: application/json`, unless you already set a content type.
+A request that is aborted or times out rejects with the browser's `AbortError` / `TimeoutError`, not an `ArthronError`.
 
-**URL rules.** `baseURL` and `path` are joined by string concatenation — `"https://a/v1" + "/users"` → `https://a/v1/users`. The prefix survives a leading slash (unlike `new URL()`). Absolute paths skip `baseURL`.
+### Derive clients
 
-### Return value — `ArthronPromise`
-
-Every method returns `Promise<Response>` with convenience helpers:
+Clients are immutable. `use` and `extend` return a new client and leave the original alone.
 
 ```ts
-const res  = await api.get("/me");                 // Response, untouched
-const body = await api.get("/me").json<User>();    // (await res).json() — T is a cast, not validation
-                     .text() .blob() .arrayBuffer() .formData()
+const base = arthron({ baseURL: API, use: [logging(), retry()] });
+const authed = base.use(auth()); // base + auth
+const admin = authed.extend({ headers: { "x-role": "admin" } }); // authed + header
 ```
 
-A `204`/empty body makes `.json()` reject, exactly like `Response.json()` would.
+`extend` shallow-merges the config, merges headers case-insensitively (child wins), and appends plugins.
+
+## Plugins
 
-### Errors — `ArthronError`
+A plugin is an object with any of four slots:
 
 ```ts
-class ArthronError extends Error {
-  status: number;        // HTTP status; 0 for network failures
-  statusText: string;
-  headers: Headers;
-  data: unknown;         // parsed body: JSON if it parses, else text, else undefined
-  response?: Response;   // the original; its body is already consumed into `data`. Absent for network failures
-  request: RequestContext;
-  cause?: unknown;       // the original error for network failures
-}
+type Plugin = {
+  name?: string;
+  middleware?: (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+  request?: (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
+  response?: (res: Response, ctx: RequestContext) => Response | Promise<Response>;
+  error?: (err: ArthronError, ctx: RequestContext) => ArthronError | Promise<ArthronError>;
+};
+
+type RequestContext = { url: string; init: RequestInit };
 ```
 
-Only two things become an `ArthronError`: a response with `ok === false`, and `fetch` itself rejecting (network failure, `status: 0`). **Everything else is rethrown untouched and skips the error interceptors** — `AbortError`, `TimeoutError`, and anything a plugin throws. A bug in an interceptor is a bug, not a 500.
+How one request runs:
 
-The message is picked from the body by `message` → `error` (string) → `error.message` → `detail`, falling back to `Request failed with status N`. Override with `errorMessage` in the config.
+```
+middleware 1
+  middleware 2
+    attempt ─ request interceptors → fetch → response interceptors
+                                           ↘ error interceptors → throw
+```
 
-```ts
-import { isArthronError } from "arthron";
+| | Middleware | Interceptor |
+|---|---|---|
+| Runs | Once per call, wrapping everything below | Once per attempt |
+| Gets | `ctx` and `next` | A value: context, `Response`, or `ArthronError` |
+| Can | Call `next` again (retry), skip it, add a deadline | Return a changed value |
+| Cannot | — | Retry, skip, or stop the error from being thrown |
+| Examples | `retry`, `timeout`, auth refresh | auth header, tracing id, error mapping |
 
-try { await api.get("/me"); }
-catch (e) { if (isArthronError(e) && e.status === 404) { /* … */ } else throw e; }
-```
+Every attempt starts from a fresh copy of the context, so a header set by an interceptor on attempt one does not leak into attempt two.
 
-## Built-in plugins
+### Built in
 
-### `logging(options?)`
+#### `retry(options)`
 
-One line when a request starts, one when it settles. The query string is dropped (it tends to carry tokens). Cancellations are not logged.
+Re-runs the attempt on network failure or a retryable status. Because it re-runs the whole attempt, request interceptors run again — a refreshed token or a new trace id is picked up automatically.
 
 | option | default | |
 |---|---|---|
-| `enabled` | `true` | arthron never reads `NODE_ENV` — pass `isDev` yourself |
-| `logger` | `console` | needs `log` and `error` |
+| `retries` | `2` | retries after the first attempt (3 requests total) |
+| `retryOn` | `[408, 429, 500, 502, 503, 504]` | network failures (`status: 0`) are always retried |
+| `methods` | `GET HEAD OPTIONS PUT DELETE` | case-insensitive |
+| `delay` | `(retry) => 300 * 2 ** retry` | ms; `retry` counts from 0 |
+| `maxRetryAfter` | `60_000` | a `Retry-After` longer than this means "don't retry" |
 
-```
-[arthron] → GET /users
-[arthron] ← GET /users 200 42ms
-[arthron] ✕ GET /users 503 1203ms
+Honours `Retry-After` (seconds or HTTP date). Never retries a `ReadableStream` body or an aborted request.
+
+#### `timeout(ms)`
+
+Aborts the attempt after `ms`, counted until the body has been fully read — a server that sends headers and then stalls still trips it. Rejects with a `TimeoutError`, which `retry` and error interceptors ignore. Combines with a `signal` you pass yourself.
+
+```ts
+arthron({ use: [retry(), timeout(5_000)] }); // 5 s per attempt
+arthron({ use: [timeout(5_000), retry()] }); // 5 s for all attempts together
 ```
 
-### `retry(options?)`
+#### `logging(options)`
 
-Retries by calling `next` again, so request interceptors (fresh auth header, fresh trace id) run on every attempt.
+```
+[arthron] → GET https://api.example.com/users
+[arthron] ← GET https://api.example.com/users 200 42ms
+[arthron] ✕ GET https://api.example.com/users 503 1203ms
+```
 
 | option | default | |
 |---|---|---|
-| `retries` | `2` | retries *after* the first attempt — 3 requests total |
-| `retryOn` | `[408, 429, 500, 502, 503, 504]` | network failures (`status 0`) are always retried |
-| `methods` | `GET HEAD OPTIONS PUT DELETE` | case-insensitive |
-| `delay` | `retry => 300 * 2 ** retry` | ms; `retry` is 0-based |
-| `maxRetryAfter` | `60_000` | a `Retry-After` longer than this (ms) means "don't retry" |
-
-`Retry-After` (seconds or HTTP-date) wins over `delay` when present and within `maxRetryAfter`; beyond it the error is thrown without retrying. `ReadableStream` bodies are never retried (they can only be read once). Respects `signal` — an aborted request stops retrying immediately.
+| `enabled` | `true` | pass `process.env.NODE_ENV !== "production"` or similar — arthron never reads env |
+| `logger` | `console` | anything with `log` and `error` |
+| `onEvent` | — | receive `{ phase, method, path, status, ms, error }` instead of console lines |
 
-## Writing your own plugin
+Query strings and `user:pass@` are never printed. Cancellations are not logged.
 
-`defineMiddleware`, `defineInterceptor.{request,response,error}` and `definePlugin` are identity functions that give you contextual typing. Use them or annotate — same result.
+### Write your own
 
-### `auth` — refresh on 401, then re-run the request
+`definePlugin`, `defineMiddleware` and `defineInterceptor.{request,response,error}` are identity functions that give you the parameter types without annotations.
 
-This is the case the middleware/interceptor split exists for. The refresh and the retry are *flow*, so they live in middleware. Attaching the header is a *value change*, so it is a request interceptor — and because every `next` re-runs the interceptors, the retried request automatically picks up the new token.
+**Refresh a session on 401, then redo the request.** The refresh is flow, so it is middleware. The header is a value, so it is a request interceptor — and because `next` re-runs the interceptors, the retried request carries the new token without extra code.
 
 ```ts
 import { definePlugin, isArthronError } from "arthron";
 
-export const auth = ({ getToken, refresh }: {
-  getToken: () => string | null;
-  refresh: () => Promise<void>;
-}) =>
+export const auth = (store: { token: () => string | null; refresh: () => Promise<void> }) =>
   definePlugin({
     name: "auth",
     request: (ctx) => {
-      const token = getToken();
+      const token = store.token();
       if (!token) return ctx;
       return { ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, authorization: `Bearer ${token}` } } };
     },
@@ -190,53 +209,89 @@ export const auth = ({ getToken, refresh }: {
         return await next(ctx);
       } catch (e) {
         if (!isArthronError(e) || e.status !== 401) throw e;
-        await refresh();          // throws → propagates; caller decides to log out
-        return next(ctx);         // whole attempt again, request interceptor adds the new token
+        await store.refresh(); // if this throws, the caller sees it
+        return next(ctx);
       }
     },
   });
 ```
 
-### `errorRedirect` — react to errors without changing them
-
-An error interceptor can only *look* and *return*; it cannot swallow. That makes it the right home for side effects like navigation.
+**Send users to an error page.** Error interceptors can look and act, but the error is thrown regardless — which is what you want for a side effect like navigation.
 
 ```ts
 import { defineInterceptor } from "arthron";
 
 export const errorRedirect = (navigate: (to: string) => void) =>
   defineInterceptor.error((err, ctx) => {
-    const isGet = (ctx.init.method ?? "GET") === "GET";
-    if (isGet && err.status === 404) navigate("/not-found");
-    if (isGet && err.status >= 500) navigate("/error");
-    return err; // still thrown
+    if ((ctx.init.method ?? "GET") !== "GET") return err;
+    if (err.status === 404) navigate("/not-found");
+    if (err.status >= 500) navigate("/error");
+    return err;
   });
 
 api.use({ error: errorRedirect(router.push) });
 ```
 
-### `timeout` — a four-line middleware
+**Attach a trace id.** A one-line request interceptor.
+
+```ts
+api.use({ request: (ctx) => ({ ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, "x-trace-id": crypto.randomUUID() } } }) });
+```
+
+## Reference
+
+### `arthron(config)`
+
+```ts
+type ArthronConfig = {
+  baseURL?: string;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  fetch?: typeof fetch; // inject for tests or a polyfill; resolved per request
+  use?: Plugin[];
+  errorMessage?: (data: unknown, res: Response) => string | undefined;
+};
+```
 
-`AbortSignal.any` needs Node 20.3+ or a current browser; on Node 18 combine the signals with an `AbortController` by hand.
+### Client
 
 ```ts
-import { defineMiddleware } from "arthron";
+get(path, init) · delete(path, init) · head(path, init)
+post(path, body, init) · put(path, body, init) · patch(path, body, init)
+request(path, { method, body, ...init })
+use(...plugins) → new client
+extend(config) → new client
+```
+
+All arguments after `path` are optional, except `method` in `request`.
+
+### `ArthronError`
 
-export const timeout = (ms: number) =>
-  defineMiddleware((ctx, next) =>
-    next({ ...ctx, init: { ...ctx.init, signal: AbortSignal.any([ctx.init.signal, AbortSignal.timeout(ms)].filter(Boolean) as AbortSignal[]) } }),
-  );
+```ts
+class ArthronError extends Error {
+  status: number; // 0 for network failures
+  statusText: string;
+  headers: Headers;
+  data: unknown;
+  response?: Response; // absent for network failures
+  request: RequestContext;
+  cause?: unknown; // the underlying error for network failures
+}
 ```
 
-The resulting `TimeoutError` is rethrown untouched — it is not an `ArthronError`, so `retry` will not retry it.
+### Rules worth knowing
+
+- **URLs are joined by string concatenation.** `baseURL: "https://a/v1"` + `"/users"` → `https://a/v1/users`. The `/v1` survives, unlike with `new URL()`. Absolute URLs bypass `baseURL`.
+- **Bodies.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams` and `ReadableStream` go through untouched. Anything else — including `null` — becomes JSON with `content-type: application/json` unless you set a content type. `GET`/`HEAD` with a body is rejected with a `TypeError`.
+- **`credentials` is not set unless you set it.** Cross-origin cookies need `credentials: "include"`.
+- **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 `BigInt` in a JSON body, a missing `method` in `request` — all surface as a rejected promise.
 
-## Gotchas
+## For tooling and agents
 
-- **`Response` bodies are single-use.** A response interceptor that wants to peek must `res.clone()` first; one that wants to change the body returns a new `Response`.
-- **`credentials` is not set by default.** Cookie-based sessions need `credentials: "include"` in the config (cross-origin) — arthron will not guess.
-- **`baseURL` joining is string concatenation.** `"…/v1"` + `"/users"` keeps `/v1`. Pass an absolute URL to escape the base.
-- **Only `!ok` and network failures become `ArthronError`.** Cancellations and plugin exceptions propagate as-is and do not reach error interceptors or `retry`.
-- **`.json<T>()` is a cast.** Validate with your schema library if you need to.
+- `llms.txt` ships in the package — a compressed API reference meant to be read by LLM-based tools (`node_modules/arthron/llms.txt`).
+- `examples/` holds type-checked, runnable recipes: LLM streaming, auth refresh, upload/download.
+- Error messages state the fix (`… — pass baseURL in arthron({ baseURL }) or use an absolute URL`).
 
 ## License