@zerotal/arch 1.7.3 → 1.7.5

package/docs/client/files.md

@@ -1,118 +0,0 @@
----
-title: Client File Transfers
-description: Uploading and downloading binary payloads.
----
-
-# File uploads & downloads
-
-The client encodes plain objects as JSON, which is the right default until the
-payload is binary. Recognising the difference is the whole of file handling here:
-on the way out, a body the platform already knows how to encode is passed through
-untouched; on the way back, you name the shape you expect.
-
-## Uploading
-
-A body that is `FormData`, `Blob`, `File`, `URLSearchParams`, `ArrayBuffer`, or a
-string is sent as-is with no JSON encoding, which lets `fetch` set the correct
-`Content-Type` — including the multipart boundary, a value that cannot be written
-by hand:
-
-```ts
-// in any frontend module
-const form = new FormData();
-form.append("avatar", file);
-await api.post("/api/avatars", form);
-```
-
-| Body              | Sent as                                     |
-| ----------------- | ------------------------------------------- |
-| Plain object      | JSON, with `Content-Type: application/json` |
-| `FormData`        | Multipart, boundary set by the platform     |
-| `File` / `Blob`   | Raw bytes                                   |
-| `URLSearchParams` | Form-encoded                                |
-| `ArrayBuffer`     | Raw bytes                                   |
-| String            | Sent verbatim                               |
-
-Do not set `Content-Type` yourself for a `FormData` upload. A hand-written header
-has no boundary parameter, and the server then fails to parse a body that is
-otherwise perfectly formed — a confusing failure worth avoiding by simply leaving
-the header alone.
-
-To send a file alongside ordinary fields, put everything in the `FormData`;
-mixing a JSON body and a file in one request is not possible:
-
-```ts
-const form = new FormData();
-form.append("title", "Quarterly report");
-form.append("document", file);
-await api.post("/api/reports", form);
-```
-
-## Downloading
-
-Responses are parsed as JSON unless you say otherwise. `responseType` names the
-shape you want:
-
-| `responseType`  | Returns              | Reach for it when                    |
-| --------------- | -------------------- | ------------------------------------ |
-| `"auto"`        | Parsed JSON, or text | The default — JSON with a safety net |
-| `"json"`        | Parsed JSON, or text | The body is known to be JSON         |
-| `"text"`        | `string`             | CSV, XML, plain text                 |
-| `"blob"`        | `Blob`               | Saving or displaying a file          |
-| `"arrayBuffer"` | `ArrayBuffer`        | Reading bytes directly               |
-
-```ts
-// in any frontend module
-const pdf = await api.get("/api/report", undefined, { responseType: "blob" });
-```
-
-`"auto"` and `"json"` fall back to the raw text when the body will not parse, so a
-misconfigured endpoint returning an HTML error page surfaces that page rather than
-a parse exception.
-
-A `204 No Content` response — or any response with `Content-Length: 0` — resolves
-to `undefined` rather than throwing, so a `DELETE` needs no special handling:
-
-```ts
-await api.delete("/api/avatars/1"); // → undefined
-```
-
-Handing a downloaded blob to the browser takes one more step, since the client
-returns the data rather than saving it:
-
-```ts
-const blob = await api.get("/api/report", undefined, { responseType: "blob" });
-
-const url = URL.createObjectURL(blob);
-const a = Object.assign(document.createElement("a"), { href: url, download: "report.pdf" });
-a.click();
-URL.revokeObjectURL(url);
-```
-
-## Reading response metadata
-
-Binary endpoints often carry the interesting information in headers. A per-request
-`meta` callback reads them without installing a global interceptor:
-
-```ts
-// in any frontend module
-let total: string | null = null;
-const users = await api.get("/api/users", undefined, {
-  meta: (m) => (total = m.headers.get("X-Total")),
-});
-```
-
-This is the way to reach pagination totals, rate-limit counters, and `ETag` values
-while still receiving the parsed body as the return value.
-
-## Query serialization
-
-Query objects serialize arrays and nested objects with bracket notation:
-`{ ids: [1, 2], filter: { status: "open" } }` becomes
-`?ids[]=1&ids[]=2&filter[status]=open`.
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Making requests](/docs/client/requests) — the full request surface.
-- [Error handling](/docs/client/errors) — what a failed transfer throws.

