kontract 0.1.0

package/dist/builder/define-endpoint.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Type-safe endpoint builder with automatic type inference.
+ *
+ * Unlike decorators, this function-based API provides full TypeScript
+ * type inference for body, query, and params without manual annotations.
+ *
+ * @example
+ * ```typescript
+ * const createUser = defineEndpoint({
+ *   route: 'POST /api/users',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body }) => {
+ *   // body is automatically typed as Static<typeof CreateUserRequest>
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ */
+import type { TSchema, Static } from '@sinclair/typebox';
+import type { AnyResponse } from '../response/types.js';
+import type { HttpMethod, AuthLevel, ResponseDefinition } from '../metadata/types.js';
+/**
+ * Route string format: "METHOD /path"
+ */
+type RouteString = `${'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'} /${string}`;
+/**
+ * Response configuration for endpoints.
+ */
+type ResponsesConfig = Record<number, TSchema | null | {
+    schema: TSchema | null;
+    description?: string;
+}>;
+/**
+ * Configuration for defineEndpoint.
+ */
+export interface EndpointConfig<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Route in format "METHOD /path" (e.g., "POST /api/users") */
+    route: RouteString;
+    /** Short summary for OpenAPI docs */
+    summary?: string;
+    /** Detailed description for OpenAPI docs */
+    description?: string;
+    /** Unique operation ID for OpenAPI */
+    operationId?: string;
+    /** Mark endpoint as deprecated */
+    deprecated?: boolean;
+    /** Authentication requirement */
+    auth?: AuthLevel;
+    /** Request body schema */
+    body?: TBody;
+    /** Query parameters schema */
+    query?: TQuery;
+    /** Path parameters schema */
+    params?: TParams;
+    /** Response definitions by status code */
+    responses: ResponsesConfig;
+}
+/**
+ * Context object passed to endpoint handlers.
+ * Types are automatically inferred from the endpoint configuration.
+ */
+export interface HandlerContext<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Validated request body (typed from body schema) */
+    body: TBody extends TSchema ? Static<TBody> : undefined;
+    /** Validated query parameters (typed from query schema) */
+    query: TQuery extends TSchema ? Static<TQuery> : undefined;
+    /** Validated path parameters (typed from params schema) */
+    params: TParams extends TSchema ? Static<TParams> : undefined;
+    /** Authenticated user (available when auth is 'required' or 'optional') */
+    user: unknown;
+    /** Raw framework request object (FastifyRequest, Hono Context, etc.) */
+    raw: unknown;
+}
+/**
+ * Handler function type with inferred parameter types.
+ */
+export type EndpointHandler<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> = (ctx: HandlerContext<TBody, TQuery, TParams>) => Promise<AnyResponse> | AnyResponse;
+/**
+ * Endpoint definition returned by defineEndpoint.
+ * Contains configuration and handler for registration with adapters.
+ */
+export interface EndpointDefinition<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Type discriminator */
+    readonly __type: 'endpoint';
+    /** Parsed HTTP method */
+    readonly method: HttpMethod;
+    /** Parsed path */
+    readonly path: string;
+    /** Original configuration */
+    readonly config: EndpointConfig<TBody, TQuery, TParams>;
+    /** Normalized response definitions */
+    readonly responses: Record<number, ResponseDefinition>;
+    /** Handler function */
+    readonly handler: EndpointHandler<TBody, TQuery, TParams>;
+}
+/**
+ * Define a type-safe API endpoint with automatic type inference.
+ *
+ * This function-based approach provides full TypeScript type inference
+ * for request body, query parameters, and path parameters without
+ * requiring manual `Static<typeof Schema>` annotations.
+ *
+ * @param config - Endpoint configuration including route, schemas, and responses
+ * @param handler - Async function that handles the request
+ * @returns EndpointDefinition for registration with framework adapters
+ *
+ * @example Basic GET endpoint
+ * ```typescript
+ * const getUser = defineEndpoint({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: null,
+ *   },
+ * }, async ({ params }) => {
+ *   // params.id is typed as string
+ *   const user = await findUser(params.id)
+ *   return user ? ok(User, user) : apiError.notFound()
+ * })
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * const createUser = defineEndpoint({
+ *   route: 'POST /api/users',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body, user }) => {
+ *   // body is typed as { name: string; email: string }
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ *
+ * @example GET with query parameters
+ * ```typescript
+ * const listUsers = defineEndpoint({
+ *   route: 'GET /api/users',
+ *   query: Type.Object({
+ *     page: Type.Optional(Type.Integer({ minimum: 1, default: 1 })),
+ *     limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+ *   }),
+ *   responses: { 200: { schema: UserList } },
+ * }, async ({ query }) => {
+ *   // query.page and query.limit are typed
+ *   return ok(UserList, await db.users.list(query))
+ * })
+ * ```
+ */
+export declare function defineEndpoint<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined>(config: EndpointConfig<TBody, TQuery, TParams>, handler: EndpointHandler<TBody, TQuery, TParams>): EndpointDefinition<TBody, TQuery, TParams>;
+/**
+ * Type guard to check if a value is an EndpointDefinition.
+ */
+export declare function isEndpointDefinition(value: unknown): value is EndpointDefinition;
+export {};
+//# sourceMappingURL=define-endpoint.d.ts.map

package/dist/builder/define-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-endpoint.d.ts","sourceRoot":"","sources":["../../src/builder/define-endpoint.ts"],"names":[],"mappings":"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"}

package/dist/builder/define-endpoint.js

@@ -0,0 +1,103 @@
+/**
+ * Parse a route string into method and path.
+ */
+function parseRoute(route) {
+    const spaceIndex = route.indexOf(' ');
+    const method = route.slice(0, spaceIndex).toLowerCase();
+    const path = route.slice(spaceIndex + 1);
+    return [method, path];
+}
+/**
+ * Normalize response definitions to consistent format.
+ */
+function normalizeResponses(responses) {
+    const normalized = {};
+    for (const [status, value] of Object.entries(responses)) {
+        if (value === null) {
+            normalized[Number(status)] = { schema: null };
+        }
+        else if (typeof value === 'object' && 'schema' in value) {
+            normalized[Number(status)] = value;
+        }
+        else {
+            normalized[Number(status)] = { schema: value };
+        }
+    }
+    return normalized;
+}
+/**
+ * Define a type-safe API endpoint with automatic type inference.
+ *
+ * This function-based approach provides full TypeScript type inference
+ * for request body, query parameters, and path parameters without
+ * requiring manual `Static<typeof Schema>` annotations.
+ *
+ * @param config - Endpoint configuration including route, schemas, and responses
+ * @param handler - Async function that handles the request
+ * @returns EndpointDefinition for registration with framework adapters
+ *
+ * @example Basic GET endpoint
+ * ```typescript
+ * const getUser = defineEndpoint({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: null,
+ *   },
+ * }, async ({ params }) => {
+ *   // params.id is typed as string
+ *   const user = await findUser(params.id)
+ *   return user ? ok(User, user) : apiError.notFound()
+ * })
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * const createUser = defineEndpoint({
+ *   route: 'POST /api/users',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body, user }) => {
+ *   // body is typed as { name: string; email: string }
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ *
+ * @example GET with query parameters
+ * ```typescript
+ * const listUsers = defineEndpoint({
+ *   route: 'GET /api/users',
+ *   query: Type.Object({
+ *     page: Type.Optional(Type.Integer({ minimum: 1, default: 1 })),
+ *     limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+ *   }),
+ *   responses: { 200: { schema: UserList } },
+ * }, async ({ query }) => {
+ *   // query.page and query.limit are typed
+ *   return ok(UserList, await db.users.list(query))
+ * })
+ * ```
+ */
+export function defineEndpoint(config, handler) {
+    const [method, path] = parseRoute(config.route);
+    return {
+        __type: 'endpoint',
+        method,
+        path,
+        config,
+        responses: normalizeResponses(config.responses),
+        handler,
+    };
+}
+/**
+ * Type guard to check if a value is an EndpointDefinition.
+ */
+export function isEndpointDefinition(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && '__type' in value
+        && value.__type === 'endpoint');
+}
+//# sourceMappingURL=define-endpoint.js.map

