@mpen/routekit 0.1.0 → 0.1.1

package/dist/client.d.mts

@@ -0,0 +1,433 @@
+//#region src/client/promise.d.ts
+/**
+ * A value that may be returned immediately or through a promise.
+ *
+ * @example
+ * ```ts
+ * const headers: MaybePromise<HeadersInit> = { authorization: 'Bearer token' }
+ * ```
+ *
+ * @typeParam T - The resolved value type.
+ */
+type MaybePromise<T> = T | Promise<T>;
+//#endregion
+//#region src/client/headers.d.ts
+type ClientHeadersInit$1 = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+/**
+ * Context passed to global header providers.
+ *
+ * @example
+ * ```ts
+ * const headers = (context: ClientHeaderContext) =>
+ *     context.url.startsWith('/admin') ? { authorization: `Bearer ${token}` } : undefined
+ * ```
+ */
+interface ClientHeaderContext {
+  /** The request URL before base URL resolution. */
+  url: string;
+  /** The request init object before execution. */
+  init: RequestInit;
+}
+/**
+ * Headers or a function that provides headers for each request.
+ *
+ * @example
+ * ```ts
+ * const headers: ClientHeaders = () => ({ authorization: `Bearer ${token}` })
+ * ```
+ */
+type ClientHeaders = ClientHeadersInit$1 | ((context: ClientHeaderContext) => MaybePromise<ClientHeadersInit$1 | undefined>);
+//#endregion
+//#region src/client/transport.d.ts
+type ClientHeadersInit = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+/**
+ * A generated client request before it is executed by a transport.
+ *
+ * @example
+ * ```ts
+ * const request: ClientRequest = {
+ *     url: '/widgets',
+ *     init: { method: 'POST' },
+ *     body: { name: 'demo' },
+ * }
+ * ```
+ */
+interface ClientRequest {
+  /** The URL path generated for the route. */
+  url: string;
+  /** Fetch-compatible request initialization. */
+  init: RequestInit;
+  /** The unencoded request body value. */
+  body?: unknown;
+}
+/**
+ * A minimal response returned by client transports.
+ *
+ * @example
+ * ```ts
+ * const response: ApiTransportResponse = {
+ *     status: 200,
+ *     body: { ok: true },
+ * }
+ * ```
+ */
+interface ApiTransportResponse {
+  /** The response status code. */
+  status: number;
+  /** The response headers, when available. */
+  headers?: ClientHeadersInit;
+  /** The parsed response body. */
+  body: unknown;
+}
+/**
+ * The async response wrapper returned by client transports.
+ *
+ * @example
+ * ```ts
+ * const response: ApiTransportResponsePromise = transport.request(request)
+ * ```
+ */
+type ApiTransportResponsePromise = Promise<ApiTransportResponse>;
+/**
+ * Transport used by generated API clients to execute typed requests.
+ *
+ * @example
+ * ```ts
+ * class AxiosTransport implements ClientTransport {
+ *     async request(request: ClientRequest): ApiTransportResponsePromise {
+ *         throw new Error('Adapt Axios into a Response-shaped object here')
+ *     }
+ * }
+ * ```
+ */
+interface ClientTransport {
+  /**
+   * Execute a generated client request.
+   *
+   * @param request - The generated request metadata and init.
+   * @returns A transport response promise.
+   */
+  request(request: ClientRequest): ApiTransportResponsePromise;
+}
+//#endregion
+//#region src/client/responses.d.ts
+/**
+ * A typed response returned by generated API clients.
+ *
+ * @example
+ * ```ts
+ * const response: ApiResponse<{ ok: true }> = await client.health.get()
+ * if (response.status === 200) {
+ *     response.body.ok
+ * }
+ * ```
+ *
+ * @typeParam T - The parsed response body type.
+ */
+interface ApiResponse<T> {
+  /** Whether the response status is in the successful 200-299 range. */
+  ok: boolean;
+  /** The response status code. */
+  status: number;
+  /** The response headers. */
+  headers: Headers;
+  /** The parsed response body. */
+  body: T;
+}
+type ApiResponseStatus<TStatus> = TStatus extends number ? TStatus : TStatus extends `${infer TNumber extends number}` ? TNumber : number;
+/**
+ * A typed response union keyed by HTTP status code.
+ *
+ * @example
+ * ```ts
+ * type WidgetResponse = ApiResponseByStatus<{
+ *     200: { id: number }
+ *     400: { message: string }
+ * }>
+ *
+ * if (response.status === 400) {
+ *     response.body.message
+ * }
+ * ```
+ *
+ * @typeParam T - A map from response status codes to parsed response body types.
+ */
+type ApiResponseByStatus<T extends object> = { [TStatus in keyof T]: Omit<ApiResponse<T[TStatus]>, 'status'> & {
+  /** The narrowed response status code. */status: ApiResponseStatus<TStatus>;
+} }[keyof T];
+/**
+ * The default async response wrapper used by generated API clients.
+ *
+ * @example
+ * ```ts
+ * const response: ApiResponsePromise<{ id: number }> = client.items.byId.get(123)
+ * ```
+ *
+ * @typeParam T - The parsed response body type.
+ */
+type ApiResponsePromise<T> = Promise<ApiResponse<T>>;
+/**
+ * The async response wrapper used by generated API clients for routes with response body types
+ * keyed by HTTP status code.
+ *
+ * @example
+ * ```ts
+ * const response: ApiResponseByStatusPromise<{ 200: { ok: true } }> = client.health.get()
+ * ```
+ *
+ * @typeParam T - A map from response status codes to parsed response body types.
+ */
+type ApiResponseByStatusPromise<T extends object> = Promise<ApiResponseByStatus<T>>;
+/**
+ * Extracts the successful `data` payload from a Routekit Problem-style success envelope.
+ *
+ * @example
+ * ```ts
+ * type Body = { success: true; data: { id: string } }
+ * type Data = RoutekitProblemSuccessData<Body> // { id: string }
+ * ```
+ *
+ * @typeParam TSuccessBody - Routekit Problem-style successful response body.
+ */
+type RoutekitProblemSuccessData<TSuccessBody> = TSuccessBody extends {
+  success: true;
+  data: infer Data;
+} ? Data : unknown;
+/**
+ * Error thrown for Routekit Problem-style response bodies.
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await resolveRoutekitProblemData(response)
+ * } catch (error) {
+ *     if (isRoutekitProblemError(error)) {
+ *         console.error(error.status, error.body.error.code)
+ *     }
+ * }
+ * ```
+ *
+ * @typeParam TProblem - Routekit Problem-style error response body.
+ */
+declare class RoutekitProblemError<TProblem> extends Error {
+  /**
+   * The response status code.
+   */
+  readonly status: number;
+  /**
+   * The response headers.
+   */
+  readonly headers: Headers;
+  /**
+   * The Routekit Problem-style response body.
+   */
+  readonly body: TProblem;
+  /**
+   * The full normalized API response.
+   */
+  readonly response: ApiResponse<TProblem>;
+  /**
+   * Create an error for a Routekit Problem-style response.
+   *
+   * @param response - Normalized API response containing a problem body.
+   */
+  constructor(response: ApiResponse<TProblem>);
+}
+/**
+ * Checks whether a value is a [`RoutekitProblemError`]{@link RoutekitProblemError}.
+ *
+ * @example
+ * ```ts
+ * if (isRoutekitProblemError(error)) {
+ *     error.body
+ * }
+ * ```
+ *
+ * @param value - Value to inspect.
+ * @returns Whether the value is a Routekit Problem error.
+ * @typeParam TProblem - Routekit Problem-style error response body.
+ */
+declare function isRoutekitProblemError<TProblem = unknown>(value: unknown): value is RoutekitProblemError<TProblem>;
+/**
+ * Normalize a transport response into the public generated API response shape.
+ *
+ * @example
+ * ```ts
+ * const response = await resolveApiResponse(transport.request(request))
+ * ```
+ *
+ * @param response - A transport response or transport response promise.
+ * @returns The normalized API response.
+ * @typeParam T - The parsed response body type.
+ */
+declare function resolveApiResponse<T>(response: ApiTransportResponse | ApiTransportResponsePromise): ApiResponsePromise<T>;
+/**
+ * Normalize a transport response into a generated API response union keyed by status code.
+ *
+ * @example
+ * ```ts
+ * const response = await resolveApiResponseByStatus<{ 200: { ok: true } }>(
+ *     transport.request(request),
+ * )
+ * ```
+ *
+ * @param response - A transport response or transport response promise.
+ * @returns The normalized API response.
+ * @typeParam T - A map from response status codes to parsed response body types.
+ */
+declare function resolveApiResponseByStatus<T extends object>(response: ApiTransportResponse | ApiTransportResponsePromise): ApiResponseByStatusPromise<T>;
+/**
+ * Resolve a Routekit Problem-style API response into its successful data payload.
+ *
+ * This helper unwraps `{ success: true, data }` bodies and throws
+ * [`RoutekitProblemError`]{@link RoutekitProblemError} for non-success problem bodies, which lets
+ * TanStack Query use its built-in success and error states while preserving rich problem details.
+ *
+ * @example
+ * ```ts
+ * const data = await resolveRoutekitProblemData<
+ *     { success: true; data: { id: string } },
+ *     { success: false; error: { code: 'not_found'; message: string } }
+ * >(transport.request(request))
+ * ```
+ *
+ * @param response - A transport response, normalized API response, or promise for either.
+ * @returns The unwrapped successful response `data` payload.
+ * @typeParam TSuccessBody - Routekit Problem-style successful response body.
+ * @typeParam TProblemBody - Routekit Problem-style problem response body.
+ */
+declare function resolveRoutekitProblemData<TSuccessBody, TProblemBody>(response: ApiResponse<TSuccessBody | TProblemBody> | ApiTransportResponse | ApiTransportResponsePromise | Promise<ApiResponse<TSuccessBody | TProblemBody>>): Promise<RoutekitProblemSuccessData<TSuccessBody>>;
+//#endregion
+//#region src/client/types.d.ts
+/**
+ * Extracts the type of a single path parameter from a path parameter object type.
+ *
+ * @example
+ * ```ts
+ * type Params = { id: string }
+ * type IdParam = SinglePathParam<Params, 'id'> // string
+ * ```
+ *
+ * @typeParam TParams - The path parameter object type.
+ * @typeParam TKey - The parameter key to extract.
+ */
+type SinglePathParam<TParams, TKey extends string> = TParams extends { [K in TKey]: infer V } ? V : unknown;
+//#endregion
+//#region src/client/transports/body-codec.d.ts
+type ClientBodyInit = NonNullable<RequestInit['body']>;
+/**
+ * The response body stream exposed to response body codecs.
+ *
+ * @example
+ * ```ts
+ * const text = await new Response(body).text()
+ * ```
+ */
+type ResponseBodyReader = ReadableStream<Uint8Array<ArrayBufferLike>> | null;
+/**
+ * Serializes request bodies and deserializes response bodies for generated clients.
+ *
+ * @example
+ * ```ts
+ * const textJsonCodec: BodyCodec = {
+ *     serialize: (value) => JSON.stringify(value),
+ *     deserialize: async (body) => JSON.parse(await new Response(body).text()),
+ * }
+ * ```
+ */
+interface BodyCodec {
+  /**
+   * Serialize a generated client body value into a Fetch-compatible body.
+   *
+   * @param value - The generated client body value.
+   * @returns A Fetch-compatible body, or nullish to omit the request body.
+   */
+  serialize(value: unknown): ClientBodyInit | null | undefined;
+  /**
+   * Deserialize a response body for generated `response.body` values.
+   *
+   * @param body - The response body stream.
+   * @param contentType - The response content type, when present.
+   * @returns The deserialized response body.
+   * @typeParam T - The expected response body type.
+   */
+  deserialize<T>(body: ResponseBodyReader, contentType: string | null): Promise<T>;
+}
+/**
+ * The default JSON codec used by generated API clients.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient(new FetchTransport({ bodyCodec: jsonBodyCodec }))
+ * ```
+ */
+declare const jsonBodyCodec: BodyCodec;
+//#endregion
+//#region src/client/transports/fetch.d.ts
+/**
+ * Options for [`FetchTransport`]{@link FetchTransport}.
+ *
+ * @example
+ * ```ts
+ * const transport = new FetchTransport({
+ *     baseUrl: 'https://api.example.com',
+ *     headers: () => ({ authorization: `Bearer ${token}` }),
+ * })
+ * ```
+ */
+interface FetchTransportOptions {
+  /** Base URL used to resolve generated relative route URLs. */
+  baseUrl?: string | URL;
+  /** Fetch implementation to call. Defaults to `globalThis.fetch`. */
+  fetch?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+  /** Global headers, or a function that returns headers for each request. */
+  headers?: ClientHeaders;
+  /** Default body codec. Defaults to [`jsonBodyCodec`]{@link jsonBodyCodec}. */
+  bodyCodec?: BodyCodec;
+}
+/**
+ * Fetch-based transport for generated API clients.
+ *
+ * @example
+ * ```ts
+ * const client = new ApiClient(
+ *     new FetchTransport({
+ *         baseUrl: 'https://api.example.com',
+ *         headers: { authorization: 'Bearer token' },
+ *     }),
+ * )
+ * ```
+ */
+declare class FetchTransport implements ClientTransport {
+  #private;
+  /**
+   * Create a Fetch-backed generated client transport.
+   *
+   * @param options - Transport configuration.
+   */
+  constructor(options?: FetchTransportOptions);
+  /**
+   * Execute a generated client request with Fetch.
+   *
+   * @param request - The generated client request.
+   * @returns A transport response promise.
+   */
+  request(request: ClientRequest): ApiTransportResponsePromise;
+}
+//#endregion
+//#region src/client/url.d.ts
+/**
+ * Append an object of query values to a URL.
+ *
+ * @example
+ * ```ts
+ * withQuery('/widgets', { view: 'full', tag: ['a', 'b'] })
+ * ```
+ *
+ * @param url - URL without generated query parameters.
+ * @param query - Query parameter object.
+ * @returns The URL with serialized query parameters.
+ */
+declare function withQuery(url: string, query: object): string;
+//#endregion
+export { ApiResponse, ApiResponseByStatus, ApiResponseByStatusPromise, ApiResponsePromise, ApiTransportResponse, ApiTransportResponsePromise, BodyCodec, ClientHeaderContext, ClientHeaders, ClientRequest, ClientTransport, FetchTransport, FetchTransportOptions, MaybePromise, ResponseBodyReader, RoutekitProblemError, RoutekitProblemSuccessData, SinglePathParam, isRoutekitProblemError, jsonBodyCodec, resolveApiResponse, resolveApiResponseByStatus, resolveRoutekitProblemData, withQuery };