package/docs/client/references.md

@@ -1,58 +0,0 @@
----
-title: Client References
-description: Every ApiClient method, config key, and error type in one table.
----
-
-# References
-
-## `createApiClient<Routes>(config)`
-
-Returns an `ApiClient<Routes>` bound to your route map. The `config` is an
-`ApiClientConfig` (see the [Configuration](/docs/client#configuration) table for the common
-fields, plus `onError`, `onResponse`, `onRequest`, `onUnauthorized`, `onForbidden`,
-and `circuitBreaker`).
-
-## ApiClient methods
-
-| Method     | Signature                                                            | Description                        |
-| ---------- | -------------------------------------------------------------------- | ---------------------------------- |
-| `get`      | `get(path, params?, options?: GetOptions): Promise<Response>`        | Typed GET; path params then query. |
-| `post`     | `post(path, body?, options?: MutationOptions): Promise<Response>`    | Typed POST with body.              |
-| `put`      | `put(path, body?, options?: MutationOptions): Promise<Response>`     | Typed PUT with body.               |
-| `patch`    | `patch(path, body?, options?: MutationOptions): Promise<Response>`   | Typed PATCH with body.             |
-| `delete`   | `delete(path, params?, options?: RequestOptions): Promise<Response>` | Typed DELETE; path params only.    |
-| `setToken` | `setToken(token: TokenSource \| null): void`                         | Update or clear the bearer token.  |
-
-## ApiClientError
-
-| Member         | Signature               | Description                            |
-| -------------- | ----------------------- | -------------------------------------- |
-| `status`       | `number`                | HTTP status code.                      |
-| `statusText`   | `string`                | HTTP status text.                      |
-| `body`         | `string`                | Raw response text.                     |
-| `headers`      | `Headers \| undefined`  | Response headers, when available.      |
-| `retryAfterMs` | `get(): number \| null` | Parsed `Retry-After` in ms, or `null`. |
-
-## ValidationError extends ApiClientError
-
-| Member              | Signature                                   | Description                        |
-| ------------------- | ------------------------------------------- | ---------------------------------- |
-| `errors`            | `Record<string, string[]>`                  | Field → messages map.              |
-| `validationMessage` | `string`                                    | Top-level `message` from the body. |
-| `has`               | `has(field: string): boolean`               | Whether a field has any error.     |
-| `first`             | `first(field: string): string \| undefined` | First message for a field.         |
-| `all`               | `all(): Record<string, string[]>`           | The full field-error map.          |
-| `fields`            | `fields(): string[]`                        | Names of every failed field.       |
-
-## CircuitBreaker
-
-| Member     | Signature                                   | Description                             |
-| ---------- | ------------------------------------------- | --------------------------------------- |
-| `call`     | `call<T>(fn: () => Promise<T>): Promise<T>` | Run `fn` under the breaker.             |
-| `state`    | `get(): CircuitState`                       | `'closed'`, `'open'`, or `'half-open'`. |
-| `failures` | `get(): number`                             | Current consecutive failure count.      |
-| `reset`    | `reset(): void`                             | Manually return to the closed state.    |
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.

package/docs/client/requests.md

@@ -1,131 +0,0 @@
----
-title: Client Requests
-description: The typed route map, making requests, and shaping them with interceptors.
----
-
-# Route map
-
-Define your API surface once. Keys are `'METHOD /path'` strings — path params are
-`{braces}` style. All fields are optional.
-
-```ts
-// app/api/api-types.ts
-export interface Routes {
-  "GET /api/users": {
-    query: { page?: number; perPage?: number; search?: string };
-    response: { data: UserResource[]; total: number };
-  };
-  "GET /api/users/{id}": {
-    params: { id: number };
-    response: UserResource;
-  };
-  "POST /api/users": {
-    body: { name: string; email: string; password: string };
-    response: UserResource;
-  };
-  "PUT /api/users/{id}": {
-    params: { id: number };
-    body: { name?: string; email?: string };
-    response: UserResource;
-  };
-  "DELETE /api/users/{id}": {
-    params: { id: number };
-    response: void;
-  };
-}
-```
-
-## Making requests
-
-```ts
-// in any frontend module
-// GET with path params
-const user = await api.get("/api/users/{id}", { id: 42 });
-//    ^? UserResource — inferred from the route map
-
-// GET with query string
-const list = await api.get("/api/users", undefined, {
-  query: { page: 2, perPage: 25, search: "alice" },
-});
-//    ^? { data: UserResource[]; total: number }
-
-// POST with body
-const created = await api.post("/api/users", {
-  name: "Alice",
-  email: "alice@example.com",
-  password: "hunter2",
-});
-//    ^? UserResource
-
-// PUT
-await api.put("/api/users/{id}", { name: "Alice Smith" }, { params: { id: 42 } });
-
-// PATCH
-await api.patch("/api/users/{id}", { email: "new@example.com" }, { params: { id: 42 } });
-
-// DELETE
-await api.delete("/api/users/{id}", { id: 42 });
-```
-
-All methods accept an optional `options` argument for per-request headers and
-extra `fetch` init fields (`signal`, `credentials`, etc.):
-
-```ts
-// in any frontend module
-const ctrl = new AbortController();
-
-await api.get("/api/users", undefined, {
-  headers: { "X-Trace-Id": requestId },
-  init: { signal: ctrl.signal },
-});
-```
-
-## Request interceptors
-
-Run one or more async functions before every outgoing request. Each interceptor
-receives the current `RequestConfig` and must return it (or a new one). Useful for
-attaching authorization headers from a reactive store without coupling the store
-to the client's constructor.
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-
-  // Single interceptor
-  onRequest: async (config) => ({
-    ...config,
-    headers: {
-      ...config.headers,
-      Authorization: `Bearer ${await tokenStore.get()}`,
-    },
-  }),
-});
-```
-
-Multiple interceptors execute in declaration order:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-  onRequest: [addAuthHeader, addRequestId, logOutgoing],
-});
-```
-
-A symmetric `onResponse` runs after every successful (2xx) response — receiving a
-`ResponseContext` of `{ status, headers, data, request }` — to unwrap envelopes or log.
-
-### RequestConfig shape
-
-| Field     | Type                     | Description                                                  |
-| --------- | ------------------------ | ------------------------------------------------------------ |
-| `method`  | `string`                 | HTTP verb — `'GET'`, `'POST'`, …                             |
-| `url`     | `string`                 | Full resolved URL (base + path + query string)               |
-| `headers` | `Record<string, string>` | Merged headers — add/override here                           |
-| `body`    | `BodyInit \| undefined`  | Serialised body (JSON string, `FormData`, …), or `undefined` |
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Reference](/docs/client/references) — the full API surface in one table.