package/dist/builder/define-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-endpoint.js","sourceRoot":"","sources":["../../src/builder/define-endpoint.ts"],"names":[],"mappings":"AAmHA;;GAEG;AACH,SAAS,UAAU,CAAC,KAAkB;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAgB,CAAA;IACrE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IACxC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,SAA0B;IACpD,MAAM,UAAU,GAAuC,EAAE,CAAA;IAEzD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;QAC/C,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC1D,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAA2B,CAAA;QAC1D,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAgB,EAAE,CAAA;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,UAAU,cAAc,CAK5B,MAA8C,EAC9C,OAAgD;IAEhD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAE/C,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,MAAM;QACN,IAAI;QACJ,MAAM;QACN,SAAS,EAAE,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC;QAC/C,OAAO;KACR,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,QAAQ,IAAI,KAAK;WAChB,KAA6B,CAAC,MAAM,KAAK,UAAU,CACxD,CAAA;AACH,CAAC"}

package/dist/builder/define-route.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Type-safe route builder with automatic type inference.
+ *
+ * Unlike decorators, this function-based API provides full TypeScript
+ * type inference for body, query, and params without manual annotations.
+ *
+ * @example
+ * ```typescript
+ * const createUser = defineRoute({
+ *   route: 'POST /api/users',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body }) => {
+ *   // body is automatically typed as Static<typeof CreateUserRequest>
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ */
+import type { TSchema, Static } from '@sinclair/typebox';
+import type { AnyResponse } from '../response/types.js';
+import type { HttpMethod, AuthLevel, ResponseDefinition } from '../metadata/types.js';
+/**
+ * Route string format: "METHOD /path"
+ */
+type RouteString = `${'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'} /${string}`;
+/**
+ * Extract the path portion from a route string.
+ * @example ExtractPathFromRoute<'GET /users/:id'> = '/users/:id'
+ */
+type ExtractPathFromRoute<T extends string> = T extends `${string} ${infer Path}` ? Path : string;
+/**
+ * Response configuration for routes.
+ */
+type ResponsesConfig = Record<number, TSchema | null | {
+    schema: TSchema | null;
+    description?: string;
+}>;
+/**
+ * Configuration for defineRoute.
+ *
+ * @typeParam TRoute - The route string type (e.g., 'GET /users/:id') for path param inference
+ */
+export interface RouteConfig<TRoute extends RouteString = RouteString, TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Route in format "METHOD /path" (e.g., "POST /api/users") */
+    route: TRoute;
+    /** Short summary for OpenAPI docs */
+    summary?: string;
+    /** Detailed description for OpenAPI docs */
+    description?: string;
+    /** Unique operation ID for OpenAPI */
+    operationId?: string;
+    /** Mark route as deprecated */
+    deprecated?: boolean;
+    /** Authentication requirement */
+    auth?: AuthLevel;
+    /** Request body schema */
+    body?: TBody;
+    /** Query parameters schema */
+    query?: TQuery;
+    /** Path parameters schema */
+    params?: TParams;
+    /** Response definitions by status code */
+    responses: ResponsesConfig;
+}
+/**
+ * Context object passed to route handlers.
+ * Types are automatically inferred from the route configuration.
+ */
+export interface HandlerContext<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Validated request body (typed from body schema) */
+    body: TBody extends TSchema ? Static<TBody> : undefined;
+    /** Validated query parameters (typed from query schema) */
+    query: TQuery extends TSchema ? Static<TQuery> : undefined;
+    /** Validated path parameters (typed from params schema) */
+    params: TParams extends TSchema ? Static<TParams> : undefined;
+    /** Authenticated user (available when auth is 'required' or 'optional') */
+    user: unknown;
+    /** Raw framework request object (FastifyRequest, Hono Context, etc.) */
+    raw: unknown;
+}
+/**
+ * Handler function type with inferred parameter types.
+ */
+export type RouteHandler<TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> = (ctx: HandlerContext<TBody, TQuery, TParams>) => Promise<AnyResponse> | AnyResponse;
+/**
+ * Route definition returned by defineRoute.
+ * Contains configuration and optionally a handler for registration with adapters.
+ *
+ * When used without a handler, the route is a "contract" that can be shared
+ * with clients for type-safe API calls.
+ *
+ * @typeParam TPath - The route path as a literal string type (e.g., '/users/:id')
+ *   Used for path parameter inference when TParams is not explicitly provided.
+ */
+export interface RouteDefinition<TPath extends string = string, TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined> {
+    /** Type discriminator */
+    readonly __type: 'route';
+    /** Parsed HTTP method */
+    readonly method: HttpMethod;
+    /** Parsed path (typed as literal for param inference) */
+    readonly path: TPath;
+    /** Original configuration */
+    readonly config: RouteConfig<RouteString, TBody, TQuery, TParams>;
+    /** Normalized response definitions */
+    readonly responses: Record<number, ResponseDefinition>;
+    /** Handler function (optional - omitted for contract-only definitions) */
+    readonly handler?: RouteHandler<TBody, TQuery, TParams>;
+}
+/**
+ * Define a type-safe API route with automatic type inference.
+ *
+ * This function-based approach provides full TypeScript type inference
+ * for request body, query parameters, and path parameters without
+ * requiring manual `Static<typeof Schema>` annotations.
+ *
+ * @param config - Route configuration including path, schemas, and responses
+ * @param handler - Optional async function that handles the request.
+ *   When omitted, creates a "contract-only" definition that can be shared with clients.
+ * @returns RouteDefinition for registration with framework adapters or client generation
+ *
+ * @example Basic GET route with handler (server-side)
+ * ```typescript
+ * const getUser = defineRoute({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: null,
+ *   },
+ * }, async ({ params }) => {
+ *   // params.id is typed as string
+ *   const user = await findUser(params.id)
+ *   return user ? ok(User, user) : apiError.notFound()
+ * })
+ * ```
+ *
+ * @example Contract-only route (for client generation)
+ * ```typescript
+ * // In shared contracts file - can be imported by both server and client
+ * export const getUserContract = defineRoute({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: { schema: ApiError },
+ *   },
+ * })
+ *
+ * // On server - attach handler
+ * const getUser = defineRoute(getUserContract.config, async ({ params }) => { ... })
+ *
+ * // On client - use contract for type-safe calls
+ * const client = createClient({ controllers: { users: usersContracts }, ... })
+ * const result = await client.users.getUser({ params: { id: '123' } })
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * const createUser = defineRoute({
+ *   route: 'POST /api/users',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body, user }) => {
+ *   // body is typed as { name: string; email: string }
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ *
+ * @example GET with query parameters
+ * ```typescript
+ * const listUsers = defineRoute({
+ *   route: 'GET /api/users',
+ *   query: Type.Object({
+ *     page: Type.Optional(Type.Integer({ minimum: 1, default: 1 })),
+ *     limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+ *   }),
+ *   responses: { 200: { schema: UserList } },
+ * }, async ({ query }) => {
+ *   // query.page and query.limit are typed
+ *   return ok(UserList, await db.users.list(query))
+ * })
+ * ```
+ */
+export declare function defineRoute<TRoute extends RouteString, TBody extends TSchema | undefined = undefined, TQuery extends TSchema | undefined = undefined, TParams extends TSchema | undefined = undefined>(config: RouteConfig<TRoute, TBody, TQuery, TParams>, handler?: RouteHandler<TBody, TQuery, TParams>): RouteDefinition<ExtractPathFromRoute<TRoute>, TBody, TQuery, TParams>;
+/**
+ * Type guard to check if a value is a RouteDefinition.
+ */
+export declare function isRouteDefinition(value: unknown): value is RouteDefinition;
+export {};
+//# sourceMappingURL=define-route.d.ts.map

package/dist/builder/define-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-route.d.ts","sourceRoot":"","sources":["../../src/builder/define-route.ts"],"names":[],"mappings":"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"}

package/dist/builder/define-route.js

@@ -0,0 +1,124 @@
+/**
+ * Parse a route string into method and path.
+ */
+function parseRoute(route) {
+    const spaceIndex = route.indexOf(' ');
+    const method = route.slice(0, spaceIndex).toLowerCase();
+    const path = route.slice(spaceIndex + 1);
+    return [method, path];
+}
+/**
+ * Normalize response definitions to consistent format.
+ */
+function normalizeResponses(responses) {
+    const normalized = {};
+    for (const [status, value] of Object.entries(responses)) {
+        if (value === null) {
+            normalized[Number(status)] = { schema: null };
+        }
+        else if (typeof value === 'object' && 'schema' in value) {
+            normalized[Number(status)] = value;
+        }
+        else {
+            normalized[Number(status)] = { schema: value };
+        }
+    }
+    return normalized;
+}
+/**
+ * Define a type-safe API route with automatic type inference.
+ *
+ * This function-based approach provides full TypeScript type inference
+ * for request body, query parameters, and path parameters without
+ * requiring manual `Static<typeof Schema>` annotations.
+ *
+ * @param config - Route configuration including path, schemas, and responses
+ * @param handler - Optional async function that handles the request.
+ *   When omitted, creates a "contract-only" definition that can be shared with clients.
+ * @returns RouteDefinition for registration with framework adapters or client generation
+ *
+ * @example Basic GET route with handler (server-side)
+ * ```typescript
+ * const getUser = defineRoute({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: null,
+ *   },
+ * }, async ({ params }) => {
+ *   // params.id is typed as string
+ *   const user = await findUser(params.id)
+ *   return user ? ok(User, user) : apiError.notFound()
+ * })
+ * ```
+ *
+ * @example Contract-only route (for client generation)
+ * ```typescript
+ * // In shared contracts file - can be imported by both server and client
+ * export const getUserContract = defineRoute({
+ *   route: 'GET /api/users/:id',
+ *   params: Type.Object({ id: Type.String({ format: 'uuid' }) }),
+ *   responses: {
+ *     200: { schema: User },
+ *     404: { schema: ApiError },
+ *   },
+ * })
+ *
+ * // On server - attach handler
+ * const getUser = defineRoute(getUserContract.config, async ({ params }) => { ... })
+ *
+ * // On client - use contract for type-safe calls
+ * const client = createClient({ controllers: { users: usersContracts }, ... })
+ * const result = await client.users.getUser({ params: { id: '123' } })
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * const createUser = defineRoute({
+ *   route: 'POST /api/users',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: { 201: { schema: User } },
+ * }, async ({ body, user }) => {
+ *   // body is typed as { name: string; email: string }
+ *   return created(User, await db.users.create(body))
+ * })
+ * ```
+ *
+ * @example GET with query parameters
+ * ```typescript
+ * const listUsers = defineRoute({
+ *   route: 'GET /api/users',
+ *   query: Type.Object({
+ *     page: Type.Optional(Type.Integer({ minimum: 1, default: 1 })),
+ *     limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+ *   }),
+ *   responses: { 200: { schema: UserList } },
+ * }, async ({ query }) => {
+ *   // query.page and query.limit are typed
+ *   return ok(UserList, await db.users.list(query))
+ * })
+ * ```
+ */
+export function defineRoute(config, handler) {
+    const [method, path] = parseRoute(config.route);
+    return {
+        __type: 'route',
+        method,
+        path: path,
+        config,
+        responses: normalizeResponses(config.responses),
+        handler,
+    };
+}
+/**
+ * Type guard to check if a value is a RouteDefinition.
+ */
+export function isRouteDefinition(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && '__type' in value
+        && value.__type === 'route');
+}
+//# sourceMappingURL=define-route.js.map

