@buenojs/bueno 0.8.4 → 0.8.6

package/src/openapi/__tests__/schema-generator.test.ts

@@ -0,0 +1,275 @@
+import { describe, test, expect } from 'bun:test';
+import { SchemaGenerator } from '../schema-generator';
+import { ApiProperty, ApiPropertyOptional } from '../decorators';
+
+// ============= Test Fixtures =============
+
+class SimpleDto {
+	@ApiProperty({ description: 'User name' })
+	name!: string;
+
+	@ApiPropertyOptional({ description: 'User email' })
+	email?: string;
+}
+
+class UserDto {
+	@ApiProperty({ description: 'User ID' })
+	id!: string;
+
+	@ApiProperty({ description: 'Email address', format: 'email' })
+	email!: string;
+
+	@ApiProperty({ description: 'Full name', minLength: 2, maxLength: 100 })
+	name!: string;
+
+	@ApiPropertyOptional({ description: 'Age', minimum: 0, maximum: 150 })
+	age?: number;
+}
+
+class CreateUserDto {
+	@ApiProperty({ description: 'Email address', example: 'user@example.com' })
+	email!: string;
+
+	@ApiProperty({ description: 'Password', minLength: 8 })
+	password!: string;
+
+	@ApiPropertyOptional({ description: 'Full name' })
+	name?: string;
+}
+
+// ============= Tests =============
+
+describe('SchemaGenerator', () => {
+	describe('Primitive type generation', () => {
+		test('should generate string schema from String type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema(String);
+			expect(schema.type).toBe('string');
+		});
+
+		test('should generate number schema from Number type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema(Number);
+			expect(schema.type).toBe('number');
+		});
+
+		test('should generate boolean schema from Boolean type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema(Boolean);
+			expect(schema.type).toBe('boolean');
+		});
+
+		test('should generate schema from string type names', () => {
+			const generator = new SchemaGenerator();
+
+			expect(generator.generateSchema('string').type).toBe('string');
+			expect(generator.generateSchema('number').type).toBe('number');
+			expect(generator.generateSchema('integer').type).toBe('integer');
+			expect(generator.generateSchema('boolean').type).toBe('boolean');
+		});
+
+		test('should generate email format for email type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema('email');
+			expect(schema.type).toBe('string');
+			expect(schema.format).toBe('email');
+		});
+
+		test('should generate date-time format for datetime type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema('datetime');
+			expect(schema.type).toBe('string');
+			expect(schema.format).toBe('date-time');
+		});
+
+		test('should generate uuid format for uuid type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema('uuid');
+			expect(schema.type).toBe('string');
+			expect(schema.format).toBe('uuid');
+		});
+
+		test('should generate uri format for url type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema('url');
+			expect(schema.type).toBe('string');
+			expect(schema.format).toBe('uri');
+		});
+	});
+
+	describe('Object/DTO schema generation', () => {
+		test('should generate schema for simple DTO', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema(SimpleDto);
+
+			expect(schema.$ref).toBeDefined();
+			expect(schema.$ref).toContain('SimpleDto');
+		});
+
+		test('should cache and return reference for same DTO', () => {
+			const generator = new SchemaGenerator();
+			const schema1 = generator.generateSchema(SimpleDto);
+			const schema2 = generator.generateSchema(SimpleDto);
+
+			expect(schema1).toEqual(schema2);
+			expect(schema1.$ref).toBe(schema2.$ref);
+		});
+
+		test('should generate schemas map with DTO properties', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			expect(schemas).toHaveProperty('UserDto');
+
+			const userSchema = schemas['UserDto'];
+			expect(userSchema.type).toBe('object');
+			expect(userSchema.properties).toBeDefined();
+			expect(userSchema.properties?.['name']).toBeDefined();
+			expect(userSchema.properties?.['email']).toBeDefined();
+			expect(userSchema.properties?.['age']).toBeDefined();
+		});
+
+		test('should respect required fields', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			const userSchema = schemas['UserDto'];
+
+			expect(userSchema.required).toContain('name');
+			expect(userSchema.required).toContain('email');
+			expect(userSchema.required).toContain('id');
+
+			// Optional fields should not be in required
+			if (userSchema.required) {
+				expect(userSchema.required.includes('age')).toBe(false);
+			}
+		});
+
+		test('should include property descriptions', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			const userSchema = schemas['UserDto'];
+
+			expect((userSchema.properties?.['name'] as any)?.description).toBe('Full name');
+			expect((userSchema.properties?.['email'] as any)?.description).toBe('Email address');
+		});
+
+		test('should include format information', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			const userSchema = schemas['UserDto'];
+
+			expect((userSchema.properties?.['email'] as any)?.format).toBe('email');
+		});
+
+		test('should include validation constraints', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			const userSchema = schemas['UserDto'];
+
+			const nameProperty = userSchema.properties?.['name'] as any;
+			expect(nameProperty?.minLength).toBe(2);
+			expect(nameProperty?.maxLength).toBe(100);
+
+			const ageProperty = userSchema.properties?.['age'] as any;
+			expect(ageProperty?.minimum).toBe(0);
+			expect(ageProperty?.maximum).toBe(150);
+		});
+
+		test('should include examples and defaults', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(CreateUserDto);
+
+			const schemas = generator.getSchemas();
+			const createSchema = schemas['CreateUserDto'];
+
+			const emailProperty = createSchema.properties?.['email'] as any;
+			expect(emailProperty?.example).toBe('user@example.com');
+		});
+	});
+
+	describe('Multiple DTO schema generation', () => {
+		test('should generate schemas for multiple DTOs', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+			generator.generateSchema(CreateUserDto);
+
+			const schemas = generator.getSchemas();
+			expect(schemas).toHaveProperty('UserDto');
+			expect(schemas).toHaveProperty('CreateUserDto');
+		});
+
+		test('should handle DTOs with same property names differently', () => {
+			const generator = new SchemaGenerator();
+			const userRef = generator.generateSchema(UserDto);
+			const createRef = generator.generateSchema(CreateUserDto);
+
+			expect(userRef.$ref).not.toBe(createRef.$ref);
+		});
+	});
+
+	describe('Schema clearing', () => {
+		test('should clear all cached schemas', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+			generator.generateSchema(CreateUserDto);
+
+			let schemas = generator.getSchemas();
+			expect(Object.keys(schemas).length).toBeGreaterThan(0);
+
+			generator.clear();
+			schemas = generator.getSchemas();
+			expect(Object.keys(schemas).length).toBe(0);
+		});
+
+		test('should regenerate schemas after clearing', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+			generator.clear();
+
+			const ref1 = generator.generateSchema(UserDto);
+			const ref2 = generator.generateSchema(UserDto);
+
+			expect(ref1).toEqual(ref2);
+		});
+	});
+
+	describe('Array type handling', () => {
+		test('should handle Array type', () => {
+			const generator = new SchemaGenerator();
+			const schema = generator.generateSchema(Array);
+			expect(schema.type).toBe('array');
+		});
+	});
+
+	describe('Type name generation', () => {
+		test('should use class name for DTO', () => {
+			const generator = new SchemaGenerator();
+			generator.generateSchema(UserDto);
+
+			const schemas = generator.getSchemas();
+			expect(schemas).toHaveProperty('UserDto');
+		});
+
+		test('should generate unique names for multiple generations', () => {
+			const generator = new SchemaGenerator();
+
+			// Create anonymous classes
+			const AnonClass1 = class {};
+			const AnonClass2 = class {};
+
+			const schema1 = generator.generateSchema(AnonClass1);
+			const schema2 = generator.generateSchema(AnonClass2);
+
+			expect(schema1.$ref).not.toBe(schema2.$ref);
+		});
+	});
+});

