@cosmneo/onion-lasagna 0.2.0 → 0.2.1

package/dist/http/route/index.d.cts

@@ -1,77 +1,96 @@
 import { SchemaAdapter, InferOutput } from '../schema/types.cjs';
-import { H as HttpMethod, R as RouteDefinition, P as PathParams, h as ResponsesConfig, j as RouterConfig, k as RouterDefinition, D as DeepMergeTwo, n as DeepMergeAll } from '../../router-definition.type-ynBhT16T.cjs';
-export { C as ContentType, L as ContextConfig, N as ExternalDocs, E as ExtractPathParamNames, F as FlattenRouter, G as GetRoute, b as HasPathParams, f as HeadersConfig, a as HttpStatusCode, I as InferRouteBody, O as InferRouteContext, r as InferRouteHeaders, u as InferRouteMethod, v as InferRoutePath, q as InferRoutePathParams, p as InferRouteQuery, s as InferRouteResponse, t as InferRouteSuccessResponse, e as PathParamsConfig, o as PrettifyDeep, Q as QueryParamsConfig, d as RequestBodyConfig, M as RequestConfig, g as ResponseConfig, c as RouteDefinitionInput, i as RouteDocumentation, l as RouterEntry, m as RouterKeys, S as SecurityRequirement, z as buildPath, y as collectRoutes, J as getPathParamNames, K as hasPathParams, w as isRouteDefinition, x as isRouterDefinition, A as normalizePath, B as pathToRegex } from '../../router-definition.type-ynBhT16T.cjs';
+import { H as HttpMethod, y as ResponsesDefinition, S as SchemaFieldInput, R as RouteDefinition, P as PathParams, z as ExtractSuccessSchema, d as RouterConfig, A as RouterDefaults, e as RouterDefinition, D as DeepMergeTwo, h as DeepMergeAll } from '../../router-definition.type-BElX-Pl4.cjs';
+export { C as ContentType, M as ExternalDocs, E as ExtractPathParamNames, F as FlattenRouter, G as GetRoute, b as HasPathParams, a as HttpStatusCode, I as InferRouteBody, m as InferRouteContext, l as InferRouteHeaders, o as InferRouteMethod, p as InferRoutePath, k as InferRoutePathParams, j as InferRouteQuery, n as InferRouteResponse, i as PrettifyDeep, K as ResponseFieldConfig, c as RouteDocumentation, J as RouteFieldMeta, N as RouteRequestDefinition, f as RouterEntry, g as RouterKeys, B as SchemaFieldConfig, L as SecurityRequirement, t as buildPath, s as collectRoutes, w as getPathParamNames, x as hasPathParams, q as isRouteDefinition, r as isRouterDefinition, u as normalizePath, v as pathToRegex } from '../../router-definition.type-BElX-Pl4.cjs';
 
 /**
- * @fileoverview Factory function for creating route definitions.
+ * @fileoverview Factory function for creating route definitions (v2).
  *
- * The `defineRoute` function is the main entry point for defining routes
- * in the unified system. It provides type inference and validation
- * for route configurations.
+ * The `defineRoute` function is the main entry point for defining routes.
+ * Request schemas are grouped under a `request` field, while responses
+ * are defined via the `responses` field with per-status-code config.
+ *
+ * Each schema field accepts either a bare `SchemaAdapter` or an object with
+ * metadata: `{ schema, description?, contentType?, required? }`.
+ *
+ * The success response type is inferred from the first 2xx status with a schema.
  *
  * @module unified/route/define-route
  */
 
