@routar/core 0.1.0 → 1.1.0

package/dist/index.d.cts

@@ -1,10 +1,15 @@
-type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
 /** Options passed to {@link Executor.execute} on every HTTP call. */
 interface ExecuteOptions {
     method: HttpMethod;
     url: string;
     params?: Record<string, unknown>;
     body?: unknown;
+    /**
+     * Per-request headers injected by middleware (e.g. `defineMiddleware`).
+     * Headers cannot be set from `createApi` call sites directly — use middleware
+     * to add dynamic headers such as `Authorization` or `X-Request-Id`.
+     */
     headers?: Record<string, string>;
     signal?: AbortSignal;
 }
@@ -82,7 +87,7 @@ interface EndpointSpec<TRequest extends RequestShape = RequestShape, TResponse e
  * - With `adapter`: returns the adapter's output type.
  * - Without `adapter`: returns `ValidatorOutput<TResponse>`.
  */
-type InferResponse<TSpec extends EndpointSpec<any, any, any>> = TSpec['adapter'] extends (raw: any) => infer R ? R : ValidatorOutput<TSpec['response']>;
+type InferResponse<TSpec extends EndpointSpec<any, any, any>> = TSpec["adapter"] extends (raw: any) => infer R ? R : ValidatorOutput<TSpec["response"]>;
 /**
  * A single entry inside a {@link RouterEndpoints} map.
  * Either a leaf endpoint spec or a nested {@link RouterDef}.
@@ -97,53 +102,156 @@ interface RouterDef<TEndpoints extends RouterEndpoints = RouterEndpoints> {
 }
 /**
  * Extracts request/response types from a typed API client for use in query
- * hooks or mutation handlers.
+ * hooks or mutation handlers. Supports nested router clients recursively.
  *
  * @example
  * ```ts
  * export type TodoApiTypes = ApiTypes<typeof todoApi>;
  * type CreateRequest = TodoApiTypes['create']['request'];
  * type CreateResponse = TodoApiTypes['create']['response'];
+ *
+ * // Nested router: api.users.todos.getList
+ * type NestedTypes = ApiTypes<typeof api>;
+ * type ListReq = NestedTypes['users']['todos']['getList']['request'];
  * ```
  */
 type ApiTypes<TApi> = {
     [K in keyof TApi]: TApi[K] extends (...args: any[]) => Promise<infer R> ? {
         request: Parameters<TApi[K]>[0];
         response: R;
-    } : never;
+    } : TApi[K] extends object ? ApiTypes<TApi[K]> : never;
 };
+/**
+ * Options for {@link createApi}.
+ *
+ * @example
+ * ```ts
+ * // Disable all validation in production
+ * createApi(executor, router, { validate: process.env.NODE_ENV !== 'production' });
+ *
+ * // Keep request validation (catch call-site bugs), skip response in prod
+ * createApi(executor, router, { validate: { request: true, response: false } });
+ * ```
+ */
+interface CreateApiOptions {
+    /**
+     * Controls whether request and response schemas are run at call time.
+     *
+     * - `true` (default) — validate both request and response.
+     * - `false` — skip both; raw params and raw response pass through.
+     * - `{ request?, response? }` — enable/disable each independently.
+     */
+    validate?: boolean | {
+        request?: boolean;
+        response?: boolean;
+    };
+}
 
