@mpen/routekit 0.1.0

package/dist/bin.mjs

@@ -0,0 +1,574 @@
+#!/usr/bin/env -S bun
+import { HttpMethod } from "@mpen/http";
+import path from "node:path";
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "util";
+import { $ } from "bun";
+import { compile } from "json-schema-to-typescript";
+//#region src/bin/gen-api-client.ts
+const DEFAULT_RESPONSE_TYPE = "ApiResponsePromise";
+const DEFAULT_FORMAT = "rk-api-client";
+const OUTPUT_FORMATS = ["rk-api-client", "ts-query-rk-problem"];
+function printHelp() {
+	console.log(`Usage: bun run packages/routekit/src/bin/gen-api-client.ts <router-file> [options]
+
+Generate a typed API client from a routekit router module.
+
+Arguments:
+  router-file                 Router module that exports a router with getRoutes()
+
+Options:
+  -o, --output <file>         File to write. Prints to stdout when omitted.
+  -w, --write                 Write to <router-file>.gen.ts beside the router file.
+  -p, --pretty                Format written output with Prettier.
+  -f, --format <format>       Output format: rk-api-client or ts-query-rk-problem. Defaults to rk-api-client.
+  --client-name <Name>        Generated client class name. Defaults to ApiClient.
+  --import-type <Type:module> Import a type used by generated schemas. Can be repeated.
+  --response-type <Type>      Generic response wrapper type. Defaults to ApiResponsePromise.
+  --help                      Show this help message.`);
+}
+function routeTypeBaseName(route) {
+	const parts = route.name.length > 0 ? route.name : ["index"];
+	return upperFirst(route.method.toLowerCase()) + parts.map(upperFirst).join("");
+}
+function getPathParamNames(routePath) {
+	return (routePath.match(/:([a-zA-Z0-9_]+)/g) ?? []).map((match) => match.slice(1));
+}
+function buildRouteTree(routes) {
+	const root = {
+		routes: [],
+		children: /* @__PURE__ */ new Map()
+	};
+	for (const route of routes) {
+		let node = root;
+		for (const segment of route.name) {
+			if (!node.children.has(segment)) node.children.set(segment, {
+				routes: [],
+				children: /* @__PURE__ */ new Map()
+			});
+			node = node.children.get(segment);
+		}
+		node.routes.push(route);
+	}
+	return root;
+}
+function classNameForParts(parts, baseName) {
+	if (parts.length === 0) return baseName;
+	return `${baseName}_${parts.map(upperFirst).join("_")}`;
+}
+function parseImportTypeOption(value) {
+	const colonIdx = value.indexOf(":");
+	if (colonIdx === -1) throw new Error(`Invalid --import-type value: "${value}"`);
+	const names = value.slice(0, colonIdx);
+	const module = value.slice(colonIdx + 1).trim();
+	const parsedNames = names.split(",").map((name) => name.trim()).filter(Boolean);
+	if (parsedNames.length === 0 || module.length === 0) throw new Error(`Invalid --import-type value: "${value}"`);
+	return {
+		names: parsedNames,
+		module
+	};
+}
+function normalizeClientName(name) {
+	if (!name) return "ApiClient";
+	return name.replace(/[^A-Za-z0-9]+/g, " ").trim().split(/\s+/).map(upperFirst).join("") || "ApiClient";
+}
+function parseOutputFormat(value) {
+	const format = value?.trim() || DEFAULT_FORMAT;
+	if (OUTPUT_FORMATS.includes(format)) return format;
+	throw new Error(`Invalid --format value: "${value}". Expected one of: ${OUTPUT_FORMATS.join(", ")}`);
+}
+function upperFirst(str) {
+	return str.slice(0, 1).toUpperCase() + str.slice(1);
+}
+function patternToUrlTemplate(routePath, pathVar = "path") {
+	const templated = routePath.replace(/:([a-zA-Z0-9_]+)/g, `\${encodeURIComponent(String(${pathVar}.$1))}`);
+	if (templated.includes("${")) return "`" + templated + "`";
+	return `"${routePath}"`;
+}
+function isUnknown(text) {
+	return text === "unknown" || text === "any";
+}
+function isUnconstrainedJsonSchema(schema) {
+	return schema === true || schema !== false && typeof schema === "object" && !Array.isArray(schema) && Object.keys(schema).length === 0;
+}
+function isNeverJsonSchema(schema) {
+	return schema === false || schema !== true && typeof schema === "object" && !Array.isArray(schema) && Object.keys(schema).length === 1 && typeof schema.not === "object" && schema.not !== null && !Array.isArray(schema.not) && Object.keys(schema.not).length === 0;
+}
+function isJsonSchemaObject(schema) {
+	return schema !== true && schema !== false && typeof schema === "object" && !Array.isArray(schema);
+}
+function isNumericStringSchema(schema) {
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return false;
+	const schemaObject = schema;
+	return schemaObject.type === "string" && typeof schemaObject.pattern === "string" && ["^\\d+$", "^[0-9]+$"].includes(schemaObject.pattern);
+}
+function widenNumericStringPathParams(schema, pathParams) {
+	if (!isJsonSchemaObject(schema)) return schema;
+	const properties = schema.properties;
+	if (!properties || typeof properties !== "object" || Array.isArray(properties)) return schema;
+	const nextProperties = { ...properties };
+	let widened = false;
+	for (const pathParam of pathParams) {
+		const propertySchema = nextProperties[pathParam];
+		if (!isNumericStringSchema(propertySchema)) continue;
+		nextProperties[pathParam] = { anyOf: [propertySchema, { type: "number" }] };
+		widened = true;
+	}
+	if (!widened) return schema;
+	return {
+		...schema,
+		properties: nextProperties
+	};
+}
+function normalizeMethod(routeMethod) {
+	if (!routeMethod) return [HttpMethod.GET];
+	return Array.isArray(routeMethod) ? routeMethod : [routeMethod];
+}
+function extractRoutes(routes) {
+	const extracted = [];
+	for (const route of routes) for (const method of normalizeMethod(route.method)) extracted.push({
+		name: route.name,
+		method,
+		path: route.path.pathname,
+		...route.schema?.request ? { requestSchema: route.schema.request } : {},
+		...route.schema?.response?.body ? { responseBodySchemas: route.schema.response.body } : {}
+	});
+	return extracted;
+}
+function resolveRouterModule(module) {
+	const candidates = [
+		module.default,
+		module.router,
+		...Object.values(module)
+	];
+	for (const candidate of candidates) if (candidate && typeof candidate === "object" && typeof candidate.getRoutes === "function") return candidate;
+	throw new Error("Unable to find an exported router with a getRoutes() method");
+}
+async function loadRuntimeRoutes(routerPath) {
+	return resolveRouterModule(await import(pathToFileURL(routerPath).href)).getRoutes();
+}
+async function compileSchemaType(name, schema) {
+	if (isUnconstrainedJsonSchema(schema)) return `export type ${name} = unknown`;
+	if (isNeverJsonSchema(schema)) return `export type ${name} = never`;
+	return (await compile(schema, name, {
+		bannerComment: "",
+		additionalProperties: false,
+		style: { singleQuote: true }
+	})).trim().replace(/\bNoName\b/g, `${name}Schema`);
+}
+async function formatWithPrettier(source, outputPath) {
+	let prettier;
+	try {
+		prettier = await import("prettier");
+	} catch (cause) {
+		throw new Error("The --pretty option requires prettier to be installed.", { cause });
+	}
+	const options = await prettier.resolveConfig(outputPath) ?? {};
+	return prettier.format(source, {
+		...options,
+		filepath: outputPath
+	});
+}
+function responseStatusAlias(typeBase, status) {
+	return `${typeBase}Response${status}`;
+}
+function isSuccessfulStatus(status) {
+	const statusNumber = Number(status);
+	return Number.isInteger(statusNumber) && statusNumber >= 200 && statusNumber < 300;
+}
+function responseStatusAliases(route, statusFilter) {
+	if (!route.responseBodySchemas) return [];
+	return Object.entries(route.responseBodySchemas).filter(([status, responseSchema]) => responseSchema !== void 0 && statusFilter(status)).map(([status]) => responseStatusAlias(route.typeBase, status));
+}
+function unionType(types, fallback) {
+	if (types.length === 0) return fallback;
+	if (types.length === 1) return types[0];
+	return types.join(" | ");
+}
+async function generateRouteTypes(route) {
+	const generated = {
+		route,
+		responseTypeSources: []
+	};
+	if (route.requestSchema?.path) generated.pathTypeSource = await compileSchemaType(`${route.typeBase}PathParams`, widenNumericStringPathParams(route.requestSchema.path, route.pathParams));
+	if (route.requestSchema?.query) generated.queryTypeSource = await compileSchemaType(`${route.typeBase}Query`, route.requestSchema.query);
+	if (route.requestSchema?.body !== void 0) generated.requestTypeSource = await compileSchemaType(`${route.typeBase}Request`, route.requestSchema.body);
+	if (route.responseBodySchemas && Object.keys(route.responseBodySchemas).length > 0) {
+		const responseTypesByStatus = [];
+		for (const [status, responseSchema] of Object.entries(route.responseBodySchemas)) {
+			if (responseSchema === void 0) continue;
+			const alias = responseStatusAlias(route.typeBase, status);
+			generated.responseTypeSources.push(await compileSchemaType(alias, responseSchema));
+			responseTypesByStatus.push(`    ${JSON.stringify(status)}: ${alias}`);
+		}
+		generated.responseTypesByStatusSource = responseTypesByStatus.length > 0 ? [
+			`export interface ${route.typeBase}ResponsesByStatus {`,
+			...responseTypesByStatus,
+			`}`,
+			`export type ${route.typeBase}Response = ${route.typeBase}ResponsesByStatus[keyof ${route.typeBase}ResponsesByStatus]`
+		].join("\n") : `export type ${route.typeBase}Response = unknown`;
+	} else {
+		const fallback = route.method === HttpMethod.HEAD ? "never" : "unknown";
+		generated.responseTypesByStatusSource = `export type ${route.typeBase}Response = ${fallback}`;
+	}
+	return generated;
+}
+function buildMethodLines(route, options, indent) {
+	const lines = [];
+	const methodName = route.method.toLowerCase();
+	const bodyType = route.requestSchema?.body !== void 0 ? `${route.typeBase}Request` : void 0;
+	const queryType = route.requestSchema?.query ? `${route.typeBase}Query` : void 0;
+	const hasPathParams = route.pathParams.length > 0;
+	const hasSinglePathParam = route.pathParams.length === 1;
+	let pathVar = "path";
+	if (hasPathParams) {
+		if (hasSinglePathParam) pathVar = "_path";
+	}
+	const shouldResolveApiResponse = options.responseType === DEFAULT_RESPONSE_TYPE;
+	const hasResponsesByStatus = !!route.responseBodySchemas && Object.keys(route.responseBodySchemas).length > 0;
+	const returnType = shouldResolveApiResponse && hasResponsesByStatus ? `ApiResponseByStatusPromise<${route.typeBase}ResponsesByStatus>` : `${options.responseType}<${route.typeBase}Response>`;
+	const params = [];
+	if (hasPathParams) {
+		let pathParamType = pathTypeForRoute(route);
+		if (hasSinglePathParam) {
+			const singleParamType = route.requestSchema?.path ? `SinglePathParam<${route.typeBase}PathParams, "${route.pathParams[0]}">` : "any";
+			pathParamType = `${pathParamType} | ${singleParamType}`;
+		}
+		params.push(`path: ${pathParamType}`);
+	}
+	if (queryType) params.push(`query: ${queryType}`);
+	if (bodyType) params.push(`body: ${bodyType}`);
+	lines.push(`${indent}${methodName} = (${params.join(", ")}): ${returnType} => {`);
+	if (hasSinglePathParam) lines.push(`${indent}    const _path = typeof path === 'object' && path !== null && !Array.isArray(path) ? path : { ${route.pathParams[0]}: path } as any`);
+	const urlExpr = patternToUrlTemplate(route.path, pathVar);
+	const finalUrlExpr = queryType ? `withQuery(${urlExpr}, query)` : urlExpr;
+	const resolverExpression = shouldResolveApiResponse && hasResponsesByStatus ? `resolveApiResponseByStatus<${route.typeBase}ResponsesByStatus>` : "resolveApiResponse";
+	lines.push(`${indent}    return ${shouldResolveApiResponse ? `${resolverExpression}(` : ""}this.transport.request({`);
+	lines.push(`${indent}        url: ${finalUrlExpr},`);
+	lines.push(`${indent}        init: {`);
+	lines.push(`${indent}            method: "${route.method}",`);
+	lines.push(`${indent}        },`);
+	if (bodyType) lines.push(`${indent}        body,`);
+	if (shouldResolveApiResponse) lines.push(`${indent}    }))`);
+	else lines.push(`${indent}    }) as ${returnType}`);
+	lines.push(`${indent}}`);
+	return lines;
+}
+function pathTypeForRoute(route) {
+	return route.requestSchema?.path ? `${route.typeBase}PathParams` : "any";
+}
+function pathParameterTypeForRoute(route) {
+	let pathParamType = pathTypeForRoute(route);
+	if (route.pathParams.length === 1) {
+		const singleParamType = route.requestSchema?.path ? `SinglePathParam<${route.typeBase}PathParams, "${route.pathParams[0]}">` : "any";
+		pathParamType = `${pathParamType} | ${singleParamType}`;
+	}
+	return pathParamType;
+}
+function routeRequestComponents(route) {
+	const components = [];
+	if (route.pathParams.length > 0) components.push({
+		name: "path",
+		type: pathParameterTypeForRoute(route)
+	});
+	if (route.requestSchema?.query) components.push({
+		name: "query",
+		type: `${route.typeBase}Query`
+	});
+	if (route.requestSchema?.body !== void 0) components.push({
+		name: "body",
+		type: `${route.typeBase}Request`
+	});
+	return components;
+}
+function emitClass(node, parts, options, lines) {
+	const className = classNameForParts(parts, options.clientName);
+	const exportKeyword = parts.length === 0 ? "export " : "";
+	const childNames = Array.from(node.children.keys());
+	lines.push(`${exportKeyword}class ${className} {`);
+	if (parts.length === 0) lines.push(`    private readonly transport: ClientTransport`);
+	for (const childName of childNames) {
+		const childClass = classNameForParts([...parts, childName], options.clientName);
+		lines.push(`    private _${childName}?: ${childClass}`);
+	}
+	if (parts.length === 0 || childNames.length > 0) lines.push(``);
+	if (parts.length === 0) {
+		lines.push(`    constructor(transport?: ClientTransport) {`);
+		lines.push(`        this.transport = transport ?? new FetchTransport()`);
+		lines.push(`    }`);
+	} else lines.push(`    constructor(private readonly transport: ClientTransport) {}`);
+	if (node.children.size > 0) {
+		lines.push(``);
+		childNames.forEach((childName, idx) => {
+			const childClass = classNameForParts([...parts, childName], options.clientName);
+			lines.push(`    get ${childName}(): ${childClass} {`);
+			lines.push(`        return (this._${childName} ??= new ${childClass}(this.transport))`);
+			lines.push(`    }`);
+			if (idx !== childNames.length - 1 || node.routes.length > 0) lines.push(``);
+		});
+	}
+	if (node.routes.length > 0) node.routes.forEach((route, idx) => {
+		const methodLines = buildMethodLines(route, options, "    ");
+		for (const line of methodLines) lines.push(line);
+		if (idx !== node.routes.length - 1) lines.push(``);
+	});
+	lines.push(`}`);
+	lines.push(``);
+	for (const [childName, childNode] of node.children) emitClass(childNode, [...parts, childName], options, lines);
+}
+function emitGeneratedRouteTypeSources(generatedTypes, lines) {
+	for (const generated of generatedTypes) {
+		if (generated.pathTypeSource && !isUnknown(generated.pathTypeSource)) lines.push(generated.pathTypeSource, ``);
+		if (generated.queryTypeSource && !isUnknown(generated.queryTypeSource)) lines.push(generated.queryTypeSource, ``);
+		if (generated.requestTypeSource && !isUnknown(generated.requestTypeSource)) lines.push(generated.requestTypeSource, ``);
+		for (const responseTypeSource of generated.responseTypeSources) if (!isUnknown(responseTypeSource)) lines.push(responseTypeSource, ``);
+		if (generated.responseTypesByStatusSource) lines.push(generated.responseTypesByStatusSource, ``);
+	}
+}
+function routeSuccessBodyType(route) {
+	return unionType(responseStatusAliases(route, isSuccessfulStatus), "unknown");
+}
+function routeProblemBodyType(route) {
+	return unionType(responseStatusAliases(route, (status) => !isSuccessfulStatus(status)), "unknown");
+}
+function isQueryRoute(route) {
+	return route.method === HttpMethod.GET || route.method === HttpMethod.HEAD;
+}
+function emitTsQueryRouteTypeAliases(generatedTypes, lines) {
+	for (const { route } of generatedTypes) {
+		const successBodyType = routeSuccessBodyType(route);
+		const problemBodyType = routeProblemBodyType(route);
+		lines.push(`export type ${route.typeBase}Data = RoutekitProblemSuccessData<${successBodyType}>`);
+		lines.push(`export type ${route.typeBase}Problem = ${problemBodyType}`);
+		lines.push(`export type ${route.typeBase}Error = RoutekitProblemError<${route.typeBase}Problem>`);
+		lines.push(``);
+		const components = routeRequestComponents(route);
+		if (!isQueryRoute(route) && components.length > 1) {
+			lines.push(`export interface ${route.typeBase}Variables {`);
+			for (const component of components) lines.push(`    ${component.name}: ${component.type}`);
+			lines.push(`}`);
+			lines.push(``);
+		}
+	}
+}
+function buildTransportRequestLines(route, indent, pathVar, queryVar, bodyVar) {
+	const lines = [];
+	const urlExpr = patternToUrlTemplate(route.path, pathVar);
+	const finalUrlExpr = queryVar ? `withQuery(${urlExpr}, ${queryVar})` : urlExpr;
+	lines.push(`${indent}transport.request({`);
+	lines.push(`${indent}    url: ${finalUrlExpr},`);
+	lines.push(`${indent}    init: {`);
+	lines.push(`${indent}        method: "${route.method}",`);
+	lines.push(`${indent}    },`);
+	if (bodyVar) lines.push(`${indent}    body: ${bodyVar},`);
+	lines.push(`${indent}})`);
+	return lines;
+}
+function pushSinglePathParamNormalization(route, lines, indent) {
+	if (route.pathParams.length !== 1) return "path";
+	lines.push(`${indent}const _path = typeof path === 'object' && path !== null && !Array.isArray(path) ? path : { ${route.pathParams[0]}: path } as any`);
+	return "_path";
+}
+function tsQueryKey(route, components) {
+	return [
+		JSON.stringify("routekit"),
+		JSON.stringify(route.method),
+		JSON.stringify(route.path),
+		...components
+	].join(", ");
+}
+function emitQueryHelper(route, lines, indent) {
+	const components = routeRequestComponents(route);
+	const params = components.map((component) => `${component.name}: ${component.type}`).join(", ");
+	const methodName = route.method.toLowerCase();
+	const successBodyType = routeSuccessBodyType(route);
+	const queryKeyComponents = [];
+	lines.push(`${indent}${methodName}: (${params}) => {`);
+	const pathVar = pushSinglePathParamNormalization(route, lines, `${indent}    `);
+	for (const component of components) queryKeyComponents.push(component.name === "path" ? pathVar : component.name);
+	lines.push(`${indent}    return queryOptions<${route.typeBase}Data, ${route.typeBase}Error>({`);
+	lines.push(`${indent}        queryKey: [${tsQueryKey(route, queryKeyComponents)}] as const,`);
+	lines.push(`${indent}        queryFn: (): Promise<${route.typeBase}Data> => {`);
+	lines.push(`${indent}            return resolveRoutekitProblemData<${successBodyType}, ${route.typeBase}Problem>(`);
+	for (const requestLine of buildTransportRequestLines(route, `${indent}                `, pathVar, route.requestSchema?.query ? "query" : void 0, route.requestSchema?.body !== void 0 ? "body" : void 0)) lines.push(requestLine);
+	lines.push(`${indent}            )`);
+	lines.push(`${indent}        },`);
+	lines.push(`${indent}    })`);
+	lines.push(`${indent}},`);
+}
+function emitMutationHelper(route, lines, indent) {
+	const components = routeRequestComponents(route);
+	const methodName = route.method.toLowerCase();
+	const successBodyType = routeSuccessBodyType(route);
+	const variablesType = components.length === 0 ? "void" : components.length === 1 ? components[0].type : `${route.typeBase}Variables`;
+	lines.push(`${indent}${methodName}: () => {`);
+	lines.push(`${indent}    return mutationOptions<${route.typeBase}Data, ${route.typeBase}Error, ${variablesType}>({`);
+	lines.push(`${indent}        mutationKey: [${tsQueryKey(route, [])}] as const,`);
+	let mutationParam = "";
+	if (components.length === 1) {
+		const component = components[0];
+		mutationParam = `${component.name}: ${component.type}`;
+	} else if (components.length > 1) mutationParam = `variables: ${route.typeBase}Variables`;
+	lines.push(`${indent}        mutationFn: (${mutationParam}): Promise<${route.typeBase}Data> => {`);
+	if (components.length > 1) for (const component of components) lines.push(`${indent}            const ${component.name} = variables.${component.name}`);
+	const pathVar = components.some((component) => component.name === "path") && route.pathParams.length === 1 ? pushSinglePathParamNormalization(route, lines, `${indent}            `) : "path";
+	lines.push(`${indent}            return resolveRoutekitProblemData<${successBodyType}, ${route.typeBase}Problem>(`);
+	for (const requestLine of buildTransportRequestLines(route, `${indent}                `, pathVar, route.requestSchema?.query ? "query" : void 0, route.requestSchema?.body !== void 0 ? "body" : void 0)) lines.push(requestLine);
+	lines.push(`${indent}            )`);
+	lines.push(`${indent}        },`);
+	lines.push(`${indent}    })`);
+	lines.push(`${indent}},`);
+}
+function emitTsQueryNodeProperties(node, lines, indent) {
+	for (const [childName, childNode] of node.children) {
+		lines.push(`${indent}${childName}: {`);
+		emitTsQueryNodeProperties(childNode, lines, `${indent}    `);
+		lines.push(`${indent}},`);
+	}
+	for (const route of node.routes) if (isQueryRoute(route)) emitQueryHelper(route, lines, indent);
+	else emitMutationHelper(route, lines, indent);
+}
+async function buildApiClientSource(routes, options) {
+	const processedRoutes = routes.map((route) => ({
+		...route,
+		typeBase: routeTypeBaseName(route),
+		pathParams: getPathParamNames(route.path)
+	}));
+	const needsSinglePathHelper = processedRoutes.some((route) => route.pathParams.length === 1);
+	const needsQueryHelper = processedRoutes.some((route) => route.requestSchema?.query);
+	const needsResponseByStatusHelper = processedRoutes.some((route) => route.responseBodySchemas && Object.keys(route.responseBodySchemas).length > 0);
+	const needsDefaultResponsePromise = processedRoutes.some((route) => !route.responseBodySchemas || Object.keys(route.responseBodySchemas).length === 0);
+	const generatedTypes = await Promise.all(processedRoutes.map(generateRouteTypes));
+	const lines = [];
+	lines.push(`// Do not modify this file. It was auto-generated with the following command:`);
+	lines.push(`// $ ${options.commandText}`);
+	lines.push(``);
+	for (const importType of options.importTypes) lines.push(`import type { ${importType.names.join(", ")} } from '${importType.module}'`);
+	const clientImports = [
+		"FetchTransport",
+		options.responseType === DEFAULT_RESPONSE_TYPE && needsDefaultResponsePromise ? "resolveApiResponse" : void 0,
+		options.responseType === DEFAULT_RESPONSE_TYPE && needsResponseByStatusHelper ? "resolveApiResponseByStatus" : void 0,
+		needsQueryHelper ? "withQuery" : void 0,
+		"type ClientTransport",
+		options.responseType === DEFAULT_RESPONSE_TYPE && needsResponseByStatusHelper ? "type ApiResponseByStatusPromise" : void 0,
+		options.responseType === DEFAULT_RESPONSE_TYPE && needsDefaultResponsePromise ? `type ${options.responseType}` : void 0,
+		needsSinglePathHelper ? "type SinglePathParam" : void 0
+	].filter(Boolean);
+	lines.push(`import { ${clientImports.join(", ")} } from '@mpen/routekit/client'`);
+	if (options.importTypes.length > 0) lines.push(``);
+	lines.push(``);
+	lines.push(``);
+	emitGeneratedRouteTypeSources(generatedTypes, lines);
+	emitClass(buildRouteTree(processedRoutes), [], options, lines);
+	return lines.join("\n");
+}
+async function buildTsQueryRkProblemSource(routes, options) {
+	const processedRoutes = routes.map((route) => ({
+		...route,
+		typeBase: routeTypeBaseName(route),
+		pathParams: getPathParamNames(route.path)
+	}));
+	const needsSinglePathHelper = processedRoutes.some((route) => route.pathParams.length === 1);
+	const needsQueryHelper = processedRoutes.some((route) => route.requestSchema?.query);
+	const generatedTypes = await Promise.all(processedRoutes.map(generateRouteTypes));
+	const lines = [];
+	lines.push(`// Do not modify this file. It was auto-generated with the following command:`);
+	lines.push(`// $ ${options.commandText}`);
+	lines.push(``);
+	for (const importType of options.importTypes) lines.push(`import type { ${importType.names.join(", ")} } from '${importType.module}'`);
+	lines.push(`import { mutationOptions, queryOptions } from '@tanstack/react-query'`);
+	const clientImports = [
+		"FetchTransport",
+		"resolveRoutekitProblemData",
+		needsQueryHelper ? "withQuery" : void 0,
+		"type ClientTransport",
+		"type RoutekitProblemError",
+		"type RoutekitProblemSuccessData",
+		needsSinglePathHelper ? "type SinglePathParam" : void 0
+	].filter(Boolean);
+	lines.push(`import { ${clientImports.join(", ")} } from '@mpen/routekit/client'`);
+	lines.push(``);
+	emitGeneratedRouteTypeSources(generatedTypes, lines);
+	emitTsQueryRouteTypeAliases(generatedTypes, lines);
+	const tree = buildRouteTree(processedRoutes);
+	lines.push(`export function createApiQueryHelpers(transport: ClientTransport = new FetchTransport()) {`);
+	lines.push(`    return {`);
+	emitTsQueryNodeProperties(tree, lines, `        `);
+	lines.push(`    }`);
+	lines.push(`}`);
+	lines.push(``);
+	return lines.join("\n");
+}
+async function main() {
+	const { positionals, values } = parseArgs({
+		allowPositionals: true,
+		strict: true,
+		options: {
+			output: {
+				type: "string",
+				short: "o"
+			},
+			write: {
+				type: "boolean",
+				short: "w"
+			},
+			pretty: {
+				type: "boolean",
+				short: "p"
+			},
+			format: {
+				type: "string",
+				short: "f"
+			},
+			"client-name": { type: "string" },
+			"import-type": {
+				type: "string",
+				multiple: true
+			},
+			"response-type": { type: "string" },
+			help: { type: "boolean" }
+		}
+	});
+	if (values.help) {
+		printHelp();
+		return;
+	}
+	const [routerPathArg] = positionals;
+	if (!routerPathArg) {
+		printHelp();
+		process.exit(1);
+	}
+	const format = parseOutputFormat(values.format);
+	const clientName = normalizeClientName(values["client-name"]);
+	const responseType = values["response-type"]?.trim() || DEFAULT_RESPONSE_TYPE;
+	const importTypes = values["import-type"]?.map(parseImportTypeOption) ?? [];
+	const routerPath = path.resolve(routerPathArg);
+	let outputPath;
+	if (values.output) outputPath = path.resolve(values.output);
+	else if (values.write) outputPath = path.join(path.dirname(routerPath), `${path.basename(routerPath, path.extname(routerPath))}.gen.ts`);
+	const routes = extractRoutes(await loadRuntimeRoutes(routerPath));
+	const rawArgs = process.argv.slice(1);
+	if (rawArgs[0] && path.isAbsolute(rawArgs[0])) rawArgs[0] = path.relative(process.cwd(), rawArgs[0]).replace(/\\/g, "/");
+	const commandText = ["bun", ...rawArgs.map((arg) => $.escape(arg))].join(" ");
+	let client = format === "rk-api-client" ? await buildApiClientSource(routes, {
+		clientName,
+		responseType,
+		importTypes,
+		commandText
+	}) : await buildTsQueryRkProblemSource(routes, {
+		importTypes,
+		commandText
+	});
+	if (outputPath) {
+		if (values.pretty) client = await formatWithPrettier(client, outputPath);
+		fs.writeFileSync(outputPath, client, "utf8");
+		console.log(`Wrote API client to ${path.relative(process.cwd(), outputPath)}`);
+	} else console.log(client);
+}
+if (import.meta.main) main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+//#endregion
+export { main };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@mpen/routekit",
+  "version": "0.1.0",
+  "description": "Typed server-side routing utilities for Fetch-compatible runtimes.",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./bin": "./dist/bin.mjs",
+    "./client": "./dist/client.mjs",
+    "./client/react": "./dist/client/react.mjs",
+    "./handlers": "./dist/handlers.mjs",
+    "./middleware": "./dist/middleware.mjs",
+    "./response/content": "./dist/response/content.mjs",
+    "./response/json-rpc": "./dist/response/json-rpc.mjs",
+    "./response/problem": "./dist/response/problem.mjs",
+    "./response/problem/valibot": "./dist/response/problem/valibot.mjs",
+    "./response/status": "./dist/response/status.mjs",
+    "./routes": "./dist/routes.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "routekit": "./dist/bin.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "module": "./dist/index.mjs",
+  "type": "module",
+  "devDependencies": {
+    "@mpen/ts-types": "0.1.5",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@tanstack/react-query": "^5",
+    "@valibot/to-json-schema": "^1.6.0",
+    "bun-types": "latest",
+    "happy-dom": "^20.9.0",
+    "maxmind": "^5",
+    "react": "^19",
+    "react-dom": "^19",
+    "tsdown": "^0.21",
+    "valibot": "^1.4.0",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "@valibot/to-json-schema": "^1.6.0",
+    "maxmind": "^5",
+    "prettier": "^3.8.3",
+    "react": "^19",
+    "@tanstack/react-query": "^5",
+    "typescript": "^5",
+    "valibot": "^1.4.0",
+    "zod": "^4.3.5"
+  },
+  "peerDependenciesMeta": {
+    "@valibot/to-json-schema": {
+      "optional": true
+    },
+    "maxmind": {
+      "optional": true
+    },
+    "valibot": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "prettier": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@mpen/http": "0.1.0",
+    "@mpen/logger": "0.2.0",
+    "json-schema-to-typescript": "^15.0.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "gen": "bun ./src/bin/gen-api-client.ts ./examples/example1/server/router-instance.ts -o ./examples/example1/client/api-client.gen.ts",
+    "gen3": "bun ./src/bin/gen-api-client.ts ./examples/example3/server/router.ts -o ./examples/example3/client/router.gen.ts -p",
+    "react:build": "bun ./examples/react/scripts/build-client.ts",
+    "react:dev": "bun ./examples/react/dev.ts",
+    "react:gen": "bun ./src/bin/gen-api-client.ts ./examples/react/server/api-router.ts -o ./examples/react/client/api/router.gen.ts -p"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "publishConfig": {
+    "access": "public"
+  }
+}