@routar/core 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -6,7 +6,7 @@ interface ExecuteOptions {
     params?: Record<string, unknown>;
     body?: unknown;
     /**
-     * Per-request headers injected by middleware (e.g. `defineMiddleware`).
+     * Per-request headers injected by a plugin's `onRequest` hook.
      * Headers cannot be set from `createApi` call sites directly — use middleware
      * to add dynamic headers such as `Authorization` or `X-Request-Id`.
      */
@@ -22,21 +22,51 @@ interface Executor {
     execute(options: ExecuteOptions): Promise<unknown>;
 }
 /**
- * Middleware function for an {@link Executor}.
+ * A named, composable unit of executor behavior.
  *
- * Receives the current {@link ExecuteOptions} and a `next` function to call
- * the next middleware (or the underlying transport). Must return the response
- * promise.
+ * Each lifecycle hook is optional — implement only what you need.
+ * Related concerns (e.g. auth header injection + 401 refresh) can be
+ * bundled into a single plugin.
  *
- * @example
+ * @example Auth plugin
  * ```ts
- * const myMiddleware: ExecutorMiddleware = async (opts, next) => {
- *   console.log(opts.method, opts.url);
- *   return next(opts);
+ * const authPlugin: ExecutorPlugin = {
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
+ *   onError: async (err) => {
+ *     if (isUnauthorized(err)) await refreshToken();
+ *     throw err;
+ *   },
  * };
  * ```
  */
-type ExecutorMiddleware = (options: ExecuteOptions, next: (options: ExecuteOptions) => Promise<unknown>) => Promise<unknown>;
+interface ExecutorPlugin {
+    /** Optional name — used for introspection and `eject`. */
+    name?: string;
+    /** Runs before the request is sent. Return modified opts to transform the request. */
+    onRequest?: (opts: ExecuteOptions) => ExecuteOptions | Promise<ExecuteOptions>;
+    /** Runs after a successful response. Return a modified value to transform the response. */
+    onResponse?: (response: unknown, opts: ExecuteOptions) => unknown | Promise<unknown>;
+    /** Runs when the request throws. Must re-throw (or throw a different error). */
+    onError?: (error: unknown, opts: ExecuteOptions) => never | Promise<never>;
+}
+/**
+ * Options for {@link createExecutor}.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
+ * ```
+ */
+interface CreateExecutorOptions {
+    /** Plugins applied in declaration order (first plugin is outermost). */
+    plugins?: ExecutorPlugin[];
+}
 /**
  * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
  *
@@ -176,13 +206,38 @@ type ApiClient<TEndpoints extends RouterEndpoints> = {
  * @param router - A {@link RouterDef} produced by {@link defineRouter}.
  * @param options - Optional settings (e.g. `validate` to skip schema parsing in production).
  *
- * @example
+ * @example Basic usage
  * ```ts
  * const todoApi = createApi(executor, todoRouter);
  * const todos = await todoApi.getList({});
  * const todo  = await todoApi.getDetail({ path: { id: 1 } });
+ * const next  = await todoApi.create({ body: { title: 'buy milk' } });
+ * ```
+ *
+ * @example Nested router — access via dot notation
+ * ```ts
+ * const api = createApi(executor, apiRouter); // apiRouter has users → todos nesting
+ * await api.users.getList({});
+ * await api.users.todos.getList({});
+ * ```
+ *
+ * @example Cancel in-flight requests with AbortSignal
+ * ```ts
+ * const controller = new AbortController();
+ * const todos = await todoApi.getList({}, controller.signal);
+ * controller.abort();
+ * ```
+ *
+ * @example Extract types from the client — no duplication
+ * ```ts
+ * import type { ApiTypes } from '@routar/core';
+ * type TodoApiTypes  = ApiTypes<typeof todoApi>;
+ * type Todo          = TodoApiTypes['getDetail']['response'];
+ * type CreateRequest = TodoApiTypes['create']['request'];
+ * ```
  *
- * // Skip response validation in production
+ * @example Skip response validation in production
+ * ```ts
  * const prodApi = createApi(executor, todoRouter, {
  *   validate: { request: true, response: process.env.NODE_ENV !== 'production' },
  * });
@@ -204,55 +259,43 @@ declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executo
 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.
+ * Creates an {@link Executor} by wrapping a transport function with plugins.
  *
- * Middlewares are applied in declaration order — the first middleware is the
- * outermost wrapper and runs first on each request.
+ * Plugins run in declaration order (first plugin is outermost).
  *
- * @param execute - The underlying transport function (fetch, axios, etc.).
- * @param middlewares - Ordered list of middlewares to apply.
+ * For `retry` and `timeout`, use the options on {@link createFetchExecutor}
+ * or configure them via the underlying HTTP client (axios, ky).
  *
  * @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()],
- * );
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
  * ```
  */
-declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, middlewares?: ExecutorMiddleware[]): Executor;
+declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, options?: CreateExecutorOptions): 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;
 