-/**
- * Request body configuration input.
- */
-interface BodyInput<TSchema extends SchemaAdapter> {
-    readonly schema: TSchema;
-    readonly contentType?: string;
-    readonly required?: boolean;
-    readonly description?: string;
-}
-/**
- * Query parameters configuration input.
- */
-interface QueryInput<TSchema extends SchemaAdapter> {
-    readonly schema: TSchema;
-    readonly description?: string;
-}
-/**
- * Path parameters configuration input.
- */
-interface ParamsInput<TSchema extends SchemaAdapter> {
-    readonly schema: TSchema;
-    readonly description?: string;
-}
-/**
- * Headers configuration input.
- */
-interface HeadersInput<TSchema extends SchemaAdapter> {
-    readonly schema: TSchema;
-    readonly description?: string;
-}
-/**
- * Context configuration input.
- * Used to validate and type context data from middleware (e.g., JWT payload).
- */
-interface ContextInput<TSchema extends SchemaAdapter> {
-    readonly schema: TSchema;
-    readonly description?: string;
-}
-/**
- * Response configuration input.
- */
-interface ResponseInput<TSchema extends SchemaAdapter | undefined = undefined> {
-    readonly description: string;
-    readonly schema?: TSchema;
-    readonly contentType?: string;
-}
 /**
  * Complete input for defineRoute.
+ *
+ * @example GET with query and response
+ * ```typescript
+ * defineRoute({
+ *   method: 'GET',
+ *   path: '/api/users',
+ *   request: {
+ *     query: zodSchema(z.object({ page: z.coerce.number().default(1) })),
+ *   },
+ *   responses: {
+ *     200: { schema: zodSchema(userListSchema) },
+ *   },
+ *   docs: { summary: 'List users', tags: ['Users'] },
+ * })
+ * ```
+ *
+ * @example POST with body and multiple statuses
+ * ```typescript
+ * defineRoute({
+ *   method: 'POST',
+ *   path: '/api/users',
+ *   request: {
+ *     body: zodSchema(createUserSchema),
+ *   },
+ *   responses: {
+ *     201: { schema: zodSchema(userSchema), description: 'Created' },
+ *     400: { description: 'Validation error' },
+ *     409: { description: 'Email already in use' },
+ *   },
+ * })
+ * ```
+ *
+ * @example DELETE with 204
+ * ```typescript
+ * defineRoute({
+ *   method: 'DELETE',
+ *   path: '/api/users/:userId',
+ *   responses: {
+ *     204: { description: 'User deleted' },
+ *     404: { description: 'User not found' },
+ *   },
+ * })
+ * ```
  */
-interface DefineRouteInput<TMethod extends HttpMethod, TPath extends string, TBody extends SchemaAdapter | undefined = undefined, TQuery extends SchemaAdapter | undefined = undefined, TParams extends SchemaAdapter | undefined = undefined, THeaders extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined, TResponses extends Record<number, ResponseInput<SchemaAdapter | undefined>> = Record<number, never>> {
+interface DefineRouteInput<TMethod extends HttpMethod, TPath extends string, TBody extends SchemaAdapter | undefined = undefined, TQuery extends SchemaAdapter | undefined = undefined, TParams extends SchemaAdapter | undefined = undefined, THeaders extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined, TResponses extends ResponsesDefinition | undefined = undefined> {
+    /** HTTP method for this route. */
     readonly method: TMethod;
+    /** URL path pattern with optional parameters (`:param` or `{param}`). */
     readonly path: TPath;
+    /** Request schemas (body, query, params, headers, context). */
     readonly request?: {
-        readonly body?: TBody extends SchemaAdapter ? BodyInput<TBody> : undefined;
-        readonly query?: TQuery extends SchemaAdapter ? QueryInput<TQuery> : undefined;
-        readonly params?: TParams extends SchemaAdapter ? ParamsInput<TParams> : undefined;
-        readonly headers?: THeaders extends SchemaAdapter ? HeadersInput<THeaders> : undefined;
-        readonly context?: TContext extends SchemaAdapter ? ContextInput<TContext> : undefined;
+        /** Request body schema (or `{ schema, description?, contentType?, required? }`). */
+        readonly body?: TBody extends SchemaAdapter ? SchemaFieldInput<TBody> : TBody;
+        /** Query parameters schema (or `{ schema, description? }`). */
+        readonly query?: TQuery extends SchemaAdapter ? SchemaFieldInput<TQuery> : TQuery;
+        /** Path parameters schema (or `{ schema, description? }`). If omitted, inferred from path template. */
+        readonly params?: TParams extends SchemaAdapter ? SchemaFieldInput<TParams> : TParams;
+        /** Headers schema (or `{ schema, description? }`). */
+        readonly headers?: THeaders extends SchemaAdapter ? SchemaFieldInput<THeaders> : THeaders;
+        /** Context schema (or `{ schema, description? }`). */
+        readonly context?: TContext extends SchemaAdapter ? SchemaFieldInput<TContext> : TContext;
     };
-    readonly responses: TResponses;
+    /**
+     * Per-status response definitions.
+     *
+     * Each key is an HTTP status code. Each value can have:
+     * - `schema` — response body schema (drives type inference for 2xx)
+     * - `description` — OpenAPI response description
+     * - `contentType` — response content type (default: `application/json`)
+     */
+    readonly responses?: TResponses;
+    /** OpenAPI documentation. */
     readonly docs?: {
         readonly summary?: string;
         readonly description?: string;
@@ -85,109 +104,29 @@ interface DefineRouteInput<TMethod extends HttpMethod, TPath extends string, TBo
         };
     };
 }
