@buenojs/bueno 0.8.5 → 0.8.7

package/dist/observability/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Observability Types
+ *
+ * Core interfaces for the error tracking and observability integration layer.
+ * Implement ErrorReporter to integrate with Sentry, Bugsnag, Datadog, etc.
+ */
+/**
+ * A single breadcrumb entry recording an event that occurred before an error
+ */
+export interface BreadcrumbEntry {
+    /** When this breadcrumb was recorded */
+    timestamp: Date;
+    /** Category of event */
+    type: "http" | "log" | "navigation" | "custom";
+    /** Severity level */
+    level: "debug" | "info" | "warning" | "error";
+    /** Human-readable description of the event */
+    message: string;
+    /** Optional structured data for context */
+    data?: Record<string, unknown>;
+}
+/**
+ * Request metadata captured at error time
+ */
+export interface ErrorRequestContext {
+    /** HTTP method */
+    method: string;
+    /** Request path */
+    path: string;
+    /** Relevant request headers (sanitized) */
+    headers: Record<string, string>;
+    /** Client IP address */
+    ip: string;
+    /** User-Agent header if present */
+    userAgent?: string;
+}
+/**
+ * User identity snapshot (sourced from context.get('user'))
+ */
+export interface ErrorUserContext {
+    id?: string | number;
+    email?: string;
+    [key: string]: unknown;
+}
+/**
+ * A captured error event with full context, ready for the reporter
+ */
+export interface ErrorEvent {
+    /** Unique ID for this error event (for deduplication) */
+    id: string;
+    /** When the error occurred */
+    timestamp: Date;
+    /** The original Error object */
+    error: Error;
+    /** Severity level */
+    level: "fatal" | "error" | "warning";
+    /** HTTP request context (undefined for non-HTTP errors) */
+    request?: ErrorRequestContext;
+    /** W3C trace ID (from traceparent header or generated) */
+    traceId?: string;
+    /** W3C span ID */
+    spanId?: string;
+    /** Authenticated user at time of error */
+    user?: ErrorUserContext;
+    /** Recent events leading up to this error */
+    breadcrumbs: BreadcrumbEntry[];
+    /** Custom tags for categorization */
+    tags?: Record<string, string>;
+    /** Any additional context */
+    extra?: Record<string, unknown>;
+}
+/**
+ * A captured message event (non-error) for the reporter
+ */
+export interface MessageEvent {
+    /** Unique ID */
+    id: string;
+    /** When the message was captured */
+    timestamp: Date;
+    /** The message text */
+    message: string;
+    /** Severity */
+    level: "debug" | "info" | "warning" | "error";
+    /** Optional extra context */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Implement this interface to report errors to your platform (Sentry, Bugsnag, etc.).
+ *
+ * @example
+ * ```typescript
+ * class SentryReporter implements ErrorReporter {
+ *   captureError(event: ErrorEvent) {
+ *     Sentry.withScope(scope => {
+ *       if (event.user) scope.setUser(event.user);
+ *       if (event.traceId) scope.setTag('traceId', event.traceId);
+ *       Sentry.captureException(event.error);
+ *     });
+ *   }
+ *   async flush() { await Sentry.flush(2000); }
+ * }
+ * ```
+ */
+export interface ErrorReporter {
+    /**
+     * Report an error event. Called asynchronously (non-blocking).
+     * Throw errors only if truly unrecoverable — they are caught and logged.
+     */
+    captureError(event: ErrorEvent): void | Promise<void>;
+    /**
+     * Report a non-error message. Optional.
+     */
+    captureMessage?(event: MessageEvent): void | Promise<void>;
+    /**
+     * Flush pending events. Called on application shutdown.
+     * Use this to ensure all buffered events are sent before process exit.
+     */
+    flush?(): Promise<void>;
+}
+/**
+ * Options for ObservabilityModule.forRoot()
+ */
+export interface ObservabilityOptions {
+    /**
+     * The reporter that receives all captured error events.
+     * Required — without a reporter, no events are sent anywhere.
+     */
+    reporter: ErrorReporter;
+    /**
+     * Maximum number of breadcrumbs to retain in the ring buffer.
+     * Older breadcrumbs are evicted when the buffer is full.
+     * @default 20
+     */
+    breadcrumbsSize?: number;
+    /**
+     * Error classes to suppress — events with these types are not reported.
+     * Useful for suppressing expected errors like 404s or 401s.
+     *
+     * @example ignoreErrors: [NotFoundError, UnauthorizedError]
+     */
+    ignoreErrors?: Array<new (...args: unknown[]) => Error>;
+    /**
+     * HTTP status codes to suppress.
+     * Errors whose statusCode property matches are not reported.
+     * @example ignoreStatusCodes: [404, 401]
+     */
+    ignoreStatusCodes?: number[];
+    /**
+     * Custom tags attached to every error event.
+     * @example tags: { environment: 'production', version: '1.2.3' }
+     */
+    tags?: Record<string, string>;
+    /**
+     * Also capture unhandled promise rejections and uncaught exceptions
+     * at the process level (outside the HTTP request pipeline).
+     * @default false
+     */
+    captureUnhandled?: boolean;
+}
+/**
+ * Configuration values that can be set via environment variables.
+ * These are applied as defaults; ObservabilityOptions take precedence.
+ */
+export interface ObservabilityConfig {
+    /** Enable/disable the observability system */
+    enabled?: boolean;
+    /** Maximum breadcrumb ring buffer size */
+    breadcrumbsSize?: number;
+    /** HTTP status codes to ignore (comma-separated in env) */
+    ignoreStatusCodes?: number[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/openapi/__tests__/decorators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decorators.test.d.ts.map

package/dist/openapi/__tests__/decorators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/decorators.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/document-builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=document-builder.test.d.ts.map

package/dist/openapi/__tests__/document-builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-builder.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/document-builder.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/route-scanner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-scanner.test.d.ts.map

package/dist/openapi/__tests__/route-scanner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-scanner.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/route-scanner.test.ts"],"names":[],"mappings":""}

package/dist/openapi/__tests__/schema-generator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-generator.test.d.ts.map

package/dist/openapi/__tests__/schema-generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-generator.test.d.ts","sourceRoot":"","sources":["../../../src/openapi/__tests__/schema-generator.test.ts"],"names":[],"mappings":""}

package/dist/openapi/decorators.d.ts

@@ -0,0 +1,173 @@
+/**
+ * OpenAPI Decorators
+ *
+ * Decorators for documenting controllers, methods, parameters, and DTOs with OpenAPI metadata.
+ */
+import type { ApiBodyOptions, ApiHeaderOptions, ApiKeySecurityOptions, ApiOperationOptions, ApiParamOptions, ApiPropertyOptions, ApiQueryOptions, ApiResponseOptions, SecuritySchemeOptions } from './types';
+/**
+ * Mark one or more tags that apply to all operations in this controller
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * @ApiTags('users', 'accounts')
+ * class UserController { ... }
+ * ```
+ */
+export declare function ApiTags(...tags: string[]): ClassDecorator;
+/**
+ * Mark this controller with Bearer token authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBearerAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiBearerAuth(name?: string, options?: SecuritySchemeOptions): ClassDecorator | MethodDecorator;
+/**
+ * Mark this controller with Basic authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBasicAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiBasicAuth(name?: string): ClassDecorator | MethodDecorator;
+/**
+ * Mark this controller with API Key authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiApiKey({ in: 'header', name: 'X-API-Key' })
+ * class ApiController { ... }
+ * ```
+ */
+export declare function ApiApiKey(options: ApiKeySecurityOptions, name?: string): ClassDecorator | MethodDecorator;
+/**
+ * Exclude this entire controller from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Controller('/internal')
+ * @ApiExcludeController()
+ * class InternalController { ... }
+ * ```
+ */
+export declare function ApiExcludeController(): ClassDecorator;
+/**
+ * Document the operation (HTTP method) with summary, description, and other metadata
+ *
+ * @example
+ * ```typescript
+ * @Get('/:id')
+ * @ApiOperation({ summary: 'Get user by ID', description: 'Retrieve a single user' })
+ * getUser(@Param('id') id: string) { ... }
+ * ```
+ */
+export declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+/**
+ * Document an HTTP response from this operation
+ * Can be used multiple times for different status codes
+ *
+ * @example
+ * ```typescript
+ * @ApiResponse({ status: 200, description: 'Success', type: UserDto })
+ * @ApiResponse({ status: 404, description: 'Not found' })
+ * getUser() { ... }
+ * ```
+ */
+export declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+/**
+ * Document a path parameter
+ * Can be used multiple times for different parameters
+ *
+ * @example
+ * ```typescript
+ * @Get('/:userId/posts/:postId')
+ * @ApiParam({ name: 'userId', type: 'string', description: 'User ID' })
+ * @ApiParam({ name: 'postId', type: 'string', description: 'Post ID' })
+ * getPost(@Param('userId') userId: string, @Param('postId') postId: string) { ... }
+ * ```
+ */
+export declare function ApiParam(options: ApiParamOptions): MethodDecorator;
+/**
+ * Document a query parameter
+ * Can be used multiple times for different parameters
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiQuery({ name: 'page', type: 'number', description: 'Page number', required: false })
+ * @ApiQuery({ name: 'limit', type: 'number', description: 'Items per page', required: false })
+ * getUsers(@Query('page') page?: number, @Query('limit') limit?: number) { ... }
+ * ```
+ */
+export declare function ApiQuery(options: ApiQueryOptions): MethodDecorator;
+/**
+ * Document an HTTP header
+ * Can be used multiple times for different headers
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiHeader({ name: 'X-Request-ID', description: 'Request ID', required: true })
+ * create() { ... }
+ * ```
+ */
+export declare function ApiHeader(options: ApiHeaderOptions): MethodDecorator;
+/**
+ * Document the request body
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiBody({ type: CreateUserDto, description: 'User data to create' })
+ * create(@Body() dto: CreateUserDto) { ... }
+ * ```
+ */
+export declare function ApiBody(options: ApiBodyOptions): MethodDecorator;
+/**
+ * Exclude this endpoint from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiExcludeEndpoint()
+ * internalOnly() { ... }
+ * ```
+ */
+export declare function ApiExcludeEndpoint(): MethodDecorator;
+/**
+ * Document a DTO property with type, description, validation rules, etc.
+ *
+ * @example
+ * ```typescript
+ * class CreateUserDto {
+ *   @ApiProperty({ description: 'Email address', example: 'user@example.com' })
+ *   email: string;
+ *
+ *   @ApiProperty({ minLength: 2, maxLength: 50, description: 'Full name' })
+ *   name: string;
+ * }
+ * ```
+ */
+export declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
+/**
+ * Document an optional DTO property
+ * Equivalent to ApiProperty with required: false
+ *
+ * @example
+ * ```typescript
+ * class UserFilterDto {
+ *   @ApiPropertyOptional({ description: 'Filter by name', example: 'John' })
+ *   name?: string;
+ * }
+ * ```
+ */
+export declare function ApiPropertyOptional(options?: Omit<ApiPropertyOptions, 'required'>): PropertyDecorator;
+//# sourceMappingURL=decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/openapi/decorators.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAGlB,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAYjB;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAOzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAW,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc,GAAG,eAAe,CAiBhH;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAU,GAAG,cAAc,GAAG,eAAe,CAiB7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,qBAAqB,EAAE,IAAI,SAAY,GAAG,cAAc,GAAG,eAAe,CAmB5G;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAKrD;AAID;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAI1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CAOxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAOlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAOlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAOpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAIhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CAK3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GAAG,iBAAiB,CAKrG"}

package/dist/openapi/document-builder.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OpenAPI Document Builder
+ *
+ * Fluent API for building OpenAPI 3.1 documents with configuration for
+ * servers, security schemes, tags, and other top-level metadata.
+ */
+import type { ApiKeySecurityOptions, OpenAPIDocument, SecuritySchemeOptions } from './types';
+/**
+ * DocumentBuilder - Fluent API for constructing OpenAPI documents
+ *
+ * @example
+ * ```typescript
+ * const document = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .setDescription('API description')
+ *   .addBearerAuth()
+ *   .addTag('users', 'User management endpoints')
+ *   .build();
+ * ```
+ */
+export declare class DocumentBuilder {
+    private document;
+    /**
+     * Set the API title
+     */
+    setTitle(title: string): this;
+    /**
+     * Set the API description
+     */
+    setDescription(description: string): this;
+    /**
+     * Set the API version
+     */
+    setVersion(version: string): this;
+    /**
+     * Set contact information
+     */
+    setContact(name: string, url?: string, email?: string): this;
+    /**
+     * Set license information
+     */
+    setLicense(name: string, url?: string): this;
+    /**
+     * Add a server
+     */
+    addServer(url: string, description?: string): this;
+    /**
+     * Add Bearer token authentication
+     *
+     * @example
+     * ```typescript
+     * builder.addBearerAuth('JWT')
+     * ```
+     */
+    addBearerAuth(name?: string, options?: SecuritySchemeOptions): this;
+    /**
+     * Add Basic authentication
+     */
+    addBasicAuth(name?: string, options?: SecuritySchemeOptions): this;
+    /**
+     * Add API Key authentication
+     */
+    addApiKey(options: ApiKeySecurityOptions, name?: string): this;
+    /**
+     * Add an OAuth2 security scheme
+     */
+    addOAuth2(name: string, authorizationUrl: string, tokenUrl?: string, refreshUrl?: string): this;
+    /**
+     * Add an OpenID Connect security scheme
+     */
+    addOpenIdConnect(name: string, url: string): this;
+    /**
+     * Add a tag for organizing operations
+     */
+    addTag(name: string, description?: string): this;
+    /**
+     * Build and return the final OpenAPI document
+     */
+    build(): OpenAPIDocument;
+}
+//# sourceMappingURL=document-builder.d.ts.map

package/dist/openapi/document-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-builder.d.ts","sourceRoot":"","sources":["../../src/openapi/document-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACX,qBAAqB,EAErB,eAAe,EAIf,qBAAqB,EACrB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAYd;IAEF;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAS7B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IASzC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASjC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5D;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAQlD;;;;;;;OAOG;IACH,aAAa,CACZ,IAAI,SAAW,EACf,OAAO,CAAC,EAAE,qBAAqB,GAC7B,IAAI;IAsBP;;OAEG;IACH,YAAY,CAAC,IAAI,SAAU,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI;IAqBnE;;OAEG;IACH,SAAS,CACR,OAAO,EAAE,qBAAqB,EAC9B,IAAI,SAAY,GACd,IAAI;IAsBP;;OAEG;IACH,SAAS,CACR,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI;IAuBP;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAgBjD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAchD;;OAEG;IACH,KAAK,IAAI,eAAe;CAGxB"}

package/dist/openapi/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * OpenAPI Module
+ *
+ * Auto-generate OpenAPI 3.1 specifications from Bueno controllers and decorators.
+ * Provides decorators for documenting API endpoints and a SwaggerModule for setup.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DocumentBuilder,
+ *   SwaggerModule,
+ *   ApiOperation,
+ *   ApiResponse,
+ *   ApiTags,
+ * } from '@buenojs/bueno/openapi';
+ *
+ * // 1. Document your controller
+ * @Controller('/users')
+ * @ApiTags('users')
+ * class UsersController {
+ *   @Get()
+ *   @ApiOperation({ summary: 'List all users' })
+ *   @ApiResponse({ status: 200, description: 'Success', type: [User] })
+ *   async getAll() { ... }
+ * }
+ *
+ * // 2. Create OpenAPI document
+ * const config = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .addBearerAuth()
+ *   .build();
+ *
+ * const document = SwaggerModule.createDocument(app, config, [UsersController]);
+ *
+ * // 3. Setup Swagger UI
+ * SwaggerModule.setup('/api-docs', app, document);
+ * ```
+ */
+export type { OpenAPIDocument, OpenAPIInfo, OpenAPIContact, OpenAPILicense, OpenAPIServer, OpenAPIPaths, OpenAPIPath, OpenAPIOperation, OpenAPIExternalDocs, OpenAPIParameter, OpenAPIRequestBody, OpenAPIMediaType, OpenAPIExample, OpenAPIResponse, OpenAPIHeader, OpenAPIResponses, OpenAPISchema, OpenAPIDiscriminator, OpenAPIXML, OpenAPIComponents, OpenAPISecurityScheme, OpenAPIOAuthFlows, OpenAPIOAuthFlow, OpenAPISecurity, OpenAPITag, SwaggerOptions, ApiOperationOptions, ApiResponseOptions, ApiParamOptions, ApiQueryOptions, ApiHeaderOptions, ApiBodyOptions, ApiPropertyOptions, SecuritySchemeOptions, ApiKeySecurityOptions, Constructor, } from './types';
+export { DocumentBuilder } from './document-builder';
+export { SchemaGenerator } from './schema-generator';
+export { RouteScanner } from './route-scanner';
+export { SwaggerModule } from './swagger-module';
+export { ApiTags, ApiBearerAuth, ApiBasicAuth, ApiApiKey, ApiExcludeController, } from './decorators';
+export { ApiOperation, ApiResponse, ApiParam, ApiQuery, ApiHeader, ApiBody, ApiExcludeEndpoint, } from './decorators';
+export { ApiProperty, ApiPropertyOptional } from './decorators';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,YAAY,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,GACX,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD,OAAO,EACN,OAAO,EACP,aAAa,EACb,YAAY,EACZ,SAAS,EACT,oBAAoB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,OAAO,EACP,kBAAkB,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/openapi/index.js

@@ -26,6 +26,59 @@ var __legacyMetadataTS = (k, v) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
+// src/openapi/metadata.ts
+var exports_metadata = {};
+__export(exports_metadata, {
+  setApiPropertyMetadata: () => setApiPropertyMetadata,
+  setApiMethodMetadata: () => setApiMethodMetadata,
+  setApiMetadata: () => setApiMetadata,
+  getApiPropertyMetadata: () => getApiPropertyMetadata,
+  getApiPropertyKeys: () => getApiPropertyKeys,
+  getApiMethodMetadata: () => getApiMethodMetadata,
+  getApiMetadata: () => getApiMetadata
+});
+function setApiMetadata(target, key, value) {
+  if (!classMetadataStore.has(target)) {
+    classMetadataStore.set(target, new Map);
+  }
+  classMetadataStore.get(target)?.set(key, value);
+}
+function getApiMetadata(target, key) {
+  return classMetadataStore.get(target)?.get(key);
+}
+function setApiMethodMetadata(target, key, value) {
+  if (!methodMetadataStore.has(target)) {
+    methodMetadataStore.set(target, new Map);
+  }
+  methodMetadataStore.get(target)?.set(key, value);
+}
+function getApiMethodMetadata(target, key) {
+  return methodMetadataStore.get(target)?.get(key);
+}
+function setApiPropertyMetadata(target, propertyKey, value) {
+  if (!propertyMetadataStore.has(target)) {
+    propertyMetadataStore.set(target, new Map);
+  }
+  const key = typeof propertyKey === "symbol" ? propertyKey.toString() : propertyKey;
+  propertyMetadataStore.get(target)?.set(key, value);
+}
+function getApiPropertyMetadata(target, propertyKey) {
+  const key = typeof propertyKey === "symbol" ? propertyKey.toString() : propertyKey;
+  return propertyMetadataStore.get(target)?.get(key);
+}
+function getApiPropertyKeys(target) {
+  const metaMap = propertyMetadataStore.get(target);
+  if (!metaMap)
+    return [];
+  return Array.from(metaMap.keys());
+}
+var classMetadataStore, methodMetadataStore, propertyMetadataStore;
+var init_metadata = __esm(() => {
+  classMetadataStore = new WeakMap;
+  methodMetadataStore = new WeakMap;
+  propertyMetadataStore = new WeakMap;
+});
+
 // src/openapi/document-builder.ts
 class DocumentBuilder {
   document = {
@@ -187,47 +240,9 @@ class DocumentBuilder {
     return this.document;
   }
 }
-// src/openapi/metadata.ts
-var classMetadataStore = new WeakMap;
-function setApiMetadata(target, key, value) {
-  if (!classMetadataStore.has(target)) {
-    classMetadataStore.set(target, new Map);
-  }
-  classMetadataStore.get(target)?.set(key, value);
-}
-function getApiMetadata(target, key) {
-  return classMetadataStore.get(target)?.get(key);
-}
-var methodMetadataStore = new WeakMap;
-function setApiMethodMetadata(target, key, value) {
-  if (!methodMetadataStore.has(target)) {
-    methodMetadataStore.set(target, new Map);
-  }
-  methodMetadataStore.get(target)?.set(key, value);
-}
-function getApiMethodMetadata(target, key) {
-  return methodMetadataStore.get(target)?.get(key);
-}
-var propertyMetadataStore = new WeakMap;
-function setApiPropertyMetadata(target, propertyKey, value) {
-  if (!propertyMetadataStore.has(target)) {
-    propertyMetadataStore.set(target, new Map);
-  }
-  const key = typeof propertyKey === "symbol" ? propertyKey.toString() : propertyKey;
-  propertyMetadataStore.get(target)?.set(key, value);
-}
-function getApiPropertyMetadata(target, propertyKey) {
-  const key = typeof propertyKey === "symbol" ? propertyKey.toString() : propertyKey;
-  return propertyMetadataStore.get(target)?.get(key);
-}
-function getApiPropertyKeys(target) {
-  const metaMap = propertyMetadataStore.get(target);
-  if (!metaMap)
-    return [];
-  return Array.from(metaMap.keys());
-}
-
 // src/openapi/schema-generator.ts
+init_metadata();
+
 class SchemaGenerator {
   schemas = new Map;
   typeNames = new Map;
@@ -395,6 +410,9 @@ class SchemaGenerator {
     this.typeCounter = 0;
   }
 }
+// src/openapi/route-scanner.ts
+init_metadata();
+
 // src/modules/metadata.ts
 var metadataStore = new WeakMap;
 function setMetadata(target, key, value) {
@@ -647,6 +665,7 @@ class SwaggerModule {
   }
 }
 // src/openapi/decorators.ts
+init_metadata();
 function ApiTags(...tags) {
   return (target) => {
     const existingTags = getApiMetadata(target, "api:tags") ?? [];