package/src/openapi/decorators.ts

@@ -0,0 +1,328 @@
+/**
+ * OpenAPI Decorators
+ *
+ * Decorators for documenting controllers, methods, parameters, and DTOs with OpenAPI metadata.
+ */
+
+import type {
+	ApiBodyOptions,
+	ApiHeaderOptions,
+	ApiKeySecurityOptions,
+	ApiOperationOptions,
+	ApiParamOptions,
+	ApiPropertyOptions,
+	ApiQueryOptions,
+	ApiResponseOptions,
+	Constructor,
+	OpenAPISecurity,
+	SecuritySchemeOptions,
+} from './types';
+import {
+	getApiMetadata,
+	getApiMethodMetadata,
+	getApiPropertyMetadata,
+	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: string[]): ClassDecorator {
+	return <TFunction extends Function>(target: TFunction): TFunction => {
+		const existingTags = getApiMetadata<string[]>(target as unknown as Constructor, 'api:tags') ?? [];
+		const combined = [...new Set([...existingTags, ...tags])];
+		setApiMetadata(target as unknown as Constructor, '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?: SecuritySchemeOptions): ClassDecorator | MethodDecorator {
+	return function (target: unknown, propertyKey?: string | symbol) {
+		const security: OpenAPISecurity[] = [{ [name]: [] }];
+		const targetObj = propertyKey
+			? (target as object) // Method decorator
+			: (target as unknown as Constructor); // Class decorator
+
+		const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+		const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+		const existingSecurity = store<OpenAPISecurity[]>(
+			targetObj,
+			'api:security',
+		) ?? [];
+
+		setSt(targetObj, 'api:security', [...existingSecurity, ...security]);
+		return propertyKey ? descriptor : target;
+	} as any;
+}
+
+/**
+ * Mark this controller with Basic authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiBasicAuth()
+ * class ApiController { ... }
+ * ```
+ */
+export function ApiBasicAuth(name = 'basic'): ClassDecorator | MethodDecorator {
+	return function (target: unknown, propertyKey?: string | symbol) {
+		const security: OpenAPISecurity[] = [{ [name]: [] }];
+		const targetObj = propertyKey
+			? (target as object) // Method decorator
+			: (target as unknown as Constructor); // Class decorator
+
+		const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+		const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+		const existingSecurity = store<OpenAPISecurity[]>(
+			targetObj,
+			'api:security',
+		) ?? [];
+
+		setSt(targetObj, 'api:security', [...existingSecurity, ...security]);
+		return propertyKey ? descriptor : target;
+	} as any;
+}
+
+/**
+ * Mark this controller with API Key authentication
+ *
+ * @example
+ * ```typescript
+ * @Controller('/api')
+ * @ApiApiKey({ in: 'header', name: 'X-API-Key' })
+ * class ApiController { ... }
+ * ```
+ */
+export function ApiApiKey(options: ApiKeySecurityOptions, name = 'api_key'): ClassDecorator | MethodDecorator {
+	return function (target: unknown, propertyKey?: string | symbol) {
+		const security: OpenAPISecurity[] = [{ [name]: [] }];
+		const targetObj = propertyKey
+			? (target as object) // Method decorator
+			: (target as unknown as Constructor); // Class decorator
+
+		const store = propertyKey ? getApiMethodMetadata : getApiMetadata;
+		const setSt = propertyKey ? setApiMethodMetadata : setApiMetadata;
+		const existingSecurity = store<OpenAPISecurity[]>(
+			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;
+	} as any;
+}
+
+/**
+ * Exclude this entire controller from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Controller('/internal')
+ * @ApiExcludeController()
+ * class InternalController { ... }
+ * ```
+ */
+export function ApiExcludeController(): ClassDecorator {
+	return <TFunction extends Function>(target: TFunction): TFunction => {
+		setApiMetadata(target as unknown as Constructor, '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: ApiOperationOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		setApiMethodMetadata(target as object, `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: ApiResponseOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		const key = `api:responses:${String(propertyKey)}`;
+		const existing = getApiMethodMetadata<ApiResponseOptions[]>(target as object, key) ?? [];
+		existing.push(options);
+		setApiMethodMetadata(target as object, 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: ApiParamOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		const key = `api:params:${String(propertyKey)}`;
+		const existing = getApiMethodMetadata<ApiParamOptions[]>(target as object, key) ?? [];
+		existing.push(options);
+		setApiMethodMetadata(target as object, 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: ApiQueryOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		const key = `api:query:${String(propertyKey)}`;
+		const existing = getApiMethodMetadata<ApiQueryOptions[]>(target as object, key) ?? [];
+		existing.push(options);
+		setApiMethodMetadata(target as object, 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: ApiHeaderOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		const key = `api:headers:${String(propertyKey)}`;
+		const existing = getApiMethodMetadata<ApiHeaderOptions[]>(target as object, key) ?? [];
+		existing.push(options);
+		setApiMethodMetadata(target as object, 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: ApiBodyOptions): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		setApiMethodMetadata(target as object, `api:body:${String(propertyKey)}`, options);
+	};
+}
+
+/**
+ * Exclude this endpoint from OpenAPI documentation
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * @ApiExcludeEndpoint()
+ * internalOnly() { ... }
+ * ```
+ */
+export function ApiExcludeEndpoint(): MethodDecorator {
+	return (target: unknown, propertyKey: string | symbol) => {
+		setApiMethodMetadata(target as object, `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?: ApiPropertyOptions): PropertyDecorator {
+	return (target: object, propertyKey: string | symbol) => {
+		const opts: ApiPropertyOptions = { ...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?: Omit<ApiPropertyOptions, 'required'>): PropertyDecorator {
+	return (target: object, propertyKey: string | symbol) => {
+		const opts: ApiPropertyOptions = { ...options, required: false };
+		setApiPropertyMetadata(target, propertyKey, opts);
+	};
+}