@achinet/nestjs-async 0.0.1

package/src/asyncapi-document.builder.ts

@@ -0,0 +1,186 @@
+import {
+  ExternalDocumentationObject,
+  SecuritySchemeObject,
+  TagObject,
+} from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import { isUndefined, negate, pickBy } from 'lodash';
+import {
+  AsyncApiDocument,
+  AsyncSecuritySchemeObject,
+  AsyncServerObject,
+} from './interface';
+
+export class AsyncApiDocumentBuilder {
+  private readonly buildDocumentBase = (): Omit<
+    AsyncApiDocument,
+    'channels'
+  > => ({
+    asyncapi: '2.5.0',
+    info: {
+      title: '',
+      description: '',
+      version: '1.0.0',
+      contact: {},
+    },
+    tags: [],
+    servers: {},
+    components: {},
+  });
+
+  private readonly document: Omit<AsyncApiDocument, 'channels'> =
+    this.buildDocumentBase();
+
+  public setTitle(title: string): this {
+    this.document.info.title = title;
+    return this;
+  }
+
+  public setDescription(description: string): this {
+    this.document.info.description = description;
+    return this;
+  }
+
+  public setVersion(version: string): this {
+    this.document.info.version = version;
+    return this;
+  }
+
+  public setTermsOfService(termsOfService: string): this {
+    this.document.info.termsOfService = termsOfService;
+    return this;
+  }
+
+  public setContact(name: string, url: string, email: string): this {
+    this.document.info.contact = { name, url, email };
+    return this;
+  }
+
+  public setLicense(name: string, url: string): this {
+    this.document.info.license = { name, url };
+    return this;
+  }
+
+  public addServer(name: string, server: AsyncServerObject): this {
+    this.document.servers![name] = server;
+    return this;
+  }
+
+  public addServers(
+    servers: { name: string; server: AsyncServerObject }[],
+  ): this {
+    for (const { name, server } of servers) {
+      this.addServer(name, server);
+    }
+
+    return this;
+  }
+
+  public setExternalDoc(description: string, url: string): this {
+    this.document.externalDocs = { description, url };
+    return this;
+  }
+
+  public setDefaultContentType(contentType: string) {
+    this.document.defaultContentType = contentType;
+    return this;
+  }
+
+  public addTag(
+    name: string,
+    description = '',
+    externalDocs?: ExternalDocumentationObject,
+  ): this {
+    this.document.tags = this.document.tags!.concat(
+      pickBy(
+        {
+          name,
+          description,
+          externalDocs,
+        },
+        negate(isUndefined),
+      ) as TagObject,
+    );
+    return this;
+  }
+
+  public addSecurity(name: string, options: AsyncSecuritySchemeObject): this {
+    this.document.components!.securitySchemes = {
+      ...(this.document.components!.securitySchemes || {}),
+      [name]: options,
+    };
+    return this;
+  }
+
+  public addBearerAuth(
+    options: SecuritySchemeObject = {
+      type: 'http',
+    },
+    name = 'bearer',
+  ): this {
+    this.addSecurity(name, {
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      ...options,
+    });
+    return this;
+  }
+
+  public addOAuth2(
+    options: SecuritySchemeObject = {
+      type: 'oauth2',
+    },
+    name = 'oauth2',
+  ): this {
+    this.addSecurity(name, {
+      flows: {},
+      ...options,
+    });
+    return this;
+  }
+
+  public addApiKey(
+    options: SecuritySchemeObject = {
+      type: 'apiKey',
+    },
+    name = 'api_key',
+  ): this {
+    this.addSecurity(name, {
+      in: 'header',
+      name,
+      ...options,
+    });
+    return this;
+  }
+
+  public addBasicAuth(
+    options: SecuritySchemeObject = {
+      type: 'http',
+    },
+    name = 'basic',
+  ): this {
+    this.addSecurity(name, {
+      scheme: 'basic',
+      ...options,
+    });
+    return this;
+  }
+
+  public addCookieAuth(
+    cookieName = 'connect.sid',
+    options: SecuritySchemeObject = {
+      type: 'apiKey',
+    },
+    securityName = 'cookie',
+  ): this {
+    this.addSecurity(securityName, {
+      in: 'cookie',
+      name: cookieName,
+      ...options,
+    });
+    return this;
+  }
+
+  public build(): Omit<AsyncApiDocument, 'components' | 'channels'> {
+    return this.document;
+  }
+}

package/src/asyncapi.constants.ts

@@ -0,0 +1,8 @@
+const DECORATORS_PREFIX = 'asyncapi';
+
+export const DECORATORS = {
+  AsyncApiClass: `${DECORATORS_PREFIX}/class`,
+  AsyncApiOperation: `${DECORATORS_PREFIX}/operation`,
+  AsyncApiPub: `${DECORATORS_PREFIX}/pub`,
+  AsyncApiSub: `${DECORATORS_PREFIX}/sub`,
+};