package/dist/client.mjs

@@ -0,0 +1,264 @@
+//#region src/client/responses.ts
+/**
+* Error thrown for Routekit Problem-style response bodies.
+*
+* @example
+* ```ts
+* try {
+*     await resolveRoutekitProblemData(response)
+* } catch (error) {
+*     if (isRoutekitProblemError(error)) {
+*         console.error(error.status, error.body.error.code)
+*     }
+* }
+* ```
+*
+* @typeParam TProblem - Routekit Problem-style error response body.
+*/
+var RoutekitProblemError = class extends Error {
+	/**
+	* The response status code.
+	*/
+	status;
+	/**
+	* The response headers.
+	*/
+	headers;
+	/**
+	* The Routekit Problem-style response body.
+	*/
+	body;
+	/**
+	* The full normalized API response.
+	*/
+	response;
+	/**
+	* Create an error for a Routekit Problem-style response.
+	*
+	* @param response - Normalized API response containing a problem body.
+	*/
+	constructor(response) {
+		super(getRoutekitProblemMessage(response.body));
+		this.name = "RoutekitProblemError";
+		this.status = response.status;
+		this.headers = response.headers;
+		this.body = response.body;
+		this.response = response;
+	}
+};
+/**
+* Checks whether a value is a [`RoutekitProblemError`]{@link RoutekitProblemError}.
+*
+* @example
+* ```ts
+* if (isRoutekitProblemError(error)) {
+*     error.body
+* }
+* ```
+*
+* @param value - Value to inspect.
+* @returns Whether the value is a Routekit Problem error.
+* @typeParam TProblem - Routekit Problem-style error response body.
+*/
+function isRoutekitProblemError(value) {
+	return value instanceof RoutekitProblemError;
+}
+function getRoutekitProblemMessage(body) {
+	if (!body || typeof body !== "object") return "Routekit problem response";
+	const error = body.error;
+	return typeof error?.message === "string" ? error.message : "Routekit problem response";
+}
+function isRoutekitProblemSuccessBody(body) {
+	return !!body && typeof body === "object" && body.success === true && "data" in body;
+}
+function isApiResponse(response) {
+	return "ok" in response && typeof response.ok === "boolean" && response.headers instanceof Headers;
+}
+/**
+* Normalize a transport response into the public generated API response shape.
+*
+* @example
+* ```ts
+* const response = await resolveApiResponse(transport.request(request))
+* ```
+*
+* @param response - A transport response or transport response promise.
+* @returns The normalized API response.
+* @typeParam T - The parsed response body type.
+*/
+async function resolveApiResponse(response) {
+	const resolved = await response;
+	return {
+		ok: resolved.status >= 200 && resolved.status < 300,
+		status: resolved.status,
+		headers: new Headers(resolved.headers),
+		body: resolved.body
+	};
+}
+/**
+* Normalize a transport response into a generated API response union keyed by status code.
+*
+* @example
+* ```ts
+* const response = await resolveApiResponseByStatus<{ 200: { ok: true } }>(
+*     transport.request(request),
+* )
+* ```
+*
+* @param response - A transport response or transport response promise.
+* @returns The normalized API response.
+* @typeParam T - A map from response status codes to parsed response body types.
+*/
+function resolveApiResponseByStatus(response) {
+	return resolveApiResponse(response);
+}
+/**
+* Resolve a Routekit Problem-style API response into its successful data payload.
+*
+* This helper unwraps `{ success: true, data }` bodies and throws
+* [`RoutekitProblemError`]{@link RoutekitProblemError} for non-success problem bodies, which lets
+* TanStack Query use its built-in success and error states while preserving rich problem details.
+*
+* @example
+* ```ts
+* const data = await resolveRoutekitProblemData<
+*     { success: true; data: { id: string } },
+*     { success: false; error: { code: 'not_found'; message: string } }
+* >(transport.request(request))
+* ```
+*
+* @param response - A transport response, normalized API response, or promise for either.
+* @returns The unwrapped successful response `data` payload.
+* @typeParam TSuccessBody - Routekit Problem-style successful response body.
+* @typeParam TProblemBody - Routekit Problem-style problem response body.
+*/
+async function resolveRoutekitProblemData(response) {
+	const resolvedResponse = await response;
+	const apiResponse = isApiResponse(resolvedResponse) ? resolvedResponse : await resolveApiResponse(resolvedResponse);
+	if (apiResponse.ok && isRoutekitProblemSuccessBody(apiResponse.body)) return apiResponse.body.data;
+	throw new RoutekitProblemError(apiResponse);
+}
+//#endregion
+//#region src/client/transports/body-codec.ts
+/**
+* The default JSON codec used by generated API clients.
+*
+* @example
+* ```ts
+* const client = new ApiClient(new FetchTransport({ bodyCodec: jsonBodyCodec }))
+* ```
+*/
+const jsonBodyCodec = {
+	serialize: (value) => JSON.stringify(value),
+	deserialize: async (body, contentType) => {
+		if (!body) return void 0;
+		const text = await new Response(body).text();
+		if (text.length === 0) return void 0;
+		if (contentType?.includes("json")) return JSON.parse(text);
+		return text;
+	}
+};
+//#endregion
+//#region src/client/transports/fetch.ts
+function mergeHeaders(...sources) {
+	const headers = new Headers();
+	for (const source of sources) {
+		if (!source) continue;
+		new Headers(source).forEach((value, key) => {
+			headers.set(key, value);
+		});
+	}
+	return headers;
+}
+function resolveUrl(url, baseUrl) {
+	return baseUrl ? new URL(url, baseUrl).toString() : url;
+}
+/**
+* Fetch-based transport for generated API clients.
+*
+* @example
+* ```ts
+* const client = new ApiClient(
+*     new FetchTransport({
+*         baseUrl: 'https://api.example.com',
+*         headers: { authorization: 'Bearer token' },
+*     }),
+* )
+* ```
+*/
+var FetchTransport = class {
+	#baseUrl;
+	#bodyCodec;
+	#fetch;
+	#headers;
+	/**
+	* Create a Fetch-backed generated client transport.
+	*
+	* @param options - Transport configuration.
+	*/
+	constructor(options = {}) {
+		this.#baseUrl = options.baseUrl;
+		this.#bodyCodec = options.bodyCodec ?? jsonBodyCodec;
+		this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+		this.#headers = options.headers;
+	}
+	/**
+	* Execute a generated client request with Fetch.
+	*
+	* @param request - The generated client request.
+	* @returns A transport response promise.
+	*/
+	async request(request) {
+		const codec = this.#bodyCodec;
+		const init = { ...request.init };
+		const headerContext = {
+			url: request.url,
+			init
+		};
+		const headers = mergeHeaders(typeof this.#headers === "function" ? await this.#headers(headerContext) : this.#headers, init.headers);
+		if (Object.hasOwn(request, "body")) {
+			const body = codec.serialize(request.body);
+			if (body != null) {
+				init.body = body;
+				if (!headers.has("content-type")) headers.set("content-type", "application/json");
+			}
+		}
+		if ([...headers].length > 0) init.headers = headers;
+		else delete init.headers;
+		const response = await this.#fetch(resolveUrl(request.url, this.#baseUrl), init);
+		return {
+			status: response.status,
+			headers: response.headers,
+			body: await codec.deserialize(response.body, response.headers.get("content-type"))
+		};
+	}
+};
+//#endregion
+//#region src/client/url.ts
+/**
+* Append an object of query values to a URL.
+*
+* @example
+* ```ts
+* withQuery('/widgets', { view: 'full', tag: ['a', 'b'] })
+* ```
+*
+* @param url - URL without generated query parameters.
+* @param query - Query parameter object.
+* @returns The URL with serialized query parameters.
+*/
+function withQuery(url, query) {
+	const searchParams = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value == null) continue;
+		if (Array.isArray(value)) {
+			for (const item of value) if (item != null) searchParams.append(key, typeof item === "object" ? JSON.stringify(item) : String(item));
+			continue;
+		}
+		searchParams.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+	}
+	const search = searchParams.toString();
+	return search.length > 0 ? `${url}?${search}` : url;
+}
+//#endregion
+export { FetchTransport, RoutekitProblemError, isRoutekitProblemError, jsonBodyCodec, resolveApiResponse, resolveApiResponseByStatus, resolveRoutekitProblemData, withQuery };