kontract 0.1.0

package/dist/errors/validation.d.ts

@@ -0,0 +1,46 @@
+import type { TSchema } from '@sinclair/typebox';
+import { OpenApiDecoratorError } from './base.js';
+/**
+ * Validation error detail for a single field.
+ */
+export interface ValidationErrorDetail {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Response format for validation errors.
+ */
+export interface ValidationErrorResponse {
+    status: number;
+    code: string;
+    message: string;
+    errors: ValidationErrorDetail[];
+}
+/**
+ * Error thrown when request validation fails.
+ */
+export declare class RequestValidationError extends OpenApiDecoratorError {
+    readonly status = 422;
+    readonly errors: ValidationErrorDetail[];
+    readonly schema: TSchema;
+    readonly data: unknown;
+    readonly source: 'body' | 'query' | 'params';
+    constructor(schema: TSchema, data: unknown, errors: ValidationErrorDetail[], source: 'body' | 'query' | 'params');
+    /**
+     * Convert to a response object suitable for sending to the client.
+     */
+    toResponse(): ValidationErrorResponse;
+}
+/**
+ * Error thrown when response validation fails (development only).
+ * This indicates a bug in the handler - the returned data doesn't match the declared schema.
+ */
+export declare class ResponseValidationError extends OpenApiDecoratorError {
+    readonly status = 500;
+    readonly errors: ValidationErrorDetail[];
+    readonly schema: TSchema;
+    readonly data: unknown;
+    constructor(schema: TSchema, data: unknown, errors: ValidationErrorDetail[]);
+}
+//# sourceMappingURL=validation.d.ts.map

package/dist/errors/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/errors/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,qBAAqB,EAAE,CAAA;CAChC;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,qBAAqB;IAC/D,SAAgB,MAAM,OAAM;IAC5B,SAAgB,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/C,SAAgB,MAAM,EAAE,OAAO,CAAA;IAC/B,SAAgB,IAAI,EAAE,OAAO,CAAA;IAC7B,SAAgB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;gBAGjD,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,qBAAqB,EAAE,EAC/B,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ;IAarC;;OAEG;IACH,UAAU,IAAI,uBAAuB;CAQtC;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,qBAAqB;IAChE,SAAgB,MAAM,OAAM;IAC5B,SAAgB,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/C,SAAgB,MAAM,EAAE,OAAO,CAAA;IAC/B,SAAgB,IAAI,EAAE,OAAO,CAAA;gBAG3B,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,qBAAqB,EAAE;CAWlC"}

package/dist/errors/validation.js

@@ -0,0 +1,52 @@
+import { OpenApiDecoratorError } from './base.js';
+/**
+ * Error thrown when request validation fails.
+ */
+export class RequestValidationError extends OpenApiDecoratorError {
+    status = 422;
+    errors;
+    schema;
+    data;
+    source;
+    constructor(schema, data, errors, source) {
+        const schemaName = schema.$id ?? schema.title ?? 'Request';
+        const errorSummary = errors.map((e) => `${e.field}: ${e.message}`).join(', ');
+        super('E_VALIDATION_ERROR', `${source} validation failed for ${schemaName}: ${errorSummary}`);
+        this.name = 'RequestValidationError';
+        this.schema = schema;
+        this.data = data;
+        this.errors = errors;
+        this.source = source;
+    }
+    /**
+     * Convert to a response object suitable for sending to the client.
+     */
+    toResponse() {
+        return {
+            status: this.status,
+            code: this.code,
+            message: 'Validation failed',
+            errors: this.errors,
+        };
+    }
+}
+/**
+ * Error thrown when response validation fails (development only).
+ * This indicates a bug in the handler - the returned data doesn't match the declared schema.
+ */
+export class ResponseValidationError extends OpenApiDecoratorError {
+    status = 500;
+    errors;
+    schema;
+    data;
+    constructor(schema, data, errors) {
+        const schemaName = schema.$id ?? schema.title ?? 'Response';
+        const errorSummary = errors.map((e) => `${e.field}: ${e.message}`).join(', ');
+        super('E_RESPONSE_VALIDATION', `Response validation failed for ${schemaName}: ${errorSummary}`);
+        this.name = 'ResponseValidationError';
+        this.schema = schema;
+        this.data = data;
+        this.errors = errors;
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/errors/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/errors/validation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAqBjD;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,qBAAqB;IAC/C,MAAM,GAAG,GAAG,CAAA;IACZ,MAAM,CAAyB;IAC/B,MAAM,CAAS;IACf,IAAI,CAAS;IACb,MAAM,CAA6B;IAEnD,YACE,MAAe,EACf,IAAa,EACb,MAA+B,EAC/B,MAAmC;QAEnC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,KAAK,IAAI,SAAS,CAAA;QAC1D,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7E,KAAK,CAAC,oBAAoB,EAAE,GAAG,MAAM,0BAA0B,UAAU,KAAK,YAAY,EAAE,CAAC,CAAA;QAE7F,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,mBAAmB;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAA;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,qBAAqB;IAChD,MAAM,GAAG,GAAG,CAAA;IACZ,MAAM,CAAyB;IAC/B,MAAM,CAAS;IACf,IAAI,CAAS;IAE7B,YACE,MAAe,EACf,IAAa,EACb,MAA+B;QAE/B,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,KAAK,IAAI,UAAU,CAAA;QAC3D,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7E,KAAK,CAAC,uBAAuB,EAAE,kCAAkC,UAAU,KAAK,YAAY,EAAE,CAAC,CAAA;QAE/F,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * kontract
+ *
+ * Framework-agnostic library for building type-safe, documented APIs with TypeBox schema support.
+ *
+ * @example
+ * ```typescript
+ * import { defineRoute, defineController } from 'kontract'
+ * import { Type } from '@sinclair/typebox'
+ *
+ * const User = Type.Object({
+ *   id: Type.Number(),
+ *   name: Type.String(),
+ * })
+ *
+ * const getUser = defineRoute({
+ *   route: 'GET /api/v1/users/:id',
+ *   params: Type.Object({ id: Type.String() }),
+ *   responses: { 200: { schema: User }, 404: null },
+ * }, async ({ params, reply }) => {
+ *   const user = await findUser(params.id)
+ *   if (!user) return reply.notFound()
+ *   return reply.ok(user)
+ * })
+ *
+ * export const usersController = defineController({ tag: 'Users' }, { getUser })
+ * ```
+ */
+export type { HttpMethod, AuthLevel, RouteString, ResponseDefinition, ResponseExample, ResponseHeader, FileUploadConfig, ApiMetadata, EndpointMetadata, ControllerMetadata, } from './metadata/types.js';
+export type { ApiResponse, BinaryResponse, AnyResponse, ApiErrorBody, ErrorCode, } from './response/types.js';
+export { isBinaryResponse, ErrorCodes } from './response/types.js';
+export { respond, ok, created, accepted, noContent, badRequest, unauthorized, forbidden, notFound, conflict, unprocessableEntity, tooManyRequests, internalServerError, badGateway, serviceUnavailable, binary, apiError, } from './response/helpers.js';
+export type { OpenApiInfo, OpenApiServer, ValidatorFn, SerializerFn, SerializerRegistration, OpenApiDecoratorConfig, UserConfig, } from './config/types.js';
+export { defineConfig, getConfig, getConfigOrUndefined, isConfigured, resetConfig, } from './config/define-config.js';
+export { OpenApiDecoratorError } from './errors/base.js';
+export { RequestValidationError, ResponseValidationError, type ValidationErrorDetail, } from './errors/validation.js';
+export { ConfigurationError, AdapterNotFoundError, SerializerNotFoundError, } from './errors/configuration.js';
+export type { RequestContext, AuthUser, AuthResult, AdapterRouteHandler, RouterAdapter, AuthAdapter, ContainerAdapter, ResponseAdapter, LoggerAdapter, FrameworkAdapters, } from './runtime/types.js';
+export type { ResponsesConfig, NormalizedResponse, NormalizedResponses, ExtractResponseSchema, ResponseSchemaFor, TypedHelper, TypedErrorHelper, ReplyHelpers, ErrorHelpers, BaseHandlerContext, } from './runtime/adapter-types.js';
+export { ERROR_CODES, createSuccessHelper, createErrorHelper, getErrorMessage, createResponseHelpers, } from './runtime/response-helpers.js';
+export { parseRouteString, normalizeResponses, isApiResponse, } from './runtime/route-utils.js';
+export type { Validator, CompiledValidator, ValidatorOptions, } from './validation/types.js';
+export type { OpenApiVersion, OpenApiDocument, OpenApiPathItem, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiMediaType, OpenApiHeader, OpenApiSchema, OpenApiSecurityScheme, } from './builder/types.js';
+export { OpenApiBuilder, type OpenApiBuilderOptions } from './builder/openapi-builder.js';
+export { defineRoute, isRouteDefinition, type RouteConfig, type HandlerContext, type RouteHandler, type RouteDefinition, } from './builder/define-route.js';
+export { defineController, isControllerDefinition, getControllerRoutes, type ControllerConfig, type ControllerDefinition, type RouteRecord, type AnyRouteDefinition, } from './builder/define-controller.js';
+export { extractParamNames, createParamsSchema, getParamsSchema, type ExtractRouteParams, type HasPathParams, type ParamsFromPath, type InferParams, } from './builder/path-params.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * kontract
+ *
+ * Framework-agnostic library for building type-safe, documented APIs with TypeBox schema support.
+ *
+ * @example
+ * ```typescript
+ * import { defineRoute, defineController } from 'kontract'
+ * import { Type } from '@sinclair/typebox'
+ *
+ * const User = Type.Object({
+ *   id: Type.Number(),
+ *   name: Type.String(),
+ * })
+ *
+ * const getUser = defineRoute({
+ *   route: 'GET /api/v1/users/:id',
+ *   params: Type.Object({ id: Type.String() }),
+ *   responses: { 200: { schema: User }, 404: null },
+ * }, async ({ params, reply }) => {
+ *   const user = await findUser(params.id)
+ *   if (!user) return reply.notFound()
+ *   return reply.ok(user)
+ * })
+ *
+ * export const usersController = defineController({ tag: 'Users' }, { getUser })
+ * ```
+ */
+export { isBinaryResponse, ErrorCodes } from './response/types.js';
+export { respond, ok, created, accepted, noContent, badRequest, unauthorized, forbidden, notFound, conflict, unprocessableEntity, tooManyRequests, internalServerError, badGateway, serviceUnavailable, binary, apiError, } from './response/helpers.js';
+export { defineConfig, getConfig, getConfigOrUndefined, isConfigured, resetConfig, } from './config/define-config.js';
+// ============ Errors ============
+export { OpenApiDecoratorError } from './errors/base.js';
+export { RequestValidationError, ResponseValidationError, } from './errors/validation.js';
+export { ConfigurationError, AdapterNotFoundError, SerializerNotFoundError, } from './errors/configuration.js';
+export { ERROR_CODES, createSuccessHelper, createErrorHelper, getErrorMessage, createResponseHelpers, } from './runtime/response-helpers.js';
+export { parseRouteString, normalizeResponses, isApiResponse, } from './runtime/route-utils.js';
+export { OpenApiBuilder } from './builder/openapi-builder.js';
+// ============ Route Builder ============
+export { defineRoute, isRouteDefinition, } from './builder/define-route.js';
+export { defineController, isControllerDefinition, getControllerRoutes, } from './builder/define-controller.js';
+// ============ Path Parameter Utilities ============
+export { extractParamNames, createParamsSchema, getParamsSchema, } from './builder/path-params.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAyBH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAElE,OAAO,EACL,OAAO,EACP,EAAE,EACF,OAAO,EACP,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,kBAAkB,EAClB,MAAM,EACN,QAAQ,GACT,MAAM,uBAAuB,CAAA;AAa9B,OAAO,EACL,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,WAAW,GACZ,MAAM,2BAA2B,CAAA;AAElC,mCAAmC;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,2BAA2B,CAAA;AA+BlC,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,GACd,MAAM,0BAA0B,CAAA;AAwBjC,OAAO,EAAE,cAAc,EAA8B,MAAM,8BAA8B,CAAA;AAEzF,0CAA0C;AAC1C,OAAO,EACL,WAAW,EACX,iBAAiB,GAKlB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GAKpB,MAAM,gCAAgC,CAAA;AAEvC,qDAAqD;AACrD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAKhB,MAAM,0BAA0B,CAAA"}

package/dist/metadata/index.d.ts

@@ -0,0 +1,2 @@
+export type { HttpMethod, AuthLevel, RouteString, ResponseDefinition, ResponseExample, ResponseHeader, FileUploadConfig, ApiMetadata, EndpointMetadata, ControllerMetadata, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metadata/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAA"}

package/dist/metadata/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/metadata/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metadata/index.ts"],"names":[],"mappings":""}

package/dist/metadata/storage.d.ts

@@ -0,0 +1,50 @@
+import type { ApiMetadata, EndpointMetadata, ControllerMetadata } from './types.js';
+/**
+ * Store API metadata for a controller class.
+ */
+export declare function setApiMetadata(target: object, metadata: ApiMetadata): void;
+/**
+ * Retrieve API metadata for a controller class.
+ */
+export declare function getApiMetadata(target: object): ApiMetadata | undefined;
+/**
+ * Check if a target has API metadata.
+ */
+export declare function hasApiMetadata(target: object): boolean;
+/**
+ * Add endpoint metadata to a controller class.
+ * Multiple endpoints can be added to the same controller.
+ */
+export declare function addEndpointMetadata(target: object, metadata: EndpointMetadata): void;
+/**
+ * Retrieve all endpoint metadata for a controller class.
+ */
+export declare function getEndpointMetadata(target: object): EndpointMetadata[];
+/**
+ * Check if a target has any endpoint metadata.
+ */
+export declare function hasEndpointMetadata(target: object): boolean;
+/**
+ * Get all registered controller classes.
+ * Controllers are registered when decorated with @Api.
+ */
+export declare function getRegisteredControllers(): object[];
+/**
+ * Clear the controller registry.
+ * Useful for testing or hot reloading.
+ */
+export declare function clearRegistry(): void;
+/**
+ * Get the number of registered controllers.
+ */
+export declare function getRegistrySize(): number;
+/**
+ * Get complete metadata for a controller, including API info and all endpoints.
+ * Returns undefined if the controller doesn't have @Api metadata.
+ */
+export declare function getControllerMetadata(controller: object): ControllerMetadata | undefined;
+/**
+ * Get complete metadata for all registered controllers.
+ */
+export declare function getAllControllerMetadata(): ControllerMetadata[];
+//# sourceMappingURL=storage.d.ts.map

package/dist/metadata/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/metadata/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAYnF;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAG1E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEtE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAIpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAEtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3D;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAID;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAWxF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAW/D"}

package/dist/metadata/storage.js

@@ -0,0 +1,100 @@
+/**
+ * WeakMap-based storage for decorator metadata.
+ * Using WeakMaps ensures metadata is garbage collected when controllers are.
+ */
+const apiMetadataMap = new WeakMap();
+const endpointMetadataMap = new WeakMap();
+const controllerRegistry = new Set();
+// ============ API Metadata ============
+/**
+ * Store API metadata for a controller class.
+ */
+export function setApiMetadata(target, metadata) {
+    apiMetadataMap.set(target, metadata);
+    controllerRegistry.add(target);
+}
+/**
+ * Retrieve API metadata for a controller class.
+ */
+export function getApiMetadata(target) {
+    return apiMetadataMap.get(target);
+}
+/**
+ * Check if a target has API metadata.
+ */
+export function hasApiMetadata(target) {
+    return apiMetadataMap.has(target);
+}
+// ============ Endpoint Metadata ============
+/**
+ * Add endpoint metadata to a controller class.
+ * Multiple endpoints can be added to the same controller.
+ */
+export function addEndpointMetadata(target, metadata) {
+    const existing = endpointMetadataMap.get(target) ?? [];
+    existing.push(metadata);
+    endpointMetadataMap.set(target, existing);
+}
+/**
+ * Retrieve all endpoint metadata for a controller class.
+ */
+export function getEndpointMetadata(target) {
+    return endpointMetadataMap.get(target) ?? [];
+}
+/**
+ * Check if a target has any endpoint metadata.
+ */
+export function hasEndpointMetadata(target) {
+    return endpointMetadataMap.has(target);
+}
+// ============ Registry ============
+/**
+ * Get all registered controller classes.
+ * Controllers are registered when decorated with @Api.
+ */
+export function getRegisteredControllers() {
+    return Array.from(controllerRegistry);
+}
+/**
+ * Clear the controller registry.
+ * Useful for testing or hot reloading.
+ */
+export function clearRegistry() {
+    controllerRegistry.clear();
+}
+/**
+ * Get the number of registered controllers.
+ */
+export function getRegistrySize() {
+    return controllerRegistry.size;
+}
+// ============ Combined Metadata ============
+/**
+ * Get complete metadata for a controller, including API info and all endpoints.
+ * Returns undefined if the controller doesn't have @Api metadata.
+ */
+export function getControllerMetadata(controller) {
+    const api = getApiMetadata(controller);
+    if (!api) {
+        return undefined;
+    }
+    return {
+        controller,
+        api,
+        endpoints: getEndpointMetadata(controller),
+    };
+}
+/**
+ * Get complete metadata for all registered controllers.
+ */
+export function getAllControllerMetadata() {
+    const result = [];
+    for (const controller of controllerRegistry) {
+        const metadata = getControllerMetadata(controller);
+        if (metadata) {
+            result.push(metadata);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=storage.js.map

package/dist/metadata/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/metadata/storage.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,OAAO,EAAuB,CAAA;AACzD,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAA8B,CAAA;AACrE,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAA;AAE5C,yCAAyC;AAEzC;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,QAAqB;IAClE,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACpC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC;AAED,8CAA8C;AAE9C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,QAA0B;IAC5E,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IACtD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACvB,mBAAmB,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AACxC,CAAC;AAED,qCAAqC;AAErC;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,kBAAkB,CAAC,KAAK,EAAE,CAAA;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAChC,CAAC;AAED,8CAA8C;AAE9C;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACtD,MAAM,GAAG,GAAG,cAAc,CAAC,UAAU,CAAC,CAAA;IACtC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO;QACL,UAAU;QACV,GAAG;QACH,SAAS,EAAE,mBAAmB,CAAC,UAAU,CAAC;KAC3C,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB;IACtC,MAAM,MAAM,GAAyB,EAAE,CAAA;IAEvC,KAAK,MAAM,UAAU,IAAI,kBAAkB,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAA;QAClD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACvB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/metadata/types.d.ts

@@ -0,0 +1,142 @@
+import type { TSchema, Static } from '@sinclair/typebox';
+/**
+ * HTTP methods supported by the framework.
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/**
+ * Authentication requirement levels for endpoints.
+ */
+export type AuthLevel = 'required' | 'optional' | 'none';
+/**
+ * Route string format: "METHOD /path" (path must start with /)
+ * @example "GET /api/v1/users"
+ * @example "POST /api/v1/users/:id"
+ */
+export type RouteString = `${'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'} /${string}`;
+/**
+ * Example value for documentation.
+ * Used in response definitions to provide sample data for OpenAPI docs.
+ */
+export interface ResponseExample<T = unknown> {
+    /** Example value matching the response schema */
+    value: T;
+    /** Short summary of what this example demonstrates */
+    summary?: string;
+}
+/**
+ * Response header definition for OpenAPI.
+ * Describes headers returned in the response.
+ */
+export interface ResponseHeader {
+    /** Header description */
+    description?: string;
+    /** Header schema (typically Type.String() or Type.Number()) */
+    schema: TSchema;
+    /** Whether this header is required (default: false) */
+    required?: boolean;
+}
+/**
+ * Response definition for an endpoint.
+ * Generic parameter T is inferred from the schema for type-safe examples.
+ *
+ * @example Basic usage
+ * ```typescript
+ * responses: {
+ *   200: { schema: UserSchema, description: 'User found' }
+ * }
+ * ```
+ *
+ * @example With type-safe examples
+ * ```typescript
+ * responses: {
+ *   200: {
+ *     schema: UserSchema,
+ *     description: 'User found',
+ *     example: { id: '1', name: 'John' }  // TypeScript will validate this matches UserSchema
+ *   }
+ * }
+ * ```
+ */
+export interface ResponseDefinition<T extends TSchema | null = TSchema | null> {
+    /** The TypeBox schema for the response body, or null for empty responses */
+    schema: T;
+    /** Description of this response (for OpenAPI docs) */
+    description?: string;
+    /** Response headers */
+    headers?: Record<string, ResponseHeader>;
+    /** Multiple named examples (type-checked against schema) */
+    examples?: T extends TSchema ? Record<string, ResponseExample<Static<T>>> : never;
+    /** Single example value (type-checked against schema) */
+    example?: T extends TSchema ? Static<T> : never;
+}
+/**
+ * File upload configuration for multipart/form-data endpoints.
+ */
+export interface FileUploadConfig {
+    /** Field name for the file input */
+    fieldName: string;
+    /** Description for the file field */
+    description?: string;
+    /** Allowed file extensions (e.g., ['csv', 'json']) */
+    allowedExtensions?: string[];
+    /** Maximum file size (e.g., '10mb') */
+    maxSize?: string;
+    /** Whether to accept multiple files (default: false) */
+    multiple?: boolean;
+}
+/**
+ * Metadata for a controller class decorated with @Api.
+ */
+export interface ApiMetadata {
+    /** OpenAPI tag for grouping endpoints */
+    tag: string;
+    /** Description of the API group */
+    description?: string;
+    /** Optional path prefix for all endpoints in this controller */
+    prefix?: string;
+}
+/**
+ * Metadata for an endpoint method decorated with @Endpoint.
+ */
+export interface EndpointMetadata {
+    /** HTTP method (lowercase) */
+    method: HttpMethod;
+    /** URL path pattern */
+    path: string;
+    /** Name of the decorated method */
+    methodName: string;
+    /** Short summary for OpenAPI */
+    summary?: string;
+    /** Detailed description for OpenAPI */
+    description?: string;
+    /** Unique operation ID for OpenAPI */
+    operationId?: string;
+    /** Whether this endpoint is deprecated */
+    deprecated?: boolean;
+    /** Authentication requirement */
+    auth: AuthLevel;
+    /** Request body schema */
+    body?: TSchema;
+    /** Query parameters schema */
+    query?: TSchema;
+    /** Path parameters schema */
+    params?: TSchema;
+    /** File upload configuration */
+    file?: FileUploadConfig;
+    /** Response definitions by status code */
+    responses: Record<number, ResponseDefinition>;
+    /** Framework-specific middleware (opaque to core) */
+    middleware?: unknown[];
+}
+/**
+ * Combined metadata for a controller with all its endpoints.
+ */
+export interface ControllerMetadata {
+    /** The controller class constructor */
+    controller: object;
+    /** Controller-level metadata */
+    api: ApiMetadata;
+    /** All endpoint metadata for this controller */
+    endpoints: EndpointMetadata[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/metadata/types.d.ts.map

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

package/dist/metadata/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/metadata/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/metadata/types.ts"],"names":[],"mappings":""}