package/src/asyncapi.module.ts

@@ -0,0 +1,76 @@
+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 { AsyncapiGenerator, AsyncapiScanner } from './services';
+
+export class AsyncApiModule {
+  private static readonly logger = new Logger(AsyncApiModule.name);
+
+  public static createDocument(
+    app: INestApplicationContext,
+    config: Omit<AsyncApiDocument, 'channels'>,
+    options: AsyncApiDocumentOptions = {},
+  ): AsyncApiDocument {
+    const asyncapiScanner = new AsyncapiScanner();
+    const document = asyncapiScanner.scanApplication(app, options);
+
+    document.components = {
+      ...(config.components || {}),
+      ...document.components,
+    };
+
+    return {
+      ...config,
+      ...document,
+    };
+  }
+
+  static async composeHtml(
+    contract: AsyncApiDocument,
+    templateOptions?: AsyncApiTemplateOptions,
+  ) {
+    const generator = new AsyncapiGenerator(templateOptions);
+    return generator.generate(contract).catch((err) => {
+      this.logger.error(err);
+      throw err;
+    });
+  }
+
+  public static async setup(
+    path: string,
+    app: INestApplication,
+    document: AsyncApiDocument,
+    templateOptions?: AsyncApiTemplateOptions,
+  ) {
+    const httpAdapter = app.getHttpAdapter();
+    const finalPath = validatePath(path);
+
+    const html = await this.composeHtml(document, templateOptions);
+    const yamlDocument = jsyaml.dump(document);
+    const jsonDocument = JSON.stringify(document);
+
+    httpAdapter.get(finalPath, (req, res) => {
+      res.type('text/html');
+      res.send(html);
+    });
+
+    httpAdapter.get(finalPath + '-json', (req, res) => {
+      res.type('application/json');
+      res.send(jsonDocument);
+    });
+
+    httpAdapter.get(finalPath + '-yaml', (req, res) => {
+      res.type('text/yaml');
+      res.send(yamlDocument);
+    });
+  }
+}

package/src/binding/asyncapi.amqp.interfaces.ts

@@ -0,0 +1,48 @@
+/**
+ * AMPQ binding
+ * @see https://github.com/asyncapi/bindings/tree/master/amqp
+ */
+
+/**
+ * This object MUST NOT contain any properties. Its name is reserved for future use.
+ */
+export interface AmqpServerBinding {}
+
+export interface AmqpChannelBinding {
+  is: string;
+  exchange?: {
+    name: string;
+    type: string;
+    durable?: boolean;
+    autoDelete?: boolean;
+    vhost?: string;
+  };
+  queue?: {
+    name: string;
+    durable?: boolean;
+    exclusive?: boolean;
+    autoDelete?: boolean;
+    vhost?: string;
+  };
+  bindingVersion?: string;
+}
+
+export interface AmqpOperationBinding {
+  expiration?: number;
+  userId?: string;
+  cc?: string[];
+  priority?: number;
+  deliveryMode?: number;
+  mandatory?: boolean;
+  bcc?: string[];
+  replyTo?: string;
+  timestamp?: boolean;
+  ack?: boolean;
+  bindingVersion?: string;
+}
+
+export interface AmqpMessageBinding {
+  contentEncoding?: string;
+  messageType?: string;
+  bindingVersion?: string;
+}

package/src/binding/asyncapi.kafka.interfaces.ts

