@achinet/nestjs-async 0.0.1 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@achinet/nestjs-async",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "",
   "author": "",
   "license": "UNLICENSED",
@@ -11,7 +11,8 @@
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
     "lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
     "clean": "rimraf dist",
-    "test": "jest"
+    "test": "jest --passWithNoTests",
+    "test:e2e": "jest --runInBand --config test/configs/jest-e2e.config.js"
   },
   "jest": {
     "moduleFileExtensions": [
@@ -25,7 +26,7 @@
     "rootDir": "./",
     "testRegex": ".*\\.spec\\.ts$",
     "transform": {
-      "^.+\\.(t|j)s$": [
+      "^.+\\.ts$": [
         "@swc/jest",
         {
           "jsc": {
@@ -41,6 +42,9 @@
         }
       ]
     },
+    "moduleNameMapper": {
+      "^@asyncapi/generator$": "<rootDir>/test/__mocks__/@asyncapi/generator.js"
+    },
     "collectCoverageFrom": [
       "**/*.(t|j)s"
     ],
@@ -48,47 +52,50 @@
     "testEnvironment": "node"
   },
   "devDependencies": {
-    "@nestjs/cli": "11.0.5",
-    "@nestjs/microservices": "11.0.11",
-    "@nestjs/platform-express": "11.0.11",
-    "@nestjs/platform-fastify": "11.0.11",
-    "@nestjs/platform-socket.io": "11.0.11",
-    "@nestjs/schematics": "11.0.2",
-    "@nestjs/testing": "11.0.11",
-    "@nestjs/websockets": "11.0.11",
-    "@types/express": "4.17.21",
-    "@types/jest": "29.5.11",
+    "@nestjs/cli": "11.0.16",
+    "@nestjs/microservices": "11.1.13",
+    "@nestjs/platform-express": "11.1.13",
+    "@nestjs/platform-fastify": "11.1.13",
+    "@nestjs/platform-socket.io": "11.1.13",
+    "@nestjs/schematics": "11.0.9",
+    "@nestjs/testing": "11.1.13",
+    "@types/express": "5.0.6",
+    "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
-    "@types/node": "20.11.14",
-    "@types/supertest": "2.0.12",
-    "@types/url-join": "4.0.3",
-    "@typescript-eslint/eslint-plugin": "6.21.0",
-    "@typescript-eslint/parser": "6.21.0",
-    "eslint": "8.57.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-prettier": "5.1.3",
-    "husky": "9.0.10",
-    "jest": "29.7.0",
-    "lint-staged": "15.2.0",
-    "prettier": "3.2.4",
-    "release-it": "17.0.3",
-    "socket.io": "4.7.4",
-    "socket.io-client": "4.7.4",
-    "supertest": "6.3.3",
-    "ts-jest": "29.1.2",
-    "ts-loader": "9.5.1",
-    "ts-node": "10.9.2",
+    "@types/lodash": "^4.17.23",
+    "@types/node": "25.2.1",
+    "@types/supertest": "6.0.3",
+    "@types/url-join": "5.0.0",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "eslint": "10.0.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prettier": "5.5.5",
+    "husky": "9.1.7",
+    "jest": "30.2.0",
+    "lint-staged": "16.2.7",
+    "prettier": "3.8.1",
+    "release-it": "19.2.4",
+    "socket.io": "4.8.3",
+    "socket.io-client": "4.8.3",
+    "supertest": "7.2.2",
+    "ts-jest": "^29.4.6",
+    "ts-loader": "9.5.4",
+    "ts-node": "^10.9.2",
     "tsconfig-paths": "4.2.0",
-    "typescript": "5.3.3"
+    "typescript": "5.9.3"
   },
   "dependencies": {
-    "@asyncapi/generator": "1.13.1",
-    "@asyncapi/html-template": "0.28.4",
-    "@nestjs/common": "^11.1.7",
-    "@nestjs/core": "^11.1.7",
-    "@nestjs/swagger": "^11.2.1",
-    "js-yaml": "4.1.0",
-    "reflect-metadata": "0.2.1"
+    "@asyncapi/generator": "^3.1.2",
+    "@asyncapi/html-template": "^3.5.4",
+    "@nestjs/common": "^11.1.13",
+    "@nestjs/core": "^11.1.13",
+    "@nestjs/swagger": "^11.2.6",
+    "@nestjs/websockets": "^11.1.13",
+    "@swc/core": "1.15.11",
+    "js-yaml": "4.1.1",
+    "lodash": "^4.17.23",
+    "reflect-metadata": "0.2.2"
   }
 }

package/sample/app.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { FelinesModule } from './felines/felines.module';
+
+@Module({
+  imports: [FelinesModule],
+})
+export class AppModule {}

package/sample/common.ts

@@ -0,0 +1,49 @@
+import { INestApplicationContext } from '@nestjs/common';
+import { HOST, PORT, SERVER } from './constants';
+import { Cat, Feline, Lion, Tiger } from './felines/class';
+import { FelinesModule } from './felines/felines.module';
+import {
+  AsyncApiDocument,
+  AsyncApiDocumentBuilder,
+  AsyncApiModule,
+  AsyncServerObject,
+} from '../src';
+
+export async function makeAsyncapiDocument(
+  app: INestApplicationContext,
+): Promise<AsyncApiDocument> {
+  const asyncApiServer: AsyncServerObject = {
+    url: `ws://${HOST}:${PORT}`,
+    protocol: 'socket.io',
+    protocolVersion: '4',
+    description:
+      'Allows you to connect using the websocket protocol to our Socket.io server.',
+    security: [{ 'user-password': [] }],
+    variables: {
+      port: {
+        description: 'Secure connection (TLS) is available through port 443.',
+        default: '443',
+      },
+    },
+    bindings: {},
+  };
+
+  const servers = Object.keys(SERVER).map((i) => ({
+    name: SERVER[i],
+    server: asyncApiServer,
+  }));
+
+  const asyncApiOptions = new AsyncApiDocumentBuilder()
+    .setTitle('Feline')
+    .setDescription('Feline server description here')
+    .setVersion('1.0')
+    .setDefaultContentType('application/json')
+    .addSecurity('user-password', { type: 'userPassword' })
+    .addServers(servers)
+    .build();
+
+  return AsyncApiModule.createDocument(app, asyncApiOptions, {
+    include: [FelinesModule],
+    extraModels: [Cat, Lion, Tiger, Feline],
+  });
+}

package/sample/constants.ts

@@ -0,0 +1,12 @@
+export const DOC_RELATIVE_PATH = '/async-api';
+export const BOOTSTRAP = 'Bootstrap';
+export const PORT = 4001;
+export const HOST = '0.0.0.0';
+export const SERVER = {
+  europe: 'europe',
+  asia: 'asia',
+  northAmerica: 'north-america',
+  southAmerica: 'south-america',
+  africa: 'africa',
+  australia: 'australia',
+};

package/sample/felines/class/cat.class.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Feline } from './feline.class';
+
+export class Cat extends Feline {
+  @ApiProperty({
+    example: 'Maine Coon',
+  })
+  breed: string;
+}

package/sample/felines/class/feline.class.ts

@@ -0,0 +1,29 @@
+enum PawsEnum {
+  left = 'left',
+  right = 'right',
+}
+
+enum GendersEnum {
+  male = 'male',
+  female = 'female',
+}
+
+export abstract class Feline {
+  id: number;
+
+  name: string;
+
+  age: number;
+
+  gender: GendersEnum;
+
+  dominantPaw: PawsEnum;
+
+  tags: string[];
+
+  birthDatetime: Date;
+
+  constructor(initializer: Record<string, unknown>) {
+    Object.assign(this, initializer);
+  }
+}

package/sample/felines/class/index.ts

@@ -0,0 +1,5 @@
+export * from './feline.class';
+export * from './cat.class';
+export * from './lion.class';
+export * from './tiger.class';
+export * from './message.class';

package/sample/felines/class/lion.class.ts

@@ -0,0 +1,5 @@
+import { Feline } from './feline.class';
+
+export class Lion extends Feline {
+  roarVolume: number;
+}

package/sample/felines/class/message.class.ts

@@ -0,0 +1,17 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export abstract class Message<T extends Record<string, any>> {
+  @ApiProperty({ format: 'uuid' })
+  correlationId: string;
+
+  @ApiProperty({ format: 'x.y.z', example: '1.0.1' })
+  version: string;
+
+  timestamp: Date;
+
+  abstract payload: T;
+
+  constructor(partialData: Partial<Message<T>>) {
+    Object.assign(this, partialData);
+  }
+}

package/sample/felines/class/tiger.class.ts

@@ -0,0 +1,5 @@
+import { Feline } from './feline.class';
+
+export class Tiger extends Feline {
+  numberOfStripes: number;
+}

package/sample/felines/dto/create-feline.dto.ts

@@ -0,0 +1,13 @@
+import { ApiProperty, getSchemaPath } from '@nestjs/swagger';
+import { Cat, Feline, Lion, Message, Tiger } from '../class';
+
+export class CreateFelineDto extends Message<Feline> {
+  @ApiProperty({
+    oneOf: [
+      { $ref: getSchemaPath(Cat) },
+      { $ref: getSchemaPath(Lion) },
+      { $ref: getSchemaPath(Tiger) },
+    ],
+  })
+  payload: Feline;
+}

package/sample/felines/dto/index.ts

@@ -0,0 +1,2 @@
+export * from '../class/message.class';
+export * from './create-feline.dto';

package/sample/felines/dto/journaling-data.dto.ts

@@ -0,0 +1,5 @@
+import { Message } from '../class';
+
+export class JournalingDataDto extends Message<Record<string, unknown>> {
+  payload: Record<string, unknown>;
+}

package/sample/felines/felines.constants.ts

@@ -0,0 +1 @@
+export const FELINES_MS = 'FELINES_MS';

package/sample/felines/felines.controller.ts

@@ -0,0 +1,76 @@
+import { Controller, Get, Inject, Logger } from '@nestjs/common';
+import { ClientProxy, EventPattern } from '@nestjs/microservices';
+import { CreateFelineDto } from './dto';
+import { AsyncApiPub, AsyncApiSub } from '../../src';
+import { Cat, Feline } from '../../sample/felines/class';
+import { JournalingDataDto } from '../../sample/felines/dto/journaling-data.dto';
+import { FELINES_MS } from '../../sample/felines/felines.constants';
+import { FelinesService } from '../../sample/felines/felines.service';
+import { FelineRto } from '../../sample/felines/rto';
+
+const EventPatternsMS = {
+  createFeline: 'ms/create/feline',
+  journal: 'ms/journal',
+};
+
+/**
+ * How to use AsyncApi in a microservices
+ */
+@Controller()
+export class FelinesController {
+  private logger: Logger = new Logger(FelinesController.name);
+
+  constructor(
+    @Inject(FELINES_MS)
+    private readonly client: ClientProxy,
+    private readonly felinesService: FelinesService,
+  ) {}
+
+  @AsyncApiSub({
+    channel: EventPatternsMS.journal,
+    message: {
+      payload: JournalingDataDto,
+    },
+  })
+  @EventPattern(EventPatternsMS.journal)
+  async journal(dataForJournaling: JournalingDataDto) {
+    const dataForJournalingString = JSON.stringify(dataForJournaling, null, 4);
+    this.logger.log(`journaling:\n${dataForJournalingString}`);
+  }
+
+  @AsyncApiPub({
+    channel: EventPatternsMS.createFeline,
+    message: {
+      payload: CreateFelineDto,
+    },
+  })
+  @AsyncApiSub({
+    channel: EventPatternsMS.createFeline,
+    message: {
+      payload: FelineRto,
+    },
+  })
+  @EventPattern(EventPatternsMS.createFeline)
+  async createFeline(createFelineDto: CreateFelineDto) {
+    const feline = await this.felinesService.create(createFelineDto);
+    this.logger.debug(`feline created:\n${JSON.stringify(feline)}`);
+    this.publishCreatedFeline(feline);
+  }
+
+  publishCreatedFeline(feline: Feline) {
+    const felineRto = new FelineRto({ payload: feline });
+    return this.client.emit(EventPatternsMS.journal, felineRto);
+  }
+
+  @Get()
+  async do() {
+    const cat = new Cat({
+      id: 123,
+      name: 'demo',
+    });
+
+    const felineRto = new CreateFelineDto({ payload: cat });
+
+    await this.createFeline(felineRto);
+  }
+}

package/sample/felines/felines.gateway.ts

@@ -0,0 +1,76 @@
+import { Logger } from '@nestjs/common';
+import {
+  ConnectedSocket,
+  MessageBody,
+  OnGatewayDisconnect,
+  OnGatewayInit,
+  SubscribeMessage,
+  WebSocketGateway,
+  WebSocketServer,
+} from '@nestjs/websockets';
+import { Namespace, Server } from 'socket.io';
+import { Socket } from 'socket.io-client';
+import { FelinesService } from './/felines.service';
+import { CreateFelineDto } from './dto';
+import { FelineExtendedRto, FelineRto } from './rto';
+import { AsyncApiPub, AsyncApiSub } from '../../src';
+
+const EventPatternsWS = {
+  createFeline: 'ws/create/feline',
+};
+
+/**
+ * How to use AsyncApi in a websockets
+ */
+@WebSocketGateway({ transports: ['websocket'], namespace: 'ws' })
+export class FelinesGateway implements OnGatewayInit, OnGatewayDisconnect {
+  @WebSocketServer()
+  private readonly server: Server;
+  private readonly logger: Logger = new Logger(FelinesGateway.name);
+
+  constructor(private readonly felinesService: FelinesService) {}
+
+  afterInit(nsp: Namespace) {
+    this.logger.log(`Gateway server init: ${nsp?.name}`);
+  }
+
+  handleDisconnect(client: Socket) {
+    this.logger.log(`Client disconnected: ${client.id}`);
+  }
+
+  @SubscribeMessage(EventPatternsWS.createFeline)
+  @AsyncApiPub({
+    channel: EventPatternsWS.createFeline,
+    message: {
+      payload: CreateFelineDto,
+    },
+  })
+  async createFeline(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() createFelineDto: CreateFelineDto,
+  ) {
+    this.logger.log(
+      `data from client ${client.id} : ${JSON.stringify(createFelineDto)}`,
+    );
+
+    const feline = await this.felinesService.create(createFelineDto);
+    await this.emitCreatedFeline(new FelineRto({ payload: feline }));
+  }
+
+  @AsyncApiSub({
+    channel: EventPatternsWS.createFeline,
+    message: [
+      {
+        name: 'oneOf demo #1',
+        payload: FelineRto,
+      },
+      {
+        name: 'oneOf demo #2',
+        payload: FelineExtendedRto,
+      },
+    ],
+  })
+  async emitCreatedFeline(felineRto: FelineRto) {
+    this.server.emit(EventPatternsWS.createFeline, felineRto);
+  }
+}

package/sample/felines/felines.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { ClientsModule, Transport } from '@nestjs/microservices';
+import { FELINES_MS } from './felines.constants';
+import { FelinesController } from './felines.controller';
+import { FelinesGateway } from './felines.gateway';
+import { FelinesService } from './felines.service';
+
+@Module({
+  imports: [
+    ClientsModule.register([{ name: FELINES_MS, transport: Transport.TCP }]),
+  ],
+  providers: [FelinesService, FelinesGateway],
+  controllers: [FelinesController],
+})
+export class FelinesModule {}

package/sample/felines/felines.service.ts

@@ -0,0 +1,24 @@
+import { Injectable } from '@nestjs/common';
+import { Feline } from './class';
+import { CreateFelineDto } from './dto';
+
+@Injectable()
+export class FelinesService {
+  private readonly felines: Feline[] = [];
+
+  async get(id: number): Promise<Feline> {
+    return this.felines[id];
+  }
+
+  async delete(id: number): Promise<boolean> {
+    const felineToDelete = this.get(id);
+    delete this.felines[id];
+    return !!felineToDelete;
+  }
+
+  async create(createFelineDto: CreateFelineDto): Promise<Feline> {
+    const feline = createFelineDto.payload;
+    this.felines.push(feline);
+    return feline;
+  }
+}

package/sample/felines/rto/feline.rto.ts

@@ -0,0 +1,17 @@
+import { ApiProperty, getSchemaPath } from '@nestjs/swagger';
+import { Cat, Feline, Lion, Message, Tiger } from '../class';
+
+export class FelineRto extends Message<Feline> {
+  @ApiProperty({
+    oneOf: [
+      { $ref: getSchemaPath(Cat) },
+      { $ref: getSchemaPath(Lion) },
+      { $ref: getSchemaPath(Tiger) },
+    ],
+  })
+  payload: Feline;
+}
+
+export class FelineExtendedRto extends FelineRto {
+  extra: string;
+}

package/sample/felines/rto/index.ts

@@ -0,0 +1 @@
+export * from './feline.rto';

package/sample/index.ts

@@ -0,0 +1,3 @@
+export * from './app.module';
+export * from './common';
+export * from './constants';

package/sample/main.ts

@@ -0,0 +1,34 @@
+import { INestApplication, Logger } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { MicroserviceOptions, Transport } from '@nestjs/microservices';
+import { ExpressAdapter } from '@nestjs/platform-express';
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+import { AppModule } from './app.module';
+import { makeAsyncapiDocument } from './common';
+import { BOOTSTRAP, DOC_RELATIVE_PATH, HOST, PORT } from './constants';
+import { AsyncApiModule } from '../src';
+
+const USE_FASTIFY = false;
+
+const adapter = USE_FASTIFY
+  ? new FastifyAdapter({
+      ignoreTrailingSlash: false,
+    })
+  : new ExpressAdapter();
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create<INestApplication>(AppModule, adapter, {});
+  const asyncapiDocument = await makeAsyncapiDocument(app);
+  await AsyncApiModule.setup(DOC_RELATIVE_PATH, app, asyncapiDocument);
+
+  app.connectMicroservice<MicroserviceOptions>({ transport: Transport.TCP });
+
+  await app.startAllMicroservices();
+  await app.listen(PORT, HOST);
+
+  const baseUrl = `http://${HOST}:${PORT}`;
+  const docUrl = baseUrl + DOC_RELATIVE_PATH;
+  Logger.log(`Server started at ${baseUrl}; AsyncApi at ${docUrl};`, BOOTSTRAP);
+}
+
+bootstrap();

