@routar/core 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -1,3 +1,83 @@
+/**
+ * The Standard Schema interface (v1), vendored to keep `@routar/core`
+ * dependency-free. Standard Schema is the common validation interface adopted
+ * by Zod 3.24+, Valibot, ArkType, and others — exposed via the `~standard`
+ * property. The spec is type-only (no runtime), and the authors explicitly
+ * permit copying the interface rather than depending on `@standard-schema/spec`.
+ *
+ * @see https://standardschema.dev
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+
+declare class ValidationError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown internally when a Standard Schema validator (`~standard.validate`)
+ * reports issues. It is wrapped as the `cause` of a {@link ValidationError} by
+ * the API client, mirroring how a thrown `.parse()` error becomes the cause —
+ * so callers branch on `ValidationError` regardless of the validator library.
+ * The structured `issues` array is preserved for drift reporting.
+ */
+declare class StandardSchemaError extends Error {
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+
 type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
 /** Options passed to {@link Executor.execute} on every HTTP call. */
 interface ExecuteOptions {
@@ -13,6 +93,39 @@ interface ExecuteOptions {
     headers?: Record<string, string>;
     signal?: AbortSignal;
 }
+/**
+ * Per-call transport options, passed as the optional second argument to any
+ * generated endpoint function: `api.create(params, { signal, headers, timeout })`.
+ *
+ * Passing a bare {@link AbortSignal} as the second argument is still supported
+ * (backward compatible) — it is treated as `{ signal }`.
+ *
+ * @example
+ * ```ts
+ * await api.create({ body }, {
+ *   signal: controller.signal,
+ *   headers: { 'Idempotency-Key': key },
+ *   timeout: 30_000,
+ * });
+ * ```
+ */
+interface EndpointCallOptions {
+    /** Aborts the request when the signal fires. */
+    signal?: AbortSignal;
+    /**
+     * Per-call headers. Seeded onto the request before plugin `onRequest` hooks
+     * run, and merged over the executor's default headers — so per-call headers
+     * win over defaults. A plugin that sets the same header key still wins on
+     * collision (plugins are cross-cutting policy such as auth).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Per-call timeout in milliseconds. Aborts the request with a `TimeoutError`
+     * when exceeded. Applied by the core client (transport-agnostic) and composes
+     * with any executor-level timeout (whichever fires first wins).
+     */
+    timeout?: number;
+}
 /**
  * Transport abstraction. Implement this to support any HTTP client.
  *
@@ -50,7 +163,17 @@ interface ExecutorPlugin {
     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). */
+    /**
+     * Runs when the request throws.
+     *
+     * The return value is ignored — this hook MUST always throw. To transform
+     * the error, throw a new error from within the hook (the original error is
+     * not automatically re-thrown for you).
+     *
+     * Transport errors reaching this hook are normalized to `HttpError` across
+     * all executors (fetch, Axios, ky), so you can branch on `instanceof
+     * HttpError` without depending on the underlying client.
+     */
     onError?: (error: unknown, opts: ExecuteOptions) => never | Promise<never>;
 }
 /**
@@ -66,6 +189,21 @@ interface ExecutorPlugin {
 interface CreateExecutorOptions {
     /** Plugins applied in declaration order (first plugin is outermost). */
     plugins?: ExecutorPlugin[];
+    /**
+     * Transforms the raw response immediately after the transport returns,
+     * before any plugin `onResponse` hooks and before schema validation in
+     * `createApi`. Use to unwrap envelope shapes like `{ data: T }`.
+     *
+     * Equivalent to an innermost `onResponse` plugin, but declarative.
+     *
+     * @example
+     * ```ts
+     * const executor = createExecutor(transport, {
+     *   unwrap: (raw) => (raw as { data: unknown })?.data ?? raw,
+     * });
+     * ```
+     */
+    unwrap?: (raw: unknown) => unknown;
 }
 /**
  * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
@@ -75,8 +213,24 @@ interface CreateExecutorOptions {
 interface Validator<TOutput> {
     parse(data: unknown): TOutput;
 }
-/** Extracts the output type of a {@link Validator}. */
-type ValidatorOutput<T extends Validator<unknown>> = T extends Validator<infer O> ? O : never;
+/**
+ * A validator accepted by routar: either the `.parse()` duck-typed
+ * {@link Validator} (Zod, Valibot, Yup, or any object with `.parse()`) **or** a
+ * [Standard Schema](https://standardschema.dev) (`~standard` — Zod 3.24+,
+ * Valibot, ArkType, …). Both forms are validated at runtime; the `.parse()` path
+ * is preferred when present (synchronous), otherwise `~standard.validate` is
+ * used (sync or async).
+ *
+ * @template TOutput Parsed/validated output type.
+ */
+type AnyValidator<TOutput = unknown> = Validator<TOutput> | StandardSchemaV1<unknown, TOutput>;
+/**
+ * Extracts the output type of an {@link AnyValidator} — the `.parse()` return
+ * type for a {@link Validator}, or the Standard Schema output type. The
+ * `Validator` branch is checked first so a schema satisfying both (e.g. Zod)
+ * resolves through its `.parse()` signature.
+ */
+type ValidatorOutput<T> = T extends Validator<infer O> ? O : T extends StandardSchemaV1<unknown, infer O> ? O : never;
 /**
  * Shape of an endpoint's request parameters.
  *
@@ -98,11 +252,11 @@ interface RequestShape {
  * @template TResponse Validator for the raw response.
  * @template TAdapter  Optional adapter function type.
  */
