@achinet/nestjs-async 0.0.1

package/src/interface/asyncapi-common.interfaces.ts

@@ -0,0 +1,172 @@
+import {
+  InfoObject,
+  ReferenceObject,
+  SchemaObject,
+  ServerVariableObject,
+} from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import {
+  AmqpChannelBinding,
+  AmqpMessageBinding,
+  AmqpOperationBinding,
+  AmqpServerBinding,
+  KafkaChannelBinding,
+  KafkaMessageBinding,
+  KafkaOperationBinding,
+  KafkaServerBinding,
+} from '../binding';
+import { AsyncOperationPayload } from './asyncapi-operation-payload.interface';
+import { AsyncServerObject } from './asyncapi-server.interface';
+
+export interface AsyncApiDocument {
+  asyncapi: string;
+  id?: string;
+  info: InfoObject;
+  servers?: Record<string, AsyncServerObject>;
+  channels: AsyncChannelsObject;
+  components?: AsyncComponentsObject;
+  tags?: AsyncTagObject[];
+  externalDocs?: ExternalDocumentationObject;
+  defaultContentType?: string;
+}
+
+export type AsyncChannelsObject = Record<string, AsyncChannelObject>;
+export interface AsyncChannelObject {
+  description?: string;
+  subscribe?: AsyncOperationObject;
+  publish?: AsyncOperationObject;
+  parameters?: Record<string, ParameterObject>;
+  bindings?: Record<string, KafkaChannelBinding | AmqpChannelBinding>;
+}
+
+export interface AsyncServerVariableObject extends ServerVariableObject {
+  examples?: string[];
+}
+
+export type SecurityObject = Record<string, string[]>;
+
+export interface AsyncComponentsObject {
+  schemas?: Record<string, SchemaObject>;
+  messages?: Record<string, AsyncMessageObject>;
+  securitySchemes?: Record<string, AsyncSecuritySchemeObject>;
+  parameters?: Record<string, ParameterObject>;
+  correlationIds?: Record<string, AsyncCorrelationObject>;
+  operationTraits?: Record<string, AsyncOperationTraitObject>;
+  messageTraits?: Record<string, AsyncMessageTraitObject>;
+  serverBindings?: Record<string, KafkaServerBinding | AmqpServerBinding>;
+  channelBindings?: Record<string, KafkaChannelBinding | AmqpChannelBinding>;
+  operationBindings?: Record<
+    string,
+    KafkaOperationBinding | AmqpOperationBinding
+  >;
+  messageBindings?: Record<string, KafkaMessageBinding | AmqpMessageBinding>;
+}
+
+export interface AsyncMessageObject extends AsyncMessageTraitObject {
+  payload?: {
+    type?: AsyncOperationPayload;
+    $ref?: AsyncOperationPayload;
+  };
+}
+
+export type MessageType = AsyncMessageObject | ReferenceObject;
+export interface OneOfMessageType {
+  oneOf: MessageType[];
+}
+
+export type AsyncOperationMessage = OneOfMessageType | MessageType;
+
+export interface AsyncOperationObject {
+  channel: string;
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: AsyncTagObject[];
+  externalDocs?: ExternalDocumentationObject;
+  bindings?: Record<string, KafkaOperationBinding | AmqpOperationBinding>;
+  traits?: Record<string, AsyncOperationTraitObject>;
+  message?: AsyncOperationMessage;
+}
+
+export interface AsyncOperationTraitObject {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: AsyncTagObject[];
+  externalDocs?: ExternalDocumentationObject;
+  bindings?: Record<string, KafkaOperationBinding | AmqpOperationBinding>;
+}
+
+export interface AsyncMessageTraitObject {
+  headers?: SchemaObject;
+  correlationId?: AsyncCorrelationObject;
+  schemaFormat?: string;
+  contentType?: string;
+  name?: string;
+  title?: string;
+  summary?: string;
+  description?: string;
+  tags?: AsyncTagObject[];
+  externalDocs?: ExternalDocumentationObject;
+  bindings?: Record<string, KafkaMessageBinding | AmqpMessageBinding>;
+}
+
+export interface AsyncCorrelationObject {
+  description?: string;
+  location: string;
+}
+
+export interface AsyncTagObject {
+  name: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+}
+
+export interface AsyncSecuritySchemeObject {
+  type: SecuritySchemeType;
+  description?: string;
+  name?: string;
+  in?: string;
+  scheme?: string;
+  bearerFormat?: string;
+  flows?: OAuthFlowsObject;
+  openIdConnectUrl?: string;
+}
+
+export declare type SecuritySchemeType =
+  | 'userPassword'
+  | 'apiKey'
+  | 'X509'
+  | 'symmetricEncryption'
+  | 'asymmetricEncryption'
+  | 'http'
+  | 'oauth2'
+  | 'openIdConnect';
+
+export interface OAuthFlowsObject {
+  implicit?: OAuthFlowObject;
+  password?: OAuthFlowObject;
+  clientCredentials?: OAuthFlowObject;
+  authorizationCode?: OAuthFlowObject;
+}
+
+export interface OAuthFlowObject {
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes: ScopesObject;
+}
+
+export type ScopesObject = Record<string, unknown>;
+
+export type ParameterObject = BaseParameterObject;
+
+export interface BaseParameterObject {
+  description?: string;
+  schema?: SchemaObject | ReferenceObject;
+  location?: string;
+}
+
+export interface ExternalDocumentationObject {
+  description?: string;
+  url: string;
+}

