kontract 0.1.0

package/dist/builder/path-params.js

@@ -0,0 +1,85 @@
+/**
+ * Path parameter extraction utilities.
+ *
+ * Provides both compile-time type inference and runtime extraction
+ * of path parameters from route strings.
+ *
+ * @example
+ * ```typescript
+ * // Type-level inference
+ * type Params = ParamsFromPath<'/users/:userId/posts/:postId'>
+ * // Result: { userId: string, postId: string }
+ *
+ * // Runtime extraction
+ * const names = extractParamNames('/users/:userId/posts/:postId')
+ * // Result: ['userId', 'postId']
+ * ```
+ */
+import { Type } from '@sinclair/typebox';
+// =============================================================================
+// Runtime Extraction
+// =============================================================================
+/**
+ * Extract parameter names from a path string at runtime.
+ *
+ * @param path - Route path with `:param` placeholders
+ * @returns Array of parameter names
+ *
+ * @example
+ * ```typescript
+ * extractParamNames('/users/:id')
+ * // Result: ['id']
+ *
+ * extractParamNames('/users/:userId/posts/:postId')
+ * // Result: ['userId', 'postId']
+ *
+ * extractParamNames('/users')
+ * // Result: []
+ * ```
+ */
+export function extractParamNames(path) {
+    const matches = path.matchAll(/:(\w+)/g);
+    return [...matches].map((m) => m[1]);
+}
+/**
+ * Create a TypeBox schema for path parameters.
+ * All parameters are `Type.String()` by default.
+ *
+ * @param paramNames - Array of parameter names
+ * @returns TypeBox object schema, or undefined if no params
+ *
+ * @example
+ * ```typescript
+ * createParamsSchema(['id'])
+ * // Result: Type.Object({ id: Type.String() })
+ *
+ * createParamsSchema(['userId', 'postId'])
+ * // Result: Type.Object({ userId: Type.String(), postId: Type.String() })
+ *
+ * createParamsSchema([])
+ * // Result: undefined
+ * ```
+ */
+export function createParamsSchema(paramNames) {
+    if (paramNames.length === 0)
+        return undefined;
+    const properties = {};
+    for (const name of paramNames) {
+        properties[name] = Type.String();
+    }
+    return Type.Object(properties);
+}
+/**
+ * Get or create a params schema for a route.
+ * Uses explicit schema if provided, otherwise generates from path.
+ *
+ * @param path - Route path
+ * @param explicitSchema - Explicitly provided params schema (optional)
+ * @returns TypeBox schema or undefined
+ */
+export function getParamsSchema(path, explicitSchema) {
+    if (explicitSchema)
+        return explicitSchema;
+    return createParamsSchema(extractParamNames(path));
+}
+//# sourceMappingURL=path-params.js.map

package/dist/builder/path-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-params.js","sourceRoot":"","sources":["../../src/builder/path-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,IAAI,EAA4C,MAAM,mBAAmB,CAAA;AAgFlF,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IACxC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAoB;IACrD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAE7C,MAAM,UAAU,GAA4B,EAAE,CAAA;IAC9C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAClC,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,cAAwB;IACpE,IAAI,cAAc;QAAE,OAAO,cAAc,CAAA;IACzC,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAA;AACpD,CAAC"}

