dixous 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # Dixous
 
-A minimal, fully typed, extendable fetch client.
+A small, fully typed HTTP client built on Fetch.
 
-Start with a simple request, then add validation, middleware, and custom response handlers as you need them.
+Dixous gives you runtime-validated responses, composable clients, and an extension system that can change how requests execute and what APIs are available on them.
 
 ## Installation
 
@@ -10,101 +10,233 @@ Start with a simple request, then add validation, middleware, and custom respons
 npm install dixous
 ```
 
-## Usage
+## Quick start
 
 ```ts
-import { dixous } from "./lib/dixous"; // Shared client created with createDixous
-import { z } from "zod";
+import { Dixous } from "dixous"
+import { z } from "zod"
 
-const image = await dixous.fetch("https://example.com/image.png").blob();
+const api = Dixous.create({
+  baseUrl: "https://api.example.com/",
+  headers: {
+    Authorization: "Bearer YOUR_API_TOKEN",
+  },
+})
 
 const User = z.object({
   id: z.number(),
   name: z.string(),
-});
+})
 
-const api = dixous({
-  baseUrl: "https://api.example.com/",
-  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
-});
-const user = await api.fetch("users/1").json(User);
+const user = await api
+  .request("users/1")
+  .json(User)
 
-console.log(user.name); // string, validated at runtime
+console.log(user.name)
 ```
 
-Requests run when you call `.json(schema)`, `.text()`, `.blob()`, `.arrayBuffer()`, or `.response()`. JSON accepts any Standard Schema v1 validator.
+The response is validated at runtime and inferred automatically from the schema.
+
+Dixous works with any [Standard Schema](https://standardschema.dev/) validator.
+
+## Why Dixous?
+
+Dixous tries to stay small without becoming limiting.
+
+* Built around native `Request` and `Response`
+* Runtime validation with full TypeScript inference
+* Immutable clients that compose and specialize naturally
+* Extensions can add options, wrap request execution, and add request APIs
+* Features such as retries, caching, logging, authentication, and custom formats stay outside the core
+* Drop down to the native `Response` whenever you need to
+
+## Extend the request API
 
-## Fully extensible
+Extensions can add entirely new request methods.
 
-Define your client once. Add response methods, middleware, and typed options with `defineExtension`.
+For example, [Schema XML](https://github.com/Asguho/schema-xml) can make XML feel like a native Dixous response format:
 
 ```ts
-// lib/dixous.ts
-import { createDixous, defineExtension } from "dixous";
-import { parseXml } from "schema-xml";
-import { z } from "zod";
+import {
+  Dixous,
+  defineExtension,
+} from "dixous"
+import { parseXml } from "schema-xml"
+import { z } from "zod"
 
-// Parse and validate XML with Schema XML.
 const xml = defineExtension({
-  methods: {
-    xml: (fetchResponse) =>
-      async <S extends z.ZodType>(schema: S): Promise<z.output<S>> =>
-        parseXml(await (await fetchResponse()).text(), schema),
-  },
-});
-
-// Retry GET requests up to three times in total on a 503 response.
-const retry = defineExtension({
-  async request({ request }, next) {
-    for (let attempt = 1; ; attempt++) {
-      request.signal.throwIfAborted();
-      const response = await next();
-      if (request.method !== "GET" || response.status !== 503 || attempt === 3) {
-        return response;
-      }
-      await response.body?.cancel();
+  operation(operation) {
+    return {
+      async xml<Schema extends z.ZodType>(
+        schema: Schema,
+      ): Promise<z.output<Schema>> {
+        const response = await operation.response()
+
+        return parseXml(
+          await response.text(),
+          schema,
+        )
+      },
     }
   },
-});
+})
+
+const api = Dixous.create({
+  extensions: [xml],
+})
+
+const Catalog = z.object({
+  catalog: z.object({
+    book: z.array(
+      z.object({
+        title: z.string(),
+      }),
+    ),
+  }),
+})
+
+const catalog = await api
+  .request("https://example.com/catalog.xml")
+  .xml(Catalog)
+
+console.log(catalog.catalog.book)
+// { title: string }[]
+```
+
+Dixous itself knows nothing about XML. Installing the extension adds `.xml(schema)` directly to the request type with full inference.
+
+Inside an extension, `operation.response()` is the response the operation reads. Dixous rejects non-OK responses before the extension sees them, so extensions only decode bodies.
+
+## Branch on status
+
+Use `.match()` when different statuses carry different bodies. Each handler receives the full operation API, including extension methods, bound to the matched response:
+
+```ts
+const result = await api
+  .request("users/1")
+  .match({
+    200: operation => operation.json(User),
+    404: operation => operation.text(),
+    422: operation => operation.json(ValidationError),
+  })
+// User | string | ValidationError
+```
+
+Statuses match exactly. An unmatched status rejects with `UnexpectedResponseError`.
+
+`match` is a default method like `json`. An extension can replace it, using `operation.execute()` for the raw response and `operation.api(response)` to rebuild the operation API over it.
+
+## Composable by design
+
+Create one shared Dixous client for your application, then import and specialize it where needed.
+
+```ts
+// lib/dixous.ts
+
+import { Dixous } from "dixous"
 