-interface EndpointSpec<TRequest extends RequestShape = RequestShape, TResponse extends Validator<unknown> = Validator<unknown>, TAdapter extends ((raw: ValidatorOutput<TResponse>) => unknown) | undefined = undefined> {
+interface EndpointSpec<TRequest extends RequestShape = RequestShape, TResponse extends AnyValidator = AnyValidator, TAdapter extends ((raw: ValidatorOutput<TResponse>) => unknown) | undefined = undefined> {
     method: HttpMethod;
     path: string;
     /** Validates and narrows request parameters before the HTTP call. */
-    request?: Validator<TRequest>;
+    request?: AnyValidator<TRequest>;
     /** Validates the raw server response. */
     response: TResponse;
     /**
@@ -151,6 +305,31 @@ type ApiTypes<TApi> = {
         response: R;
     } : TApi[K] extends object ? ApiTypes<TApi[K]> : never;
 };
+/**
+ * Per-kind validation mode.
+ *
+ * - `true` (default) — validate and throw {@link ValidationError} on failure.
+ * - `false` — skip validation; raw data passes through untouched.
+ * - `'warn'` — attempt validation but, on failure, pass the raw data through
+ *   and report the error via {@link CreateApiOptions.onValidationError} instead
+ *   of throwing. The drift-observation mode: surface schema drift without
+ *   turning it into an outage.
+ */
+type ValidationMode = boolean | "warn";
+/**
+ * Context passed to {@link CreateApiOptions.onValidationError} describing which
+ * call and which phase produced the validation failure.
+ */
+interface ValidationErrorContext {
+    /** Which phase failed — request params or the server response. */
+    kind: "request" | "response";
+    /** The endpoint's HTTP method. */
+    method: HttpMethod;
+    /** The resolved request URL (path is already substituted). */
+    url: string;
+    /** The raw data that failed validation (raw params or raw response). */
+    data: unknown;
+}
 /**
  * Options for {@link createApi}.
  *
@@ -161,6 +340,12 @@ type ApiTypes<TApi> = {
  *
  * // Keep request validation (catch call-site bugs), skip response in prod
  * createApi(executor, router, { validate: { request: true, response: false } });
+ *
+ * // Observe response drift without breaking production
+ * createApi(executor, router, {
+ *   validate: { request: true, response: 'warn' },
+ *   onValidationError: (err, ctx) => Sentry.captureException(err, { extra: ctx }),
+ * });
  * ```
  */
 interface CreateApiOptions {
@@ -169,18 +354,25 @@ interface CreateApiOptions {
      *
      * - `true` (default) — validate both request and response.
      * - `false` — skip both; raw params and raw response pass through.
-     * - `{ request?, response? }` — enable/disable each independently.
+     * - `'warn'` — validate both, but pass raw data through and report via
+     *   {@link CreateApiOptions.onValidationError} instead of throwing.
+     * - `{ request?, response? }` — set each independently (each a
+     *   {@link ValidationMode}).
      */
-    validate?: boolean | {
-        request?: boolean;
-        response?: boolean;
+    validate?: ValidationMode | {
+        request?: ValidationMode;
+        response?: ValidationMode;
     };
+    /**
+     * Called when validation fails under `'warn'` mode (instead of throwing).
+     * Use it to report schema drift to your observability stack. Never called
+     * when `validate` is `true` (which throws) or `false` (which skips).
+     */
+    onValidationError?: (error: ValidationError, context: ValidationErrorContext) => void;
 }
 
 /** 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>>;
+type EndpointFn<TSpec extends EndpointSpec<any, any, any>> = TSpec["request"] extends Validator<infer R> ? (params: R, options?: AbortSignal | EndpointCallOptions) => Promise<InferResponse<TSpec>> : TSpec["request"] extends StandardSchemaV1<unknown, infer O> ? (params: O, options?: AbortSignal | EndpointCallOptions) => Promise<InferResponse<TSpec>> : (params?: RequestShape, options?: AbortSignal | EndpointCallOptions) => Promise<InferResponse<TSpec>>;
 /**
  * Fully-typed API client produced by {@link createApi}.
  * Nested {@link RouterDef} entries become nested sub-client objects.
@@ -283,6 +475,13 @@ declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executo
  *   plugins: [authPlugin, logger()],
  * });
  * ```
+ *
+ * @example Unwrap an envelope response
+ * ```ts
+ * const executor = createExecutor(transport, {
+ *   unwrap: (raw) => (raw as { data: unknown })?.data ?? raw,
+ * });
+ * ```
  */
 declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, options?: CreateExecutorOptions): Executor;
 /**
@@ -320,6 +519,8 @@ interface FetchExecutorOptions extends CreateExecutorOptions {
  * - Non-2xx responses throw an {@link HttpError}.
  *
  * @param baseURL - Absolute base URL prepended to every endpoint path.
+ *   Accepts a static string or a sync/async factory called on every request —
+ *   useful when the origin depends on runtime environment (e.g. SSR vs CSR).
  * @param options.defaultHeaders - Async factory called on every request to
  *   produce headers (e.g. reading cookies in a Next.js server component).
  * @param options.plugins - Plugins applied around the fetch call. Each retry
@@ -335,6 +536,13 @@ interface FetchExecutorOptions extends CreateExecutorOptions {
  * const executor = createFetchExecutor('https://api.example.com');
  * ```
  *
+ * @example Dynamic base URL for SSR/CSR
+ * ```ts
+ * const executor = createFetchExecutor(
+ *   () => typeof window === 'undefined' ? 'http://localhost:3000/api' : '/api',
+ * );
+ * ```
+ *
  * @example SSR with bearer token
  * ```ts
  * const executor = createFetchExecutor('https://api.example.com', {
@@ -353,10 +561,14 @@ interface FetchExecutorOptions extends CreateExecutorOptions {
  * });
  * ```
  */
-declare function createFetchExecutor(baseURL: string, options?: FetchExecutorOptions): Executor;
+declare function createFetchExecutor(baseURL: string | (() => string | Promise<string>), options?: FetchExecutorOptions): Executor;
 /**
  * Thrown by {@link createFetchExecutor} when the server returns a non-2xx
- * status code.
+ * status code. The Axios and ky executors also normalize their transport
+ * errors to `HttpError`, so `onError` plugins and callers can branch on a
+ * single error type regardless of the underlying transport. The original
+ * transport error (e.g. an `AxiosError` or ky `HTTPError`) is preserved on
+ * the `cause` property.
  *
  * @example
  * ```ts
@@ -373,7 +585,13 @@ declare class HttpError extends Error {
     readonly status: number;
     readonly statusText: string;
     readonly body: unknown;
-    constructor(status: number, statusText: string, body?: unknown);
+    readonly url?: string;
+    readonly method?: string;
+    constructor(status: number, statusText: string, body?: unknown, options?: {
+        url?: string;
+        method?: string;
+        cause?: unknown;
+    });
 }
 
 /**
@@ -393,6 +611,33 @@ type PathParams<TPath extends string> = TPath extends `${string}:${infer Param}/
 type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never] ? {} : {
     path: Record<PathParams<TPath>, unknown>;
 };
+/**
+ * Builds the envelope request output type from the SE-12 separated bucket
+ * validators. Each bucket contributes its key only when supplied — the tuple
+ * wrapping (`[T] extends [never]`) prevents the `never` default from
+ * distributing and collapsing the whole intersection.
+ */
+type BucketRequestOutput<TPathParams, TQuery, TBody> = ([
+    TPathParams
+] extends [never] ? {} : {
+    path: ValidatorOutput<TPathParams>;
+}) & ([TQuery] extends [never] ? {} : {
+    query: ValidatorOutput<TQuery>;
+}) & ([TBody] extends [never] ? {} : {
+    body: ValidatorOutput<TBody>;
+});
+/**
+ * The `pathParams` field of the separated form: required when `TPath` has
+ * dynamic segments, optional otherwise. The validator type is further
+ * constrained (at the generic level) to cover every `:param` name.
+ */
+type BucketPathField<TPath extends string, TPathParams> = [
+    PathParams<TPath>
+] extends [never] ? {
+    pathParams?: TPathParams;
+} : {
+    pathParams: TPathParams;
+};
 /**
  * Type-safe endpoint definition helper.
  *
@@ -465,31 +710,31 @@ type PathConstraint<TPath extends string> = [PathParams<TPath>] extends [never]
  * });
  * ```
  */
-declare function endpoint<TMethod extends HttpMethod, TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>, TOut>(spec: {
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TReq extends AnyValidator<RequestShape & PathConstraint<TPath>>, TResponse extends AnyValidator, TOut>(spec: {
     method: TMethod;
     path: TPath;
-    request: Validator<TRequest>;
+    request: TReq;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 }): {
     method: TMethod;
     path: string;
-    request: Validator<TRequest>;
+    request: TReq;
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 };
-declare function endpoint<TMethod extends HttpMethod, TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>>(spec: {
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TReq extends AnyValidator<RequestShape & PathConstraint<TPath>>, TResponse extends AnyValidator>(spec: {
     method: TMethod;
     path: TPath;
-    request: Validator<TRequest>;
+    request: TReq;
     response: TResponse;
 }): {
     method: TMethod;
     path: string;
-    request: Validator<TRequest>;
+    request: TReq;
     response: TResponse;
 };
-declare function endpoint<TMethod extends HttpMethod, TResponse extends Validator<unknown>, TOut>(spec: {
+declare function endpoint<TMethod extends HttpMethod, TResponse extends AnyValidator, TOut>(spec: {
     method: TMethod;
     path: string;
     response: TResponse;
@@ -500,7 +745,7 @@ declare function endpoint<TMethod extends HttpMethod, TResponse extends Validato
     response: TResponse;
     adapter: (raw: ValidatorOutput<TResponse>) => TOut;
 };
-declare function endpoint<TMethod extends HttpMethod, TResponse extends Validator<unknown>>(spec: {
+declare function endpoint<TMethod extends HttpMethod, TResponse extends AnyValidator>(spec: {
     method: TMethod;
     path: string;
     response: TResponse;
@@ -509,6 +754,32 @@ declare function endpoint<TMethod extends HttpMethod, TResponse extends Validato
     path: string;
     response: TResponse;
 };
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TResponse extends AnyValidator, TOut, TPathParams extends AnyValidator<Record<PathParams<TPath>, unknown>> = never, TQuery extends AnyValidator = never, TBody extends AnyValidator = never>(spec: {
+    method: TMethod;
+    path: TPath;
+    query?: TQuery;
+    body?: TBody;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+} & BucketPathField<TPath, TPathParams>): {
+    method: TMethod;
+    path: string;
+    request: Validator<BucketRequestOutput<TPathParams, TQuery, TBody>>;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+};
+declare function endpoint<TMethod extends HttpMethod, TPath extends string, TResponse extends AnyValidator, TPathParams extends AnyValidator<Record<PathParams<TPath>, unknown>> = never, TQuery extends AnyValidator = never, TBody extends AnyValidator = never>(spec: {
+    method: TMethod;
+    path: TPath;
+    query?: TQuery;
+    body?: TBody;
+    response: TResponse;
+} & BucketPathField<TPath, TPathParams>): {
+    method: TMethod;
+    path: string;
+    request: Validator<BucketRequestOutput<TPathParams, TQuery, TBody>>;
+    response: TResponse;
+};
 
 /**
  * Groups a set of endpoint specs (and optional nested routers) under a shared
@@ -596,9 +867,17 @@ declare function serializeParams(params: Record<string, unknown>): URLSearchPara
 declare function joinPaths(...segments: string[]): string;
 declare function resolvePath(pathTemplate: string, params?: Record<string, unknown>): string;
 
-declare class ValidationError extends Error {
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
-}
+/**
+ * Validates `data` with an {@link AnyValidator}, returning the parsed value.
+ *
+ * Prefers the synchronous `.parse()` path when present (Zod, Valibot, Yup, or
+ * any object with `.parse()`); a thrown parse error propagates unchanged.
+ * Otherwise uses the Standard Schema `~standard.validate` path (sync or async);
+ * reported issues are thrown as a {@link StandardSchemaError}.
+ *
+ * Exported for executor / mock-handler authors who need routar's exact
+ * validate-or-throw semantics for both validator styles.
+ */
+declare function runValidator(validator: AnyValidator, data: unknown): Promise<unknown>;
 
-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 };
+export { type AnyValidator, type ApiClient, type ApiClientWithRouter, type ApiTypes, type CreateApiOptions, type CreateExecutorOptions, type EndpointCallOptions, 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, StandardSchemaError, StandardSchemaV1, TimeoutError, ValidationError, type ValidationErrorContext, type ValidationMode, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, definePlugin, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, logger, resolvePath, runValidator, serializeParams };