-/**
- * Converts response inputs to response config type.
- */
-type ToResponsesConfig<T extends Record<number, ResponseInput<SchemaAdapter | undefined>>> = {
-    [K in keyof T]: T[K] extends ResponseInput<infer TSchema> ? {
-        description: string;
-        schema: TSchema extends SchemaAdapter ? TSchema : undefined;
-        contentType?: string;
-    } : never;
-};
+type ResolveBody<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+type ResolveQuery<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+type ResolveParams<T, TPath extends string> = T extends SchemaAdapter ? InferOutput<T> : PathParams<TPath>;
+type ResolveHeaders<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+type ResolveContext<T> = T extends SchemaAdapter ? InferOutput<T> : undefined;
+type ResolveResponse<T> = T extends ResponsesDefinition ? ExtractSuccessSchema<T> extends SchemaAdapter ? InferOutput<ExtractSuccessSchema<T>> : undefined : undefined;
 /**
  * Creates a route definition from the provided configuration.
  *
- * This is the main entry point for defining routes in the unified system.
- * The resulting definition can be used for:
- * - Type-safe client generation
- * - Server-side route registration
- * - OpenAPI specification generation
+ * This is the main entry point for defining routes. The resulting definition
+ * can be used for type-safe client generation, server-side route registration,
+ * and OpenAPI specification generation.
  *
- * @param input - Route configuration
+ * @param input - Route configuration with request schemas and responses
  * @returns A frozen RouteDefinition object with full type information
- *
- * @example Basic GET route
- * ```typescript
- * import { defineRoute } from '@cosmneo/onion-lasagna/http';
- * import { zodSchema, z } from '@cosmneo/onion-lasagna/http/schema/zod';
- *
- * const listUsers = defineRoute({
- *   method: 'GET',
- *   path: '/api/users',
- *   request: {
- *     query: {
- *       schema: zodSchema(z.object({
- *         page: z.coerce.number().optional().default(1),
- *         limit: z.coerce.number().optional().default(20),
- *       })),
- *     },
- *   },
- *   responses: {
- *     200: {
- *       description: 'List of users',
- *       schema: zodSchema(z.object({
- *         users: z.array(z.object({
- *           id: z.string(),
- *           name: z.string(),
- *         })),
- *         total: z.number(),
- *       })),
- *     },
- *   },
- *   docs: {
- *     summary: 'List all users',
- *     tags: ['Users'],
- *   },
- * });
- * ```
- *
- * @example POST route with path parameters
- * ```typescript
- * const createTask = defineRoute({
- *   method: 'POST',
- *   path: '/api/projects/:projectId/tasks',
- *   request: {
- *     body: {
- *       schema: zodSchema(z.object({
- *         title: z.string().min(1).max(200),
- *         description: z.string().optional(),
- *       })),
- *     },
- *   },
- *   responses: {
- *     201: {
- *       description: 'Task created',
- *       schema: zodSchema(z.object({
- *         id: z.string().uuid(),
- *         title: z.string(),
- *         projectId: z.string(),
- *         createdAt: z.string().datetime(),
- *       })),
- *     },
- *     400: {
- *       description: 'Invalid request',
- *     },
- *     404: {
- *       description: 'Project not found',
- *     },
- *   },
- *   docs: {
- *     summary: 'Create a new task',
- *     tags: ['Tasks'],
- *     operationId: 'createTask',
- *   },
- * });
- * ```
  */