-// Add a typed query option.
-const query = defineExtension<{ query?: Record<string, string> }>()({
+export const dixous = Dixous.create({
+  baseUrl: "https://api.example.com/",
+  extensions: [
+    retry(),
+    query(),
+  ],
+})
+```
+
+Elsewhere:
+
+```ts
+import { dixous } from "./lib/dixous"
+
+const github = dixous.create({
+  baseUrl: "https://api.github.com/",
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+  retryAttempts: 5,
+})
+
+const users = await github
+  .request("users", {
+    query: {
+      since: "100",
+    },
+  })
+  .json(Users)
+```
+
+Derived clients inherit their parent's configuration, extensions, and types, while more specific configuration overrides shared defaults. The parent client is never changed.
+
+## Extend request behavior
+
+Extensions can also change how requests execute and contribute their own typed options.
+
+```ts
+const query = defineExtension<{
+  query?: Record<string, string>
+}>()({
   async request(context, next) {
-    const url = new URL(context.request.url);
+    const url = new URL(context.request.url)
+
     for (const [key, value] of Object.entries(context.options.query ?? {})) {
-      url.searchParams.append(key, value);
+      url.searchParams.append(key, value)
     }
-    context.request = new Request(url, context.request);
-    return next();
+
+    context.request = new Request(
+      url,
+      context.request,
+    )
+
+    return next()
   },
-});
+})
+```
+
+Install it:
 
-export const dixous = createDixous({ extensions: [xml, query, retry] });
+```ts
+const api = Dixous.create({
+  extensions: [query],
+})
 ```
-Use the extended client anywhere:
+
+And the option becomes part of the client:
 
 ```ts
-import { dixous } from "./lib/dixous";
-import { z } from "zod";
+const books = await api
+  .request("books", {
+    query: {
+      author: "Ursula K. Le Guin",
+    },
+  })
+  .json(Books)
+```
 
-const Catalog = z.object({
-  catalog: z.object({ book: z.array(z.object({ title: z.string() })) }),
-});
+Without the extension, `query` is not part of the request options.
 
-const result = await dixous.fetch("https://example.com/catalog", {
-  query: { author: "Ursula K. Le Guin" },
-}).xml(Catalog);
+The same mechanism can power retries, authentication, caching, logging, tracing, rate limiting, and more.
 
-console.log(result.catalog.book); // { title: string }[]
-```
+## Native when you need it
 
