@kizunajs/fetch 2.0.0-beta.13 → 2.0.0-beta.14

package/dist/index.mjs

@@ -1,263 +1,956 @@
-import { buildPath, isProblemDetails, isRouteDefinition, isStreamResponse, isValidationError, streamMode } from "kizunajs";
-//#region src/sse.ts
-const parseData = (text) => {
-	try {
-		return JSON.parse(text);
-	} catch {
-		return text;
-	}
+import { ValidationErrorSchema } from "kizunajs/schemas";
+import { defineClient, isBinarySchema, isFileSchema, isStreamResponse, isVoidSchema, listedRoutes, readDef, readDeprecation, readDiscriminatedUnion, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, sanitizeIdentifier, streamContentType, streamMode, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
+import { z } from "zod";
+//#region src/runtime.ts
+/**
+* The code every generated client runs, written into the file below its route
+* table. It imports nothing, so a client installs nothing, and it always comes
+* from the release that wrote the table it reads.
+*/
+const runtimeSource = String.raw`/**
+ * What the client knows about one response: nothing for a body it reads as
+ * JSON, the media type for one that streams.
+ */
+export type GeneratedResponse =
+    | Record<string, never>
+    | {
+          stream: true;
+          contentType: string;
+      };
+
+/**
+ * One route in the table: how to reach it, and how to read each status it
+ * answers with.
+ */
+export interface GeneratedRoute {
+    method: string;
+    path: string;
+    contentType?: string;
+    responses: Record<number, GeneratedResponse>;
+}
+
+/**
+ * The route table, nested the way the client is.
+ */
+export interface GeneratedRoutes {
+    [key: string]: GeneratedRoutes | GeneratedRoute;
+}
+
+/**
+ * The request onRequest receives before it is sent. A header set on headers
+ * is sent with it.
+ */
+export interface OutgoingRequest {
+    url: string;
+    method: string;
+    headers: Headers;
+    route: GeneratedRoute;
+}
+
+/**
+ * Where the client sends its requests, and what it adds to each one.
+ */
+export interface ClientConfig {
+    baseUrl: string;
+    baseHeaders?: Record<string, string>;
+    credentials?: RequestCredentials;
+    fetch?: typeof fetch;
+    onRequest?: (request: OutgoingRequest) => void | Promise<void>;
+}
+
+/**
+ * One method on the client. Its '~route' names the method it sends and
+ * whether its response streams, so a wrapper like @kizunajs/tanstack-query
+ * reads both off the client.
+ */
+export type ClientMethod<Method extends string, Streams extends boolean, Args, Result> = ({} extends Args
+    ? (args?: Args) => Promise<Result>
+    : (args: Args) => Promise<Result>) & {
+    readonly '~route': GeneratedRoute & {
+        readonly method: Method;
+        readonly streams: Streams;
+    };
+};
+
+interface CallArgs {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string | undefined>;
+    fetchOptions?: RequestInit;
+}
+
+/**
+ * Dates go on the wire as ISO 8601, everything else as String gives it.
+ */
+const serializeValue = (value: unknown): string => (value instanceof Date ? value.toISOString() : String(value));
+
+const buildPath = (path: string, params: Record<string, unknown> = {}): string =>
+    path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_, name: string) => {
+        const value = params[name];
+        if (value === undefined) throw new Error('Missing path parameter: ' + name);
+        return encodeURIComponent(serializeValue(value));
+    });
+
+/**
+ * An array repeats its key, and an undefined or null field is left out.
+ */
+const buildSearchParams = (fields: Record<string, unknown>): URLSearchParams => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null) continue;
+        for (const item of Array.isArray(value) ? value : [value]) params.append(key, serializeValue(item));
+    }
+    return params;
+};
+
+const buildFormData = (fields: Record<string, unknown>): FormData => {
+    const formData = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            if (item instanceof Blob) formData.append(key, item);
+            else if (item !== undefined && item !== null) formData.append(key, typeof item === 'string' ? item : JSON.stringify(item));
+        }
+    }
+    return formData;
 };
-const findLineEnd = (buffer, final) => {
-	for (let index = 0; index < buffer.length; index += 1) {
-		const character = buffer[index];
-		if (character === "\n") return {
-			index,
-			length: 1
-		};
-		if (character === "\r") {
-			if (index + 1 < buffer.length) return {
-				index,
-				length: buffer[index + 1] === "\n" ? 2 : 1
-			};
-			if (final) return {
-				index,
-				length: 1
-			};
-			return;
+
+/**
+ * A multipart body leaves Content-Type to fetch, which adds the boundary.
+ */
+const encodeBody = (route: GeneratedRoute, body: unknown, headers: Headers): BodyInit => {
+    switch (route.contentType) {
+        case 'multipart/form-data':
+            return body instanceof FormData ? body : buildFormData(body as Record<string, unknown>);
+        case 'application/x-www-form-urlencoded':
+            if (!headers.has('Content-Type')) headers.set('Content-Type', 'application/x-www-form-urlencoded');
+            return buildSearchParams(body as Record<string, unknown>);
+        default:
+            if (!headers.has('Content-Type')) headers.set('Content-Type', 'application/json');
+            return JSON.stringify(body);
+    }
+};
+
+const parseJson = (text: string): unknown => {
+    try {
+        return JSON.parse(text) as unknown;
+    } catch {
+        return text;
+    }
+};
+
+interface ServerSentEvent {
+    event?: string;
+    data: unknown;
+    id?: string;
+    retry?: number;
+}
+
+/**
+ * A lone carriage return at the end may be half of CRLF, so it waits for more
+ * unless the stream is over.
+ */
+const findLineEnd = (buffer: string, final: boolean): { index: number; length: number } | undefined => {
+    for (let index = 0; index < buffer.length; index += 1) {
+        const character = buffer[index];
+        if (character === '\n') return { index, length: 1 };
+        if (character === '\r') {
+            if (index + 1 < buffer.length) return { index, length: buffer[index + 1] === '\n' ? 2 : 1 };
+            if (final) return { index, length: 1 };
+            return undefined;
+        }
+    }
+    return undefined;
+};
+
+/**
+ * Reads text/event-stream as the WHATWG HTML specification parses it.
+ */
+async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let first = true;
+    let dataLines: string[] = [];
+    let eventType = '';
+    let lastEventId = '';
+    let retry: number | undefined;
+
+    const dispatch = (): ServerSentEvent | undefined => {
+        if (dataLines.length === 0) {
+            eventType = '';
+            return undefined;
+        }
+        const message: ServerSentEvent = {
+            data: parseJson(dataLines.join('\n')),
+        };
+        if (eventType !== '') message.event = eventType;
+        if (lastEventId !== '') message.id = lastEventId;
+        if (retry !== undefined) message.retry = retry;
+        dataLines = [];
+        eventType = '';
+        retry = undefined;
+        return message;
+    };
+
+    const processLine = (line: string): ServerSentEvent | undefined => {
+        if (line === '') return dispatch();
+        if (line.startsWith(':')) return undefined;
+        const separator = line.indexOf(':');
+        const field = separator === -1 ? line : line.slice(0, separator);
+        let value = separator === -1 ? '' : line.slice(separator + 1);
+        if (value.startsWith(' ')) value = value.slice(1);
+        switch (field) {
+            case 'event':
+                eventType = value;
+                break;
+            case 'data':
+                dataLines.push(value);
+                break;
+            case 'id':
+                if (!value.includes('\0')) lastEventId = value;
+                break;
+            case 'retry':
+                if (/^\d+$/.test(value)) retry = Number(value);
+                break;
+        }
+        return undefined;
+    };
+
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            let chunk = done ? decoder.decode() : decoder.decode(value, { stream: true });
+            if (first && chunk.length > 0) {
+                if (chunk.charCodeAt(0) === 0xfeff) chunk = chunk.slice(1);
+                first = false;
+            }
+            buffer += chunk;
+            for (;;) {
+                const lineEnd = findLineEnd(buffer, done);
+                if (lineEnd === undefined) break;
+                const line = buffer.slice(0, lineEnd.index);
+                buffer = buffer.slice(lineEnd.index + lineEnd.length);
+                const message = processLine(line);
+                if (message !== undefined) yield message;
+            }
+            if (done) return;
+        }
+    } finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
+
+async function* readText(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                const tail = decoder.decode();
+                if (tail.length > 0) yield tail;
+                return;
+            }
+            const text = decoder.decode(value, { stream: true });
+            if (text.length > 0) yield text;
+        }
+    } finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
+
+async function* readBytes(body: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) return;
+            yield value;
+        }
+    } finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
+
+const readStream = (body: ReadableStream<Uint8Array>, contentType: string): AsyncIterable<unknown> => {
+    const essence = (contentType.split(';')[0] ?? '').trim().toLowerCase();
+    if (essence === 'text/event-stream') return readEvents(body);
+    if (essence.startsWith('text/')) return readText(body);
+    return readBytes(body);
+};
+
+const buildMethod = (route: GeneratedRoute, config: ClientConfig) => {
+    const call = async (args: CallArgs = {}) => {
+        const query = args.query === undefined ? '' : buildSearchParams(args.query).toString();
+        const url = config.baseUrl + buildPath(route.path, args.params) + (query.length > 0 ? '?' + query : '');
+        const headers = new Headers(config.baseHeaders);
+        for (const [name, value] of Object.entries(args.headers ?? {})) {
+            if (value !== undefined) headers.set(name, value);
+        }
+        const init: RequestInit = {
+            method: route.method,
+            headers,
+        };
+        if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
+        if (config.credentials !== undefined) init.credentials = config.credentials;
+        await config.onRequest?.({
+            url,
+            method: route.method,
+            headers,
+            route,
+        });
+
+        const response = await (config.fetch ?? fetch)(url, {
+            ...init,
+            ...args.fetchOptions,
+        });
+        const responseHeaders: Record<string, string> = {};
+        response.headers.forEach((value, name) => {
+            responseHeaders[name] = value;
+        });
+        const declared = route.responses[response.status];
+        if (declared !== undefined && 'stream' in declared && response.body !== null) {
+            return {
+                status: response.status,
+                body: readStream(response.body, declared.contentType),
+                headers: responseHeaders,
+            };
+        }
+        const text = await response.text();
+        return {
+            status: response.status,
+            body: text.length > 0 ? parseJson(text) : undefined,
+            headers: responseHeaders,
+        };
+    };
+    const streams = Object.values(route.responses).some((response) => 'stream' in response);
+    return Object.defineProperty(call, '~route', {
+        value: {
+            ...route,
+            streams,
+        },
+    });
+};
+
+const isRoute = (node: GeneratedRoutes | GeneratedRoute): node is GeneratedRoute => typeof node['method'] === 'string';
+
+const buildTree = (routes: GeneratedRoutes, config: ClientConfig): Record<string, unknown> => {
+    const tree: Record<string, unknown> = {};
+    for (const [key, node] of Object.entries(routes)) {
+        tree[key] = isRoute(node) ? buildMethod(node, config) : buildTree(node, config);
+    }
+    return tree;
+};
+
+/**
+ * Sends the request context headers with every request. An explicit
+ * baseHeaders entry wins.
+ */
+const buildClient = (routes: GeneratedRoutes, config: ClientConfig & { requestContext?: object }): Record<string, unknown> => {
+    const contextHeaders: Record<string, string> = {};
+    for (const [name, value] of Object.entries(config.requestContext ?? {})) {
+        if (value !== undefined) contextHeaders[name] = String(value);
+    }
+    return buildTree(routes, {
+        ...config,
+        baseHeaders: {
+            ...contextHeaders,
+            ...config.baseHeaders,
+        },
+    });
+};
+`;
+//#endregion
+//#region src/zod-to-typescript.ts
+/**
+* Collects the named types a walk produces, so a model shared by many routes is
+* declared once.
+*/
+var TypeCollector = class {
+	named = /* @__PURE__ */ new Map();
+	claimed = /* @__PURE__ */ new Set();
+	brands = /* @__PURE__ */ new Map();
+	/**
+	* Which side of a pipe a schema is read from: the input a request sends, or
+	* the output a response carries.
+	*/
+	direction = "output";
+	/**
+	* Reads the schemas `read` walks from the side a request sends.
+	*/
+	readingInput(read) {
+		const previous = this.direction;
+		this.direction = "input";
+		try {
+			return read();
+		} finally {
+			this.direction = previous;
 		}
 	}
+	readsInput() {
+		return this.direction === "input";
+	}
+	/**
+	* Claims a name before its body is walked, so a model that refers to itself
+	* resolves to its own name instead of recursing. Answers whether the caller
+	* is the one that has to emit it.
+	*/
+	claim(name) {
+		if (this.claimed.has(name)) return false;
+		this.claimed.add(name);
+		return true;
+	}
+	add(type) {
+		this.named.set(type.name, type);
+	}
+	/**
+	* Declares a brand as a named type, `UserId = string & KizunaBrand<"UserId">`,
+	* and answers the name.
+	*/
+	addBrand(brand, base, example) {
+		const name = sanitizeIdentifier(brand);
+		const existing = this.brands.get(name);
+		if (existing !== void 0 && (existing.brand !== brand || existing.base !== base)) throw new Error(`@kizunajs/fetch: brand ${quote(brand)} wraps both ${existing.base} and ${base}. Give each its own name.`);
+		if (existing === void 0) this.brands.set(name, {
+			brand,
+			base,
+			example
+		});
+		return name;
+	}
+	usesBrand() {
+		return this.brands.size > 0;
+	}
+	/**
+	* Each brand's name, the type it wraps, and a value for its `@example`, for
+	* the constructors the file exports.
+	*/
+	allBrands() {
+		return [...this.brands].map(([name, { base, example }]) => ({
+			name,
+			base,
+			example
+		}));
+	}
+	all() {
+		for (const name of this.brands.keys()) if (this.named.has(name)) throw new Error(`@kizunajs/fetch: brand ${quote(name)} has the same name as a model. Give each its own name.`);
+		const brands = [...this.brands].map(([name, { brand, base }]) => ({
+			name,
+			description: `A branded \`${base}\`. Responses hand one back, and \`to${name}\` makes one from a plain value.`,
+			body: `${base} & KizunaBrand<${quote(brand)}>`
+		}));
+		return [...this.named.values(), ...brands].sort((left, right) => left.name.localeCompare(right.name));
+	}
 };
+const quote = (value) => JSON.stringify(value);
 /**
-* Parses `text/event-stream` per the WHATWG HTML specification.
+* What a brand wraps: the scalars, as the JSON carries them.
 */
-async function* parseServerSentEvents(body) {
-	const reader = body.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	let first = true;
-	let dataLines = [];
-	let eventType = "";
-	let lastEventId = "";
-	let retry;
-	const dispatch = () => {
-		if (dataLines.length === 0) {
-			eventType = "";
-			return;
-		}
-		const message = { data: parseData(dataLines.join("\n")) };
-		if (eventType !== "") message.event = eventType;
-		if (lastEventId !== "") message.id = lastEventId;
-		if (retry !== void 0) message.retry = retry;
-		dataLines = [];
-		eventType = "";
-		retry = void 0;
-		return message;
-	};
-	const processLine = (line) => {
-		if (line === "") return dispatch();
-		if (line.startsWith(":")) return void 0;
-		const separator = line.indexOf(":");
-		const field = separator === -1 ? line : line.slice(0, separator);
-		let value = separator === -1 ? "" : line.slice(separator + 1);
-		if (value.startsWith(" ")) value = value.slice(1);
-		switch (field) {
-			case "event":
-				eventType = value;
-				break;
-			case "data":
-				dataLines.push(value);
-				break;
-			case "id":
-				if (!value.includes("\0")) lastEventId = value;
-				break;
-			case "retry":
-				if (/^\d+$/.test(value)) retry = Number(value);
-				break;
-		}
-	};
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			let chunk = done ? decoder.decode() : decoder.decode(value, { stream: true });
-			if (first && chunk.length > 0) {
-				if (chunk.charCodeAt(0) === 65279) chunk = chunk.slice(1);
-				first = false;
-			}
-			buffer += chunk;
-			for (;;) {
-				const lineEnd = findLineEnd(buffer, done);
-				if (lineEnd === void 0) break;
-				const line = buffer.slice(0, lineEnd.index);
-				buffer = buffer.slice(lineEnd.index + lineEnd.length);
-				const message = processLine(line);
-				if (message !== void 0) yield message;
-			}
-			if (done) return;
-		}
-	} finally {
-		reader.cancel().catch(() => void 0);
+const BRANDABLE_BASES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/**
+* A literal as the type the JSON carries, so `z.literal(true)` is `true`.
+*/
+const literalType = (value) => {
+	if (typeof value === "string") return quote(value);
+	if (typeof value === "bigint") return `${value}n`;
+	if (value === void 0) return "undefined";
+	return String(value);
+};
+const indent$1 = (text, depth = 1) => text.split("\n").map((line) => line.length > 0 ? "    ".repeat(depth) + line : line).join("\n");
+/**
+* A property name, quoted only when it is not a plain identifier.
+*/
+const propertyKey = (key) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : quote(key);
+/**
+* A doc comment over the lines it is given, or nothing when there are none.
+* Always multi-line, the way the rest of this repository writes them.
+*/
+const docComment = (lines) => {
+	const body = lines.flatMap((line) => line.split("\n"));
+	if (body.length === 0) return "";
+	return `/**\n${body.map((line) => ` * ${line}`.trimEnd()).join("\n")}\n */\n`;
+};
+/**
+* Renders a declared example as the TypeScript literal a caller would write.
+*/
+const exampleLiteral = (value) => {
+	if (typeof value === "string") return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+	if (value === void 0) return "undefined";
+	return JSON.stringify(value) ?? "undefined";
+};
+const STRING_SAMPLES = {
+	email: "ada@example.com",
+	url: "https://example.com",
+	uuid: "3f1c2d9e-5b6a-4c7d-8e9f-0a1b2c3d4e5f",
+	datetime: "2026-01-01T00:00:00Z",
+	date: "2026-01-01",
+	time: "00:00:00"
+};
+const stringSample = (schema, key) => {
+	const def = readDef(schema);
+	const formats = [def.format, ...(def.checks ?? []).map((check) => check.format ?? check.def?.format)];
+	for (const format of formats) if (format !== void 0 && format in STRING_SAMPLES) return exampleLiteral(STRING_SAMPLES[format]);
+	if (key !== void 0 && /id$/i.test(key)) return exampleLiteral("1");
+	return exampleLiteral("string");
+};
+/**
+* A value a caller could pass for a schema, used in the `@example` on each
+* client method. A schema that declares an example is taken at its word;
+* anything else gets a value of the right shape.
+*/
+const sampleValue = (schema, depth = 0, key) => {
+	const [declared] = readMetaExamples(schema);
+	if (declared !== void 0) return exampleLiteral(declared);
+	if (isFileSchema(schema)) return "new File([], 'upload.txt')";
+	if (isBinarySchema(schema)) return "new Uint8Array()";
+	const def = readDef(schema);
+	if (def.type === "default" && def.defaultValue !== void 0) return exampleLiteral(def.defaultValue);
+	if (def.type === "pipe") {
+		const side = def.in ?? def.out;
+		return side ? sampleValue(side, depth, key) : "undefined";
 	}
-}
-async function* readTextChunks(body) {
-	const reader = body.getReader();
-	const decoder = new TextDecoder();
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) {
-				const tail = decoder.decode();
-				if (tail.length > 0) yield tail;
-				return;
-			}
-			const text = decoder.decode(value, { stream: true });
-			if (text.length > 0) yield text;
+	if (def.innerType && def.type !== "object") return sampleValue(def.innerType, depth, key);
+	switch (def.type) {
+		case "number":
+		case "int": return "1";
+		case "bigint": return exampleLiteral("1");
+		case "boolean": return "true";
+		case "date": return exampleLiteral("2026-01-01");
+		case "null": return "null";
+		case "literal": return def.values?.length ? exampleLiteral(def.values[0]) : "undefined";
+		case "enum": {
+			const [first] = Object.values(def.entries ?? {});
+			return first === void 0 ? "undefined" : exampleLiteral(first);
 		}
-	} finally {
-		reader.cancel().catch(() => void 0);
-	}
-}
-async function* readByteChunks(body) {
-	const reader = body.getReader();
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) return;
-			yield value;
+		case "array":
+			if (!def.element || depth >= SAMPLE_DEPTH) return "[]";
+			return `[\n${indent$1(`${sampleValue(def.element, depth + 1, key)},`)}\n]`;
+		case "tuple": return `[${(def.items ?? []).map((item) => sampleValue(item, depth + 1, key)).join(", ")}]`;
+		case "object": return sampleObject(schema, depth);
+		case "record": return "{}";
+		case "union": {
+			const options = readDiscriminatedUnion(schema)?.options ?? def.options ?? [];
+			return options[0] ? sampleValue(options[0], depth, key) : "undefined";
 		}
-	} finally {
-		reader.cancel().catch(() => void 0);
+		case "string": return stringSample(schema, key);
+		default: return "undefined";
 	}