-declare function defineRoute<TMethod extends HttpMethod, TPath extends string, TBody extends SchemaAdapter | undefined = undefined, TQuery extends SchemaAdapter | undefined = undefined, TParams extends SchemaAdapter | undefined = undefined, THeaders extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined, TResponses extends Record<number, ResponseInput<SchemaAdapter | undefined>> = Record<number, never>>(input: DefineRouteInput<TMethod, TPath, TBody, TQuery, TParams, THeaders, TContext, TResponses>): RouteDefinition<TMethod, TPath, TBody extends SchemaAdapter ? InferOutput<TBody> : undefined, TQuery extends SchemaAdapter ? InferOutput<TQuery> : undefined, TParams extends SchemaAdapter ? InferOutput<TParams> : PathParams<TPath>, THeaders extends SchemaAdapter ? InferOutput<THeaders> : undefined, TContext extends SchemaAdapter ? InferOutput<TContext> : undefined, ToResponsesConfig<TResponses> & ResponsesConfig>;
+declare function defineRoute<TMethod extends HttpMethod, TPath extends string, TBody extends SchemaAdapter | undefined = undefined, TQuery extends SchemaAdapter | undefined = undefined, TParams extends SchemaAdapter | undefined = undefined, THeaders extends SchemaAdapter | undefined = undefined, TContext extends SchemaAdapter | undefined = undefined, TResponses extends ResponsesDefinition | undefined = undefined>(input: DefineRouteInput<TMethod, TPath, TBody, TQuery, TParams, THeaders, TContext, TResponses>): RouteDefinition<TMethod, TPath, ResolveBody<TBody>, ResolveQuery<TQuery>, ResolveParams<TParams, TPath>, ResolveHeaders<THeaders>, ResolveContext<TContext>, ResolveResponse<TResponses>>;
 
 /**
  * @fileoverview Factory function for creating router definitions.
  *
  * The `defineRouter` function groups routes into a hierarchical structure
- * that enables organized API clients, OpenAPI tag grouping, and structured
- * server route registration.
+ * with optional router-level defaults for context and tags.
  *
  * @module unified/route/define-router
  */
@@ -199,18 +138,25 @@ interface DefineRouterOptions {
     /**
      * Base path prefix for all routes in this router.
      * Will be prepended to all route paths.
+     */
+    readonly basePath?: string;
+    /**
+     * Default values applied to all child routes.
      *
      * @example
      * ```typescript
-     * defineRouter({ ... }, { basePath: '/api/v1' })
+     * defineRouter({
+     *   list: listUsersRoute,
+     *   get: getUserRoute,
+     * }, {
+     *   defaults: {
+     *     context: zodSchema(executionContextSchema),
+     *     tags: ['Users'],
+     *   },
+     * })
      * ```
      */
-    readonly basePath?: string;
-    /**
-     * Default tags for all routes in this router.
-     * Will be merged with route-specific tags.
-     */
-    readonly tags?: readonly string[];
+    readonly defaults?: RouterDefaults;
 }
 /**
  * Creates a router definition from a configuration object.
@@ -219,7 +165,7 @@ interface DefineRouterOptions {
  * - Organized API structure with nested namespaces
  * - Typed client method generation
  * - OpenAPI tag grouping
- * - Server route registration
+ * - Router-level defaults for context and tags
  *
  * @param routes - Object containing routes and nested routers
  * @param options - Optional router configuration
@@ -227,90 +173,33 @@ interface DefineRouterOptions {
  *
  * @example Basic router
  * ```typescript
- * import { defineRouter } from '@cosmneo/onion-lasagna/http';
- *
  * const api = defineRouter({
  *   users: {
  *     list: listUsersRoute,
  *     get: getUserRoute,
  *     create: createUserRoute,
- *     update: updateUserRoute,
- *     delete: deleteUserRoute,
- *   },
- *   posts: {
- *     list: listPostsRoute,
- *     get: getPostRoute,
- *     create: createPostRoute,
  *   },
  * });
- *
- * // Client usage:
- * // client.users.list({ query: { page: 1 } })
- * // client.users.get({ params: { id: '123' } })
- * // client.posts.create({ body: { title: 'Hello' } })
  * ```
  *
- * @example Nested routers
+ * @example With router-level defaults
  * ```typescript
- * const projectRouter = defineRouter({
- *   list: listProjectsRoute,
- *   get: getProjectRoute,
- *   tasks: {
- *     list: listTasksRoute,
- *     create: createTaskRoute,
- *     update: updateTaskRoute,
- *   },
- *   members: {
- *     list: listMembersRoute,
- *     add: addMemberRoute,
- *     remove: removeMemberRoute,
- *   },
- * });
- *
  * const api = defineRouter({
- *   projects: projectRouter.routes,
- *   users: userRouter.routes,
- * });
- *
- * // Client usage:
- * // client.projects.tasks.create({ params: { projectId: '123' }, body: { ... } })
- * ```
- *
- * @example With base path and tags
- * ```typescript
- * const adminApi = defineRouter({
- *   users: {
- *     list: listUsersRoute,
- *     ban: banUserRoute,
- *   },
- *   analytics: {
- *     dashboard: getDashboardRoute,
- *     reports: getReportsRoute,
- *   },
+ *   list: listUsersRoute,
+ *   get: getUserRoute,
  * }, {
- *   basePath: '/admin',
- *   tags: ['Admin'],
+ *   basePath: '/api/v1',
+ *   defaults: {
+ *     context: zodSchema(executionContextSchema),
+ *     tags: ['Users'],
+ *   },
  * });
+ * // Context is applied to all routes that don't define their own.
+ * // Tags are merged with each route's existing tags.
  * ```
  */
 declare function defineRouter<T extends RouterConfig>(routes: T, options?: DefineRouterOptions): RouterDefinition<T>;
 type RouterInput<T extends RouterConfig> = T | RouterDefinition<T>;