-The XML example uses [Schema XML](https://github.com/Asguho/schema-xml) and Zod (`npm install schema-xml zod`). 
+Use `.response()` whenever the HTTP response itself is part of your application logic:
 
-## Development
+```ts
+const response = await api
+  .request("users/1")
+  .response()
 
-```sh
-npm ci
-npm test
+if (response.status === 404) {
+  // Handle an expected missing user.
+}
+
+if (response.ok) {
+  const body = await response.json()
+}
 ```
 
-See [RELEASING.md](./RELEASING.md) for npm and JSR publishing.
+It returns the final native `Response` without applying a status policy.
+
+Requests are lazy and memoized per `request()` call: `.response()`, `.match()`, and the body readers share one execution, while response bodies keep their normal native consumption semantics.
+
+See [Extensions](./docs/extensions.md) for middleware ordering, retries, caching, logging, custom formats, extension state, and advanced composition.

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+import type { StandardSchemaIssue } from "./standard-schema.ts";
+export declare class UnexpectedResponseError extends Error {
+    readonly request: Request;
+    readonly response: Response;
+    constructor(request: Request, response: Response);
+}
+export declare class ResponseValidationError extends Error {
+    readonly request: Request;
+    readonly response: Response;
+    readonly issues: readonly StandardSchemaIssue[];
+    constructor(request: Request, response: Response, issues: readonly StandardSchemaIssue[]);
+}
+export declare class ConcurrentNextError extends Error {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAAlE,YAAqB,OAAO,EAAE,OAAO,EAAW,QAAQ,EAAE,QAAQ,EAGjE;CACF;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,OAAO,EAAE,OAAO;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE;IAHjD,YACW,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,SAAS,mBAAmB,EAAE,EAIhD;CACF;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,cAGC;CACF"}

package/dist/errors.js

@@ -0,0 +1,29 @@
+export class UnexpectedResponseError extends Error {
+    request;
+    response;
+    constructor(request, response) {
+        super(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
+        this.request = request;
+        this.response = response;
+        this.name = "UnexpectedResponseError";
+    }
+}
+export class ResponseValidationError extends Error {
+    request;
+    response;
+    issues;
+    constructor(request, response, issues) {
+        super("Response failed schema validation");
+        this.request = request;
+        this.response = response;
+        this.issues = issues;
+        this.name = "ResponseValidationError";
+    }
+}
+export class ConcurrentNextError extends Error {
+    constructor() {
+        super("Concurrent calls to the same next() are not allowed");
+        this.name = "ConcurrentNextError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC3B,OAAO;IAAoB,QAAQ;IAAxD,YAAqB,OAAgB,EAAW,QAAkB;QAChE,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;uBADrE,OAAO;wBAAoB,QAAQ;QAEtD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAErC,OAAO;IACP,QAAQ;IACR,MAAM;IAHjB,YACW,OAAgB,EAChB,QAAkB,EAClB,MAAsC;QAE/C,KAAK,CAAC,mCAAmC,CAAC,CAAC;uBAJlC,OAAO;wBACP,QAAQ;sBACR,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C;QACE,KAAK,CAAC,qDAAqD,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,19 +1,12 @@
-import { type DefaultResponseMethods } from "./response-methods.ts";
-import type { ContextKey, Dixous, Extension, ExtensionClientOptions, ExtensionDefinition, ExtensionMeta, ExtensionMethods, ExtensionRequestOptions, NoClientOptionOverrides, NoRequestInitOverrides, ResponseMethods } from "./types.ts";
-export { SchemaValidationError } from "./response-methods.ts";
-export type { DefaultResponseMethods, InferOutput } from "./response-methods.ts";
-export type { BaseClientOptions, ClientOptions, Context, ContextKey, Dixous, Extension, Fetcher, FetchResponse, Middleware, Next, RequestContext, RequestOptions, } from "./types.ts";
-export declare function createContextKey<T>(): ContextKey<T>;
-export declare function defineExtension<const Methods extends ResponseMethods = {}>(extension: ExtensionDefinition<{}, {}, Methods>): Extension<{}, {}, Methods>;
-export declare function defineExtension<RequestExtra extends object & NoRequestInitOverrides = {}, ClientExtra extends object & NoClientOptionOverrides = {}>(): <const Methods extends ResponseMethods = {}>(extension: ExtensionDefinition<RequestExtra, ClientExtra, Methods>) => Extension<RequestExtra, ClientExtra, Methods>;
-export declare class HttpError extends Error {
-    readonly request: Request;
-    readonly response: Response;
-    readonly status: number;
-    constructor(request: Request, response: Response);
+import type { AnyExtension, ApplyExtensionApi, ApplyExtensionOptions, CreateOptions, DefaultOperationApi, Dixous as DixousClient, Extension, ExtensionDefinition } from "./types.ts";
+export { ConcurrentNextError, ResponseValidationError, UnexpectedResponseError } from "./errors.ts";
+export type { InferOutput, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1 } from "./standard-schema.ts";
+export type { AnyExtension, CoreOptions, CreateOptions, DefaultOperationApi, Extension, ExtensionDefinition, Match, MatchedOperation, MatchResult, Next, OperationContext, RequestContext, RequestInput, RequestMiddleware, RequestOperation, RequestOptions, ReservedOperationKey, StatusHandlers, } from "./types.ts";
+export declare function defineExtension<const OperationApi extends object = {}>(definition: ExtensionDefinition<{}, OperationApi>): Extension<{}, OperationApi>;
+export declare function defineExtension<Options extends object>(): <const OperationApi extends object = {}>(definition: ExtensionDefinition<Options, OperationApi>) => Extension<Options, OperationApi>;
+export interface Dixous<Options extends object = {}, OperationApi extends object = DefaultOperationApi> extends DixousClient<Options, OperationApi> {
 }
-export declare function createDixous<const Extensions extends readonly ExtensionMeta[] = []>(options?: {
-    extensions?: Extensions;
-    fetch?: typeof globalThis.fetch;
-}): Dixous<ExtensionRequestOptions<Extensions>, ExtensionClientOptions<Extensions>, DefaultResponseMethods & ExtensionMethods<Extensions>>;
+export declare const Dixous: {
+    create<const Extensions extends readonly AnyExtension[] = []>(options?: CreateOptions<{}, Extensions>): Dixous<ApplyExtensionOptions<{}, Extensions>, ApplyExtensionApi<DefaultOperationApi, Extensions>>;
+};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAGV,UAAU,EACV,MAAM,EACN,SAAS,EACT,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EAIvB,uBAAuB,EACvB,sBAAsB,EAGtB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEjF,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,OAAO,EACP,UAAU,EACV,MAAM,EACN,SAAS,EACT,OAAO,EACP,aAAa,EACb,UAAU,EACV,IAAI,EACJ,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,wBAAgB,gBAAgB,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAEnD;AAcD,wBAAgB,eAAe,CAAC,KAAK,CAAC,OAAO,SAAS,eAAe,GAAG,EAAE,EACxE,SAAS,EAAE,mBAAmB,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,GAC9C,SAAS,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAC9B,wBAAgB,eAAe,CAC7B,YAAY,SAAS,MAAM,GAAG,sBAAsB,GAAG,EAAE,EACzD,WAAW,SAAS,MAAM,GAAG,uBAAuB,GAAG,EAAE,KACtD,CAAC,KAAK,CAAC,OAAO,SAAS,eAAe,GAAG,EAAE,EAC9C,SAAS,EAAE,mBAAmB,CAAC,YAAY,EAAE,WAAW,EAAE,OAAO,CAAC,KAC/D,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AAMnD,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAM/C;CACF;AAoFD,wBAAgB,YAAY,CAC1B,KAAK,CAAC,UAAU,SAAS,SAAS,aAAa,EAAE,GAAG,EAAE,EACtD,OAAO,CAAC,EAAE;IACV,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,GAAG,MAAM,CACR,uBAAuB,CAAC,UAAU,CAAC,EACnC,sBAAsB,CAAC,UAAU,CAAC,EAClC,sBAAsB,GAAG,gBAAgB,CAAC,UAAU,CAAC,CACtD,CA2CA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAe,aAAa,EAClF,mBAAmB,EAAE,MAAM,IAAI,YAAY,EAAE,SAAS,EACtD,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACpG,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACrH,YAAY,EACV,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,mBAAmB,EAAE,SAAS,EACxE,mBAAmB,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EACjF,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EACjF,oBAAoB,EAAE,cAAc,GACrC,MAAM,YAAY,CAAC;AAEpB,wBAAgB,eAAe,CAAC,KAAK,CAAC,YAAY,SAAS,MAAM,GAAG,EAAE,EACpE,UAAU,EAAE,mBAAmB,CAAC,EAAE,EAAE,YAAY,CAAC,GAChD,SAAS,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/B,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,KAAK,CAAC,KAAK,CAAC,YAAY,SAAS,MAAM,GAAG,EAAE,EAChG,UAAU,EAAE,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,KACnD,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAoHtC,MAAM,WAAW,MAAM,CAAC,OAAO,SAAS,MAAM,GAAG,EAAE,EAAE,YAAY,SAAS,MAAM,GAAG,mBAAmB,CACpG,SAAQ,YAAY,CAAC,OAAO,EAAE,YAAY,CAAC;CAAG;AAEhD,eAAO,MAAM,MAAM,EAAE;IACnB,MAAM,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,YAAY,EAAE,GAAG,EAAE,EAC1D,OAAO,CAAC,EAAE,aAAa,CAAC,EAAE,EAAE,UAAU,CAAC,GACtC,MAAM,CAAC,qBAAqB,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,iBAAiB,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC,CAAC;CAGrG,CAAC"}

package/dist/index.js

@@ -1,73 +1,26 @@
-import { defaultResponseMethods } from "./response-methods.js";
-export { SchemaValidationError } from "./response-methods.js";
-export function createContextKey() {
-    return Symbol();
+import { ConcurrentNextError, UnexpectedResponseError } from "./errors.js";
+import { defaultOperationApi } from "./response-methods.js";
+export { ConcurrentNextError, ResponseValidationError, UnexpectedResponseError } from "./errors.js";
+export function defineExtension(definition) {
+    return definition === undefined ? (entry) => entry : definition;
 }
-function createContext() {
-    const values = new Map();
-    return {
-        get(key) {
-            return values.get(key);
-        },
-        set(key, value) {
-            values.set(key, value);
-        },
-    };
-}
-export function defineExtension(extension) {
-    // Extension metadata is a type-only brand; composition uses the captured values.
-    return extension === undefined ? (definition) => definition : extension;
-}
-export class HttpError extends Error {
-    request;
-    response;
-    status;
-    constructor(request, response) {
-        super(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
-        this.name = "HttpError";
-        this.request = request;
-        this.response = response;
-        this.status = response.status;
+function mergeHeaders(...sources) {
+    const headers = new Headers();
+    for (const source of sources) {
+        if (source !== undefined)
+            new Headers(source).forEach((value, name) => headers.set(name, value));
     }
+    return headers;
 }
-function snapshotClient(options = {}) {
-    const client = { ...options };
-    if (client.baseUrl !== undefined)
-        client.baseUrl = client.baseUrl.toString();
-    if (client.headers !== undefined)
-        client.headers = new Headers(client.headers);
-    return Object.freeze(client);
-}
-function snapshotOptions(options = {}) {
-    const snapshot = { ...options };
-    if (snapshot.headers !== undefined)
-        snapshot.headers = new Headers(snapshot.headers);
-    return Object.freeze(snapshot);
-}
-function createTemplate(input, options, client) {
-    const headers = new Headers(client.headers);
-    if (input instanceof Request) {
-        input.headers.forEach((value, name) => headers.set(name, value));
-    }
-    if (options.headers !== undefined) {
-        new Headers(options.headers).forEach((value, name) => headers.set(name, value));
-    }
-    const source = !(input instanceof Request) && client.baseUrl !== undefined
-        ? new URL(input.toString(), client.baseUrl)
-        : input;
-    return new Request(source, { ...options, headers });
-}
-function runMiddleware(middleware, context, fetchImpl) {
+function runMiddleware(middleware, context, transport) {
     async function dispatch(index) {
         const current = middleware[index];
         if (current === undefined)
-            return fetchImpl(context.request.clone());
-        // Each middleware invocation owns its guard. Sequential retries re-enter
-        // the downstream chain with the same context and new downstream guards.
+            return transport(context.request);
         let running = false;
         return current(context, async () => {
             if (running)
-                throw new Error("Overlapping next() calls are not allowed");
+                throw new ConcurrentNextError();
             running = true;
             try {
                 return await dispatch(index + 1);
@@ -79,60 +32,76 @@ function runMiddleware(middleware, context, fetchImpl) {
     }
     return dispatch(0);
 }
-function createFetchResponse(template, options, client, middleware, fetchImpl) {
-    let execution;
-    return () => {
-        // Defer execution until after storing the promise, including when a
-        // synchronous middleware re-enters its operation's FetchResponse.
-        execution ??= Promise.resolve().then(async () => {
-            const context = {
-                request: template.clone(),
-                options,
-                client,
-                state: createContext(),
-            };
-            const response = await runMiddleware(middleware, context, fetchImpl);
-            if (!response.ok)
-                throw new HttpError(context.request, response);
-            return response;
+const reservedOperationKeys = ["response", "then"];
+function createOperation(context, execute, extensions) {
+    const build = (response) => {
+        const scoped = Object.create(context, {
+            response: { value: response, enumerable: true },
+            execute: { value: execute, enumerable: true },
+            api: { value: (matched) => build(async () => matched), enumerable: true },
+        });
+        const operation = Object.assign(Object.create(null), defaultOperationApi(scoped));
+        for (const extension of extensions) {
+            const contribution = extension.operation?.(scoped);
+            if (contribution !== undefined) {
+                for (const key of reservedOperationKeys) {
+                    if (key in contribution)
+                        throw new TypeError(`Extension operation cannot replace ${key}`);
+                }
+                Object.assign(operation, contribution);
+            }
+        }
+        return Object.defineProperties(operation, {
+            response: { value: execute, enumerable: true },
+            then: { value: undefined },
         });
-        return execution;
     };
+    return build(async () => {
+        const response = await execute();
+        if (!response.ok)
+            throw new UnexpectedResponseError(context.request, response);
+        return response;
+    });
 }
-export function createDixous(options) {
-    const fetchImpl = options?.fetch ?? globalThis.fetch;
-    const middleware = [];
-    const methods = new Map(Object.entries(defaultResponseMethods));
-    for (const entry of options?.extensions ?? []) {
-        // Contributions are erased only inside the kernel; the public signature
-        // intersects their exact types when constructing the resulting client.
-        const extension = entry;
-        if (extension.request !== undefined)
-            middleware.push(extension.request);
-        for (const [name, factory] of Object.entries(extension.methods ?? {})) {
-            if (methods.has(name))
-                throw new Error(`Duplicate response method: ${name}`);
-            methods.set(name, factory);
-        }
-    }
-    function configured(clientOptions) {
-        const client = snapshotClient(clientOptions);
-        return {
-            fetch(input, requestOptions) {
-                const snapshot = snapshotOptions(requestOptions);
-                const template = createTemplate(input, snapshot, client);
-                const pending = Object.create(null);
-                for (const [name, factory] of methods) {
-                    pending[name] = (...args) => {
-                        const fetchResponse = createFetchResponse(template, snapshot, client, middleware, fetchImpl);
-                        // Factories and method work are lazy too, and run once per call.
-                        return factory(fetchResponse)(...args);
-                    };
-                }
-                return Object.freeze(pending);
-            },
-        };
-    }
-    return Object.assign(configured, { fetch: configured().fetch });
+function createClient(parent = {}, supplied = {}) {
+    const { extensions: inherited = [], ...defaults } = parent;
+    const { extensions: appended = [], ...overrides } = supplied;
+    const configuration = Object.freeze({
+        ...defaults,
+        ...overrides,
+        ...(overrides.baseUrl !== undefined ? { baseUrl: overrides.baseUrl.toString() } : {}),
+        headers: mergeHeaders(defaults.headers, overrides.headers),
+        // Capture contributions so later mutations cannot alter an immutable client.
+        extensions: Object.freeze([...inherited, ...appended].map(entry => Object.freeze({ ...entry }))),
+    });
+    const { extensions, ...clientOptions } = configuration;
+    const middleware = extensions.flatMap(entry => entry.request ? [entry.request] : []);
+    const transport = configuration.fetch ?? globalThis.fetch;
+    return Object.freeze({
+        create(options) { return createClient(configuration, options); },
+        request(input, suppliedOptions = {}) {
+            const options = Object.freeze({
+                ...clientOptions,
+                ...suppliedOptions,
+                headers: mergeHeaders(configuration.headers, input instanceof Request ? input.headers : undefined, suppliedOptions.headers),
+            });
+            const source = !(input instanceof Request) && configuration.baseUrl !== undefined
+                ? new URL(input.toString(), configuration.baseUrl)
+                : input;
+            const request = new Request(source, options);
+            let execution;
+            const execute = () => {
+                // Store the promise before middleware can synchronously re-enter execute().
+                execution ??= Promise.resolve().then(() => runMiddleware(middleware, context, transport));
+                return execution;
+            };
+            const context = { input, request, options };
+            Object.defineProperties(context, { input: { writable: false }, options: { writable: false } });
+            return createOperation(context, execute, extensions);
+        },
+    });
 }
+export const Dixous = Object.freeze({
+    create: createClient.bind(undefined, {}),
+});
 //# sourceMappingURL=index.js.map