package/src/interface/asyncapi-document-options.interface.ts

@@ -0,0 +1,3 @@
+import { SwaggerDocumentOptions } from '@nestjs/swagger';
+
+export interface AsyncApiDocumentOptions extends SwaggerDocumentOptions {}

package/src/interface/asyncapi-message.interface.ts

@@ -0,0 +1,10 @@
+import { AsyncApiOperationHeaders } from './asyncapi-operation-headers.interface';
+import { AsyncOperationPayload } from './asyncapi-operation-payload.interface';
+
+export interface OneAsyncApiMessage {
+  name?: string;
+  payload: AsyncOperationPayload;
+  headers?: AsyncApiOperationHeaders;
+}
+
+export type AsyncApiMessage = OneAsyncApiMessage | OneAsyncApiMessage[];

package/src/interface/asyncapi-operation-headers.interface.ts

@@ -0,0 +1,6 @@
+export interface AsyncApiOperationHeaders {
+  [key: string]: {
+    description: string;
+    [key: string]: unknown;
+  };
+}

package/src/interface/asyncapi-operation-options-raw.interface.ts

@@ -0,0 +1,23 @@
+import { AsyncOperationObject } from './asyncapi-common.interfaces';
+import { AsyncOperationPayload } from './asyncapi-operation-payload.interface';
+
+export interface RawAsyncApiMessage {
+  name?: string;
+  payload: {
+    type: AsyncOperationPayload;
+  };
+  headers?: {
+    type: 'object';
+    properties: {
+      [key: string]: {
+        description: string;
+        type: 'string';
+        [key: string]: unknown;
+      };
+    };
+  };
+}
+
+export interface AsyncApiOperationOptionsRaw extends AsyncOperationObject {
+  type: 'sub' | 'pub';
+}

package/src/interface/asyncapi-operation-options.interface.ts

@@ -0,0 +1,12 @@
+import { AsyncOperationObject } from './asyncapi-common.interfaces';
+import { AsyncApiMessage } from './asyncapi-message.interface';
+
+export interface AsyncApiSpecificOperationOptions
+  extends Omit<AsyncOperationObject, 'message'> {
+  message: AsyncApiMessage;
+}
+
+export interface AsyncApiOperationOptions
+  extends AsyncApiSpecificOperationOptions {
+  type: 'pub' | 'sub';
+}