@@ -0,0 +1,35 @@
+/**
+ * Kafka binding
+ * @see https://github.com/asyncapi/bindings/tree/master/kafka
+ */
+import { SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+
+export interface KafkaServerBinding {
+  schemaRegistryUrl: string;
+  schemaRegistryVendor: string;
+  /**
+   * x.y.z
+   */
+  bindingVersion: string;
+}
+
+export interface KafkaChannelBinding {
+  topic: string;
+  partitions: number;
+  replicas: number;
+  /**
+   * x.y.z
+   */
+  bindingVersion: string;
+}
+
+export interface KafkaOperationBinding {
+  groupId?: SchemaObject;
+  clientId?: SchemaObject;
+  bindingVersion?: string;
+}
+
+export interface KafkaMessageBinding {
+  key?: SchemaObject;
+  bindingVersion?: string;
+}

package/src/binding/index.ts

@@ -0,0 +1,2 @@
+export * from './asyncapi.amqp.interfaces';
+export * from './asyncapi.kafka.interfaces';

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

@@ -0,0 +1,70 @@
+import { createMethodDecorator } from '@nestjs/swagger/dist/decorators/helpers';
+import {
+  AsyncApiOperationHeaders,
+  AsyncApiOperationOptions,
+  AsyncMessageObject,
+  AsyncOperationObject,
+} from '../interface';
+import { OneAsyncApiMessage } from '../interface/asyncapi-message.interface';
+
+function makeHeaders(headers?: AsyncApiOperationHeaders) {
+  return headers
+    ? {
+        type: 'object',
+        properties: Object.entries(headers)
+          .map(([key, value]) => ({
+            [key]: {
+              type: 'string',
+              ...value,
+            },
+          }))
+          .reduce((acc, j) => ({ ...acc, ...j }), {}),
+      }
+    : undefined;
+}
+
+function makeMessage(
+  message: OneAsyncApiMessage,
+  defaultName: string,
+): AsyncMessageObject {
+  return {
+    ...message,
+    name: message.name || defaultName,
+    payload: {
+      type: message.payload,
+    },
+    headers: makeHeaders(message.headers),
+  };
+}
+
+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}`),
+            ),
+          }
+        : makeMessage(i.message, methodName);
+
+      const transformedOptionInstance = {
+        ...i,
+        message,
+      };
+
+      return transformedOptionInstance;
+    });
+
+    return createMethodDecorator(metaKey, transformedOptions)(
+      target,
+      propertyKey,
+      descriptor,
+    );
+  };
+}

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

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

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

@@ -0,0 +1,18 @@
+import { DECORATORS } from '../asyncapi.constants';
+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',
+    }),
+  );
+  return AsyncApiOperationForMetaKey(DECORATORS.AsyncApiPub, options);
+}

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

@@ -0,0 +1,9 @@
+import { createMixedDecorator } from '@nestjs/swagger/dist/decorators/helpers';
+import { DECORATORS } from '../asyncapi.constants';
+
+/**
+ * Mark class that has to be scanned for AsyncApi operations
+ */
+export function AsyncApi() {
+  return createMixedDecorator(DECORATORS.AsyncApiClass, true);
+}

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

@@ -0,0 +1,18 @@
+import { DECORATORS } from '../asyncapi.constants';
+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',
+    }),
+  );
+  return AsyncApiOperationForMetaKey(DECORATORS.AsyncApiSub, options);
+}

package/src/decorators/index.ts

@@ -0,0 +1,4 @@
+export * from './asyncapi-service.decorator';
+export * from './asyncapi-operation.decorator';
+export * from './asyncapi-sub.decorator';
+export * from './asyncapi-pub.decorator';

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

@@ -0,0 +1,30 @@
+import { Type } from '@nestjs/common';
+import { CONTROLLER_WATERMARK } from '@nestjs/common/constants';
+import { DECORATORS } from '../asyncapi.constants';
+
+let GATEWAY_METADATA;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  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 exploreAsyncapiClassMetadata = (metatype: Type<unknown>) => {
+  return Reflect.getMetadata(DECORATORS.AsyncApiClass, metatype);
+};
+
+export const exploreControllerMetadata = (metatype: Type<unknown>) => {
+  return Reflect.getMetadata(CONTROLLER_WATERMARK, metatype);
+};
+
+export const exploreGatewayMetadata = (metatype: Type<unknown>) => {
+  return Reflect.getMetadata(GATEWAY_METADATA, metatype);
+};

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

@@ -0,0 +1,49 @@
+import { Type } from '@nestjs/common';
+import { SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import { DECORATORS } from '../asyncapi.constants';
+import { AsyncApiOperationOptionsRaw } from '../interface';
+import { OperationObjectFactory } from '../services';
+
+const operationObjectFactory = new OperationObjectFactory();
+
+export const exploreAsyncApiOperationMetadata = (
+  schemas: Record<string, SchemaObject>,
+  _instance: object,
+  _prototype: Type<unknown>,
+  method: object,
+) => {
+  const metadataOperations: AsyncApiOperationOptionsRaw[] = Reflect.getMetadata(
+    DECORATORS.AsyncApiOperation,
+    method,
+  );
+  const metadataSubs: AsyncApiOperationOptionsRaw[] = Reflect.getMetadata(
+    DECORATORS.AsyncApiSub,
+    method,
+  );
+  const metadataPubs: AsyncApiOperationOptionsRaw[] = Reflect.getMetadata(
+    DECORATORS.AsyncApiPub,
+    method,
+  );
+
+  const metadataCombined = [
+    ...(metadataOperations ? Object.values(metadataOperations) : []),
+    ...(metadataSubs ? Object.values(metadataSubs) : []),
+    ...(metadataPubs ? Object.values(metadataPubs) : []),
+  ];
+
+  return metadataCombined.map((option: AsyncApiOperationOptionsRaw) => {
+    const { channel, type } = option;
+
+    const methodTypeData = {
+      ...option,
+      ...operationObjectFactory.create(option, ['application/json'], schemas),
+      channel: undefined,
+      type: undefined,
+    };
+
+    return {
+      channel,
+      [type]: methodTypeData,
+    };
+  });
+};

package/src/explorers/index.ts

@@ -0,0 +1,2 @@
+export * from './asyncapi-operation.explorer';
+export * from './asyncapi-class.explorer';

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './asyncapi-document.builder';
+export * from './interface';
+export * from './asyncapi.module';
+export * from './decorators';