-/**
- * Merges multiple routers into a single router with deep merge.
- *
- * Overlapping sub-router keys are recursively merged instead of overwritten.
- * Leaf routes (RouteDefinition) use last-one-wins semantics.
- *
- * @example
- * ```typescript
- * const api = mergeRouters(
- *   userRouter,
- *   organizationRouter,
- *   feedbackRouter,
- * );
- * // If all three define `users`, their sub-routes are deep-merged.
- * ```
- */
 declare function mergeRouters<T1 extends RouterConfig, T2 extends RouterConfig>(r1: RouterInput<T1>, r2: RouterInput<T2>): RouterDefinition<DeepMergeTwo<T1, T2>>;
 declare function mergeRouters<T1 extends RouterConfig, T2 extends RouterConfig, T3 extends RouterConfig>(r1: RouterInput<T1>, r2: RouterInput<T2>, r3: RouterInput<T3>): RouterDefinition<DeepMergeAll<[T1, T2, T3]>>;
 declare function mergeRouters<T1 extends RouterConfig, T2 extends RouterConfig, T3 extends RouterConfig, T4 extends RouterConfig>(r1: RouterInput<T1>, r2: RouterInput<T2>, r3: RouterInput<T3>, r4: RouterInput<T4>): RouterDefinition<DeepMergeAll<[T1, T2, T3, T4]>>;
@@ -320,4 +209,21 @@ declare function mergeRouters<T1 extends RouterConfig, T2 extends RouterConfig,
 declare function mergeRouters<T1 extends RouterConfig, T2 extends RouterConfig, T3 extends RouterConfig, T4 extends RouterConfig, T5 extends RouterConfig, T6 extends RouterConfig, T7 extends RouterConfig, T8 extends RouterConfig>(r1: RouterInput<T1>, r2: RouterInput<T2>, r3: RouterInput<T3>, r4: RouterInput<T4>, r5: RouterInput<T5>, r6: RouterInput<T6>, r7: RouterInput<T7>, r8: RouterInput<T8>): RouterDefinition<DeepMergeAll<[T1, T2, T3, T4, T5, T6, T7, T8]>>;
 declare function mergeRouters(...routers: RouterInput<RouterConfig>[]): RouterDefinition<RouterConfig>;
 
-export { DeepMergeAll, DeepMergeTwo, type DefineRouterOptions, HttpMethod, PathParams, ResponsesConfig, RouteDefinition, RouterConfig, RouterDefinition, defineRoute, defineRouter, mergeRouters };
+/**
+ * @fileoverview Route utility functions.
+ *
+ * @module unified/route/utils
+ */
+/**
+ * Generates an operationId from a router key path.
+ *
+ * Converts dotted key paths to camelCase:
+ * - `"users.list"` → `"usersList"`
+ * - `"organizations.members.get"` → `"organizationsMembersGet"`
+ *
+ * @param key - The dotted router key path
+ * @returns A camelCase operationId string
+ */
+declare function generateOperationId(key: string): string;
+
+export { DeepMergeAll, DeepMergeTwo, type DefineRouterOptions, ExtractSuccessSchema, HttpMethod, PathParams, ResponsesDefinition, RouteDefinition, RouterConfig, RouterDefaults, RouterDefinition, SchemaFieldInput, defineRoute, defineRouter, generateOperationId, mergeRouters };