package/src/interface/asyncapi-operation-payload.interface.ts

@@ -0,0 +1,7 @@
+import { Type } from '@nestjs/common';
+
+export type AsyncOperationPayload =
+  | Type<unknown>
+  | Function
+  | [Function]
+  | string;

package/src/interface/asyncapi-server.interface.ts

@@ -0,0 +1,14 @@
+import { ServerObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import { AmqpServerBinding, KafkaServerBinding } from '../binding';
+import {
+  AsyncServerVariableObject,
+  SecurityObject,
+} from './asyncapi-common.interfaces';
+
+export interface AsyncServerObject extends Omit<ServerObject, 'variables'> {
+  variables?: Record<string, AsyncServerVariableObject>;
+  protocol: string;
+  protocolVersion?: string;
+  security?: SecurityObject[];
+  bindings?: Record<string, KafkaServerBinding | AmqpServerBinding>;
+}

package/src/interface/asyncapi-template-options.interface.ts

@@ -0,0 +1,20 @@
+/**
+ * @see https://github.com/asyncapi/html-template#supported-parameters
+ **/
+export interface AsyncApiTemplateOptions {
+  /** @default byTagsNoRoot **/
+  sidebarOrganization?: 'byTags' | 'byTagsNoRoot';
+  /**
+   * @example /docs
+   **/
+  baseHref?: string;
+  /** @default true **/
+  singleFile?: boolean;
+  /** @example asyncapi.html **/
+  outFilename?: string;
+  /**
+   * @description 	Generates output HTML as PDF
+   * @default false
+   */
+  pdf?: boolean;
+}

package/src/interface/denormalized-doc-resolvers.interface.ts

@@ -0,0 +1,6 @@
+export interface DenormalizedDocResolvers {
+  root: Function[];
+  security: Function[];
+  tags: Function[];
+  operations: Function[];
+}

package/src/interface/denormalized-doc.interface.ts

@@ -0,0 +1,10 @@
+import {
+  AsyncApiDocument,
+  AsyncChannelObject,
+  AsyncOperationObject,
+} from './asyncapi-common.interfaces';
+
+export interface DenormalizedDoc extends Partial<AsyncApiDocument> {
+  root?: { name: string } & AsyncChannelObject;
+  operations?: { pub: AsyncOperationObject; sub: AsyncOperationObject };
+}

package/src/interface/generator-options.interface.ts

@@ -0,0 +1,21 @@
+import { AsyncApiDocument } from './asyncapi-common.interfaces';
+import { AsyncApiTemplateOptions } from './asyncapi-template-options.interface';
+
+export interface GeneratorOptions {
+  templateName: string;
+  targetDir: string;
+  entrypoint?: string;
+  noOverwriteGlobs: string[];
+  disabledHooks: { [key: string]: string | boolean | string[] };
+  output: 'string' | 'fs';
+  forceWrite: boolean;
+  debug: boolean;
+  install: boolean;
+  templateConfig: Record<string, unknown>;
+  hooks: Record<string, unknown>;
+  templateParams: AsyncApiTemplateOptions;
+  generate: (document: AsyncApiDocument) => Promise<void>;
+  generateFromURL: (url: string) => Promise<void>;
+  generateFromFile: (path: string) => Promise<void>;
+  generateFromString: (yaml: string, args?: unknown) => Promise<string>;
+}

package/src/interface/index.ts

@@ -0,0 +1,12 @@
+export * from './asyncapi-common.interfaces';
+export * from './asyncapi-template-options.interface';
+export * from './asyncapi-operation-headers.interface';
+export * from './asyncapi-operation-payload.interface';
+export * from './asyncapi-operation-options.interface';
+export * from './asyncapi-document-options.interface';
+export * from './asyncapi-server.interface';
+export * from './denormalized-doc.interface';
+export * from './denormalized-doc-resolvers.interface';
+export * from './generator-options.interface';
+
+export * from './asyncapi-operation-options-raw.interface';

package/src/services/asyncapi.explorer.ts

@@ -0,0 +1,121 @@
+import { Type } from '@nestjs/common';
+import { MetadataScanner } from '@nestjs/core';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import { flatten } from 'lodash';
+import {
+  asyncApiClassAnnotationLabels,
+  exploreAsyncapiClassMetadata,
+  exploreAsyncApiOperationMetadata,
+  exploreControllerMetadata,
+  exploreGatewayMetadata,
+} from '../explorers';
+import { DenormalizedDoc, DenormalizedDocResolvers } from '../interface';
+
+export class AsyncApiExplorer {
+  private readonly metadataScanner = new MetadataScanner();
+  private readonly schemas: SchemaObject[] = [];
+  private readonly schemaRefsStack: string[] = [];
+
+  private operationIdFactory = (controllerKey: string, methodKey: string) =>
+    controllerKey ? `${controllerKey}_${methodKey}` : methodKey;
+
+  public explorerAsyncapiServices(
+    wrapper: InstanceWrapper,
+    modulePath?: string,
+    globalPrefix?: string,
+    operationIdFactory?: (controllerKey: string, methodKey: string) => string,
+  ) {
+    if (operationIdFactory) {
+      this.operationIdFactory = operationIdFactory;
+    }
+
+    const { instance, metatype } = wrapper;
+    if (
+      !instance ||
+      !metatype ||
+      !Reflect.getMetadataKeys(metatype).find((label) =>
+        asyncApiClassAnnotationLabels.includes(label),
+      )
+    ) {
+      return [];
+    }
+
+    const prototype = Object.getPrototypeOf(instance);
+    const documentResolvers: DenormalizedDocResolvers = {
+      root: [
+        exploreAsyncapiClassMetadata,
+        exploreControllerMetadata,
+        exploreGatewayMetadata,
+      ],
+      security: [],
+      tags: [],
+      operations: [exploreAsyncApiOperationMetadata],
+    };
+
+    return this.generateDenormalizedDocument(
+      metatype as Type<unknown>,
+      prototype,
+      instance,
+      documentResolvers,
+      modulePath,
+      globalPrefix,
+    );
+  }
+
+  public getSchemas(): Record<string, SchemaObject> {
+    const ret = { ...this.schemas } as unknown as Record<string, SchemaObject>;
+    return ret;
+  }
+
+  private generateDenormalizedDocument(
+    metatype: Type<unknown>,
+    prototype: Type<unknown>,
+    instance: object,
+    documentResolvers: DenormalizedDocResolvers,
+    _modulePath?: string,
+    _globalPrefix?: string,
+  ): DenormalizedDoc[] {
+    const denormalizedAsyncapiServices = this.metadataScanner.scanFromPrototype<
+      unknown,
+      DenormalizedDoc[]
+    >(instance, prototype, (name) => {
+      const targetCallback = prototype[name];
+      const methodMetadata = documentResolvers.root.reduce((_metadata, fn) => {
+        const serviceMetadata = fn(metatype);
+
+        const channels = documentResolvers.operations.reduce(
+          (operations, exploreOperationsMeta) => {
+            const meta = exploreOperationsMeta(
+              this.schemas,
+              instance,
+              prototype,
+              targetCallback,
+            );
+            if (!meta) {
+              return operations;
+            }
+
+            meta.forEach((op) => {
+              if (operations.hasOwnProperty(op.channel)) {
+                operations[op.channel] = { ...operations[op.channel], ...op };
+              } else {
+                operations[op.channel] = op;
+              }
+            });
+            return operations;
+          },
+          {},
+        );
+
+        return Object.keys(channels).map((channel) => ({
+          root: { ...serviceMetadata, name: channel },
+          operations: channels[channel],
+        }));
+      }, []);
+      return methodMetadata;
+    });
+
+    return flatten(denormalizedAsyncapiServices);
+  }
+}

package/src/services/asyncapi.generator.ts

@@ -0,0 +1,33 @@
+import Generator from '@asyncapi/generator';
+import jsyaml from 'js-yaml';
+import os from 'os';
+import {
+  AsyncApiDocument,
+  AsyncApiTemplateOptions,
+  GeneratorOptions,
+} from '../interface';
+
+export class AsyncapiGenerator {
+  private readonly generator: GeneratorOptions;
+
+  constructor(readonly templateOptions?: AsyncApiTemplateOptions) {
+    this.generator = new Generator('@asyncapi/html-template', os.tmpdir(), {
+      forceWrite: true,
+      entrypoint: 'index.html',
+      output: 'string',
+      templateParams: {
+        singleFile: true,
+        ...templateOptions,
+      },
+    });
+  }
+
+  public async generate(contract: AsyncApiDocument): Promise<string> {
+    const yaml = jsyaml.dump(contract);
+    return this.generator.generateFromString(yaml, {
+      resolve: {
+        file: false,
+      },
+    });
+  }
+}

package/src/services/asyncapi.scanner.ts

@@ -0,0 +1,155 @@
+import { INestApplicationContext, Type } from '@nestjs/common';
+import { MODULE_PATH } from '@nestjs/common/constants';
+import { Injectable, InjectionToken } from '@nestjs/common/interfaces';
+import { NestContainer } from '@nestjs/core/injector/container';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { Module } from '@nestjs/core/injector/module';
+import { SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
+import { ModelPropertiesAccessor } from '@nestjs/swagger/dist/services/model-properties-accessor';
+import { SchemaObjectFactory } from '@nestjs/swagger/dist/services/schema-object-factory';
+import { SwaggerTypesMapper } from '@nestjs/swagger/dist/services/swagger-types-mapper';
+import { stripLastSlash } from '@nestjs/swagger/dist/utils/strip-last-slash.util';
+import { flatten, isEmpty } from 'lodash';
+import {
+  AsyncApiDocument,
+  AsyncApiDocumentOptions,
+  DenormalizedDoc,
+} from '../interface';
+import { AsyncApiExplorer } from './asyncapi.explorer';
+import { AsyncapiTransformer } from './asyncapi.transformer';
+
+export class AsyncapiScanner {
+  private readonly transformer = new AsyncapiTransformer();
+  private readonly explorer = new AsyncApiExplorer();
+  private readonly modelPropertiesAccessor = new ModelPropertiesAccessor();
+  private readonly swaggerTypesMapper = new SwaggerTypesMapper();
+  private readonly schemaObjectFactory = new SchemaObjectFactory(
+    this.modelPropertiesAccessor,
+    this.swaggerTypesMapper,
+  );
+
+  public scanApplication(
+    app: INestApplicationContext,
+    options: AsyncApiDocumentOptions,
+  ): Omit<AsyncApiDocument, 'asyncapi' | 'info'> {
+    const {
+      deepScanRoutes,
+      include: includedModules = [],
+      extraModels = [],
+      ignoreGlobalPrefix = false,
+      operationIdFactory,
+    } = options;
+
+    const container: NestContainer = (app as any).container;
+    const modules: Module[] = this.getModules(
+      container.getModules(),
+      includedModules,
+    );
+    const globalPrefix = !ignoreGlobalPrefix
+      ? stripLastSlash(this.getGlobalPrefix(app))
+      : '';
+
+    const denormalizedChannels = modules.reduce(
+      (channels, { providers, metatype, imports, controllers }) => {
+        let allProviders = new Map([...providers, ...controllers]);
+
+        if (deepScanRoutes) {
+          // only load submodules routes if asked
+          const isGlobal = (module: Type<any>) =>
+            !container.isGlobalModule(module);
+
+          Array.from(imports.values())
+            .filter(isGlobal as any)
+            .map(
+              ({
+                providers: relatedProviders,
+                controllers: relatedControllers,
+              }) => ({
+                relatedProviders,
+                relatedControllers,
+              }),
+            )
+            .forEach(({ relatedProviders, relatedControllers }) => {
+              allProviders = new Map([
+                ...allProviders,
+                ...relatedProviders,
+                ...relatedControllers,
+              ]);
+            });
+        }
+        const path = metatype
+          ? Reflect.getMetadata(MODULE_PATH, metatype)
+          : undefined;
+
+        return [
+          ...channels,
+          ...this.scanModuleProviders(
+            allProviders,
+            path,
+            globalPrefix,
+            operationIdFactory,
+          ),
+        ];
+      },
+      [],
+    );
+
+    const schemas = this.explorer.getSchemas();
+    this.addExtraModels(schemas, extraModels);
+    const normalizedChannels = this.transformer.normalizeChannels(
+      flatten(denormalizedChannels),
+    );
+    return {
+      ...normalizedChannels,
+      components: { schemas },
+    };
+  }
+
+  private scanModuleProviders(
+    providers: Map<InjectionToken, InstanceWrapper<Injectable>>,
+    modulePath?: string,
+    globalPrefix?: string,
+    operationIdFactory?: (controllerKey: string, methodKey: string) => string,
+  ): DenormalizedDoc[] {
+    const denormalizedArray = [...providers.values()].reduce(
+      (denormalized, prov) => {
+        const object = this.explorer.explorerAsyncapiServices(
+          prov,
+          modulePath,
+          globalPrefix,
+          operationIdFactory,
+        );
+        return [...denormalized, ...object];
+      },
+      [],
+    );
+
+    return flatten(denormalizedArray) as any;
+  }
+
+  private getModules(
+    modulesContainer: Map<string, Module>,
+    include: Function[],
+  ): Module[] {
+    if (!include || isEmpty(include)) {
+      return [...modulesContainer.values()];
+    }
+    return [...modulesContainer.values()].filter(({ metatype }) =>
+      include.some((item) => item === metatype),
+    );
+  }
+
+  private getGlobalPrefix(app: INestApplicationContext): string {
+    const internalConfigRef = (app as any).config;
+    return internalConfigRef?.getGlobalPrefix() || '';
+  }
+
+  private addExtraModels(
+    schemas: Record<string, SchemaObject>,
+    extraModels: Function[],
+  ) {
+    extraModels.forEach((item) => {
+      this.schemaObjectFactory.exploreModelSchema(item, schemas);
+    });
+  }
+}

package/src/services/asyncapi.transformer.ts

@@ -0,0 +1,39 @@
+import {
+  AsyncChannelObject,
+  AsyncChannelsObject,
+  DenormalizedDoc,
+} from '../interface';
+
+export class AsyncapiTransformer {
+  public normalizeChannels(
+    denormalizedDocs: DenormalizedDoc[],
+  ): Record<'channels', AsyncChannelsObject> {
+    const flatChannels = denormalizedDocs.map((doc: DenormalizedDoc) => {
+      const key = doc.root?.name;
+      const value: AsyncChannelObject = {
+        description: doc.root?.description,
+        bindings: doc.root?.bindings,
+        parameters: doc.root?.parameters,
+        subscribe: doc.operations?.sub,
+        publish: doc.operations?.pub,
+      };
+      return { key, value };
+    });
+
+    const channels = flatChannels.reduce((acc, { key, value }) => {
+      // skip entries without a channel name
+      if (!key) return acc;
+
+      if (!acc[key]) {
+        acc[key] = value;
+      }
+
+      acc[key].publish = acc[key].publish ?? value.publish;
+      acc[key].subscribe = acc[key].subscribe ?? value.subscribe;
+
+      return acc;
+    }, {} as AsyncChannelsObject);
+
+    return { channels };
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export * from './asyncapi.generator';
+export * from './operation-object.factory';
+export * from './asyncapi.explorer';
+export * from './asyncapi.scanner';
+export * from './asyncapi.scanner';