package/src/asyncapi-document.builder.ts

@@ -4,17 +4,10 @@ import {
   TagObject,
 } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
 import { isUndefined, negate, pickBy } from 'lodash';
-import {
-  AsyncApiDocument,
-  AsyncSecuritySchemeObject,
-  AsyncServerObject,
-} from './interface';
+import { AsyncApiDocument, AsyncSecuritySchemeObject, AsyncServerObject } from './interface';
 
 export class AsyncApiDocumentBuilder {
-  private readonly buildDocumentBase = (): Omit<
-    AsyncApiDocument,
-    'channels'
-  > => ({
+  private readonly buildDocumentBase = (): Omit<AsyncApiDocument, 'channels'> => ({
     asyncapi: '2.5.0',
     info: {
       title: '',
@@ -27,8 +20,7 @@ export class AsyncApiDocumentBuilder {
     components: {},
   });
 
-  private readonly document: Omit<AsyncApiDocument, 'channels'> =
-    this.buildDocumentBase();
+  private readonly document: Omit<AsyncApiDocument, 'channels'> = this.buildDocumentBase();
 
   public setTitle(title: string): this {
     this.document.info.title = title;
@@ -65,9 +57,7 @@ export class AsyncApiDocumentBuilder {
     return this;
   }
 
-  public addServers(
-    servers: { name: string; server: AsyncServerObject }[],
-  ): this {
+  public addServers(servers: { name: string; server: AsyncServerObject }[]): this {
     for (const { name, server } of servers) {
       this.addServer(name, server);
     }
@@ -85,11 +75,7 @@ export class AsyncApiDocumentBuilder {
     return this;
   }
 
-  public addTag(
-    name: string,
-    description = '',
-    externalDocs?: ExternalDocumentationObject,
-  ): this {
+  public addTag(name: string, description = '', externalDocs?: ExternalDocumentationObject): this {
     this.document.tags = this.document.tags!.concat(
       pickBy(
         {

package/src/asyncapi.module.ts

@@ -1,15 +1,7 @@
-import {
-  INestApplication,
-  INestApplicationContext,
-  Logger,
-} from '@nestjs/common';
+import { INestApplication, INestApplicationContext, Logger } from '@nestjs/common';
 import { validatePath } from '@nestjs/swagger/dist/utils/validate-path.util';
 import jsyaml from 'js-yaml';
-import {
-  AsyncApiDocument,
-  AsyncApiDocumentOptions,
-  AsyncApiTemplateOptions,
-} from './interface';
+import { AsyncApiDocument, AsyncApiDocumentOptions, AsyncApiTemplateOptions } from './interface';
 import { AsyncapiGenerator, AsyncapiScanner } from './services';
 
 export class AsyncApiModule {
@@ -34,10 +26,7 @@ export class AsyncApiModule {
     };
   }
 
-  static async composeHtml(
-    contract: AsyncApiDocument,
-    templateOptions?: AsyncApiTemplateOptions,
-  ) {
+  static async composeHtml(contract: AsyncApiDocument, templateOptions?: AsyncApiTemplateOptions) {
     const generator = new AsyncapiGenerator(templateOptions);
     return generator.generate(contract).catch((err) => {
       this.logger.error(err);
@@ -63,12 +52,12 @@ export class AsyncApiModule {
       res.send(html);
     });
 
-    httpAdapter.get(finalPath + '-json', (req, res) => {
+    httpAdapter.get(`${finalPath}-json`, (req, res) => {
       res.type('application/json');
       res.send(jsonDocument);
     });
 
-    httpAdapter.get(finalPath + '-yaml', (req, res) => {
+    httpAdapter.get(`${finalPath}-yaml`, (req, res) => {
       res.type('text/yaml');
       res.send(yamlDocument);
     });