-}
-//#endregion
-//#region src/client.ts
-const buildFormData = (body) => {
-	const formData = new FormData();
-	for (const [key, entry] of Object.entries(body)) {
-		const values = Array.isArray(entry) ? entry : [entry];
-		for (const value of values) if (value instanceof File || value instanceof Blob) formData.append(key, value);
-		else if (value !== void 0 && value !== null) formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+};
+const SAMPLE_DEPTH = 2;
+/**
+* The required fields of an object schema, written as the literal a caller
+* would pass. Optional fields are left out, since an example shows the least
+* the route needs.
+*/
+const sampleObject = (schema, depth = 0) => {
+	const shape = readObjectShape(schema);
+	if (!shape) return "{}";
+	const required = Object.entries(shape).filter(([, field]) => !unwrapOptionalWrappers(field).optional);
+	if (required.length === 0 || depth >= SAMPLE_DEPTH) return "{}";
+	return `{\n${indent$1(required.map(([key, field]) => `${propertyKey(key)}: ${sampleValue(unwrapOptionalWrappers(field).inner, depth + 1, key)},`).join("\n"))}\n}`;
+};
+/**
+* What an editor shows above a field: its description, whether it is on its way
+* out, and the values the schema declares as examples.
+*/
+const fieldDoc = (field) => {
+	const lines = [];
+	const description = readMetaDescription(field);
+	if (description !== void 0) lines.push(description);
+	const deprecation = readDeprecation(field);
+	if (deprecation !== void 0) {
+		if (lines.length > 0) lines.push("");
+		lines.push(`@deprecated ${deprecation.message ?? ""}`.trimEnd());
 	}
-	return formData;
+	for (const example of readMetaExamples(field)) {
+		if (lines.length > 0) lines.push("");
+		lines.push("@example", exampleLiteral(example));
+	}
+	return lines;
+};
+const objectBody = (schema, collector, hint) => {
+	const shape = readObjectShape(schema);
+	if (!shape) return "Record<string, unknown>";
+	const entries = Object.entries(shape);
+	if (entries.length === 0) return "Record<string, never>";
+	return `{\n${indent$1(entries.map(([key, field]) => {
+		const doc = docComment(fieldDoc(field));
+		const mark = unwrapOptionalWrappers(field).optional ? "?" : "";
+		return `${doc}${propertyKey(key)}${mark}: ${typeOf(field, collector, `${hint}${toPascalCase(key)}`)};`;
+	}).join("\n"))}\n}`;
 };
 /**
-* Serializes a query or path value for the URL. Dates use ISO 8601; everything
-* else uses `String`.
+* The TypeScript type a schema describes. Named models are collected and
+* referenced; anonymous shapes are inlined. A brand is named like a model.
 */
-const serializeValue = (value) => value instanceof Date ? value.toISOString() : String(value);
-const buildQueryString = (query) => {
-	const params = new URLSearchParams();
-	for (const [key, value] of Object.entries(query)) {
-		if (value === void 0 || value === null) continue;
-		if (Array.isArray(value)) for (const item of value) params.append(key, serializeValue(item));
-		else params.append(key, serializeValue(value));
+const typeOf = (schema, collector, hint) => {
+	const type = unbrandedTypeOf(schema, collector, hint);
+	const brand = readMetaBrand(schema);
+	if (brand === void 0 || !BRANDABLE_BASES.has(type)) return type;
+	return collector.addBrand(brand, type, sampleValue(schema, 0, brand));
+};
+const unbrandedTypeOf = (schema, collector, hint) => {
+	if (isFileSchema(schema)) return "File | Blob";
+	if (isBinarySchema(schema)) return "Uint8Array";
+	const def = readDef(schema);
+	if (def.type === "nullable" && def.innerType) return `${typeOf(def.innerType, collector, hint)} | null`;
+	if (def.type === "nullish" && def.innerType) return `${typeOf(def.innerType, collector, hint)} | null`;
+	if (def.innerType && def.type !== "object") return typeOf(def.innerType, collector, hint);
+	if (def.type === "pipe") {
+		const side = collector.readsInput() ? def.in : def.out ?? def.in;
+		return side ? typeOf(side, collector, hint) : "unknown";
+	}
+	const modelName = readMetaId(schema);
+	if (modelName !== void 0) {
+		if (collector.claim(modelName)) collector.add({
+			name: modelName,
+			description: readMetaDescription(schema),
+			body: structuralType(schema, collector, modelName)
+		});
+		return modelName;
 	}
-	const result = params.toString();
-	return result.length > 0 ? `?${result}` : "";
+	return structuralType(schema, collector, hint);
 };
-const CLIENT_ROUTE = Symbol.for("kizuna.client-route");
 /**
-* The route a client method answers, or `undefined` for anything that is not
-* one.
+* The type a schema describes by its shape, its name already spent by the caller.
 */
-const routeOf = (value) => typeof value === "function" ? value[CLIENT_ROUTE] : void 0;
-const buildRouteFn = (route, config) => {
-	const call = async (args = {}) => {
-		const url = config.baseUrl + buildPath(route.path, args.params) + (args.query ? buildQueryString(args.query) : "");
-		const headers = {
-			...config.baseHeaders ?? {},
-			...args.headers ?? {}
-		};
-		let body;
-		if (args.body !== void 0) {
-			const hasContentTypeHeader = "Content-Type" in headers || "content-type" in headers;
-			switch (route.contentType) {
-				case "multipart/form-data":
-					body = args.body instanceof FormData ? args.body : buildFormData(args.body);
-					break;
-				case "application/x-www-form-urlencoded":
-					if (!hasContentTypeHeader) headers["Content-Type"] = "application/x-www-form-urlencoded";
-					body = new URLSearchParams(args.body);
-					break;
-				default:
-					if (!hasContentTypeHeader) headers["Content-Type"] = "application/json";
-					body = JSON.stringify(args.body);
-			}
+const structuralType = (schema, collector, hint) => {
+	const def = readDef(schema);
+	switch (def.type) {
+		case "string": return "string";
+		case "number":
+		case "int": return "number";
+		case "bigint": return "string";
+		case "boolean": return "boolean";
+		case "date": return "string";
+		case "null": return "null";
+		case "any":
+		case "unknown": return "unknown";
+		case "never": return "never";
+		case "void":
+		case "undefined": return "undefined";
+		case "literal": {
+			const values = def.values ?? [];
+			return values.length > 0 ? values.map(literalType).join(" | ") : "never";
 		}
-		const requestHeaders = new Headers(headers);
-		if (config.onRequest) await config.onRequest({
-			url,
-			method: route.method,
-			headers: requestHeaders,
-			route
-		});
-		const res = await (config.fetch ?? fetch)(url, {
-			method: route.method,
-			headers: requestHeaders,
-			body,
-			credentials: config.credentials,
-			...args.fetchOptions
-		});
-		const responseHeaders = {};
-		res.headers.forEach((value, key) => {
-			responseHeaders[key] = value;
-		});
-		const responseSpec = route.responses[res.status];
-		if (isStreamResponse(responseSpec) && res.body !== null) return {
-			status: res.status,
-			body: readStream(res.body, responseSpec),
-			headers: responseHeaders
-		};
-		const text = await res.text();
-		let parsed;
-		try {
-			parsed = text.length > 0 ? JSON.parse(text) : void 0;
-		} catch {
-			parsed = text;
+		case "enum": {
+			const values = Object.values(def.entries ?? {});
+			return values.length > 0 ? values.map(literalType).join(" | ") : "never";
 		}
-		return {
-			status: res.status,
-			body: parsed,
-			headers: responseHeaders
-		};
-	};
-	call[CLIENT_ROUTE] = route;
-	return call;
-};
-const readStream = (body, definition) => {
-	switch (streamMode(definition)) {
-		case "events": return parseServerSentEvents(body);
-		case "text": return readTextChunks(body);
-		case "binary": return readByteChunks(body);
+		case "array": return def.element ? `Array<${typeOf(def.element, collector, `${hint}Item`)}>` : "unknown[]";
+		case "tuple": {
+			const items = (def.items ?? []).map((item, index) => typeOf(item, collector, `${hint}${index}`));
+			const rest = def.rest ? [`...Array<${typeOf(def.rest, collector, `${hint}Rest`)}>`] : [];
+			return `[${[...items, ...rest].join(", ")}]`;
+		}
+		case "object": return objectBody(schema, collector, hint);
+		case "record": return `Record<string, ${def.valueType ? typeOf(def.valueType, collector, `${hint}Value`) : "unknown"}>`;
+		case "union": {
+			const options = readDiscriminatedUnion(schema)?.options ?? def.options ?? [];
+			if (options.length === 0) return "unknown";
+			return options.map((option, index) => typeOf(option, collector, `${hint}${index}`)).join(" | ");
+		}
+		default: return "unknown";
+	}
+};
+//#endregion
+//#region src/generator.ts
+const indent = (text, depth = 1) => text.split("\n").map((line) => line.length > 0 ? "    ".repeat(depth) + line : line).join("\n");
+const pathParamNames = (path) => [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1] ?? "");
+/**
+* One server-sent event, typed from what the response declares. A record of
+* event name to schema becomes a union discriminated on `event`; a single
+* schema is the only shape a message takes.
+*/
+const eventUnion = (stream, collector, namespace) => {
+	const frame = "id?: string; retry?: number";
+	if (stream && typeof stream === "object" && !("_zod" in stream) && !("_def" in stream)) {
+		const arms = Object.entries(stream).map(([event, schema]) => `{ event: '${event}'; data: ${typeOf(schema, collector, `${namespace}${toPascalCase(event)}`)}; ${frame} }`);
+		return arms.length > 0 ? arms.join(" | ") : `{ event?: string; data: string; ${frame} }`;
 	}
+	return `{ event?: string; data: ${typeOf(stream, collector, `${namespace}Message`)}; ${frame} }`;
+};
+const streamBody = (mode, stream, collector, namespace) => {
+	if (mode === "binary") return "AsyncIterable<Uint8Array>";
+	if (mode === "text") return "AsyncIterable<string>";
+	return `AsyncIterable<${eventUnion(stream, collector, namespace)}>`;
 };
-const buildClientTree = (router, config) => {
-	const result = {};
-	for (const key of Object.keys(router)) {
-		const node = router[key];
-		if (isRouteDefinition(node)) result[key] = buildRouteFn(node, config);
-		else if (node && typeof node === "object") result[key] = buildClientTree(node, config);
+/**
+* The call a route's `@example` shows: the arguments it cannot be called
+* without, filled with values of the shape each schema declares.
+*/
+const exampleCall = (routeKey, route) => {
+	const entries = [];
+	const params = pathParamNames(route.path);
+	if (params.length > 0) {
+		const shape = route.pathParams ? readObjectShape(route.pathParams) : void 0;
+		const fields = params.map((name) => {
+			const declared = shape?.[name];
+			return `${name}: ${declared ? sampleValue(declared, 0, name) : "'1'"},`;
+		});
+		entries.push(`params: {\n${indent(fields.join("\n"))}\n},`);
 	}
-	return result;
+	if (route.query && requiresArgument(route.query)) entries.push(`query: ${sampleObject(route.query)},`);
+	if (route.body && !isVoidSchema(route.body) && requiresArgument(route.body)) entries.push(`body: ${sampleValue(route.body)},`);
+	if (route.headers && requiresArgument(route.headers)) entries.push(`headers: ${sampleObject(route.headers)},`);
+	return `const result = await client.${routeKey}(${entries.length > 0 ? `{\n${indent(entries.join("\n"))}\n}` : ""});`;
+};
+/**
+* Whether a schema has anything a caller has to pass, so a route whose query is
+* every-field-optional keeps its example to the call itself.
+*/
+const requiresArgument = (schema) => {
+	const shape = readObjectShape(schema);
+	if (!shape) return true;
+	return Object.values(shape).some((field) => !unwrapOptionalWrappers(field).optional);
 };
 /**
-* Folds the request context headers into `baseHeaders`, so every request
-* carries them. An explicit `baseHeaders` entry wins.
+* What an editor shows above a client method: what the route is for, whether it
+* is on its way out, and how it is called.
 */
-const withContextHeaders = (config) => {
-	const contextHeaders = config.requestContext;
-	if (!contextHeaders) return config;
+const routeDoc = (routeKey, route) => {
+	const lines = [];
+	if (route.summary) lines.push(route.summary);
+	if (route.description) {
+		if (lines.length > 0) lines.push("");
+		lines.push(route.description);
+	}
+	if (route.deprecated !== void 0 && route.deprecated !== false) {
+		const message = typeof route.deprecated === "string" ? route.deprecated : typeof route.deprecated === "object" ? route.deprecated.message : void 0;
+		if (lines.length > 0) lines.push("");
+		lines.push(`@deprecated ${message ?? ""}`.trimEnd());
+	}
+	if (lines.length > 0) lines.push("");
+	lines.push("@example", exampleCall(routeKey, route));
+	return docComment(lines);
+};
+const emitRoute = (routeKey, key, route, collector, namespaceName) => {
+	const namespace = routeKey.split(".").map(toPascalCase).join("");
+	const members = [];
+	const args = [];
+	const params = pathParamNames(route.path);
+	const { pathParams, query, body, headers } = route;
+	if (params.length > 0) {
+		const paramsType = pathParams ? collector.readingInput(() => typeOf(pathParams, collector, `${namespace}Params`)) : `{\n${indent(params.map((name) => `${name}: string;`).join("\n"))}\n}`;
+		members.push(`export type Params = ${paramsType};`);
+		args.push(`params: ${namespaceName}.${namespace}.Params`);
+	}
+	if (query) {
+		members.push(`export type Query = ${collector.readingInput(() => typeOf(query, collector, `${namespace}Query`))};`);
+		args.push(`query${requiresArgument(query) ? "" : "?"}: ${namespaceName}.${namespace}.Query`);
+	}
+	if (body && !isVoidSchema(body)) {
+		members.push(`export type Body = ${collector.readingInput(() => typeOf(body, collector, `${namespace}Body`))};`);
+		args.push(`body: ${namespaceName}.${namespace}.Body`);
+	}
+	if (headers) {
+		members.push(`export type Headers = ${collector.readingInput(() => typeOf(headers, collector, `${namespace}Headers`))};`);
+		args.push(`headers${requiresArgument(headers) ? "" : "?"}: ${namespaceName}.${namespace}.Headers`);
+	} else args.push("headers?: Record<string, string>");
+	args.push("fetchOptions?: RequestInit");
+	const validates = route.body !== void 0 || route.query !== void 0;
+	const declaredBadRequest = Object.keys(route.responses).includes("400");
+	const validationBody = validates ? typeOf(ValidationErrorSchema, collector, "ValidationError") : void 0;
+	const results = Object.entries(route.responses).map(([status, response]) => {
+		const headers = resolveResponseHeaders(response);
+		const headerType = headers ? typeOf(headers, collector, `${namespace}${status}Headers`) : "Record<string, string>";
+		if (isStreamResponse(response)) return `{ status: ${status}; body: ${streamBody(streamMode(response), response.stream, collector, `${namespace}${status}`)}; headers: ${headerType} }`;
+		const schema = resolveResponseBody(response);
+		const body = schema ? typeOf(schema, collector, `${namespace}${status}`) : "undefined";
+		return `{ status: ${status}; body: ${status === "400" && validationBody ? `${body} | ${validationBody}` : body}; headers: ${headerType} }`;
+	});
+	if (validationBody && !declaredBadRequest) results.push(`{ status: 400; body: ${validationBody}; headers: Record<string, string> }`);
+	members.push(`export type Result =\n${indent(results.map((result) => `| ${result}`).join("\n"))};`);
+	const argsType = `{\n${indent(args.map((arg) => `${arg};`).join("\n"))}\n}`;
+	const tableEntries = [`method: '${route.method}'`, `path: '${route.path}'`];
+	if (route.contentType) tableEntries.push(`contentType: '${route.contentType}'`);
+	const responses = Object.entries(route.responses).map(([status, response]) => isStreamResponse(response) ? `${status}: { stream: true, contentType: '${streamContentType(response)}' }` : `${status}: {}`);
+	if (validationBody && !declaredBadRequest) responses.push("400: {}");
+	tableEntries.push(`responses: {\n${indent(responses.map((entry) => `${entry},`).join("\n"))}\n}`);
+	const streams = Object.values(route.responses).some((response) => isStreamResponse(response));
 	return {
-		...config,
-		baseHeaders: {
-			...Object.fromEntries(Object.entries(contextHeaders).filter(([, value]) => value !== void 0)),
-			...config.baseHeaders ?? {}
+		namespace,
+		signature: `${routeDoc(routeKey, route)}${key}: ClientMethod<'${route.method}', ${streams}, ${argsType}, ${namespaceName}.${namespace}.Result>;`,
+		declaration: `export namespace ${namespace} {\n${indent(members.join("\n\n"))}\n}`,
+		table: `${key}: {\n${indent(tableEntries.map((entry) => `${entry},`).join("\n"))}\n},`
+	};
+};
+const isRoute = (value) => !!value && typeof value === "object" && typeof value.method === "string";
+const emitTree = (routes, prefix, collector, namespaceName) => {
+	const signatures = [];
+	const tables = [];
+	const declarations = [];
+	for (const key of Object.keys(routes)) {
+		const node = routes[key];
+		const routeKey = prefix ? `${prefix}.${key}` : key;
+		if (isRoute(node)) {
+			const emitted = emitRoute(routeKey, key, node, collector, namespaceName);
+			signatures.push(emitted.signature);
+			tables.push(emitted.table);
+			declarations.push(emitted.declaration);
+			continue;
+		}
+		if (node && typeof node === "object") {
+			const group = emitTree(node, routeKey, collector, namespaceName);
+			signatures.push(`${key}: {\n${indent(group.signatures)}\n};`);
+			tables.push(`${key}: {\n${indent(group.table)}\n},`);
+			declarations.push(...group.declarations);
 		}
+	}
+	return {
+		signatures: signatures.join("\n"),
+		table: tables.join("\n"),
+		declarations
 	};
 };
 /**
-* Builds the client tree a generated client exposes. The generated file owns the
-* types; this owns the requests.
+* Renders a TypeScript client from an api: its named types, the route table
+* the runtime reads, and a `createClient` typed against both.
+*/
+/**
+* The headers a request context declares, as one interface the caller fills
+* once. Absent when the API declares no request context that reads headers.
+*/
+const emitRequestContext = (contract, collector) => {
+	const declarations = Object.values(contract.requestContext ?? {});
+	const fields = [];
+	let required = false;
+	for (const declaration of declarations) {
+		const headers = declaration.headers;
+		if (!headers) continue;
+		required ||= requiresArgument(headers);
+		const inner = collector.readingInput(() => typeOf(headers, collector, "RequestContext")).trim().replace(/^\{/, "").replace(/\}$/, "").split("\n").map((line) => line.trim()).filter((line) => line !== "").join("\n");
+		if (inner !== "") fields.push(inner);
+	}
+	if (fields.length === 0) return void 0;
+	return {
+		declaration: `export interface RequestContext {\n${indent(fields.join("\n"))}\n}`,
+		required
+	};
+};
+/**
+* A constructor per brand, so a value from outside the API becomes one with
+* `toUserId('usr_k7f3q9')` rather than a cast.
+*/
+const emitBrandConstructors = (collector, namespaceName) => collector.allBrands().map(({ name, base, example }) => `
+${docComment([
+	`Brands a value from outside the API, like a URL segment, as \`${namespaceName}.${name}\`. A value from a response is branded already.`,
+	"",
+	"@example",
+	`const id = to${name}(${example});`
+])}export const to${name} = (value: ${base}): ${namespaceName}.${name} => value as ${namespaceName}.${name};
+`).join("");
+/**
+* Tells kizuna's validation error from a 400 the route declares itself.
+*/
+const emitValidationGuard = (namespaceName) => `
+${docComment([
+	`Whether a \`400\` body is the validation error kizuna sends, rather than a \`400\` the route declares itself.`,
+	"",
+	"@example",
+	"if (result.status === 400 && isValidationError(result.body)) {",
+	"    console.log(result.body.errors);",
+	"}"
+])}export const isValidationError = (body: unknown): body is ${namespaceName}.ValidationError =>
+    typeof body === 'object' && body !== null && 'errors' in body && Array.isArray(body.errors);
+`;
+/**
+* Declared in the file, so a brand needs nothing installed.
+*/
+const BRAND_DECLARATION = `declare const kizunaBrand: unique symbol;
+
+/**
+ * Tells one branded type from another with the same base.
+ */
+type KizunaBrand<Name extends string> = {
+    readonly [kizunaBrand]: {
+        readonly [Key in Name]: true;
+    };
+};
+
+`;
+const generateFetchClient = (contract, options = {}) => {
+	const { namespace: namespaceName = "API", regenerateCommand = "kizuna generate", source } = options;
+	const collector = new TypeCollector();
+	const tree = emitTree(listedRoutes(contract), "", collector, namespaceName);
+	const requestContext = emitRequestContext(contract, collector);
+	const api = [...collector.all().map((model) => {
+		return `${model.description ? `/**\n * ${model.description}\n */\n` : ""}export type ${model.name} = ${model.body};`;
+	}), ...tree.declarations].join("\n\n");
+	const brands = emitBrandConstructors(collector, namespaceName);
+	const guards = collector.all().some((model) => model.name === "ValidationError") ? emitValidationGuard(namespaceName) : "";
+	return `/* eslint-disable */
+/**
+${[
+		" * Generated by @kizunajs/fetch. Do not edit.",
+		" *",
+		...source === void 0 ? [] : [` * Source: ${source}`],
+		` * Regenerate: ${regenerateCommand}`
+	].join("\n")}
+ */
+${collector.usesBrand() ? BRAND_DECLARATION : ""}export namespace ${namespaceName} {
+${indent(api)}
+}
+
+export interface Client {
+${indent(tree.signatures)}
+}
+
+const routes: GeneratedRoutes = {
+${indent(tree.table)}
+};
+${brands}${guards}
+${requestContext === void 0 ? `/**
+ * A client for this API. Pass the base URL and anything else the runtime takes.
+ */
+export const createClient = (config: ClientConfig): Client => buildClient(routes, config) as unknown as Client;` : `${requestContext.declaration}
+
+/**
+ * A client for this API. Pass the base URL, the request context headers this
+ * API declares, and anything else the runtime takes.
+ */
+export const createClient = (config: ClientConfig & { requestContext${requestContext.required ? "" : "?"}: RequestContext }): Client =>
+    buildClient(routes, config) as unknown as Client;`}
+
+${runtimeSource}`;
+};
+/**
+* A TypeScript client for `kizuna.config.ts`.
+*
+* @example
+* fetchClient({
+*     output: './packages/api-client/src/generated.ts',
+* });
 */
-const createGeneratedClient = (routes, config) => buildClientTree(routes, withContextHeaders(config));
+const fetchClient = defineClient({
+	target: "fetch",
+	options: z.object({
+		/**
+		* Name of the generated namespace holding every model and every route's
+		* `Params`, `Query`, `Body`, `Headers` and `Result`.
+		*
+		* @default 'API'
+		*/
+		namespace: z.string().optional(),
+		/**
+		* Command the file's header tells a reader to run.
+		*
+		* @default 'kizuna generate'
+		*/
+		regenerateCommand: z.string().optional(),
+		/**
+		* Path to the api this was generated from, relative to the generated
+		* file. Named in the header so tooling can tell when the client has fallen
+		* behind, and so a reader knows where the API is declared.
+		*/
+		source: z.string().optional()
+	}),
+	generate: ({ options, api }) => ({ finalize: () => generateFetchClient(api, options) })
+});
 //#endregion
-export { CLIENT_ROUTE, createGeneratedClient, isProblemDetails, isValidationError, routeOf };
+export { fetchClient, generateFetchClient };