package/dist/builder/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * OpenAPI 3.1.0 specification types.
+ * Minimal subset needed for the builder.
+ */
+export type OpenApiVersion = '3.1.0' | '3.0.3';
+export interface OpenApiDocument {
+    openapi: OpenApiVersion;
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    paths: Record<string, OpenApiPathItem>;
+    components?: {
+        schemas?: Record<string, OpenApiSchema>;
+        securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    };
+    tags?: OpenApiTag[];
+    security?: Array<Record<string, string[]>>;
+}
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+}
+export interface OpenApiTag {
+    name: string;
+    description?: string;
+}
+export interface OpenApiPathItem {
+    get?: OpenApiOperation;
+    post?: OpenApiOperation;
+    put?: OpenApiOperation;
+    patch?: OpenApiOperation;
+    delete?: OpenApiOperation;
+    parameters?: OpenApiParameter[];
+}
+export interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    security?: Array<Record<string, string[]>>;
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBody;
+    responses: Record<string, OpenApiResponse>;
+}
+export interface OpenApiParameter {
+    name: string;
+    in: 'query' | 'path' | 'header' | 'cookie';
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: OpenApiSchema;
+}
+export interface OpenApiRequestBody {
+    description?: string;
+    required?: boolean;
+    content: Record<string, OpenApiMediaType>;
+}
+export interface OpenApiResponse {
+    description: string;
+    content?: Record<string, OpenApiMediaType>;
+    headers?: Record<string, OpenApiHeader>;
+}
+export interface OpenApiMediaType {
+    schema?: OpenApiSchema | {
+        $ref: string;
+    };
+    example?: unknown;
+    examples?: Record<string, {
+        value: unknown;
+        summary?: string;
+    }>;
+}
+export interface OpenApiHeader {
+    description?: string;
+    required?: boolean;
+    schema?: OpenApiSchema;
+}
+export interface OpenApiSchema {
+    type?: string;
+    format?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    const?: unknown;
+    nullable?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
+    example?: unknown;
+    properties?: Record<string, OpenApiSchema>;
+    required?: string[];
+    additionalProperties?: boolean | OpenApiSchema;
+    items?: OpenApiSchema;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    allOf?: OpenApiSchema[];
+    anyOf?: OpenApiSchema[];
+    oneOf?: OpenApiSchema[];
+    not?: OpenApiSchema;
+    $ref?: string;
+}
+export interface OpenApiSecurityScheme {
+    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    description?: string;
+    name?: string;
+    in?: 'query' | 'header' | 'cookie';
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: OpenApiOAuthFlows;
+    openIdConnectUrl?: string;
+}
+export interface OpenApiOAuthFlows {
+    implicit?: OpenApiOAuthFlow;
+    password?: OpenApiOAuthFlow;
+    clientCredentials?: OpenApiOAuthFlow;
+    authorizationCode?: OpenApiOAuthFlow;
+}
+export interface OpenApiOAuthFlow {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/builder/types.js

@@ -0,0 +1,6 @@
+/**
+ * OpenAPI 3.1.0 specification types.
+ * Minimal subset needed for the builder.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/builder/types.js.map

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

package/dist/config/defaults.d.ts

@@ -0,0 +1,10 @@
+import type { OpenApiDecoratorConfig } from './types.js';
+/**
+ * Default runtime configuration values.
+ */
+export declare const defaultRuntimeConfig: Required<OpenApiDecoratorConfig['runtime']>;
+/**
+ * Merge user config with defaults.
+ */
+export declare function mergeWithDefaults(userConfig: Partial<OpenApiDecoratorConfig>): OpenApiDecoratorConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/config/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAExD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAI5E,CAAA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAC1C,sBAAsB,CAexB"}

package/dist/config/defaults.js

@@ -0,0 +1,28 @@
+/**
+ * Default runtime configuration values.
+ */
+export const defaultRuntimeConfig = {
+    validateResponses: false,
+    validateRequests: true,
+    stripUnknownProperties: false,
+};
+/**
+ * Merge user config with defaults.
+ */
+export function mergeWithDefaults(userConfig) {
+    return {
+        openapi: userConfig.openapi ?? {
+            info: {
+                title: 'API',
+                version: '1.0.0',
+            },
+        },
+        runtime: {
+            ...defaultRuntimeConfig,
+            ...userConfig.runtime,
+        },
+        validator: userConfig.validator,
+        serializers: userConfig.serializers,
+    };
+}
+//# sourceMappingURL=defaults.js.map

package/dist/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgD;IAC/E,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,IAAI;IACtB,sBAAsB,EAAE,KAAK;CAC9B,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAA2C;IAE3C,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI;YAC7B,IAAI,EAAE;gBACJ,KAAK,EAAE,KAAK;gBACZ,OAAO,EAAE,OAAO;aACjB;SACF;QACD,OAAO,EAAE;YACP,GAAG,oBAAoB;YACvB,GAAG,UAAU,CAAC,OAAO;SACtB;QACD,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,WAAW,EAAE,UAAU,CAAC,WAAW;KACpC,CAAA;AACH,CAAC"}

package/dist/config/define-config.d.ts

@@ -0,0 +1,50 @@
+import type { OpenApiDecoratorConfig, UserConfig } from './types.js';
+/**
+ * Define and register the OpenAPI decorator configuration.
+ *
+ * This function should be called once at application startup,
+ * before any decorated controllers are loaded.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from 'kontract'
+ *
+ * defineConfig({
+ *   openapi: {
+ *     info: {
+ *       title: 'My API',
+ *       version: '1.0.0',
+ *       description: 'A great API',
+ *     },
+ *     servers: [
+ *       { url: 'https://api.example.com', description: 'Production' },
+ *     ],
+ *   },
+ *   runtime: {
+ *     validateResponses: process.env.NODE_ENV !== 'production',
+ *     validateRequests: true,
+ *   },
+ *   validator: myAjvValidator,
+ * })
+ * ```
+ */
+export declare function defineConfig(userConfig: UserConfig): OpenApiDecoratorConfig;
+/**
+ * Get the current configuration.
+ * @throws ConfigurationError if config hasn't been set
+ */
+export declare function getConfig(): OpenApiDecoratorConfig;
+/**
+ * Get the current configuration, or undefined if not set.
+ * Useful for checking if the library has been configured.
+ */
+export declare function getConfigOrUndefined(): OpenApiDecoratorConfig | undefined;
+/**
+ * Check if the library has been configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Reset configuration (useful for testing).
+ */
+export declare function resetConfig(): void;
+//# sourceMappingURL=define-config.d.ts.map

package/dist/config/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAUpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,sBAAsB,CAW3E;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,sBAAsB,CAOlD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,sBAAsB,GAAG,SAAS,CAEzE;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAMlC"}

package/dist/config/define-config.js

@@ -0,0 +1,80 @@
+import { mergeWithDefaults } from './defaults.js';
+import { configureResponses } from '../response/helpers.js';
+import { ConfigurationError } from '../errors/configuration.js';
+/**
+ * Global configuration store.
+ */
+let globalConfig = null;
+/**
+ * Define and register the OpenAPI decorator configuration.
+ *
+ * This function should be called once at application startup,
+ * before any decorated controllers are loaded.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from 'kontract'
+ *
+ * defineConfig({
+ *   openapi: {
+ *     info: {
+ *       title: 'My API',
+ *       version: '1.0.0',
+ *       description: 'A great API',
+ *     },
+ *     servers: [
+ *       { url: 'https://api.example.com', description: 'Production' },
+ *     ],
+ *   },
+ *   runtime: {
+ *     validateResponses: process.env.NODE_ENV !== 'production',
+ *     validateRequests: true,
+ *   },
+ *   validator: myAjvValidator,
+ * })
+ * ```
+ */
+export function defineConfig(userConfig) {
+    const config = mergeWithDefaults(userConfig);
+    // Configure response helpers with validation settings
+    configureResponses({
+        validateResponses: config.runtime.validateResponses ?? false,
+        validator: config.validator,
+    });
+    globalConfig = config;
+    return config;
+}
+/**
+ * Get the current configuration.
+ * @throws ConfigurationError if config hasn't been set
+ */
+export function getConfig() {
+    if (!globalConfig) {
+        throw new ConfigurationError('Configuration not initialized. Call defineConfig() before using decorators.');
+    }
+    return globalConfig;
+}
+/**
+ * Get the current configuration, or undefined if not set.
+ * Useful for checking if the library has been configured.
+ */
+export function getConfigOrUndefined() {
+    return globalConfig ?? undefined;
+}
+/**
+ * Check if the library has been configured.
+ */
+export function isConfigured() {
+    return globalConfig !== null;
+}
+/**
+ * Reset configuration (useful for testing).
+ */
+export function resetConfig() {
+    globalConfig = null;
+    configureResponses({
+        validateResponses: false,
+        validator: undefined,
+    });
+}
+//# sourceMappingURL=define-config.js.map

package/dist/config/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;GAEG;AACH,IAAI,YAAY,GAAkC,IAAI,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,YAAY,CAAC,UAAsB;IACjD,MAAM,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAA;IAE5C,sDAAsD;IACtD,kBAAkB,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,IAAI,KAAK;QAC5D,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAA;IAEF,YAAY,GAAG,MAAM,CAAA;IACrB,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,kBAAkB,CAC1B,6EAA6E,CAC9E,CAAA;IACH,CAAC;IACD,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,IAAI,SAAS,CAAA;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,KAAK,IAAI,CAAA;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,YAAY,GAAG,IAAI,CAAA;IACnB,kBAAkB,CAAC;QACjB,iBAAiB,EAAE,KAAK;QACxB,SAAS,EAAE,SAAS;KACrB,CAAC,CAAA;AACJ,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+export type { OpenApiInfo, OpenApiServer, ValidatorFn, SerializerFn, SerializerRegistration, OpenApiDecoratorConfig, UserConfig, } from './types.js';
+export { defaultRuntimeConfig, mergeWithDefaults } from './defaults.js';
+export { defineConfig, getConfig, getConfigOrUndefined, isConfigured, resetConfig, } from './define-config.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,UAAU,GACX,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGvE,OAAO,EACL,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,WAAW,GACZ,MAAM,oBAAoB,CAAA"}

package/dist/config/index.js

@@ -0,0 +1,5 @@
+// Defaults
+export { defaultRuntimeConfig, mergeWithDefaults } from './defaults.js';
+// Configuration helpers
+export { defineConfig, getConfig, getConfigOrUndefined, isConfigured, resetConfig, } from './define-config.js';
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAWA,WAAW;AACX,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEvE,wBAAwB;AACxB,OAAO,EACL,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,YAAY,EACZ,WAAW,GACZ,MAAM,oBAAoB,CAAA"}

package/dist/config/types.d.ts

@@ -0,0 +1,103 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { ValidationErrorDetail } from '../errors/validation.js';
+/**
+ * OpenAPI document base information.
+ */
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+/**
+ * OpenAPI server configuration.
+ */
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+}
+/**
+ * Validator function type.
+ * Should return validation errors or undefined/void if valid.
+ */
+export type ValidatorFn = (schema: TSchema, data: unknown) => ValidationErrorDetail[] | void;
+/**
+ * Serializer function type.
+ * Transforms data before validation and response.
+ */
+export type SerializerFn<T = unknown> = (data: T) => unknown;
+/**
+ * Serializer registration with type guard.
+ */
+export interface SerializerRegistration<T = unknown> {
+    /** Type guard to check if data should use this serializer */
+    check: (data: unknown) => data is T;
+    /** Serialization function */
+    serialize: SerializerFn<T>;
+    /** Optional priority (higher = checked first) */
+    priority?: number;
+}
+/**
+ * Complete framework configuration.
+ */
+export interface OpenApiDecoratorConfig {
+    /**
+     * OpenAPI document information.
+     */
+    openapi: {
+        info: OpenApiInfo;
+        servers?: OpenApiServer[];
+    };
+    /**
+     * Runtime behavior options.
+     */
+    runtime: {
+        /**
+         * Validate responses against schemas in development.
+         * Recommended: true in dev, false in production.
+         * @default false
+         */
+        validateResponses?: boolean;
+        /**
+         * Validate request body, query, and params.
+         * @default true
+         */
+        validateRequests?: boolean;
+        /**
+         * Strip unknown properties from request data.
+         * @default false
+         */
+        stripUnknownProperties?: boolean;
+    };
+    /**
+     * Custom validator implementation.
+     * If not provided, responses won't be validated at runtime.
+     */
+    validator?: ValidatorFn;
+    /**
+     * Custom serializers for transforming data before validation.
+     */
+    serializers?: SerializerRegistration[];
+}
+/**
+ * Partial config for user input (most fields optional).
+ */
+export type UserConfig = {
+    openapi: {
+        info: OpenApiInfo;
+        servers?: OpenApiServer[];
+    };
+    runtime?: Partial<OpenApiDecoratorConfig['runtime']>;
+    validator?: ValidatorFn;
+    serializers?: SerializerRegistration[];
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAEpE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;IACD,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,MAAM,CAAA;QACZ,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,qBAAqB,EAAE,GAAG,IAAI,CAAA;AAE5F;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAA;AAE5D;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IACjD,6DAA6D;IAC7D,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,CAAA;IACnC,6BAA6B;IAC7B,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE;QACP,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;KAC1B,CAAA;IAED;;OAEG;IACH,OAAO,EAAE;QACP;;;;WAIG;QACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;QAE3B;;;WAGG;QACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;QAE1B;;;WAGG;QACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;KACjC,CAAA;IAED;;;OAGG;IACH,SAAS,CAAC,EAAE,WAAW,CAAA;IAEvB;;OAEG;IACH,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE;QACP,IAAI,EAAE,WAAW,CAAA;QACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;KAC1B,CAAA;IACD,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAA;IACpD,SAAS,CAAC,EAAE,WAAW,CAAA;IACvB,WAAW,CAAC,EAAE,sBAAsB,EAAE,CAAA;CACvC,CAAA"}

package/dist/config/types.js

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

package/dist/config/types.js.map

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

package/dist/decorators/api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for the @Api class decorator.
+ */
+export interface ApiOptions {
+    /** 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;
+}
+/**
+ * Class decorator that marks a controller for OpenAPI documentation.
+ *
+ * The tag is used to group endpoints in the OpenAPI spec.
+ * The optional prefix is prepended to all endpoint paths in this controller.
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Api({ tag: 'Users', description: 'User management endpoints' })
+ * export class UsersController {
+ *   // endpoints...
+ * }
+ * ```
+ *
+ * @example With prefix
+ * ```typescript
+ * @Api({ tag: 'Admin', description: 'Admin endpoints', prefix: '/admin' })
+ * export class AdminController {
+ *   // All endpoints in this controller will be prefixed with /admin
+ * }
+ * ```
+ */
+export declare function Api(options: ApiOptions): ClassDecorator;
+//# sourceMappingURL=api.d.ts.map

package/dist/decorators/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/decorators/api.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CASvD"}

package/dist/decorators/api.js

@@ -0,0 +1,34 @@
+import { setApiMetadata } from '../metadata/storage.js';
+/**
+ * Class decorator that marks a controller for OpenAPI documentation.
+ *
+ * The tag is used to group endpoints in the OpenAPI spec.
+ * The optional prefix is prepended to all endpoint paths in this controller.
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Api({ tag: 'Users', description: 'User management endpoints' })
+ * export class UsersController {
+ *   // endpoints...
+ * }
+ * ```
+ *
+ * @example With prefix
+ * ```typescript
+ * @Api({ tag: 'Admin', description: 'Admin endpoints', prefix: '/admin' })
+ * export class AdminController {
+ *   // All endpoints in this controller will be prefixed with /admin
+ * }
+ * ```
+ */
+export function Api(options) {
+    return function (target) {
+        const metadata = {
+            tag: options.tag,
+            description: options.description,
+            prefix: options.prefix,
+        };
+        setApiMetadata(target, metadata);
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/decorators/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/decorators/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAevD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,GAAG,CAAC,OAAmB;IACrC,OAAO,UAAU,MAAM;QACrB,MAAM,QAAQ,GAAgB;YAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAA;QACD,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAClC,CAAC,CAAA;AACH,CAAC"}