package/dist/builder/define-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-route.js","sourceRoot":"","sources":["../../src/builder/define-route.ts"],"names":[],"mappings":"AAmIA;;GAEG;AACH,SAAS,UAAU,CAAC,KAAkB;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAgB,CAAA;IACrE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IACxC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,SAA0B;IACpD,MAAM,UAAU,GAAuC,EAAE,CAAA;IAEzD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;QAC/C,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC1D,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAA2B,CAAA;QAC1D,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAgB,EAAE,CAAA;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,UAAU,WAAW,CAMzB,MAAmD,EACnD,OAA8C;IAE9C,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAE/C,OAAO;QACL,MAAM,EAAE,OAAO;QACf,MAAM;QACN,IAAI,EAAE,IAAoC;QAC1C,MAAM;QACN,SAAS,EAAE,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC;QAC/C,OAAO;KACR,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;WACtB,KAAK,KAAK,IAAI;WACd,QAAQ,IAAI,KAAK;WAChB,KAA6B,CAAC,MAAM,KAAK,OAAO,CACrD,CAAA;AACH,CAAC"}

package/dist/builder/index.d.ts

@@ -0,0 +1,5 @@
+export type { OpenApiVersion, OpenApiDocument, OpenApiInfo, OpenApiServer, OpenApiTag, OpenApiPathItem, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiMediaType, OpenApiHeader, OpenApiSchema, OpenApiSecurityScheme, OpenApiOAuthFlows, OpenApiOAuthFlow, } from './types.js';
+export { defineRoute, isRouteDefinition, type RouteConfig, type HandlerContext, type RouteHandler, type RouteDefinition, } from './define-route.js';
+export { defineController, isControllerDefinition, getControllerRoutes, type ControllerConfig, type ControllerDefinition, type RouteRecord, type AnyRouteDefinition, } from './define-controller.js';
+export { extractParamNames, createParamsSchema, getParamsSchema, type ExtractRouteParams, type HasPathParams, type ParamsFromPath, type InferParams, } from './path-params.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builder/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,aAAa,EACb,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAA"}

package/dist/builder/index.js

@@ -0,0 +1,7 @@
+// Route builder
+export { defineRoute, isRouteDefinition, } from './define-route.js';
+// Controller builder
+export { defineController, isControllerDefinition, getControllerRoutes, } from './define-controller.js';
+// Path parameter utilities
+export { extractParamNames, createParamsSchema, getParamsSchema, } from './path-params.js';
+//# sourceMappingURL=index.js.map

package/dist/builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builder/index.ts"],"names":[],"mappings":"AAmBA,gBAAgB;AAChB,OAAO,EACL,WAAW,EACX,iBAAiB,GAKlB,MAAM,mBAAmB,CAAA;AAE1B,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GAKpB,MAAM,wBAAwB,CAAA;AAE/B,2BAA2B;AAC3B,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAKhB,MAAM,kBAAkB,CAAA"}