@achinet/nestjs-async 0.0.1 → 0.1.0

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);
     });

package/src/decorators/asyncapi-operation-for-meta-key.decorator.ts

@@ -23,10 +23,7 @@ function makeHeaders(headers?: AsyncApiOperationHeaders) {
     : undefined;
 }
 
-function makeMessage(
-  message: OneAsyncApiMessage,
-  defaultName: string,
-): AsyncMessageObject {
+function makeMessage(message: OneAsyncApiMessage, defaultName: string): AsyncMessageObject {
   return {
     ...message,
     name: message.name || defaultName,
@@ -37,19 +34,14 @@ function makeMessage(
   };
 }
 
-export function AsyncApiOperationForMetaKey(
-  metaKey: string,
-  options: AsyncApiOperationOptions[],
-): MethodDecorator {
+export function AsyncApiOperationForMetaKey(metaKey: string, options: AsyncApiOperationOptions[]): MethodDecorator {
   return (target, propertyKey: string | symbol, descriptor) => {
     const methodName = `${target.constructor.name}#${String(propertyKey)}`;
 
     const transformedOptions: AsyncOperationObject[] = options.map((i) => {
       const message = Array.isArray(i.message)
         ? {
-            oneOf: i.message.map((i, index) =>
-              makeMessage(i, `${methodName}#${index}`),
-            ),
+            oneOf: i.message.map((j, index) => makeMessage(j, `${methodName}#${index}`)),
           }
         : makeMessage(i.message, methodName);
 
@@ -61,10 +53,6 @@ export function AsyncApiOperationForMetaKey(
       return transformedOptionInstance;
     });
 
-    return createMethodDecorator(metaKey, transformedOptions)(
-      target,
-      propertyKey,
-      descriptor,
-    );
+    return createMethodDecorator(metaKey, transformedOptions)(target, propertyKey, descriptor);
   };
 }

package/src/decorators/asyncapi-operation.decorator.ts

@@ -2,8 +2,6 @@ import { DECORATORS } from '../asyncapi.constants';
 import { AsyncApiOperationOptions } from '../interface';
 import { AsyncApiOperationForMetaKey } from './asyncapi-operation-for-meta-key.decorator';
 
-export function AsyncApiOperation(
-  ...options: AsyncApiOperationOptions[]
-): MethodDecorator {
+export function AsyncApiOperation(...options: AsyncApiOperationOptions[]): MethodDecorator {
   return AsyncApiOperationForMetaKey(DECORATORS.AsyncApiOperation, options);
 }

package/src/decorators/asyncapi-pub.decorator.ts

@@ -1,18 +1,11 @@
 import { DECORATORS } from '../asyncapi.constants';
-import {
-  AsyncApiOperationOptions,
-  AsyncApiSpecificOperationOptions,
-} from '../interface';
+import { AsyncApiOperationOptions, AsyncApiSpecificOperationOptions } from '../interface';
 import { AsyncApiOperationForMetaKey } from './asyncapi-operation-for-meta-key.decorator';
 
-export function AsyncApiPub(
-  ...specificOperationOptions: AsyncApiSpecificOperationOptions[]
-) {
-  const options: AsyncApiOperationOptions[] = specificOperationOptions.map(
-    (i) => ({
-      ...i,
-      type: 'pub',
-    }),
-  );
+export function AsyncApiPub(...specificOperationOptions: AsyncApiSpecificOperationOptions[]) {
+  const options: AsyncApiOperationOptions[] = specificOperationOptions.map((i) => ({
+    ...i,
+    type: 'pub',
+  }));
   return AsyncApiOperationForMetaKey(DECORATORS.AsyncApiPub, options);
 }

package/src/decorators/asyncapi-sub.decorator.ts

@@ -1,18 +1,11 @@
 import { DECORATORS } from '../asyncapi.constants';
-import {
-  AsyncApiOperationOptions,
-  AsyncApiSpecificOperationOptions,
-} from '../interface';
+import { AsyncApiOperationOptions, AsyncApiSpecificOperationOptions } from '../interface';
 import { AsyncApiOperationForMetaKey } from './asyncapi-operation-for-meta-key.decorator';
 
-export function AsyncApiSub(
-  ...specificOperationOptions: AsyncApiSpecificOperationOptions[]
-) {
-  const options: AsyncApiOperationOptions[] = specificOperationOptions.map(
-    (i) => ({
-      ...i,
-      type: 'sub',
-    }),
-  );
+export function AsyncApiSub(...specificOperationOptions: AsyncApiSpecificOperationOptions[]) {
+  const options: AsyncApiOperationOptions[] = specificOperationOptions.map((i) => ({
+    ...i,
+    type: 'sub',
+  }));
   return AsyncApiOperationForMetaKey(DECORATORS.AsyncApiSub, options);
 }

package/src/explorers/asyncapi-class.explorer.ts

@@ -4,18 +4,14 @@ import { DECORATORS } from '../asyncapi.constants';
 
 let GATEWAY_METADATA;
 try {
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  // eslint-disable-next-line
   const wsConstants = require('@nestjs/websockets/constants');
   GATEWAY_METADATA = wsConstants.GATEWAY_METADATA;
 } catch {
   GATEWAY_METADATA = '__gateway__'; // in case @nestjs/websockets is not installed GATEWAY_METADATA value is irrelevant
 }
 
-export const asyncApiClassAnnotationLabels = [
-  DECORATORS.AsyncApiClass,
-  CONTROLLER_WATERMARK,
-  GATEWAY_METADATA,
-];
+export const asyncApiClassAnnotationLabels = [DECORATORS.AsyncApiClass, CONTROLLER_WATERMARK, GATEWAY_METADATA];
 
 export const exploreAsyncapiClassMetadata = (metatype: Type<unknown>) => {
   return Reflect.getMetadata(DECORATORS.AsyncApiClass, metatype);