@routar/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kyungbae Min
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @routar/core
+
+Core package for [routar](https://github.com/kbmin1129/routar) — endpoint definitions, typed router, API client factory, and middleware system.
+
+## Install
+
+```bash
+npm install @routar/core
+```
+
+See the [main README](https://github.com/kbmin1129/routar) for full documentation.

package/dist/index.cjs

@@ -0,0 +1,200 @@
+'use strict';
+
+// src/define-router.ts
+function defineRouter(prefix, endpoints) {
+  return { prefix, endpoints };
+}
+
+// src/define-endpoint.ts
+function endpoint(spec) {
+  return spec;
+}
+
+// src/utils/path.ts
+function joinPaths(...segments) {
+  const joined = segments.filter((s) => s !== "").join("/").replace(/\/+/g, "/");
+  return joined.endsWith("/") && joined.length > 1 ? joined.slice(0, -1) : joined || "/";
+}
+function resolvePath(pathTemplate, params) {
+  if (!params) return pathTemplate;
+  return pathTemplate.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key) => {
+    const value = params[key];
+    if (value == null) throw new Error(`Missing path parameter: ${key}`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+// src/utils/validate.ts
+var ValidationError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ValidationError";
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        writable: true,
+        enumerable: true
+      });
+    }
+  }
+};
+
+// src/create-api.ts
+function createApi(executor, routerOrPrefixOrEndpoints, endpointsArg) {
+  let prefix;
+  let endpoints;
+  if (typeof routerOrPrefixOrEndpoints === "string") {
+    prefix = routerOrPrefixOrEndpoints;
+    if (!endpointsArg) throw new Error("endpoints is required when prefix is provided");
+    endpoints = endpointsArg;
+  } else if ("prefix" in routerOrPrefixOrEndpoints && "endpoints" in routerOrPrefixOrEndpoints) {
+    prefix = routerOrPrefixOrEndpoints.prefix;
+    endpoints = routerOrPrefixOrEndpoints.endpoints;
+  } else {
+    prefix = "";
+    endpoints = routerOrPrefixOrEndpoints;
+  }
+  return buildClient(executor, prefix, endpoints);
+}
+function buildClient(executor, prefix, endpoints) {
+  const client = {};
+  for (const [key, entry] of Object.entries(endpoints)) {
+    if ("prefix" in entry && "endpoints" in entry) {
+      const nested = entry;
+      client[key] = buildClient(executor, joinPaths(prefix, nested.prefix), nested.endpoints);
+    } else {
+      const spec = entry;
+      client[key] = async (params = {}, signal) => {
+        let validatedParams = params;
+        if (spec.request) {
+          try {
+            validatedParams = spec.request.parse(params);
+          } catch (err) {
+            throw new ValidationError("Request validation failed", err);
+          }
+        }
+        const url = resolvePath(
+          joinPaths(prefix, spec.path),
+          validatedParams?.path
+        );
+        const raw = await executor.execute({
+          method: spec.method,
+          url,
+          params: validatedParams?.query,
+          body: validatedParams?.body,
+          signal
+        });
+        let validated;
+        try {
+          validated = spec.response.parse(raw);
+        } catch (err) {
+          throw new ValidationError("Response validation failed", err);
+        }
+        if (spec.adapter) {
+          return spec.adapter(validated);
+        }
+        return validated;
+      };
+    }
+  }
+  return client;
+}
+
+// src/create-executor.ts
+function createExecutor(execute, middlewares = []) {
+  const chain = middlewares.reduceRight(
+    (next, mw) => (opts) => mw(opts, next),
+    execute
+  );
+  return { execute: chain };
+}
+
+// src/middleware.ts
+function defineMiddleware(fn) {
+  return fn;
+}
+function withRetry(count, options) {
+  return defineMiddleware(async (opts, next) => {
+    let lastError;
+    for (let attempt = 0; attempt <= count; attempt++) {
+      try {
+        return await next(opts);
+      } catch (err) {
+        lastError = err;
+        if (attempt === count) break;
+        if (options?.shouldRetry && !options.shouldRetry(err, attempt)) break;
+      }
+    }
+    throw lastError;
+  });
+}
+function withTimeout(ms) {
+  return defineMiddleware(async (opts, next) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    const signal = opts.signal ? anySignal([opts.signal, controller.signal]) : controller.signal;
+    try {
+      return await next({ ...opts, signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+}
+function withLogger(options) {
+  const log = options?.log ?? ((msg, data) => console.log(msg, data));
+  return defineMiddleware(async (opts, next) => {
+    const start = Date.now();
+    log(`[routar] ${opts.method} ${opts.url}`, { params: opts.params, body: opts.body });
+    try {
+      const result = await next(opts);
+      log(`[routar] ${opts.method} ${opts.url} \u2014 ${Date.now() - start}ms`);
+      return result;
+    } catch (err) {
+      log(`[routar] ${opts.method} ${opts.url} \u2014 error after ${Date.now() - start}ms`, err);
+      throw err;
+    }
+  });
+}
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort();
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  return controller.signal;
+}
+
+// src/utils/params.ts
+function serializeParams(params) {
+  const result = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item != null) result.append(key, String(item));
+      }
+    } else {
+      result.append(key, String(value));
+    }
+  }
+  return result;
+}
+
+exports.ValidationError = ValidationError;
+exports.createApi = createApi;
+exports.createExecutor = createExecutor;
+exports.defineMiddleware = defineMiddleware;
+exports.defineRouter = defineRouter;
+exports.endpoint = endpoint;
+exports.joinPaths = joinPaths;
+exports.resolvePath = resolvePath;
+exports.serializeParams = serializeParams;
+exports.withLogger = withLogger;
+exports.withRetry = withRetry;
+exports.withTimeout = withTimeout;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/define-router.ts","../src/define-endpoint.ts","../src/utils/path.ts","../src/utils/validate.ts","../src/create-api.ts","../src/create-executor.ts","../src/middleware.ts","../src/utils/params.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { RouterDef, RouterEndpoints } from './types.js';\n\n/**\n * Groups a set of endpoint specs (and optional nested routers) under a shared\n * URL prefix.\n *\n * The returned {@link RouterDef} can be passed directly to {@link createApi}\n * to produce a fully-typed API client. Nesting another {@link RouterDef} as a\n * value creates a sub-client whose prefix is the concatenation of both prefixes.\n *\n * @param prefix - Base path prepended to every endpoint's `path` (e.g. `'/users'`).\n * @param endpoints - Record of named {@link EndpointSpec}s or nested {@link RouterDef}s.\n *\n * @example\n * ```ts\n * // Flat router\n * export const todoRouter = defineRouter('/todos', {\n *   getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),\n *   getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),\n *   create:    endpoint({ method: 'POST', path: '/',    response: TodoSchema }),\n * });\n *\n * // Nested router — api.users.todos.getList() resolves to GET /users/todos/\n * export const userRouter = defineRouter('/users', {\n *   getList: endpoint({ method: 'GET', path: '/', response: UserListSchema }),\n *   todos: defineRouter('/todos', {\n *     getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),\n *     getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),\n *   }),\n * });\n * ```\n */\nexport function defineRouter<TEndpoints extends RouterEndpoints>(\n  prefix: string,\n  endpoints: TEndpoints,\n): RouterDef<TEndpoints> {\n  return { prefix, endpoints };\n}\n","import type {\n  HttpMethod,\n  RequestShape,\n  Validator,\n  ValidatorOutput,\n} from './types.js';\n\n/**\n * Extracts `:param` segment names from a path template string as a union of\n * string literals.\n *\n * @example\n * ```ts\n * type P = PathParams<'/:userId/posts/:postId'>; // 'userId' | 'postId'\n * ```\n */\nexport type PathParams<TPath extends string> =\n  TPath extends `${string}:${infer Param}/${infer Rest}`\n    ? Param | PathParams<Rest>\n    : TPath extends `${string}:${infer Param}`\n      ? Param\n      : never;\n\n/**\n * When `TPath` contains dynamic segments (`:param`), requires `request.path`\n * to include all extracted param names. No constraint for static paths.\n */\ntype PathConstraint<TPath extends string> =\n  [PathParams<TPath>] extends [never]\n    ? {}\n    : { path: Record<PathParams<TPath>, unknown> };\n\n/**\n * Type-safe endpoint definition helper.\n *\n * Use this instead of a plain object literal to get full type inference on\n * `adapter` without requiring explicit annotations or `as any` casts.\n * The four overloads cover every combination of optional `request` validator\n * and optional `adapter` function while keeping all return-type fields\n * required so that TypeScript can narrow them downstream.\n *\n * When `path` contains dynamic segments (e.g. `'/:id'`), TypeScript enforces\n * that `request` includes a matching `path` field with those param names.\n * A mismatch or missing key is a compile-time error.\n *\n * @example\n * ```ts\n * // ✅ path has ':id' → request.path.id is required\n * const getDetail = endpoint({\n *   method: 'GET',\n *   path: '/:id',\n *   request: z.object({ path: z.object({ id: z.number() }) }),\n *   response: TodoSchema,\n *   adapter: toTodoItem,\n * });\n *\n * // ❌ compile error — 'id' is missing from request.path\n * const broken = endpoint({\n *   method: 'GET',\n *   path: '/:id',\n *   request: z.object({ query: z.object({ foo: z.string() }) }),\n *   response: TodoSchema,\n * });\n * ```\n */\n// request O + adapter O\nexport function endpoint<\n  TPath extends string,\n  TRequest extends RequestShape & PathConstraint<TPath>,\n  TResponse extends Validator<unknown>,\n  TOut,\n>(spec: {\n  method: HttpMethod;\n  path: TPath;\n  request: Validator<TRequest>;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n}): {\n  method: HttpMethod;\n  path: string;\n  request: Validator<TRequest>;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n};\n\n// request O + adapter X\nexport function endpoint<\n  TPath extends string,\n  TRequest extends RequestShape & PathConstraint<TPath>,\n  TResponse extends Validator<unknown>,\n>(spec: {\n  method: HttpMethod;\n  path: TPath;\n  request: Validator<TRequest>;\n  response: TResponse;\n}): {\n  method: HttpMethod;\n  path: string;\n  request: Validator<TRequest>;\n  response: TResponse;\n};\n\n// request X + adapter O\nexport function endpoint<\n  TResponse extends Validator<unknown>,\n  TOut,\n>(spec: {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n}): {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n};\n\n// request X + adapter X\nexport function endpoint<\n  TResponse extends Validator<unknown>,\n>(spec: {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n}): {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n};\n\nexport function endpoint(spec: unknown): unknown {\n  return spec;\n}\n","export function joinPaths(...segments: string[]): string {\n  const joined = segments\n    .filter(s => s !== '')\n    .join('/')\n    .replace(/\\/+/g, '/');\n  return joined.endsWith('/') && joined.length > 1\n    ? joined.slice(0, -1)\n    : joined || '/';\n}\n\nexport function resolvePath(\n  pathTemplate: string,\n  params?: Record<string, unknown>,\n): string {\n  if (!params) return pathTemplate;\n  return pathTemplate.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key) => {\n    const value = params[key];\n    if (value == null) throw new Error(`Missing path parameter: ${key}`);\n    return encodeURIComponent(String(value));\n  });\n}\n","export class ValidationError extends Error {\n  constructor(\n    message: string,\n    public readonly cause?: unknown,\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n    if (cause !== undefined) {\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        writable: true,\n        enumerable: true,\n      });\n    }\n  }\n}\n","import type {\n  Executor,\n  RouterDef,\n  RouterEndpoints,\n  EndpointSpec,\n  InferResponse,\n  RequestShape,\n} from './types.js';\nimport { joinPaths, resolvePath } from './utils/path.js';\nimport { ValidationError } from './utils/validate.js';\n\n/** Callable type for a single endpoint on the generated API client. */\ntype EndpointFn<TSpec extends EndpointSpec<any, any, any>> = (\n  params: TSpec['request'] extends { parse: (data: unknown) => infer R } ? R : RequestShape,\n  signal?: AbortSignal,\n) => Promise<InferResponse<TSpec>>;\n\n/**\n * Fully-typed API client produced by {@link createApi}.\n * Nested {@link RouterDef} entries become nested sub-client objects.\n */\ntype ApiClient<TEndpoints extends RouterEndpoints> = {\n  [K in keyof TEndpoints]: TEndpoints[K] extends RouterDef<infer TNestedEndpoints>\n    ? ApiClient<TNestedEndpoints>\n    : TEndpoints[K] extends EndpointSpec<any, any, any>\n      ? EndpointFn<TEndpoints[K]>\n      : never;\n};\n\n/**\n * Builds a fully-typed API client from an {@link Executor} and a router\n * (or bare endpoint map).\n *\n * Three call signatures are supported:\n * - `createApi(executor, router)` — preferred; pass the result of {@link defineRouter}.\n * - `createApi(executor, prefix, endpoints)` — inline router without {@link defineRouter}.\n * - `createApi(executor, endpoints)` — no prefix; useful for flat endpoint maps.\n *\n * Each key in `endpoints` becomes a typed async function on the returned client.\n * The function validates the request with `spec.request.parse` (if present),\n * resolves path parameters, calls the executor, validates the response with\n * `spec.response.parse`, and applies `spec.adapter` (if present).\n *\n * @param executor - Transport to use for every HTTP call.\n * @param router - A {@link RouterDef} produced by {@link defineRouter}.\n *\n * @example\n * ```ts\n * const todoApi = createApi(executor, todoRouter);\n * const todos = await todoApi.getList({});\n * const todo  = await todoApi.getDetail({ path: { id: 1 } });\n * ```\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  router: RouterDef<TEndpoints>,\n): ApiClient<TEndpoints>;\n\n/**\n * @param executor - Transport to use for every HTTP call.\n * @param prefix - URL prefix prepended to every endpoint path.\n * @param endpoints - Record of named endpoint specs.\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  prefix: string,\n  endpoints: TEndpoints,\n): ApiClient<TEndpoints>;\n\n/**\n * @param executor - Transport to use for every HTTP call.\n * @param endpoints - Record of named endpoint specs (no URL prefix).\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  endpoints: TEndpoints,\n): ApiClient<TEndpoints>;\n\nexport function createApi(\n  executor: Executor,\n  routerOrPrefixOrEndpoints: RouterDef<any> | RouterEndpoints | string,\n  endpointsArg?: RouterEndpoints,\n): Record<string, any> {\n  let prefix: string;\n  let endpoints: RouterEndpoints;\n\n  if (typeof routerOrPrefixOrEndpoints === 'string') {\n    prefix = routerOrPrefixOrEndpoints;\n    if (!endpointsArg) throw new Error('endpoints is required when prefix is provided');\n    endpoints = endpointsArg;\n  } else if (\n    'prefix' in routerOrPrefixOrEndpoints &&\n    'endpoints' in routerOrPrefixOrEndpoints\n  ) {\n    prefix = (routerOrPrefixOrEndpoints as RouterDef<any>).prefix;\n    endpoints = (routerOrPrefixOrEndpoints as RouterDef<any>).endpoints;\n  } else {\n    prefix = '';\n    endpoints = routerOrPrefixOrEndpoints as RouterEndpoints;\n  }\n\n  return buildClient(executor, prefix, endpoints);\n}\n\nfunction buildClient(\n  executor: Executor,\n  prefix: string,\n  endpoints: RouterEndpoints,\n): Record<string, any> {\n  const client: Record<string, any> = {};\n\n  for (const [key, entry] of Object.entries(endpoints)) {\n    if ('prefix' in entry && 'endpoints' in entry) {\n      // Nested RouterDef — recurse with merged prefix\n      const nested = entry as RouterDef<any>;\n      client[key] = buildClient(executor, joinPaths(prefix, nested.prefix), nested.endpoints);\n    } else {\n      // Leaf EndpointSpec\n      const spec = entry as EndpointSpec<any, any, any>;\n      client[key] = async (params: RequestShape = {}, signal?: AbortSignal) => {\n        let validatedParams: RequestShape = params;\n        if (spec.request) {\n          try {\n            validatedParams = spec.request.parse(params);\n          } catch (err) {\n            throw new ValidationError('Request validation failed', err);\n          }\n        }\n\n        const url = resolvePath(\n          joinPaths(prefix, spec.path),\n          validatedParams?.path,\n        );\n\n        const raw = await executor.execute({\n          method: spec.method,\n          url,\n          params: validatedParams?.query as Record<string, unknown> | undefined,\n          body: validatedParams?.body,\n          signal,\n        });\n\n        let validated: unknown;\n        try {\n          validated = spec.response.parse(raw);\n        } catch (err) {\n          throw new ValidationError('Response validation failed', err);\n        }\n\n        if (spec.adapter) {\n          return spec.adapter(validated as any);\n        }\n        return validated;\n      };\n    }\n  }\n\n  return client;\n}\n","import type { Executor, ExecuteOptions, ExecutorMiddleware } from './types.js';\n\n/**\n * Creates an {@link Executor} by wrapping a transport function with an\n * optional middleware chain.\n *\n * Middlewares are applied in declaration order — the first middleware is the\n * outermost wrapper and runs first on each request.\n *\n * @param execute - The underlying transport function (fetch, axios, etc.).\n * @param middlewares - Ordered list of middlewares to apply.\n *\n * @example\n * ```ts\n * const executor = createExecutor(\n *   async ({ method, url, body }) => {\n *     const res = await fetch(url, { method, body: JSON.stringify(body) });\n *     return res.json();\n *   },\n *   [withTimeout(5000), withRetry(3), withLogger()],\n * );\n * ```\n */\nexport function createExecutor(\n  execute: (options: ExecuteOptions) => Promise<unknown>,\n  middlewares: ExecutorMiddleware[] = [],\n): Executor {\n  const chain = middlewares.reduceRight<(options: ExecuteOptions) => Promise<unknown>>(\n    (next, mw) => (opts) => mw(opts, next),\n    execute,\n  );\n  return { execute: chain };\n}\n","import type { ExecutorMiddleware } from './types.js';\n\n/**\n * Identity helper that returns the middleware as-is.\n *\n * Wrap your middleware function with this to get full type inference on `opts`\n * and `next` without having to annotate the type manually.\n *\n * @example\n * ```ts\n * const withCorrelationId = defineMiddleware((opts, next) =>\n *   next({ ...opts, headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() } })\n * );\n * ```\n */\nexport function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware {\n  return fn;\n}\n\n/**\n * Retries a failed request up to `count` additional times.\n *\n * By default all errors trigger a retry. Pass `shouldRetry` to skip retries\n * for non-transient errors (e.g. 4xx responses).\n *\n * @param count - Number of retries (not counting the initial attempt).\n * @param options.shouldRetry - Return `false` to stop retrying early.\n *\n * @example\n * ```ts\n * withRetry(3, {\n *   shouldRetry: (err) => err instanceof HttpError && err.status >= 500,\n * })\n * ```\n */\nexport function withRetry(\n  count: number,\n  options?: { shouldRetry?: (error: unknown, attempt: number) => boolean },\n): ExecutorMiddleware {\n  return defineMiddleware(async (opts, next) => {\n    let lastError: unknown;\n    for (let attempt = 0; attempt <= count; attempt++) {\n      try {\n        return await next(opts);\n      } catch (err) {\n        lastError = err;\n        if (attempt === count) break;\n        if (options?.shouldRetry && !options.shouldRetry(err, attempt)) break;\n      }\n    }\n    throw lastError;\n  });\n}\n\n/**\n * Aborts a request if it does not complete within `ms` milliseconds.\n *\n * Merges the timeout signal with any existing `AbortSignal` on the request,\n * so whichever fires first wins.\n *\n * @param ms - Timeout in milliseconds.\n */\nexport function withTimeout(ms: number): ExecutorMiddleware {\n  return defineMiddleware(async (opts, next) => {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), ms);\n\n    const signal = opts.signal\n      ? anySignal([opts.signal, controller.signal])\n      : controller.signal;\n\n    try {\n      return await next({ ...opts, signal });\n    } finally {\n      clearTimeout(timer);\n    }\n  });\n}\n\n/**\n * Logs each request and its outcome (success duration or error).\n *\n * @param options.log - Custom logging function. Defaults to `console.log`.\n *\n * @example\n * ```ts\n * withLogger({ log: (msg, data) => logger.debug(msg, data) })\n * ```\n */\nexport function withLogger(options?: {\n  log?: (message: string, data?: unknown) => void;\n}): ExecutorMiddleware {\n  const log = options?.log ?? ((msg, data) => console.log(msg, data));\n  return defineMiddleware(async (opts, next) => {\n    const start = Date.now();\n    log(`[routar] ${opts.method} ${opts.url}`, { params: opts.params, body: opts.body });\n    try {\n      const result = await next(opts);\n      log(`[routar] ${opts.method} ${opts.url} — ${Date.now() - start}ms`);\n      return result;\n    } catch (err) {\n      log(`[routar] ${opts.method} ${opts.url} — error after ${Date.now() - start}ms`, err);\n      throw err;\n    }\n  });\n}\n\n/** Combines multiple AbortSignals into one that aborts when any of them fire. */\nfunction anySignal(signals: AbortSignal[]): AbortSignal {\n  const controller = new AbortController();\n  for (const signal of signals) {\n    if (signal.aborted) {\n      controller.abort();\n      return controller.signal;\n    }\n    signal.addEventListener('abort', () => controller.abort(), { once: true });\n  }\n  return controller.signal;\n}\n","export function serializeParams(params: Record<string, unknown>): URLSearchParams {\n  const result = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    if (value == null) continue;\n    if (Array.isArray(value)) {\n      for (const item of value) {\n        if (item != null) result.append(key, String(item));\n      }\n    } else {\n      result.append(key, String(value));\n    }\n  }\n  return result;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,382 @@
+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;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * Transport abstraction. Implement this to support any HTTP client.
+ *
+ * @see {@link createExecutor} to build an executor with middleware support.
+ */
+interface Executor {
+    execute(options: ExecuteOptions): Promise<unknown>;
+}
+/**
+ * Middleware function for an {@link Executor}.
+ *
+ * Receives the current {@link ExecuteOptions} and a `next` function to call
+ * the next middleware (or the underlying transport). Must return the response
+ * promise.
+ *
+ * @example
+ * ```ts
+ * const myMiddleware: ExecutorMiddleware = async (opts, next) => {
+ *   console.log(opts.method, opts.url);
+ *   return next(opts);
+ * };
+ * ```
+ */
+type ExecutorMiddleware = (options: ExecuteOptions, next: (options: ExecuteOptions) => Promise<unknown>) => Promise<unknown>;
+/**
+ * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
+ *
+ * @template TOutput Parsed output type.
+ */
+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;
+/**
+ * Shape of an endpoint's request parameters.
+ *
+ * All fields are optional at the type level; each endpoint declares only what
+ * it actually uses via its `request` validator.
+ */
+interface RequestShape {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+}
+/**
+ * Full specification of a single API endpoint.
+ *
+ * Prefer using the {@link endpoint} helper to define specs — it provides
+ * contextual typing for `adapter` without requiring `any` casts.
+ *
+ * @template TRequest  Validated request shape.
+ * @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> {
+    method: HttpMethod;
+    path: string;
+    /** Validates and narrows request parameters before the HTTP call. */
+    request?: Validator<TRequest>;
+    /** Validates the raw server response. */
+    response: TResponse;
+    /**
+     * Transforms the validated response before returning to the caller.
+     * When present, the endpoint's return type is the adapter's output type.
+     */
+    adapter?: TAdapter;
+}
+/**
+ * Resolves the final return type of an endpoint call.
+ *
+ * - 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']>;
+/**
+ * A single entry inside a {@link RouterEndpoints} map.
+ * Either a leaf endpoint spec or a nested {@link RouterDef}.
+ */
+type RouterEntry = EndpointSpec<any, any, any> | RouterDef<any>;
+/** A record of named {@link EndpointSpec}s or nested {@link RouterDef}s. */
+type RouterEndpoints = Record<string, RouterEntry>;
+/** The return type of {@link defineRouter}. Passed directly to {@link createApi}. */
+interface RouterDef<TEndpoints extends RouterEndpoints = RouterEndpoints> {
+    prefix: string;
+    endpoints: TEndpoints;
+}
+/**
+ * Extracts request/response types from a typed API client for use in query
+ * hooks or mutation handlers.
+ *
+ * @example
+ * ```ts
+ * export type TodoApiTypes = ApiTypes<typeof todoApi>;
+ * type CreateRequest = TodoApiTypes['create']['request'];
+ * type CreateResponse = TodoApiTypes['create']['response'];
+ * ```
+ */
+type ApiTypes<TApi> = {
+    [K in keyof TApi]: TApi[K] extends (...args: any[]) => Promise<infer R> ? {
+        request: Parameters<TApi[K]>[0];
+        response: R;
+    } : never;
+};
+
+/**
+ * Groups a set of endpoint specs (and optional nested routers) under a shared
+ * URL prefix.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @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 }),
+ * });
+ *
+ * // 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 }),
+ *   }),
+ * });
+ * ```
+ */
+declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
+
+/**
+ * Extracts `:param` segment names from a path template string as a union of
+ * string literals.
+ *
+ * @example
+ * ```ts
+ * type P = PathParams<'/:userId/posts/:postId'>; // 'userId' | 'postId'
+ * ```
+ */
+type PathParams<TPath extends string> = TPath extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParams<Rest> : TPath extends `${string}:${infer Param}` ? Param : never;
+/**
+ * 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] ? {} : {
+    path: Record<PathParams<TPath>, unknown>;
+};
+/**
+ * Type-safe endpoint definition helper.
+ *
+ * Use this instead of a plain object literal to get full type inference on
+ * `adapter` without requiring explicit annotations or `as any` casts.
+ * The four overloads cover every combination of optional `request` validator
+ * and optional `adapter` function while keeping all return-type fields
+ * required so that TypeScript can narrow them downstream.
+ *
+ * When `path` contains dynamic segments (e.g. `'/:id'`), TypeScript enforces
+ * that `request` includes a matching `path` field with those param names.
+ * A mismatch or missing key is a compile-time error.
+ *
+ * @example
+ * ```ts
+ * // ✅ path has ':id' → request.path.id is required
+ * const getDetail = endpoint({
+ *   method: 'GET',
+ *   path: '/:id',
+ *   request: z.object({ path: z.object({ id: z.number() }) }),
+ *   response: TodoSchema,
+ *   adapter: toTodoItem,
+ * });
+ *
+ * // ❌ compile error — 'id' is missing from request.path
+ * const broken = endpoint({
+ *   method: 'GET',
+ *   path: '/:id',
+ *   request: z.object({ query: z.object({ foo: z.string() }) }),
+ *   response: TodoSchema,
+ * });
+ * ```
+ */
+declare function endpoint<TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>, TOut>(spec: {
+    method: HttpMethod;
+    path: TPath;
+    request: Validator<TRequest>;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+}): {
+    method: HttpMethod;
+    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;
+    path: TPath;
+    request: Validator<TRequest>;
+    response: TResponse;
+}): {
+    method: HttpMethod;
+    path: string;
+    request: Validator<TRequest>;
+    response: TResponse;
+};
+declare function endpoint<TResponse extends Validator<unknown>, TOut>(spec: {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+}): {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+};
+declare function endpoint<TResponse extends Validator<unknown>>(spec: {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+}): {
+    method: HttpMethod;
+    path: string;
+    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>;
+
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+declare function withTimeout(ms: number): ExecutorMiddleware;
+/**
+ * Logs each request and its outcome (success duration or error).
+ *
+ * @param options.log - Custom logging function. Defaults to `console.log`.
+ *
+ * @example
+ * ```ts
+ * withLogger({ log: (msg, data) => logger.debug(msg, data) })
+ * ```
+ */
+declare function withLogger(options?: {
+    log?: (message: string, data?: unknown) => void;
+}): ExecutorMiddleware;
+
+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);
+}
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+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;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * Transport abstraction. Implement this to support any HTTP client.
+ *
+ * @see {@link createExecutor} to build an executor with middleware support.
+ */
+interface Executor {
+    execute(options: ExecuteOptions): Promise<unknown>;
+}
+/**
+ * Middleware function for an {@link Executor}.
+ *
+ * Receives the current {@link ExecuteOptions} and a `next` function to call
+ * the next middleware (or the underlying transport). Must return the response
+ * promise.
+ *
+ * @example
+ * ```ts
+ * const myMiddleware: ExecutorMiddleware = async (opts, next) => {
+ *   console.log(opts.method, opts.url);
+ *   return next(opts);
+ * };
+ * ```
+ */
+type ExecutorMiddleware = (options: ExecuteOptions, next: (options: ExecuteOptions) => Promise<unknown>) => Promise<unknown>;
+/**
+ * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
+ *
+ * @template TOutput Parsed output type.
+ */
+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;
+/**
+ * Shape of an endpoint's request parameters.
+ *
+ * All fields are optional at the type level; each endpoint declares only what
+ * it actually uses via its `request` validator.
+ */
+interface RequestShape {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+}
+/**
+ * Full specification of a single API endpoint.
+ *
+ * Prefer using the {@link endpoint} helper to define specs — it provides
+ * contextual typing for `adapter` without requiring `any` casts.
+ *
+ * @template TRequest  Validated request shape.
+ * @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> {
+    method: HttpMethod;
+    path: string;
+    /** Validates and narrows request parameters before the HTTP call. */
+    request?: Validator<TRequest>;
+    /** Validates the raw server response. */
+    response: TResponse;
+    /**
+     * Transforms the validated response before returning to the caller.
+     * When present, the endpoint's return type is the adapter's output type.
+     */
+    adapter?: TAdapter;
+}
+/**
+ * Resolves the final return type of an endpoint call.
+ *
+ * - 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']>;
+/**
+ * A single entry inside a {@link RouterEndpoints} map.
+ * Either a leaf endpoint spec or a nested {@link RouterDef}.
+ */
+type RouterEntry = EndpointSpec<any, any, any> | RouterDef<any>;
+/** A record of named {@link EndpointSpec}s or nested {@link RouterDef}s. */
+type RouterEndpoints = Record<string, RouterEntry>;
+/** The return type of {@link defineRouter}. Passed directly to {@link createApi}. */
+interface RouterDef<TEndpoints extends RouterEndpoints = RouterEndpoints> {
+    prefix: string;
+    endpoints: TEndpoints;
+}
+/**
+ * Extracts request/response types from a typed API client for use in query
+ * hooks or mutation handlers.
+ *
+ * @example
+ * ```ts
+ * export type TodoApiTypes = ApiTypes<typeof todoApi>;
+ * type CreateRequest = TodoApiTypes['create']['request'];
+ * type CreateResponse = TodoApiTypes['create']['response'];
+ * ```
+ */
+type ApiTypes<TApi> = {
+    [K in keyof TApi]: TApi[K] extends (...args: any[]) => Promise<infer R> ? {
+        request: Parameters<TApi[K]>[0];
+        response: R;
+    } : never;
+};
+
+/**
+ * Groups a set of endpoint specs (and optional nested routers) under a shared
+ * URL prefix.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @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 }),
+ * });
+ *
+ * // 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 }),
+ *   }),
+ * });
+ * ```
+ */
+declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
+
+/**
+ * Extracts `:param` segment names from a path template string as a union of
+ * string literals.
+ *
+ * @example
+ * ```ts
+ * type P = PathParams<'/:userId/posts/:postId'>; // 'userId' | 'postId'
+ * ```
+ */
+type PathParams<TPath extends string> = TPath extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParams<Rest> : TPath extends `${string}:${infer Param}` ? Param : never;
+/**
+ * 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] ? {} : {
+    path: Record<PathParams<TPath>, unknown>;
+};
+/**
+ * Type-safe endpoint definition helper.
+ *
+ * Use this instead of a plain object literal to get full type inference on
+ * `adapter` without requiring explicit annotations or `as any` casts.
+ * The four overloads cover every combination of optional `request` validator
+ * and optional `adapter` function while keeping all return-type fields
+ * required so that TypeScript can narrow them downstream.
+ *
+ * When `path` contains dynamic segments (e.g. `'/:id'`), TypeScript enforces
+ * that `request` includes a matching `path` field with those param names.
+ * A mismatch or missing key is a compile-time error.
+ *
+ * @example
+ * ```ts
+ * // ✅ path has ':id' → request.path.id is required
+ * const getDetail = endpoint({
+ *   method: 'GET',
+ *   path: '/:id',
+ *   request: z.object({ path: z.object({ id: z.number() }) }),
+ *   response: TodoSchema,
+ *   adapter: toTodoItem,
+ * });
+ *
+ * // ❌ compile error — 'id' is missing from request.path
+ * const broken = endpoint({
+ *   method: 'GET',
+ *   path: '/:id',
+ *   request: z.object({ query: z.object({ foo: z.string() }) }),
+ *   response: TodoSchema,
+ * });
+ * ```
+ */
+declare function endpoint<TPath extends string, TRequest extends RequestShape & PathConstraint<TPath>, TResponse extends Validator<unknown>, TOut>(spec: {
+    method: HttpMethod;
+    path: TPath;
+    request: Validator<TRequest>;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+}): {
+    method: HttpMethod;
+    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;
+    path: TPath;
+    request: Validator<TRequest>;
+    response: TResponse;
+}): {
+    method: HttpMethod;
+    path: string;
+    request: Validator<TRequest>;
+    response: TResponse;
+};
+declare function endpoint<TResponse extends Validator<unknown>, TOut>(spec: {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+}): {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+    adapter: (raw: ValidatorOutput<TResponse>) => TOut;
+};
+declare function endpoint<TResponse extends Validator<unknown>>(spec: {
+    method: HttpMethod;
+    path: string;
+    response: TResponse;
+}): {
+    method: HttpMethod;
+    path: string;
+    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>;
+
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+declare function withTimeout(ms: number): ExecutorMiddleware;
+/**
+ * Logs each request and its outcome (success duration or error).
+ *
+ * @param options.log - Custom logging function. Defaults to `console.log`.
+ *
+ * @example
+ * ```ts
+ * withLogger({ log: (msg, data) => logger.debug(msg, data) })
+ * ```
+ */
+declare function withLogger(options?: {
+    log?: (message: string, data?: unknown) => void;
+}): ExecutorMiddleware;
+
+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);
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,187 @@
+// src/define-router.ts
+function defineRouter(prefix, endpoints) {
+  return { prefix, endpoints };
+}
+
+// src/define-endpoint.ts
+function endpoint(spec) {
+  return spec;
+}
+
+// src/utils/path.ts
+function joinPaths(...segments) {
+  const joined = segments.filter((s) => s !== "").join("/").replace(/\/+/g, "/");
+  return joined.endsWith("/") && joined.length > 1 ? joined.slice(0, -1) : joined || "/";
+}
+function resolvePath(pathTemplate, params) {
+  if (!params) return pathTemplate;
+  return pathTemplate.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key) => {
+    const value = params[key];
+    if (value == null) throw new Error(`Missing path parameter: ${key}`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+// src/utils/validate.ts
+var ValidationError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ValidationError";
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        writable: true,
+        enumerable: true
+      });
+    }
+  }
+};
+
+// src/create-api.ts
+function createApi(executor, routerOrPrefixOrEndpoints, endpointsArg) {
+  let prefix;
+  let endpoints;
+  if (typeof routerOrPrefixOrEndpoints === "string") {
+    prefix = routerOrPrefixOrEndpoints;
+    if (!endpointsArg) throw new Error("endpoints is required when prefix is provided");
+    endpoints = endpointsArg;
+  } else if ("prefix" in routerOrPrefixOrEndpoints && "endpoints" in routerOrPrefixOrEndpoints) {
+    prefix = routerOrPrefixOrEndpoints.prefix;
+    endpoints = routerOrPrefixOrEndpoints.endpoints;
+  } else {
+    prefix = "";
+    endpoints = routerOrPrefixOrEndpoints;
+  }
+  return buildClient(executor, prefix, endpoints);
+}
+function buildClient(executor, prefix, endpoints) {
+  const client = {};
+  for (const [key, entry] of Object.entries(endpoints)) {
+    if ("prefix" in entry && "endpoints" in entry) {
+      const nested = entry;
+      client[key] = buildClient(executor, joinPaths(prefix, nested.prefix), nested.endpoints);
+    } else {
+      const spec = entry;
+      client[key] = async (params = {}, signal) => {
+        let validatedParams = params;
+        if (spec.request) {
+          try {
+            validatedParams = spec.request.parse(params);
+          } catch (err) {
+            throw new ValidationError("Request validation failed", err);
+          }
+        }
+        const url = resolvePath(
+          joinPaths(prefix, spec.path),
+          validatedParams?.path
+        );
+        const raw = await executor.execute({
+          method: spec.method,
+          url,
+          params: validatedParams?.query,
+          body: validatedParams?.body,
+          signal
+        });
+        let validated;
+        try {
+          validated = spec.response.parse(raw);
+        } catch (err) {
+          throw new ValidationError("Response validation failed", err);
+        }
+        if (spec.adapter) {
+          return spec.adapter(validated);
+        }
+        return validated;
+      };
+    }
+  }
+  return client;
+}
+
+// src/create-executor.ts
+function createExecutor(execute, middlewares = []) {
+  const chain = middlewares.reduceRight(
+    (next, mw) => (opts) => mw(opts, next),
+    execute
+  );
+  return { execute: chain };
+}
+
+// src/middleware.ts
+function defineMiddleware(fn) {
+  return fn;
+}
+function withRetry(count, options) {
+  return defineMiddleware(async (opts, next) => {
+    let lastError;
+    for (let attempt = 0; attempt <= count; attempt++) {
+      try {
+        return await next(opts);
+      } catch (err) {
+        lastError = err;
+        if (attempt === count) break;
+        if (options?.shouldRetry && !options.shouldRetry(err, attempt)) break;
+      }
+    }
+    throw lastError;
+  });
+}
+function withTimeout(ms) {
+  return defineMiddleware(async (opts, next) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    const signal = opts.signal ? anySignal([opts.signal, controller.signal]) : controller.signal;
+    try {
+      return await next({ ...opts, signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+}
+function withLogger(options) {
+  const log = options?.log ?? ((msg, data) => console.log(msg, data));
+  return defineMiddleware(async (opts, next) => {
+    const start = Date.now();
+    log(`[routar] ${opts.method} ${opts.url}`, { params: opts.params, body: opts.body });
+    try {
+      const result = await next(opts);
+      log(`[routar] ${opts.method} ${opts.url} \u2014 ${Date.now() - start}ms`);
+      return result;
+    } catch (err) {
+      log(`[routar] ${opts.method} ${opts.url} \u2014 error after ${Date.now() - start}ms`, err);
+      throw err;
+    }
+  });
+}
+function anySignal(signals) {
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort();
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  return controller.signal;
+}
+
+// src/utils/params.ts
+function serializeParams(params) {
+  const result = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item != null) result.append(key, String(item));
+      }
+    } else {
+      result.append(key, String(value));
+    }
+  }
+  return result;
+}
+
+export { ValidationError, createApi, createExecutor, defineMiddleware, defineRouter, endpoint, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/define-router.ts","../src/define-endpoint.ts","../src/utils/path.ts","../src/utils/validate.ts","../src/create-api.ts","../src/create-executor.ts","../src/middleware.ts","../src/utils/params.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { RouterDef, RouterEndpoints } from './types.js';\n\n/**\n * Groups a set of endpoint specs (and optional nested routers) under a shared\n * URL prefix.\n *\n * The returned {@link RouterDef} can be passed directly to {@link createApi}\n * to produce a fully-typed API client. Nesting another {@link RouterDef} as a\n * value creates a sub-client whose prefix is the concatenation of both prefixes.\n *\n * @param prefix - Base path prepended to every endpoint's `path` (e.g. `'/users'`).\n * @param endpoints - Record of named {@link EndpointSpec}s or nested {@link RouterDef}s.\n *\n * @example\n * ```ts\n * // Flat router\n * export const todoRouter = defineRouter('/todos', {\n *   getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),\n *   getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),\n *   create:    endpoint({ method: 'POST', path: '/',    response: TodoSchema }),\n * });\n *\n * // Nested router — api.users.todos.getList() resolves to GET /users/todos/\n * export const userRouter = defineRouter('/users', {\n *   getList: endpoint({ method: 'GET', path: '/', response: UserListSchema }),\n *   todos: defineRouter('/todos', {\n *     getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),\n *     getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema }),\n *   }),\n * });\n * ```\n */\nexport function defineRouter<TEndpoints extends RouterEndpoints>(\n  prefix: string,\n  endpoints: TEndpoints,\n): RouterDef<TEndpoints> {\n  return { prefix, endpoints };\n}\n","import type {\n  HttpMethod,\n  RequestShape,\n  Validator,\n  ValidatorOutput,\n} from './types.js';\n\n/**\n * Extracts `:param` segment names from a path template string as a union of\n * string literals.\n *\n * @example\n * ```ts\n * type P = PathParams<'/:userId/posts/:postId'>; // 'userId' | 'postId'\n * ```\n */\nexport type PathParams<TPath extends string> =\n  TPath extends `${string}:${infer Param}/${infer Rest}`\n    ? Param | PathParams<Rest>\n    : TPath extends `${string}:${infer Param}`\n      ? Param\n      : never;\n\n/**\n * When `TPath` contains dynamic segments (`:param`), requires `request.path`\n * to include all extracted param names. No constraint for static paths.\n */\ntype PathConstraint<TPath extends string> =\n  [PathParams<TPath>] extends [never]\n    ? {}\n    : { path: Record<PathParams<TPath>, unknown> };\n\n/**\n * Type-safe endpoint definition helper.\n *\n * Use this instead of a plain object literal to get full type inference on\n * `adapter` without requiring explicit annotations or `as any` casts.\n * The four overloads cover every combination of optional `request` validator\n * and optional `adapter` function while keeping all return-type fields\n * required so that TypeScript can narrow them downstream.\n *\n * When `path` contains dynamic segments (e.g. `'/:id'`), TypeScript enforces\n * that `request` includes a matching `path` field with those param names.\n * A mismatch or missing key is a compile-time error.\n *\n * @example\n * ```ts\n * // ✅ path has ':id' → request.path.id is required\n * const getDetail = endpoint({\n *   method: 'GET',\n *   path: '/:id',\n *   request: z.object({ path: z.object({ id: z.number() }) }),\n *   response: TodoSchema,\n *   adapter: toTodoItem,\n * });\n *\n * // ❌ compile error — 'id' is missing from request.path\n * const broken = endpoint({\n *   method: 'GET',\n *   path: '/:id',\n *   request: z.object({ query: z.object({ foo: z.string() }) }),\n *   response: TodoSchema,\n * });\n * ```\n */\n// request O + adapter O\nexport function endpoint<\n  TPath extends string,\n  TRequest extends RequestShape & PathConstraint<TPath>,\n  TResponse extends Validator<unknown>,\n  TOut,\n>(spec: {\n  method: HttpMethod;\n  path: TPath;\n  request: Validator<TRequest>;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n}): {\n  method: HttpMethod;\n  path: string;\n  request: Validator<TRequest>;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n};\n\n// request O + adapter X\nexport function endpoint<\n  TPath extends string,\n  TRequest extends RequestShape & PathConstraint<TPath>,\n  TResponse extends Validator<unknown>,\n>(spec: {\n  method: HttpMethod;\n  path: TPath;\n  request: Validator<TRequest>;\n  response: TResponse;\n}): {\n  method: HttpMethod;\n  path: string;\n  request: Validator<TRequest>;\n  response: TResponse;\n};\n\n// request X + adapter O\nexport function endpoint<\n  TResponse extends Validator<unknown>,\n  TOut,\n>(spec: {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n}): {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n  adapter: (raw: ValidatorOutput<TResponse>) => TOut;\n};\n\n// request X + adapter X\nexport function endpoint<\n  TResponse extends Validator<unknown>,\n>(spec: {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n}): {\n  method: HttpMethod;\n  path: string;\n  response: TResponse;\n};\n\nexport function endpoint(spec: unknown): unknown {\n  return spec;\n}\n","export function joinPaths(...segments: string[]): string {\n  const joined = segments\n    .filter(s => s !== '')\n    .join('/')\n    .replace(/\\/+/g, '/');\n  return joined.endsWith('/') && joined.length > 1\n    ? joined.slice(0, -1)\n    : joined || '/';\n}\n\nexport function resolvePath(\n  pathTemplate: string,\n  params?: Record<string, unknown>,\n): string {\n  if (!params) return pathTemplate;\n  return pathTemplate.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key) => {\n    const value = params[key];\n    if (value == null) throw new Error(`Missing path parameter: ${key}`);\n    return encodeURIComponent(String(value));\n  });\n}\n","export class ValidationError extends Error {\n  constructor(\n    message: string,\n    public readonly cause?: unknown,\n  ) {\n    super(message);\n    this.name = 'ValidationError';\n    if (cause !== undefined) {\n      Object.defineProperty(this, 'cause', {\n        value: cause,\n        writable: true,\n        enumerable: true,\n      });\n    }\n  }\n}\n","import type {\n  Executor,\n  RouterDef,\n  RouterEndpoints,\n  EndpointSpec,\n  InferResponse,\n  RequestShape,\n} from './types.js';\nimport { joinPaths, resolvePath } from './utils/path.js';\nimport { ValidationError } from './utils/validate.js';\n\n/** Callable type for a single endpoint on the generated API client. */\ntype EndpointFn<TSpec extends EndpointSpec<any, any, any>> = (\n  params: TSpec['request'] extends { parse: (data: unknown) => infer R } ? R : RequestShape,\n  signal?: AbortSignal,\n) => Promise<InferResponse<TSpec>>;\n\n/**\n * Fully-typed API client produced by {@link createApi}.\n * Nested {@link RouterDef} entries become nested sub-client objects.\n */\ntype ApiClient<TEndpoints extends RouterEndpoints> = {\n  [K in keyof TEndpoints]: TEndpoints[K] extends RouterDef<infer TNestedEndpoints>\n    ? ApiClient<TNestedEndpoints>\n    : TEndpoints[K] extends EndpointSpec<any, any, any>\n      ? EndpointFn<TEndpoints[K]>\n      : never;\n};\n\n/**\n * Builds a fully-typed API client from an {@link Executor} and a router\n * (or bare endpoint map).\n *\n * Three call signatures are supported:\n * - `createApi(executor, router)` — preferred; pass the result of {@link defineRouter}.\n * - `createApi(executor, prefix, endpoints)` — inline router without {@link defineRouter}.\n * - `createApi(executor, endpoints)` — no prefix; useful for flat endpoint maps.\n *\n * Each key in `endpoints` becomes a typed async function on the returned client.\n * The function validates the request with `spec.request.parse` (if present),\n * resolves path parameters, calls the executor, validates the response with\n * `spec.response.parse`, and applies `spec.adapter` (if present).\n *\n * @param executor - Transport to use for every HTTP call.\n * @param router - A {@link RouterDef} produced by {@link defineRouter}.\n *\n * @example\n * ```ts\n * const todoApi = createApi(executor, todoRouter);\n * const todos = await todoApi.getList({});\n * const todo  = await todoApi.getDetail({ path: { id: 1 } });\n * ```\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  router: RouterDef<TEndpoints>,\n): ApiClient<TEndpoints>;\n\n/**\n * @param executor - Transport to use for every HTTP call.\n * @param prefix - URL prefix prepended to every endpoint path.\n * @param endpoints - Record of named endpoint specs.\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  prefix: string,\n  endpoints: TEndpoints,\n): ApiClient<TEndpoints>;\n\n/**\n * @param executor - Transport to use for every HTTP call.\n * @param endpoints - Record of named endpoint specs (no URL prefix).\n */\nexport function createApi<TEndpoints extends RouterEndpoints>(\n  executor: Executor,\n  endpoints: TEndpoints,\n): ApiClient<TEndpoints>;\n\nexport function createApi(\n  executor: Executor,\n  routerOrPrefixOrEndpoints: RouterDef<any> | RouterEndpoints | string,\n  endpointsArg?: RouterEndpoints,\n): Record<string, any> {\n  let prefix: string;\n  let endpoints: RouterEndpoints;\n\n  if (typeof routerOrPrefixOrEndpoints === 'string') {\n    prefix = routerOrPrefixOrEndpoints;\n    if (!endpointsArg) throw new Error('endpoints is required when prefix is provided');\n    endpoints = endpointsArg;\n  } else if (\n    'prefix' in routerOrPrefixOrEndpoints &&\n    'endpoints' in routerOrPrefixOrEndpoints\n  ) {\n    prefix = (routerOrPrefixOrEndpoints as RouterDef<any>).prefix;\n    endpoints = (routerOrPrefixOrEndpoints as RouterDef<any>).endpoints;\n  } else {\n    prefix = '';\n    endpoints = routerOrPrefixOrEndpoints as RouterEndpoints;\n  }\n\n  return buildClient(executor, prefix, endpoints);\n}\n\nfunction buildClient(\n  executor: Executor,\n  prefix: string,\n  endpoints: RouterEndpoints,\n): Record<string, any> {\n  const client: Record<string, any> = {};\n\n  for (const [key, entry] of Object.entries(endpoints)) {\n    if ('prefix' in entry && 'endpoints' in entry) {\n      // Nested RouterDef — recurse with merged prefix\n      const nested = entry as RouterDef<any>;\n      client[key] = buildClient(executor, joinPaths(prefix, nested.prefix), nested.endpoints);\n    } else {\n      // Leaf EndpointSpec\n      const spec = entry as EndpointSpec<any, any, any>;\n      client[key] = async (params: RequestShape = {}, signal?: AbortSignal) => {\n        let validatedParams: RequestShape = params;\n        if (spec.request) {\n          try {\n            validatedParams = spec.request.parse(params);\n          } catch (err) {\n            throw new ValidationError('Request validation failed', err);\n          }\n        }\n\n        const url = resolvePath(\n          joinPaths(prefix, spec.path),\n          validatedParams?.path,\n        );\n\n        const raw = await executor.execute({\n          method: spec.method,\n          url,\n          params: validatedParams?.query as Record<string, unknown> | undefined,\n          body: validatedParams?.body,\n          signal,\n        });\n\n        let validated: unknown;\n        try {\n          validated = spec.response.parse(raw);\n        } catch (err) {\n          throw new ValidationError('Response validation failed', err);\n        }\n\n        if (spec.adapter) {\n          return spec.adapter(validated as any);\n        }\n        return validated;\n      };\n    }\n  }\n\n  return client;\n}\n","import type { Executor, ExecuteOptions, ExecutorMiddleware } from './types.js';\n\n/**\n * Creates an {@link Executor} by wrapping a transport function with an\n * optional middleware chain.\n *\n * Middlewares are applied in declaration order — the first middleware is the\n * outermost wrapper and runs first on each request.\n *\n * @param execute - The underlying transport function (fetch, axios, etc.).\n * @param middlewares - Ordered list of middlewares to apply.\n *\n * @example\n * ```ts\n * const executor = createExecutor(\n *   async ({ method, url, body }) => {\n *     const res = await fetch(url, { method, body: JSON.stringify(body) });\n *     return res.json();\n *   },\n *   [withTimeout(5000), withRetry(3), withLogger()],\n * );\n * ```\n */\nexport function createExecutor(\n  execute: (options: ExecuteOptions) => Promise<unknown>,\n  middlewares: ExecutorMiddleware[] = [],\n): Executor {\n  const chain = middlewares.reduceRight<(options: ExecuteOptions) => Promise<unknown>>(\n    (next, mw) => (opts) => mw(opts, next),\n    execute,\n  );\n  return { execute: chain };\n}\n","import type { ExecutorMiddleware } from './types.js';\n\n/**\n * Identity helper that returns the middleware as-is.\n *\n * Wrap your middleware function with this to get full type inference on `opts`\n * and `next` without having to annotate the type manually.\n *\n * @example\n * ```ts\n * const withCorrelationId = defineMiddleware((opts, next) =>\n *   next({ ...opts, headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() } })\n * );\n * ```\n */\nexport function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware {\n  return fn;\n}\n\n/**\n * Retries a failed request up to `count` additional times.\n *\n * By default all errors trigger a retry. Pass `shouldRetry` to skip retries\n * for non-transient errors (e.g. 4xx responses).\n *\n * @param count - Number of retries (not counting the initial attempt).\n * @param options.shouldRetry - Return `false` to stop retrying early.\n *\n * @example\n * ```ts\n * withRetry(3, {\n *   shouldRetry: (err) => err instanceof HttpError && err.status >= 500,\n * })\n * ```\n */\nexport function withRetry(\n  count: number,\n  options?: { shouldRetry?: (error: unknown, attempt: number) => boolean },\n): ExecutorMiddleware {\n  return defineMiddleware(async (opts, next) => {\n    let lastError: unknown;\n    for (let attempt = 0; attempt <= count; attempt++) {\n      try {\n        return await next(opts);\n      } catch (err) {\n        lastError = err;\n        if (attempt === count) break;\n        if (options?.shouldRetry && !options.shouldRetry(err, attempt)) break;\n      }\n    }\n    throw lastError;\n  });\n}\n\n/**\n * Aborts a request if it does not complete within `ms` milliseconds.\n *\n * Merges the timeout signal with any existing `AbortSignal` on the request,\n * so whichever fires first wins.\n *\n * @param ms - Timeout in milliseconds.\n */\nexport function withTimeout(ms: number): ExecutorMiddleware {\n  return defineMiddleware(async (opts, next) => {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), ms);\n\n    const signal = opts.signal\n      ? anySignal([opts.signal, controller.signal])\n      : controller.signal;\n\n    try {\n      return await next({ ...opts, signal });\n    } finally {\n      clearTimeout(timer);\n    }\n  });\n}\n\n/**\n * Logs each request and its outcome (success duration or error).\n *\n * @param options.log - Custom logging function. Defaults to `console.log`.\n *\n * @example\n * ```ts\n * withLogger({ log: (msg, data) => logger.debug(msg, data) })\n * ```\n */\nexport function withLogger(options?: {\n  log?: (message: string, data?: unknown) => void;\n}): ExecutorMiddleware {\n  const log = options?.log ?? ((msg, data) => console.log(msg, data));\n  return defineMiddleware(async (opts, next) => {\n    const start = Date.now();\n    log(`[routar] ${opts.method} ${opts.url}`, { params: opts.params, body: opts.body });\n    try {\n      const result = await next(opts);\n      log(`[routar] ${opts.method} ${opts.url} — ${Date.now() - start}ms`);\n      return result;\n    } catch (err) {\n      log(`[routar] ${opts.method} ${opts.url} — error after ${Date.now() - start}ms`, err);\n      throw err;\n    }\n  });\n}\n\n/** Combines multiple AbortSignals into one that aborts when any of them fire. */\nfunction anySignal(signals: AbortSignal[]): AbortSignal {\n  const controller = new AbortController();\n  for (const signal of signals) {\n    if (signal.aborted) {\n      controller.abort();\n      return controller.signal;\n    }\n    signal.addEventListener('abort', () => controller.abort(), { once: true });\n  }\n  return controller.signal;\n}\n","export function serializeParams(params: Record<string, unknown>): URLSearchParams {\n  const result = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    if (value == null) continue;\n    if (Array.isArray(value)) {\n      for (const item of value) {\n        if (item != null) result.append(key, String(item));\n      }\n    } else {\n      result.append(key, String(value));\n    }\n  }\n  return result;\n}\n"]}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@routar/core",
+  "version": "0.1.0",
+  "description": "Schema-first HTTP API client — endpoint definitions, typed router, API client factory, and middleware system",
+  "keywords": ["api", "http", "typescript", "zod", "schema", "type-safe", "fetch", "axios", "middleware", "rest"],
+  "author": "Kyungbae Min",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/minr2kb/routar.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/minr2kb/routar#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "publishConfig": { "access": "public" }
+}