@routar/core 1.2.1 → 1.4.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.
  *
@@ -116,7 +146,7 @@ interface RouterDef<TEndpoints extends RouterEndpoints = RouterEndpoints> {
  * ```
  */
 type ApiTypes<TApi> = {
-    [K in keyof TApi]: TApi[K] extends (...args: any[]) => Promise<infer R> ? {
+    [K in keyof TApi as K extends "$router" ? never : K]: TApi[K] extends (...args: any[]) => Promise<infer R> ? {
         request: Parameters<TApi[K]>[0];
         response: R;
     } : TApi[K] extends object ? ApiTypes<TApi[K]> : never;
@@ -158,6 +188,17 @@ type EndpointFn<TSpec extends EndpointSpec<any, any, any>> = TSpec["request"] ex
 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;
 };
+/**
+ * An {@link ApiClient} that also carries its source {@link RouterDef} on the
+ * `$router` property. This is the actual return type of {@link createApi};
+ * downstream tools (e.g. `@routar/react-query`) recover the router (prefix +
+ * endpoint methods) from it without it being re-passed. `$router` is
+ * non-enumerable and excluded from {@link ApiTypes}; the `$` prefix keeps it
+ * from colliding with endpoint names.
+ */
+type ApiClientWithRouter<TEndpoints extends RouterEndpoints> = ApiClient<TEndpoints> & {
+    readonly $router: RouterDef<TEndpoints>;
+};
 /**
  * Builds a fully-typed API client from an {@link Executor} and a router
  * (or bare endpoint map).
@@ -213,71 +254,59 @@ type ApiClient<TEndpoints extends RouterEndpoints> = {
  * });
  * ```
  */
-declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, router: RouterDef<TEndpoints>, options?: CreateApiOptions): ApiClient<TEndpoints>;
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, router: RouterDef<TEndpoints>, options?: CreateApiOptions): ApiClientWithRouter<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>;
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, prefix: string, endpoints: TEndpoints, options?: CreateApiOptions): ApiClientWithRouter<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>;
+declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, endpoints: TEndpoints, options?: CreateApiOptions): ApiClientWithRouter<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.
  *
@@ -293,7 +322,13 @@ 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
@@ -310,22 +345,15 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * });
  * ```
  *
- * @example Next.js App Router — forward cookies from the incoming request
+ * @example With retry and timeout
  * ```ts
  * const executor = createFetchExecutor('https://api.example.com', {
- *   defaultHeaders: async () => {
- *     const { cookies } = await import('next/headers');
- *     const token = (await cookies()).get('access_token')?.value;
- *     return token ? { Authorization: `Bearer ${token}` } : {};
- *   },
- *   middlewares: [withTimeout(8_000), withRetry(2)],
+ *   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.
@@ -342,19 +370,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);
 }
 
 /**
@@ -387,6 +406,10 @@ 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.
  *
+ * The literal HTTP method (`'GET'`, `'POST'`, …) is preserved on the return
+ * type — `endpoint({ method: 'GET', ... }).method` is typed `'GET'`, not the
+ * `HttpMethod` union.
+ *
  * @example Basic GET with no params
  * ```ts
  * const getList = endpoint({ method: 'GET', path: '/', response: z.array(TodoSchema) });
@@ -442,47 +465,47 @@ type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never]
  * });
  * ```
  */
-declare function endpoint<TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>, TOut>(spec: {
-    method: HttpMethod;
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>, TOut>(spec: {
+    method: TMethod;
     path: TPath;
     request: Validator<TRequest>;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 }): {
-    method: HttpMethod;
+    method: TMethod;
     path: string;
     request: Validator<TRequest>;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 };
-declare function endpoint<TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>>(spec: {
-    method: HttpMethod;
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>>(spec: {
+    method: TMethod;
     path: TPath;
     request: Validator<TRequest>;
     response: TResponse;
 }): {
-    method: HttpMethod;
+    method: TMethod;
     path: string;
     request: Validator<TRequest>;
     response: TResponse;
 };
-declare function endpoint<TResponse extends Validator<unknown>, TOut>(spec: {
-    method: HttpMethod;
+declare function endpoint<TMethod extends HttpMethod, TResponse extends Validator<unknown>, TOut>(spec: {
+    method: TMethod;
     path: string;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 }): {
-    method: HttpMethod;
+    method: TMethod;
     path: string;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 };
-declare function endpoint<TResponse extends Validator<unknown>>(spec: {
-    method: HttpMethod;
+declare function endpoint<TMethod extends HttpMethod, TResponse extends Validator<unknown>>(spec: {
+    method: TMethod;
     path: string;
     response: TResponse;
 }): {
-    method: HttpMethod;
+    method: TMethod;
     path: string;
     response: TResponse;
 };
@@ -522,71 +545,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.
- *
- * @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,
- * })
- * ```
- */
-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.
+ * Identity helper that returns the plugin as-is, providing full type inference.
  *
  * @example
  * ```ts
- * const executor = createFetchExecutor('https://api.example.com', {
- *   middlewares: [withTimeout(5_000)],
+ * const authPlugin = definePlugin({
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
  * });
- *
- * // Combine with retry — timeout applies per attempt
- * const executor = createExecutor(transport, [
- *   withTimeout(5_000),
- *   withRetry(3, { shouldRetry: (err) => !(err instanceof HttpError && err.status < 500) }),
- *   withLogger(),
- * ]);
  * ```
  */
-declare function withTimeout(ms: number): ExecutorMiddleware;
+declare function definePlugin(plugin: ExecutorPlugin): ExecutorPlugin;
 /**
  * Logs each request and its outcome (success duration or error).
  *
@@ -594,12 +575,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;
 
@@ -618,4 +601,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 ApiClient, type ApiClientWithRouter, 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 };