package/docs/client/resilience.md

@@ -1,141 +0,0 @@
----
-title: Client Resilience
-description: Timeouts, retries, and the circuit breaker that spares a failing upstream.
----
-
-# Timeouts & retries
-
-Set a default `timeout` (ms) and/or a `retry` policy on the client, and override either per request:
-
-```ts
-// app/api/client.ts
-const api = createApiClient<Routes>({
-  timeout: 10_000,
-  retry: 2, // or { attempts, methods, statuses, backoff, respectRetryAfter }
-});
-
-await api.get("/api/users", undefined, { timeout: 2_000, retry: false });
-```
-
-Retries apply to **idempotent** methods by default (GET/PUT/DELETE/HEAD/OPTIONS) and trigger on
-network errors, request timeouts, and `408 / 425 / 429 / 5xx` responses, using exponential backoff
-with jitter and honoring any `Retry-After` header. A timeout aborts via `AbortSignal`; pass your
-own `signal` to cancel manually (it's combined with the timeout).
-
-> **Warning** — A caller-cancelled request (`AbortError`) is never retried, but a request that
-> times out (`TimeoutError`) is treated as transient and retried per your policy.
-
-## Circuit breaker
-
-Attach a circuit breaker to stop hammering a struggling upstream service and fail
-fast instead. When the circuit is open, requests throw `CircuitBreakerOpenError`
-immediately — no network call is made.
-
-```ts
-// app/api/client.ts
-import { createApiClient } from "@zerotal/client";
-
-// Option 1 — options object (creates a dedicated breaker)
-const api = createApiClient<Routes>({
-  baseUrl: "https://api.example.com",
-  circuitBreaker: {
-    threshold: 5, // open after 5 consecutive failures
-    resetTimeout: 30_000, // attempt recovery after 30 s
-  },
-});
-
-// Option 2 — shared instance (multiple clients trip the same circuit)
-import { CircuitBreaker } from "@zerotal/client";
-
-const breaker = new CircuitBreaker({ threshold: 3, resetTimeout: 10_000 });
-
-const usersApi = createApiClient<Routes>({ baseUrl: "…", circuitBreaker: breaker });
-const postsApi = createApiClient<Routes>({ baseUrl: "…", circuitBreaker: breaker });
-```
-
-### Which option should I use?
-
-- **Options object** — one client talks to one upstream. Each client gets its own dedicated breaker.
-- **Shared `CircuitBreaker` instance** — several clients hit the _same_ upstream and should trip together as a unit.
-
-```ts
-// in any frontend module
-import { CircuitBreakerOpenError } from "@zerotal/client";
-
-try {
-  await api.get("/api/users");
-} catch (err) {
-  if (err instanceof CircuitBreakerOpenError) {
-    // Return cached data, show degraded UI, etc.
-  }
-}
-```
-
-### Failure classification
-
-By default:
-
-- **5xx responses** → counted as failures (upstream is unhealthy)
-- **4xx responses** → not counted (client mistakes, not upstream outages)
-- **Network / DNS / timeout errors** → counted as failures
-
-Override with a custom predicate:
-
-```ts
-// in any frontend module
-new CircuitBreaker({
-  isFailure: (err) => {
-    if (err instanceof ApiClientError) return err.status >= 500;
-    return true; // any non-ApiClientError (network failure) counts
-  },
-});
-```
-
-## Standalone CircuitBreaker
-
-`CircuitBreaker` can wrap any async operation — not just HTTP requests.
-
-```ts
-// in any module
-import { CircuitBreaker, CircuitBreakerOpenError } from "@zerotal/client";
-
-const breaker = new CircuitBreaker({ threshold: 3, resetTimeout: 15_000 });
-
-async function fetchPricing() {
-  return breaker.call(async () => {
-    const res = await fetch("https://pricing.internal/v1/rates");
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    return res.json();
-  });
-}
-```
-
-### State machine
-
-| State       | Behaviour                                               |
-| ----------- | ------------------------------------------------------- |
-| `closed`    | Requests pass through; consecutive failures are counted |
-| `open`      | All calls immediately throw `CircuitBreakerOpenError`   |
-| `half-open` | One probe request is allowed through to test recovery   |
-
-Transitions:
-
-- **closed → open** when failure count reaches `threshold`
-- **open → half-open** after `resetTimeout` ms
-- **half-open → closed** on a successful probe
-- **half-open → open** on a failed probe (timer resets)
-
-While in `half-open`, concurrent calls that arrive before the probe completes also
-throw `CircuitBreakerOpenError` — only one probe goes through at a time.
-
-```ts
-// in any module
-breaker.state; // 'closed' | 'open' | 'half-open'
-breaker.failures; // current consecutive failure count
-breaker.reset(); // manually reset to closed (e.g. after an admin action)
-```
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Reference](/docs/client/references) — the full API surface in one table.