+type FetchRetryOption = number | {
+    count: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+interface FetchExecutorOptions extends CreateExecutorOptions {
+    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    retry?: FetchRetryOption;
+    timeout?: number;
+}
 /**
  * Creates an {@link Executor} backed by the browser / Node.js `fetch` API.
  *
@@ -268,9 +311,20 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * @param baseURL - Absolute base URL prepended to every endpoint path.
  * @param options.defaultHeaders - Async factory called on every request to
  *   produce headers (e.g. reading cookies in a Next.js server component).
- * @param options.middlewares - Middleware chain applied before the fetch call.
+ * @param options.plugins - Plugins applied around the fetch call. Each retry
+ *   attempt re-runs `onRequest` hooks (so headers are refreshed per attempt)
+ *   and `onError` hooks. Token-refresh-on-401 patterns work by updating an
+ *   external token store in `onError` and letting `onRequest` pick it up on
+ *   the next attempt.
+ * @param options.retry - Number of retries, or `{ count, shouldRetry? }`.
+ * @param options.timeout - Per-attempt timeout in milliseconds.
+ *
+ * @example Minimal — no options needed
+ * ```ts
+ * const executor = createFetchExecutor('https://api.example.com');
+ * ```
  *
- * @example
+ * @example SSR with bearer token
  * ```ts
  * const executor = createFetchExecutor('https://api.example.com', {
  *   defaultHeaders: async () => {
@@ -279,11 +333,16 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  *   },
  * });
  * ```
+ *
+ * @example With retry and timeout
+ * ```ts
+ * const executor = createFetchExecutor('https://api.example.com', {
+ *   retry: 2,
+ *   timeout: 8_000,
+ * });
+ * ```
  */
-declare function createFetchExecutor(baseURL: string, options?: {
-    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    middlewares?: ExecutorMiddleware[];
-}): Executor;
+declare function createFetchExecutor(baseURL: string, options?: FetchExecutorOptions): Executor;
 /**
  * Thrown by {@link createFetchExecutor} when the server returns a non-2xx
  * status code.
@@ -300,19 +359,10 @@ declare function createFetchExecutor(baseURL: string, options?: {
  * ```
  */
 declare class HttpError extends Error {
-    /** HTTP status code (e.g. 404, 500). */
     readonly status: number;
-    /** HTTP status text (e.g. "Not Found"). */
     readonly statusText: string;
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
     readonly body: unknown;
-    constructor(
-    /** HTTP status code (e.g. 404, 500). */
-    status: number, 
-    /** HTTP status text (e.g. "Not Found"). */
-    statusText: string, 
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
-    body?: unknown);
+    constructor(status: number, statusText: string, body?: unknown);
 }
 
 /**
@@ -345,7 +395,43 @@ type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never]
  * that `request` includes a matching `path` field with those param names.
  * A mismatch or missing key is a compile-time error.
  *
- * @example
+ * @example Basic GET with no params
+ * ```ts
+ * const getList = endpoint({ method: 'GET', path: '/', response: z.array(TodoSchema) });
+ * ```
+ *
+ * @example GET with query params
+ * ```ts
+ * const search = endpoint({
+ *   method: 'GET',
+ *   path: '/search',
+ *   request: z.object({ query: z.object({ q: z.string(), limit: z.number().optional() }) }),
+ *   response: z.array(TodoSchema),
+ * });
+ * ```
+ *
+ * @example POST with body
+ * ```ts
+ * const create = endpoint({
+ *   method: 'POST',
+ *   path: '/',
+ *   request: z.object({ body: z.object({ title: z.string() }) }),
+ *   response: TodoSchema,
+ * });
+ * ```
+ *
+ * @example Adapter — raw is inferred from the response schema, no cast needed
+ * ```ts
+ * const getDetail = endpoint({
+ *   method: 'GET',
+ *   path: '/:id',
+ *   request: z.object({ path: z.object({ id: z.number() }) }),
+ *   response: TodoRawSchema,
+ *   adapter: (raw) => ({ ...raw, label: `#${raw.id} ${raw.title}` }),
+ * });
+ * ```
+ *
+ * @example Path param enforcement
  * ```ts
  * // ✅ path has ':id' → request.path.id is required
  * const getDetail = endpoint({
@@ -353,7 +439,6 @@ type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never]
  *   path: '/:id',
  *   request: z.object({ path: z.object({ id: z.number() }) }),
  *   response: TodoSchema,
- *   adapter: toTodoItem,
  * });
  *
  * // ❌ compile error — 'id' is missing from request.path
@@ -445,57 +530,29 @@ declare function isRouterDef(entry: object): entry is RouterDef<RouterEndpoints>
 declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
 
 /**
- * Thrown by {@link withTimeout} when a request exceeds the configured duration.
- * Distinguishable from a user-initiated {@link AbortSignal} cancellation.
+ * Thrown by the built-in `timeout` option when a request exceeds the
+ * configured duration. Distinguishable from a user-initiated
+ * {@link AbortSignal} cancellation.
  */
 declare class TimeoutError extends Error {
     readonly ms: number;
     constructor(ms: number);
 }
 /**
- * Identity helper that returns the middleware as-is.
- *
- * Wrap your middleware function with this to get full type inference on `opts`
- * and `next` without having to annotate the type manually.
+ * Identity helper that returns the plugin as-is, providing full type inference.
  *
  * @example
  * ```ts
- * const withCorrelationId = defineMiddleware((opts, next) =>
- *   next({ ...opts, headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() } })
- * );
- * ```
- */
-declare function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware;
-/**
- * Retries a failed request up to `count` additional times.
- *
- * By default all errors trigger a retry. Pass `shouldRetry` to skip retries
- * for non-transient errors (e.g. 4xx responses).
- *
- * @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
- * withRetry(3, {
- *   shouldRetry: (err) => err instanceof HttpError && err.status >= 500,
- * })
+ * const authPlugin = definePlugin({
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
+ * });
  * ```
  */
-declare function withRetry(count: number, options?: {
-    shouldRetry?: (error: unknown, attempt: number) => boolean;
-}): ExecutorMiddleware;
-/**
- * Aborts a request if it does not complete within `ms` milliseconds.
- *
- * Merges the timeout signal with any existing `AbortSignal` on the request,
- * so whichever fires first wins.
- *
- * @param ms - Timeout in milliseconds.
- */
-declare function withTimeout(ms: number): ExecutorMiddleware;
+declare function definePlugin(plugin: ExecutorPlugin): ExecutorPlugin;
 /**
  * Logs each request and its outcome (success duration or error).
  *
@@ -503,12 +560,14 @@ declare function withTimeout(ms: number): ExecutorMiddleware;
  *
  * @example
  * ```ts
- * withLogger({ log: (msg, data) => logger.debug(msg, data) })
+ * createExecutor(transport, {
+ *   plugins: [logger({ log: (msg, data) => myLogger.debug(msg, data) })],
+ * })
  * ```
  */
-declare function withLogger(options?: {
+declare function logger(options?: {
     log?: (message: string, data?: unknown) => void;
-}): ExecutorMiddleware;
+}): ExecutorPlugin;
 
 declare function serializeParams(params: Record<string, unknown>): URLSearchParams;
 
@@ -527,4 +586,4 @@ declare class ValidationError extends Error {
     constructor(message: string, cause?: unknown);
 }
 
-export { type ApiTypes, type CreateApiOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorMiddleware, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, defineMiddleware, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };
+export { type ApiTypes, type CreateApiOptions, type CreateExecutorOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorPlugin, type FetchExecutorOptions, type FetchRetryOption, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, definePlugin, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, logger, resolvePath, serializeParams };