+/** Callable type for a single endpoint on the generated API client. */
+type EndpointFn<TSpec extends EndpointSpec<any, any, any>> = TSpec["request"] extends {
+    parse: (data: unknown) => infer R;
+} ? (params: R, signal?: AbortSignal) => Promise<InferResponse<TSpec>> : (params?: RequestShape, signal?: AbortSignal) => Promise<InferResponse<TSpec>>;
 /**
- * Groups a set of endpoint specs (and optional nested routers) under a shared
- * URL prefix.
+ * Fully-typed API client produced by {@link createApi}.
+ * Nested {@link RouterDef} entries become nested sub-client objects.
+ */
+type ApiClient<TEndpoints extends RouterEndpoints> = {
+    [K in keyof TEndpoints]: TEndpoints[K] extends RouterDef<infer TNestedEndpoints> ? ApiClient<TNestedEndpoints> : TEndpoints[K] extends EndpointSpec<any, any, any> ? EndpointFn<TEndpoints[K]> : never;
+};
+/**
+ * Builds a fully-typed API client from an {@link Executor} and a router
+ * (or bare endpoint map).
  *
- * The returned {@link RouterDef} can be passed directly to {@link createApi}
- * to produce a fully-typed API client. Nesting another {@link RouterDef} as a
- * value creates a sub-client whose prefix is the concatenation of both prefixes.
+ * Three call signatures are supported:
+ * - `createApi(executor, router)` — preferred; pass the result of {@link defineRouter}.
+ * - `createApi(executor, prefix, endpoints)` — inline router without {@link defineRouter}.
+ * - `createApi(executor, endpoints)` — no prefix; useful for flat endpoint maps.
  *
- * @param prefix - Base path prepended to every endpoint's `path` (e.g. `'/users'`).
- * @param endpoints - Record of named {@link EndpointSpec}s or nested {@link RouterDef}s.
+ * Each key in `endpoints` becomes a typed async function on the returned client.
+ * The function validates the request with `spec.request.parse` (if present),
+ * resolves path parameters, calls the executor, validates the response with
+ * `spec.response.parse`, and applies `spec.adapter` (if present).
+ *
+ * @param executor - Transport to use for every HTTP call.
+ * @param router - A {@link RouterDef} produced by {@link defineRouter}.
+ * @param options - Optional settings (e.g. `validate` to skip schema parsing in production).
  *
  * @example
  * ```ts
- * // Flat router
- * export const todoRouter = defineRouter('/todos', {
- *   getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),
- *   getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),
- *   create:    endpoint({ method: 'POST', path: '/',    response: TodoSchema }),
- * });
+ * const todoApi = createApi(executor, todoRouter);
+ * const todos = await todoApi.getList({});
+ * const todo  = await todoApi.getDetail({ path: { id: 1 } });
  *
- * // Nested router — api.users.todos.getList() resolves to GET /users/todos/
- * export const userRouter = defineRouter('/users', {
- *   getList: endpoint({ method: 'GET', path: '/', response: UserListSchema }),
- *   todos: defineRouter('/todos', {
- *     getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),
- *     getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),
- *   }),
+ * // Skip response validation in production
+ * const prodApi = createApi(executor, todoRouter, {
+ *   validate: { request: true, response: process.env.NODE_ENV !== 'production' },
  * });
  * ```
  */
-declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, router: RouterDef<TEndpoints>, options?: CreateApiOptions): ApiClient<TEndpoints>;
+/**
+ * @param executor - Transport to use for every HTTP call.
+ * @param prefix - URL prefix prepended to every endpoint path.
+ * @param endpoints - Record of named endpoint specs.
+ * @param options - Optional settings.
+ */
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, prefix: string, endpoints: TEndpoints, options?: CreateApiOptions): ApiClient<TEndpoints>;
+/**
+ * @param executor - Transport to use for every HTTP call.
+ * @param endpoints - Record of named endpoint specs (no URL prefix).
+ * @param options - Optional settings.
+ */
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, endpoints: TEndpoints, options?: CreateApiOptions): ApiClient<TEndpoints>;
+
+/**
+ * Creates an {@link Executor} by wrapping a transport function with an
+ * optional middleware chain.
+ *
+ * Middlewares are applied in declaration order — the first middleware is the
+ * outermost wrapper and runs first on each request.
+ *
+ * @param execute - The underlying transport function (fetch, axios, etc.).
+ * @param middlewares - Ordered list of middlewares to apply.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor(
+ *   async ({ method, url, body }) => {
+ *     const res = await fetch(url, { method, body: JSON.stringify(body) });
+ *     return res.json();
+ *   },
+ *   [withTimeout(5000), withRetry(3), withLogger()],
+ * );
+ * ```
+ */
+declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, middlewares?: ExecutorMiddleware[]): Executor;
+/**
+ * Creates an {@link Executor} that selects the underlying transport at
+ * request time based on the result of `resolver`.
+ *
+ * Use this to unify SSR and CSR behind a single API client — the resolver
+ * picks the right executor per request, so `createApi` is called once and
+ * works in both environments without duplicate `*ServerApi` instances.
+ *
+ * The resolver receives the full {@link ExecuteOptions} so it can branch on
+ * environment, URL prefix, auth context, or any runtime condition.
+ *
+ * @param resolver - Called on every request; returns the executor to delegate to.
+ *
+ * @example
+ * ```ts
+ * // SSR vs CSR — pick transport based on environment
+ * const apiExecutor = dispatchExecutor(() =>
+ *   typeof window === 'undefined' ? serverExecutor : clientExecutor,
+ * );
+ *
+ * // Route by URL prefix — internal routes use a different transport
+ * const apiExecutor = dispatchExecutor((opts) =>
+ *   opts.url.startsWith('/internal') ? internalExecutor : publicExecutor,
+ * );
+ * ```
+ */
+declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor): Executor;
 
 /**
  * Extracts `:param` segment names from a path template string as a union of
@@ -159,9 +267,7 @@ type PathParams<TPath extends string> = TPath extends `${string}:${infer Param}/
  * When `TPath` contains dynamic segments (`:param`), requires `request.path`
  * to include all extracted param names. No constraint for static paths.
  */