package/docs/client/testing.md

@@ -1,146 +0,0 @@
----
-title: Testing the Client
-description: Stub the global fetch, cover the failure paths, and drive the circuit breaker.
----
-
-# Testing
-
-Set your suite up once as described in [Testing](/docs/testing). `ApiClient`
-calls the global `fetch`, so a test controls it by replacing that — there is no
-separate fake to install.
-
-```typescript
-// tests/services/BillingClient.test.ts
-import { test, expect, afterEach } from "bun:test";
-import { ApiClient } from "@zerotal/client";
-
-const realFetch = globalThis.fetch;
-afterEach(() => {
-  globalThis.fetch = realFetch;
-});
-
-test("maps a customer payload onto our shape", async () => {
-  globalThis.fetch = async () =>
-    new Response(JSON.stringify({ id: "cus_1", email: "jane@example.com" }), {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    });
-
-  const client = new ApiClient({ baseUrl: "https://api.example.com" });
-  const customer = await client.get("/customers/cus_1");
-
-  expect(customer.email).toBe("jane@example.com");
-});
-```
-
-**Restore `fetch` in `afterEach`, not at the end of the test.** A test that
-throws before its cleanup line leaves the stub installed, and every later test in
-the file talks to it instead of the network — producing failures that point at
-innocent code.
-
-## Asserting on the request
-
-Stubbing the response proves your code reads the answer correctly. It says nothing
-about whether you asked the right question — a client that sends the wrong URL,
-loses a query parameter, or drops the auth header passes every response-shaped test
-and still fails in production. Capture what `fetch` received and assert on it:
-
-```typescript
-// tests/services/BillingClient.test.ts
-test("sends the query and the auth header", async () => {
-  let url: string | undefined;
-  let init: RequestInit | undefined;
-
-  globalThis.fetch = async (u, i) => {
-    url = String(u);
-    init = i;
-    return new Response("[]", { status: 200 });
-  };
-
-  const client = new ApiClient({
-    baseUrl: "https://api.example.com",
-    token: "tok_123",
-  });
-  await client.get("/customers", { status: "active" });
-
-  expect(url).toBe("https://api.example.com/customers?status=active");
-  expect(new Headers(init?.headers).get("Authorization")).toBe("Bearer tok_123");
-});
-```
-
-Wrap the headers in `new Headers(...)` before reading them. Casing is normalised
-that way, so the assertion holds whether the value arrived as a plain object or as
-a `Headers` instance from a per-request override.
-
-Uploads deserve one such test each. Asserting that `init.body` is the `FormData`
-you passed — rather than a JSON string — is what pins down that the body was not
-re-encoded on its way out.
-
-**Test the failure paths, because they are the ones production hits.** A 500, a
-timeout, and a malformed body all reach your code differently:
-
-```typescript
-// tests/services/BillingClient.test.ts
-test("a 500 surfaces as ApiClientError", async () => {
-  globalThis.fetch = async () => new Response("upstream boom", { status: 500 });
-
-  await expect(client.get("/customers/cus_1")).rejects.toBeInstanceOf(ApiClientError);
-});
-```
-
-A network failure is a different case again, and the stub models it by rejecting
-instead of resolving — which is how you reach the branch that never receives a
-status at all:
-
-```typescript
-globalThis.fetch = async () => {
-  throw new TypeError("Failed to fetch");
-};
-
-await expect(client.get("/customers")).rejects.not.toBeInstanceOf(ApiClientError);
-```
-
-## Retries and the circuit breaker
-
-A retry policy is invisible from the outside — the caller sees one resolved promise
-whether it took one attempt or four. Counting calls is what makes the behaviour
-observable:
-
-```typescript
-// tests/services/BillingClient.test.ts
-let calls = 0;
-globalThis.fetch = async () => {
-  calls++;
-  return calls < 3 ? new Response("", { status: 503 }) : new Response("{}", { status: 200 });
-};
-
-await client.get("/customers");
-expect(calls).toBe(3); // two failures, then success
-```
-
-**A circuit breaker is a state machine**, so drive it with repeated failures and
-assert it opens — then that it refuses without calling `fetch` at all:
-
-```typescript
-// tests/services/BillingClient.test.ts
-let calls = 0;
-globalThis.fetch = async () => {
-  calls++;
-  return new Response("", { status: 500 });
-};
-
-for (let i = 0; i < threshold; i++) await client.get("/x").catch(() => {});
-const before = calls;
-
-await expect(client.get("/x")).rejects.toBeInstanceOf(CircuitBreakerOpenError);
-expect(calls).toBe(before); // the open circuit short-circuits, no request made
-```
-
-That last assertion is the point of a breaker — without it you have tested that
-an error is thrown, not that the upstream was spared.
-
-## Next steps
-
-- [Client overview](/docs/client) — the guide's front page and the rest of the sections.
-- [Resilience](/docs/client/resilience) — the retry and breaker policies under test.
-- [Error handling](/docs/client/errors) — the errors these tests assert on.