@martel/calyx 1.8.0 → 1.9.0

package/tests/openapi.test.ts

@@ -3,17 +3,25 @@ import {
   Module,
   Controller,
   Get,
+  Post,
   Param,
+  Query,
+  Body,
   CalyxFactory,
   ApiTags,
   ApiOperation,
   ApiResponse,
   ApiProperty,
+  ApiBody,
+  ApiQuery,
+  ApiHeader,
+  ApiBearerAuth,
   DocumentBuilder,
   SwaggerModule,
+  PartialType,
 } from '../src/index.ts';
 
-// 1. Model class
+// 1. DTO Model
 class Item {
   @ApiProperty({ description: 'The unique identifier', type: Number })
   id!: number;
@@ -22,15 +30,42 @@ class Item {
   name!: string;
 }
 
+// 2. Request Body DTO
+class CreateItemDto {
+  @ApiProperty({ description: 'The name of the item', type: String, required: true })
+  name!: string;
+
+  @ApiProperty({ description: 'The item price', type: Number, required: true })
+  price!: number;
+}
+
+// 3. Partial DTO using mapped type
+class UpdateItemDto extends PartialType(CreateItemDto) {}
+
 @ApiTags('Items')
+@ApiBearerAuth('jwt')
 @Controller('items')
 class ItemsController {
   @Get(':id')
   @ApiOperation({ summary: 'Get item by id', description: 'Returns a single item' })
   @ApiResponse({ status: 200, description: 'Item found successfully', type: Item })
-  getItem(@Param('id') id: string) {
+  @ApiHeader({ name: 'x-request-id', description: 'Correlation identifier' })
+  getItem(@Param('id') id: string, @Query('fields') fields?: string) {
     return { id: 1, name: 'Gadget' };
   }
+
+  @Post()
+  @ApiOperation({ summary: 'Create a new item' })
+  @ApiResponse({ status: 201, description: 'Item created successfully', type: Item })
+  createItem(@Body() body: CreateItemDto) {
+    return { id: 2, ...body };
+  }
+
+  @Post('update')
+  @ApiOperation({ summary: 'Partial update' })
+  updateItem(@Body() body: UpdateItemDto) {
+    return { id: 3, ...body };
+  }
 }
 
 @Module({
@@ -46,11 +81,12 @@ describe('OpenAPI (Swagger) Generation', () => {
   beforeAll(async () => {
     app = await CalyxFactory.create(TestApp);
     
-    // Build OpenAPI config
+    // Build OpenAPI config with bearer authentication
     const config = new DocumentBuilder()
       .setTitle('My Test API')
       .setDescription('OpenAPI description')
       .setVersion('2.0.0')
+      .addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }, 'jwt')
       .build();
     
     const document = SwaggerModule.createDocument(app, config);
@@ -64,25 +100,56 @@ describe('OpenAPI (Swagger) Generation', () => {
     await app.close();
   });
 
-  test('should serve OpenAPI JSON specification with paths and components', async () => {
+  test('should serve OpenAPI JSON specification with correct types and schemas', async () => {
     const res = await fetch(`${baseUrl}/api-json`);
     expect(res.status).toBe(200);
     const spec = await res.json();
 
+    // 1. Basic Specs
     expect(spec.openapi).toBe('3.0.0');
     expect(spec.info.title).toBe('My Test API');
     expect(spec.info.version).toBe('2.0.0');
+
+    // 2. Security Setup
+    expect(spec.components.securitySchemes.jwt).toBeDefined();
+    expect(spec.components.securitySchemes.jwt.scheme).toBe('bearer');
+
+    // 3. GET /items/{id} endpoint parameters (path, query, header)
     expect(spec.paths['/items/{id}']).toBeDefined();
-    
     const getOp = spec.paths['/items/{id}'].get;
     expect(getOp.summary).toBe('Get item by id');
     expect(getOp.tags).toContain('Items');
-    expect(getOp.parameters[0].name).toBe('id');
-    expect(getOp.parameters[0].in).toBe('path');
-    
-    expect(spec.components.schemas.Item).toBeDefined();
-    expect(spec.components.schemas.Item.properties.name.type).toBe('string');
-    expect(spec.components.schemas.Item.properties.id.type).toBe('number');
+    expect(getOp.security).toEqual([{ jwt: [] }]);
+
+    const params = getOp.parameters;
+    const pathP = params.find((p: any) => p.in === 'path');
+    const queryP = params.find((p: any) => p.in === 'query');
+    const headerP = params.find((p: any) => p.in === 'header');
+
+    expect(pathP).toBeDefined();
+    expect(pathP.name).toBe('id');
+
+    expect(queryP).toBeDefined();
+    expect(queryP.name).toBe('fields');
+
+    expect(headerP).toBeDefined();
+    expect(headerP.name).toBe('x-request-id');
+
+    // 4. POST /items request body and schema DTO definition
+    expect(spec.paths['/items']).toBeDefined();
+    const postOp = spec.paths['/items'].post;
+    expect(postOp.requestBody).toBeDefined();
+    expect(postOp.requestBody.content['application/json'].schema.$ref).toBe('#/components/schemas/CreateItemDto');
+
+    expect(spec.components.schemas.CreateItemDto).toBeDefined();
+    expect(spec.components.schemas.CreateItemDto.required).toContain('name');
+    expect(spec.components.schemas.CreateItemDto.properties.name.type).toBe('string');
+    expect(spec.components.schemas.CreateItemDto.properties.price.type).toBe('number');
+
+    // 5. Mapped Type (PartialType)
+    expect(spec.components.schemas.UpdateItemDto).toBeDefined();
+    expect(spec.components.schemas.UpdateItemDto.required).toBeUndefined(); // all optional
+    expect(spec.components.schemas.UpdateItemDto.properties.name.type).toBe('string');
   });
 
   test('should serve Swagger UI html wrapper', async () => {

package/tests/techniques.test.ts

@@ -0,0 +1,471 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync, rmdirSync } from 'fs';
+import { join } from 'path';
+import { Observable, interval, of } from 'rxjs';
+import { map, take } from 'rxjs/operators';
+import {
+  CalyxFactory,
+  Module,
+  Controller,
+  Get,
+  Post,
+  Body,
+  Injectable,
+  Inject,
+  TypeOrmModule,
+  MongooseModule,
+  InjectRepository,
+  InjectModel,
+  Req,
+  Res,
+  Repository,
+  Model,
+  Version,
+  VersioningType,
+  QueueModule,
+  InjectQueue,
+  Queue,
+  Processor,
+  Process,
+  type Job,
+  Logger,
+  Cookies,
+  compression,
+  FileInterceptor,
+  UploadedFile,
+  UploadedFiles,
+  UseInterceptors,
+  StreamableFile,
+  HttpModule,
+  HttpService,
+  session,
+  Session,
+  Render,
+  Sse,
+} from '../src/index.ts';
+
+// 1. Entities & Schemas
+class DBUser {
+  id?: number;
+  name!: string;
+  role!: string;
+}
+
+class MongoCat {
+  _id?: any;
+  name!: string;
+  age!: number;
+}
+
+// 2. Queue Processor
+@Processor('test-queue')
+class TestQueueProcessor {
+  static processedJobs: any[] = [];
+
+  @Process('test-job')
+  handleTestJob(job: Job) {
+    TestQueueProcessor.processedJobs.push(job.data);
+    return { status: 'ok', handled: true };
+  }
+}
+
+// 3. Controller under Test
+@Controller('test')
+class TechniquesController {
+  constructor(
+    @InjectRepository(DBUser)
+    private readonly userRepo: Repository<DBUser>,
+    @InjectModel('Cat')
+    private readonly catModel: Model<MongoCat>,
+    @InjectQueue('test-queue')
+    private readonly queue: Queue,
+    private readonly httpService: HttpService
+  ) {}
+
+  // DB Tests
+  @Post('db/user')
+  async createUser(@Body() body: { name: string; role: string }) {
+    const user = new DBUser();
+    user.name = body.name;
+    user.role = body.role;
+    return await this.userRepo.save(user);
+  }
+
+  @Get('db/users')
+  async getUsers() {
+    return await this.userRepo.find();
+  }
+
+  @Post('mongo/cat')
+  async createCat(@Body() body: { name: string; age: number }) {
+    return await this.catModel.create(body);
+  }
+
+  @Get('mongo/cats')
+  async getCats() {
+    return await this.catModel.find().exec();
+  }
+
+  // Versioning Tests
+  @Version('1')
+  @Get('versioned')
+  getVersion1() {
+    return 'version 1';
+  }
+
+  @Version('2')
+  @Get('versioned')
+  getVersion2() {
+    return 'version 2';
+  }
+
+  // Queue Tests
+  @Post('queue/job')
+  async addJob(@Body() body: any) {
+    const job = await this.queue.add('test-job', body);
+    return { id: job.id, status: job.status };
+  }
+
+  // Cookies
+  @Get('cookies')
+  getCookies(@Cookies('test_cookie') val: string) {
+    return { test_cookie: val };
+  }
+
+  @Post('cookies')
+  setCookies(@Req() req: any, @Res() res: any) {
+    res.cookie('test_cookie', 'calyx_val', { httpOnly: true });
+    res.send({ status: 'cookie_set' });
+  }
+
+  // Compression & Files
+  @Get('long-text')
+  getLongText() {
+    return 'A'.repeat(5000); // long string to trigger compression
+  }
+
+  @Post('upload')
+  @UseInterceptors(new FileInterceptor('file'))
+  uploadFile(@UploadedFile() file: any) {
+    return {
+      fieldname: file.fieldname,
+      originalname: file.originalname,
+      size: file.size,
+      content: file.buffer.toString(),
+    };
+  }
+
+  @Get('stream')
+  streamFile() {
+    const buffer = Buffer.from('streamable file contents');
+    return new StreamableFile(buffer, { type: 'text/plain', disposition: 'attachment; filename="test.txt"' });
+  }
+
+  // Http Service
+  @Get('fetch-local')
+  fetchLocal() {
+    return this.httpService.get('http://localhost:3999/test/long-text').pipe(
+      map((res) => ({ size: res.data.length, status: res.status }))
+    );
+  }
+
+  // Session
+  @Get('session')
+  getSession(@Session() sessionData: any) {
+    sessionData.counter = (sessionData.counter || 0) + 1;
+    return { counter: sessionData.counter };
+  }
+
+  // MVC Render
+  @Get('render')
+  @Render('test-template')
+  renderView() {
+    return { title: 'Calyx Framework', message: 'Hello MVC!' };
+  }
+
+  // SSE
+  @Sse('sse')
+  sseStream(): Observable<any> {
+    return interval(10).pipe(
+      take(3),
+      map((num) => ({ data: { count: num }, id: String(num), type: 'message' }))
+    );
+  }
+}
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({ type: 'sqlite', database: ':memory:' }),
+    TypeOrmModule.forFeature([DBUser]),
+    MongooseModule.forRoot('mongodb://localhost/test_db'),
+    MongooseModule.forFeature([{ name: 'Cat' }]),
+    QueueModule.registerQueue({ name: 'test-queue' }),
+    HttpModule.register(),
+  ],
+  controllers: [TechniquesController],
+  providers: [TestQueueProcessor],
+})
+class TechniquesTestApp {}
+
+describe('Calyx NestJS Techniques Integration Tests', () => {
+  let app: any;
+  let baseUrl: string;
+  const PORT = 3999;
+  const viewsDir = join(import.meta.dirname, '../views');
+
+  beforeAll(async () => {
+    // Write a mock view template
+    if (!existsSync(viewsDir)) {
+      mkdirSync(viewsDir, { recursive: true });
+    }
+    writeFileSync(
+      join(viewsDir, 'test-template.html'),
+      '<html><body><h1>{{ title }}</h1><p>{{ message }}</p></body></html>'
+    );
+
+    app = await CalyxFactory.create(TechniquesTestApp);
+    app.enableVersioning({
+      type: VersioningType.HEADER,
+      header: 'X-API-Version',
+    });
+    app.setViewsDir(viewsDir);
+    app.enableCompression();
+    app.use(session({ name: 'test_session', ttl: 100 }));
+
+    await app.listen(PORT);
+    baseUrl = `http://localhost:${PORT}`;
+  });
+
+  afterAll(async () => {
+    await app.close();
+    // Clean up template
+    try {
+      unlinkSync(join(viewsDir, 'test-template.html'));
+      rmdirSync(viewsDir);
+    } catch {
+      // ignore
+    }
+  });
+
+  test('Database Module: should save and find entity successfully', async () => {
+    const createRes = await fetch(`${baseUrl}/test/db/user`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'Alice', role: 'admin' }),
+    });
+    expect(createRes.status).toBe(201);
+    const user = await createRes.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('Alice');
+
+    const getRes = await fetch(`${baseUrl}/test/db/users`);
+    expect(getRes.status).toBe(200);
+    const users = await getRes.json();
+    expect(users.length).toBeGreaterThanOrEqual(1);
+    expect(users[0].name).toBe('Alice');
+  });
+
+  test('Mongo Module: should create and find document successfully', async () => {
+    const createRes = await fetch(`${baseUrl}/test/mongo/cat`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'Garfield', age: 5 }),
+    });
+    expect(createRes.status).toBe(201);
+    const cat = await createRes.json();
+    expect(cat._id).toBeDefined();
+    expect(cat.name).toBe('Garfield');
+
+    const getRes = await fetch(`${baseUrl}/test/mongo/cats`);
+    expect(getRes.status).toBe(200);
+    const cats = await getRes.json();
+    expect(cats.length).toBeGreaterThanOrEqual(1);
+    expect(cats[0].name).toBe('Garfield');
+  });
+
+  test('Versioning Module: should match route version based on Header', async () => {
+    const resV1 = await fetch(`${baseUrl}/test/versioned`, {
+      headers: { 'X-API-Version': '1' },
+    });
+    expect(resV1.status).toBe(200);
+    expect(await resV1.text()).toBe('version 1');
+
+    const resV2 = await fetch(`${baseUrl}/test/versioned`, {
+      headers: { 'X-API-Version': '2' },
+    });
+    expect(resV2.status).toBe(200);
+    expect(await resV2.text()).toBe('version 2');
+  });
+
+  test('Queue Module: should execute task queue job asynchronously', async () => {
+    TestQueueProcessor.processedJobs = [];
+    const res = await fetch(`${baseUrl}/test/queue/job`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ message: 'hello queue' }),
+    });
+    expect(res.status).toBe(201);
+
+    // Wait a brief moment for the queue microtask to process the job
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(TestQueueProcessor.processedJobs.length).toBe(1);
+    expect(TestQueueProcessor.processedJobs[0]).toEqual({ message: 'hello queue' });
+  });
+
+  test('Cookies: should parse request cookies and set response cookies', async () => {
+    const setRes = await fetch(`${baseUrl}/test/cookies`, { method: 'POST' });
+    expect(setRes.status).toBe(200);
+    const cookieHeader = setRes.headers.get('set-cookie');
+    expect(cookieHeader).toContain('test_cookie=calyx_val');
+
+    // Get cookies using client cookie header
+    const getRes = await fetch(`${baseUrl}/test/cookies`, {
+      headers: { cookie: 'test_cookie=calyx_val' },
+    });
+    const body = await getRes.json();
+    expect(body.test_cookie).toBe('calyx_val');
+  });
+
+  test('Compression Middleware: should compress response body when accepted', async () => {
+    const normalRes = await fetch(`${baseUrl}/test/long-text`, {
+      headers: { 'accept-encoding': 'identity' },
+    });
+    expect(normalRes.status).toBe(200);
+    expect(normalRes.headers.get('content-encoding')).toBeNull();
+
+    const compressedRes = await fetch(`${baseUrl}/test/long-text`, {
+      headers: { 'accept-encoding': 'gzip' },
+    });
+    expect(compressedRes.status).toBe(200);
+    expect(compressedRes.headers.get('content-encoding')).toBe('gzip');
+  });
+
+  test('File Upload: should parse multipart/form-data body and extract file properties', async () => {
+    const formData = new FormData();
+    const blob = new Blob(['uploaded file data'], { type: 'text/plain' });
+    formData.append('file', blob, 'hello.txt');
+
+    const res = await fetch(`${baseUrl}/test/upload`, {
+      method: 'POST',
+      body: formData,
+    });
+    expect(res.status).toBe(201);
+    const data = await res.json();
+    expect(data.originalname).toBe('hello.txt');
+    expect(data.content).toBe('uploaded file data');
+  });
+
+  test('Streaming Files: should stream response with correct headers', async () => {
+    const res = await fetch(`${baseUrl}/test/stream`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/plain');
+    expect(res.headers.get('content-disposition')).toBe('attachment; filename="test.txt"');
+    const content = await res.text();
+    expect(content).toBe('streamable file contents');
+  });
+
+  test('HTTP Client Module: should make HTTP request using HttpService', async () => {
+    const res = await fetch(`${baseUrl}/test/fetch-local`);
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.status).toBe(200);
+    expect(data.size).toBe(5000);
+  });
+
+  test('Session: should persist session state across requests', async () => {
+    const res1 = await fetch(`${baseUrl}/test/session`);
+    expect(res1.status).toBe(200);
+    const body1 = await res1.json();
+    expect(body1.counter).toBe(1);
+
+    const cookie = res1.headers.get('set-cookie');
+    expect(cookie).toContain('test_session=');
+
+    // Extract session ID
+    const sid = cookie!.split(';')[0];
+
+    const res2 = await fetch(`${baseUrl}/test/session`, {
+      headers: { cookie: sid },
+    });
+    expect(res2.status).toBe(200);
+    const body2 = await res2.json();
+    expect(body2.counter).toBe(2);
+  });
+
+  test('MVC Rendering: should compile and render template', async () => {
+    const res = await fetch(`${baseUrl}/test/render`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/html');
+    const html = await res.text();
+    expect(html).toContain('<h1>Calyx Framework</h1>');
+    expect(html).toContain('<p>Hello MVC!</p>');
+  });
+
+  test('Server-Sent Events (SSE): should stream events as text/event-stream', async () => {
+    const res = await fetch(`${baseUrl}/test/sse`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/event-stream');
+
+    const reader = res.body?.getReader();
+    expect(reader).toBeDefined();
+
+    const decoder = new TextDecoder();
+    let text = '';
+    while (true) {
+      const { done, value } = await reader!.read();
+      if (done) break;
+      text += decoder.decode(value);
+    }
+
+    expect(text).toContain('id: 0');
+    expect(text).toContain('event: message');
+    expect(text).toContain('data: {"count":0}');
+
+    expect(text).toContain('id: 1');
+    expect(text).toContain('data: {"count":1}');
+
+    expect(text).toContain('id: 2');
+    expect(text).toContain('data: {"count":2}');
+  });
+
+  test('Database Module: should delegate to real TypeORM repository when available', async () => {
+    const mockRepo = {
+      save: async (entity: any) => ({ ...entity, id: 999, delegated: true }),
+      find: async () => [{ id: 999, name: 'Delegated User', delegated: true }],
+    };
+    const mockDataSource = {
+      getRepository: () => mockRepo,
+    };
+
+    const repo = new Repository(Promise.resolve(mockDataSource), DBUser, false);
+
+    const saved = await repo.save({ name: 'Bob' } as any);
+    expect(saved.id).toBe(999);
+    expect(saved.delegated).toBe(true);
+
+    const list = await repo.find();
+    expect(list[0].name).toBe('Delegated User');
+  });
+
+  test('Mongo Module: should delegate to real Mongoose Model when available', async () => {
+    const mockMongooseModel = {
+      create: async (doc: any) => ({ ...doc, _id: 'mock_mongo_id', delegated: true }),
+      find: (conds: any) => ({
+        exec: async () => [{ _id: 'mock_mongo_id', name: 'Delegated Cat', delegated: true }]
+      }),
+    };
+    const mockConnection = {
+      models: {},
+      model: () => mockMongooseModel,
+    };
+
+    const model = new Model(Promise.resolve(mockConnection), 'Cat', {}, false);
+
+    const created = await model.create({ name: 'Tom' });
+    expect(created._id).toBe('mock_mongo_id');
+    expect(created.delegated).toBe(true);
+
+    const list = await model.find().exec();
+    expect(list[0].name).toBe('Delegated Cat');
+  });
+});