-type PathConstraint<TPath extends string> = [
-    PathParams<TPath>
-] extends [never] ? {} : {
+type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never] ? {} : {
     path: Record<PathParams<TPath>, unknown>;
 };
 /**
@@ -242,77 +348,16 @@ declare function endpoint<TResponse extends Validator<unknown>>(spec: {
     response: TResponse;
 };
 
-/** Callable type for a single endpoint on the generated API client. */
-type EndpointFn<TSpec extends EndpointSpec<any, any, any>> = (params: TSpec['request'] extends {
-    parse: (data: unknown) => infer R;
-} ? R : RequestShape, signal?: AbortSignal) => Promise<InferResponse<TSpec>>;
-/**
- * Fully-typed API client produced by {@link createApi}.
- * Nested {@link RouterDef} entries become nested sub-client objects.
- */
-type ApiClient<TEndpoints extends RouterEndpoints> = {
-    [K in keyof TEndpoints]: TEndpoints[K] extends RouterDef<infer TNestedEndpoints> ? ApiClient<TNestedEndpoints> : TEndpoints[K] extends EndpointSpec<any, any, any> ? EndpointFn<TEndpoints[K]> : never;
-};
-/**
- * Builds a fully-typed API client from an {@link Executor} and a router
- * (or bare endpoint map).
- *
- * Three call signatures are supported:
- * - `createApi(executor, router)` — preferred; pass the result of {@link defineRouter}.
- * - `createApi(executor, prefix, endpoints)` — inline router without {@link defineRouter}.
- * - `createApi(executor, endpoints)` — no prefix; useful for flat endpoint maps.
- *
- * Each key in `endpoints` becomes a typed async function on the returned client.
- * The function validates the request with `spec.request.parse` (if present),
- * resolves path parameters, calls the executor, validates the response with
- * `spec.response.parse`, and applies `spec.adapter` (if present).
- *
- * @param executor - Transport to use for every HTTP call.
- * @param router - A {@link RouterDef} produced by {@link defineRouter}.
- *
- * @example
- * ```ts
- * const todoApi = createApi(executor, todoRouter);
- * const todos = await todoApi.getList({});
- * const todo  = await todoApi.getDetail({ path: { id: 1 } });
- * ```
- */
-declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, router: RouterDef<TEndpoints>): ApiClient<TEndpoints>;
-/**
- * @param executor - Transport to use for every HTTP call.
- * @param prefix - URL prefix prepended to every endpoint path.
- * @param endpoints - Record of named endpoint specs.
- */
-declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, prefix: string, endpoints: TEndpoints): ApiClient<TEndpoints>;
-/**
- * @param executor - Transport to use for every HTTP call.
- * @param endpoints - Record of named endpoint specs (no URL prefix).
- */
-declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, endpoints: TEndpoints): ApiClient<TEndpoints>;
+declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
 
 /**
- * Creates an {@link Executor} by wrapping a transport function with an
- * optional middleware chain.
- *
- * Middlewares are applied in declaration order — the first middleware is the
- * outermost wrapper and runs first on each request.
- *
- * @param execute - The underlying transport function (fetch, axios, etc.).
- * @param middlewares - Ordered list of middlewares to apply.
- *
- * @example
- * ```ts
- * const executor = createExecutor(
- *   async ({ method, url, body }) => {
- *     const res = await fetch(url, { method, body: JSON.stringify(body) });
- *     return res.json();
- *   },
- *   [withTimeout(5000), withRetry(3), withLogger()],
- * );
- * ```
+ * Thrown by {@link withTimeout} when a request exceeds the configured duration.
+ * Distinguishable from a user-initiated {@link AbortSignal} cancellation.
  */
-declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, middlewares?: ExecutorMiddleware[]): Executor;
-
+declare class TimeoutError extends Error {
+    readonly ms: number;
+    constructor(ms: number);
+}
 /**
  * Identity helper that returns the middleware as-is.
  *
@@ -335,6 +380,8 @@ declare function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware;
  *
  * @param count - Number of retries (not counting the initial attempt).
  * @param options.shouldRetry - Return `false` to stop retrying early.
+ *   Receives the error and a zero-based `attempt` index (0 = first failure,
+ *   1 = second failure, …) so you can limit retries by count or error type.
  *
  * @example
  * ```ts
@@ -369,14 +416,21 @@ declare function withLogger(options?: {
     log?: (message: string, data?: unknown) => void;
 }): ExecutorMiddleware;
 
+declare function serializeParams(params: Record<string, unknown>): URLSearchParams;
+
+/**
+ * Joins URL path segments, normalising repeated slashes and trailing slashes.
+ *
+ * **Note:** Intended for relative API paths only. Absolute URLs containing
+ * `://` will be collapsed (`https://` → `https:/`). Pass absolute URLs
+ * directly to the executor instead of through this helper.
+ */
 declare function joinPaths(...segments: string[]): string;
 declare function resolvePath(pathTemplate: string, params?: Record<string, unknown>): string;
 
-declare function serializeParams(params: Record<string, unknown>): URLSearchParams;
-
 declare class ValidationError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 
-export { type ApiTypes, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorMiddleware, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, defineMiddleware, defineRouter, endpoint, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };
+export { type ApiTypes, type CreateApiOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorMiddleware, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, defineMiddleware, defineRouter, dispatchExecutor, endpoint, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };