@buenojs/bueno 0.8.10 → 0.8.11

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/observability/types.js

@@ -0,0 +1,8 @@
+/**
+ * Observability Types
+ *
+ * Core interfaces for the error tracking and observability integration layer.
+ * Implement ErrorReporter to integrate with Sentry, Bugsnag, Datadog, etc.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/observability/types.js.map

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

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/decorators.js

@@ -0,0 +1,276 @@
+/**
+ * OpenAPI Decorators
+ *
+ * Decorators for documenting controllers, methods, parameters, and DTOs with OpenAPI metadata.
+ */
+import { getApiMetadata, getApiMethodMetadata, setApiMetadata, setApiMethodMetadata, setApiPropertyMetadata, } from './metadata';
+// ============= Class-Level Decorators =============
+/**
+ * Mark one or more tags that apply to all operations in this controller
+ *
+ * @example
+ * ```typescript
+ * @Controller('/users')
+ * @ApiTags('users', 'accounts')
+ * class UserController { ... }
+ * ```
+ */
+export function ApiTags(...tags) {
+    return (target) => {
+        const existingTags = getApiMetadata(target, 'api:tags') ?? [];
+        const combined = [...new Set([...existingTags, ...tags])];
+        setApiMetadata(target, 'api:tags', combined);
+        return target;
+    };
+}
+/**
+ * Mark this controller with Bearer token authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBearerAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export function ApiBearerAuth(name = 'bearer', options) {
+    return function (target, propertyKey) {
+        const security = [{ [name]: [] }];
+        const targetObj = propertyKey
+            ? target // Method decorator
+            : target; // Class decorator
+        const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+        const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+        const existingSecurity = store(targetObj, 'api:security') ?? [];
+        setSt(targetObj, 'api:security', [...existingSecurity, ...security]);
+        return propertyKey ? descriptor : target;
+    };
+}
+/**
+ * Mark this controller with Basic authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBasicAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export function ApiBasicAuth(name = 'basic') {
+    return function (target, propertyKey) {
+        const security = [{ [name]: [] }];
+        const targetObj = propertyKey
+            ? target // Method decorator
+            : target; // Class decorator
+        const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+        const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+        const existingSecurity = store(targetObj, 'api:security') ?? [];
+        setSt(targetObj, 'api:security', [...existingSecurity, ...security]);
+        return propertyKey ? descriptor : target;
+    };
+}
+/**
+ * Mark this controller with API Key authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiApiKey({ in: 'header', name: 'X-API-Key' })
+ * class ApiController { ... }
+ * ```
+ */
+export function ApiApiKey(options, name = 'api_key') {
+    return function (target, propertyKey) {
+        const security = [{ [name]: [] }];
+        const targetObj = propertyKey
+            ? target // Method decorator
+            : target; // Class decorator
+        const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+        const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+        const existingSecurity = store(targetObj, 'api:security') ?? [];
+        // Store security scheme metadata for document builder
+        setSt(targetObj, `api:security:scheme:${name}`, options);
+        setSt(targetObj, 'api:security', [...existingSecurity, ...security]);
+        return propertyKey ? descriptor : target;
+    };
+}
+/**
+ * Exclude this entire controller from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Controller('/internal')
+ * @ApiExcludeController()
+ * class InternalController { ... }
+ * ```
+ */
+export function ApiExcludeController() {
+    return (target) => {
+        setApiMetadata(target, 'api:exclude', true);
+        return target;
+    };
+}
+// ============= Method-Level Decorators =============
+/**
+ * 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 function ApiOperation(options) {
+    return (target, propertyKey) => {
+        setApiMethodMetadata(target, `api:operation:${String(propertyKey)}`, options);
+    };
+}
+/**
+ * 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 function ApiResponse(options) {
+    return (target, propertyKey) => {
+        const key = `api:responses:${String(propertyKey)}`;
+        const existing = getApiMethodMetadata(target, key) ?? [];
+        existing.push(options);
+        setApiMethodMetadata(target, key, existing);
+    };
+}
+/**
+ * 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 function ApiParam(options) {
+    return (target, propertyKey) => {
+        const key = `api:params:${String(propertyKey)}`;
+        const existing = getApiMethodMetadata(target, key) ?? [];
+        existing.push(options);
+        setApiMethodMetadata(target, key, existing);
+    };
+}
+/**
+ * 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 function ApiQuery(options) {
+    return (target, propertyKey) => {
+        const key = `api:query:${String(propertyKey)}`;
+        const existing = getApiMethodMetadata(target, key) ?? [];
+        existing.push(options);
+        setApiMethodMetadata(target, key, existing);
+    };
+}
+/**
+ * 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 function ApiHeader(options) {
+    return (target, propertyKey) => {
+        const key = `api:headers:${String(propertyKey)}`;
+        const existing = getApiMethodMetadata(target, key) ?? [];
+        existing.push(options);
+        setApiMethodMetadata(target, key, existing);
+    };
+}
+/**
+ * Document the request body
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiBody({ type: CreateUserDto, description: 'User data to create' })
+ * create(@Body() dto: CreateUserDto) { ... }
+ * ```
+ */
+export function ApiBody(options) {
+    return (target, propertyKey) => {
+        setApiMethodMetadata(target, `api:body:${String(propertyKey)}`, options);
+    };
+}
+/**
+ * Exclude this endpoint from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiExcludeEndpoint()
+ * internalOnly() { ... }
+ * ```
+ */
+export function ApiExcludeEndpoint() {
+    return (target, propertyKey) => {
+        setApiMethodMetadata(target, `api:exclude:${String(propertyKey)}`, true);
+    };
+}
+// ============= Property-Level Decorators (for DTOs) =============
+/**
+ * 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 function ApiProperty(options) {
+    return (target, propertyKey) => {
+        const opts = { ...options, required: options?.required !== false };
+        setApiPropertyMetadata(target, propertyKey, opts);
+    };
+}
+/**
+ * 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 function ApiPropertyOptional(options) {
+    return (target, propertyKey) => {
+        const opts = { ...options, required: false };
+        setApiPropertyMetadata(target, propertyKey, opts);
+    };
+}
+//# sourceMappingURL=decorators.js.map

package/dist/openapi/decorators.js.map

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