@achinet/nestjs-async 0.0.1 → 0.1.0

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

@@ -12,18 +12,9 @@ export const exploreAsyncApiOperationMetadata = (
   _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 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) : []),

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

@@ -54,10 +54,7 @@ export interface AsyncComponentsObject {
   messageTraits?: Record<string, AsyncMessageTraitObject>;
   serverBindings?: Record<string, KafkaServerBinding | AmqpServerBinding>;
   channelBindings?: Record<string, KafkaChannelBinding | AmqpChannelBinding>;
-  operationBindings?: Record<
-    string,
-    KafkaOperationBinding | AmqpOperationBinding
-  >;
+  operationBindings?: Record<string, KafkaOperationBinding | AmqpOperationBinding>;
   messageBindings?: Record<string, KafkaMessageBinding | AmqpMessageBinding>;
 }
 

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

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

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

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

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

@@ -1,9 +1,6 @@
 import { ServerObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
 import { AmqpServerBinding, KafkaServerBinding } from '../binding';
-import {
-  AsyncServerVariableObject,
-  SecurityObject,
-} from './asyncapi-common.interfaces';
+import { AsyncServerVariableObject, SecurityObject } from './asyncapi-common.interfaces';
 
 export interface AsyncServerObject extends Omit<ServerObject, 'variables'> {
   variables?: Record<string, AsyncServerVariableObject>;

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

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

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

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

package/src/services/asyncapi.explorer.ts

@@ -14,7 +14,9 @@ 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) =>
@@ -34,20 +36,14 @@ export class AsyncApiExplorer {
     if (
       !instance ||
       !metatype ||
-      !Reflect.getMetadataKeys(metatype).find((label) =>
-        asyncApiClassAnnotationLabels.includes(label),
-      )
+      !Reflect.getMetadataKeys(metatype).find((label) => asyncApiClassAnnotationLabels.includes(label))
     ) {
       return [];
     }
 
     const prototype = Object.getPrototypeOf(instance);
     const documentResolvers: DenormalizedDocResolvers = {
-      root: [
-        exploreAsyncapiClassMetadata,
-        exploreControllerMetadata,
-        exploreGatewayMetadata,
-      ],
+      root: [exploreAsyncapiClassMetadata, exploreControllerMetadata, exploreGatewayMetadata],
       security: [],
       tags: [],
       operations: [exploreAsyncApiOperationMetadata],
@@ -76,45 +72,40 @@ export class AsyncApiExplorer {
     _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 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,
-            );
+          const channels = documentResolvers.operations.reduce((operationsParam, exploreOperationsMeta) => {
+            const operations = operationsParam;
+            const meta = exploreOperationsMeta(this.schemas, instance, prototype, targetCallback);
             if (!meta) {
               return operations;
             }
 
             meta.forEach((op) => {
-              if (operations.hasOwnProperty(op.channel)) {
+              // @eslint-disable-next-line
+              if (Object.prototype.hasOwnProperty.call(operations, 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 Object.keys(channels).map((channel) => ({
+            root: { ...serviceMetadata, name: channel },
+            operations: channels[channel],
+          }));
+        }, []);
+        return methodMetadata;
+      },
+    );
 
     return flatten(denormalizedAsyncapiServices);
   }

package/src/services/asyncapi.generator.ts

@@ -1,33 +1,45 @@
-import Generator from '@asyncapi/generator';
+import fs from 'fs/promises';
 import jsyaml from 'js-yaml';
 import os from 'os';
-import {
-  AsyncApiDocument,
-  AsyncApiTemplateOptions,
-  GeneratorOptions,
-} from '../interface';
+import path from 'path';
+import { AsyncApiDocument, AsyncApiTemplateOptions, GeneratorOptions } from '../interface';
 
 export class AsyncapiGenerator {
-  private readonly generator: GeneratorOptions;
+  private readonly templateOptions?: AsyncApiTemplateOptions;
 
-  constructor(readonly templateOptions?: AsyncApiTemplateOptions) {
-    this.generator = new Generator('@asyncapi/html-template', os.tmpdir(), {
+  constructor(templateOptions?: AsyncApiTemplateOptions) {
+    this.templateOptions = templateOptions;
+  }
+
+  public async generate(contract: AsyncApiDocument): Promise<string> {
+    // Lazy-load @asyncapi/generator to avoid loading it at module initialization time.
+    // This allows tests and code that only use decorators to work without
+    // requiring the full generator dependency tree (which has nested semver issues in Jest).
+    const { default: Generator } = await import('@asyncapi/generator');
+
+    const yaml = jsyaml.dump(contract);
+    const tmpDir = path.join(os.tmpdir(), `asyncapi-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+    const generator: GeneratorOptions = new Generator('@asyncapi/html-template', tmpDir, {
       forceWrite: true,
-      entrypoint: 'index.html',
-      output: 'string',
       templateParams: {
         singleFile: true,
-        ...templateOptions,
+        ...this.templateOptions,
       },
     });
-  }
 
-  public async generate(contract: AsyncApiDocument): Promise<string> {
-    const yaml = jsyaml.dump(contract);
-    return this.generator.generateFromString(yaml, {
+    await generator.generateFromString(yaml, {
       resolve: {
         file: false,
       },
     });
+
+    const htmlPath = path.join(tmpDir, 'index.html');
+    const html = await fs.readFile(htmlPath, 'utf-8');
+
+    // Clean up temp directory
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+
+    return html;
   }
 }

package/src/services/asyncapi.scanner.ts

@@ -1,7 +1,6 @@
 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';
@@ -10,23 +9,20 @@ import { SchemaObjectFactory } from '@nestjs/swagger/dist/services/schema-object
 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 { 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,
-  );
+
+  private readonly schemaObjectFactory = new SchemaObjectFactory(this.modelPropertiesAccessor, this.swaggerTypesMapper);
 
   public scanApplication(
     app: INestApplicationContext,
@@ -40,65 +36,35 @@ export class AsyncapiScanner {
       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 { container } = app as any;
+    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),
-    );
+    const normalizedChannels = this.transformer.normalizeChannels(flatten(denormalizedChannels));
     return {
       ...normalizedChannels,
       components: { schemas },
@@ -111,32 +77,19 @@ export class AsyncapiScanner {
     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];
-      },
-      [],
-    );
+    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[] {
+  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),
-    );
+    return [...modulesContainer.values()].filter(({ metatype }) => include.some((item) => item === metatype));
   }
 
   private getGlobalPrefix(app: INestApplicationContext): string {
@@ -144,10 +97,7 @@ export class AsyncapiScanner {
     return internalConfigRef?.getGlobalPrefix() || '';
   }
 
-  private addExtraModels(
-    schemas: Record<string, SchemaObject>,
-    extraModels: Function[],
-  ) {
+  private addExtraModels(schemas: Record<string, SchemaObject>, extraModels: Function[]) {
     extraModels.forEach((item) => {
       this.schemaObjectFactory.exploreModelSchema(item, schemas);
     });

package/src/services/asyncapi.transformer.ts

@@ -1,13 +1,7 @@
-import {
-  AsyncChannelObject,
-  AsyncChannelsObject,
-  DenormalizedDoc,
-} from '../interface';
+import { AsyncChannelObject, AsyncChannelsObject, DenormalizedDoc } from '../interface';
 
 export class AsyncapiTransformer {
-  public normalizeChannels(
-    denormalizedDocs: DenormalizedDoc[],
-  ): Record<'channels', AsyncChannelsObject> {
+  public normalizeChannels(denormalizedDocs: DenormalizedDoc[]): Record<'channels', AsyncChannelsObject> {
     const flatChannels = denormalizedDocs.map((doc: DenormalizedDoc) => {
       const key = doc.root?.name;
       const value: AsyncChannelObject = {

package/src/services/index.ts

@@ -2,4 +2,3 @@ export * from './asyncapi.generator';
 export * from './operation-object.factory';
 export * from './asyncapi.explorer';
 export * from './asyncapi.scanner';
-export * from './asyncapi.scanner';

package/test/__mocks__/@asyncapi/generator.js

@@ -0,0 +1,41 @@
+/**
+ * Mock for @asyncapi/generator to avoid ESM issues in Jest tests.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class MockGenerator {
+  constructor(templateName, targetDir, options = {}) {
+    this.templateName = templateName;
+    this.targetDir = targetDir;
+    this.options = options;
+  }
+
+  async generateFromString(yaml) {
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>AsyncAPI Documentation</title>
+</head>
+<body>
+  <h1>AsyncAPI Documentation</h1>
+  <p>Mock HTML generated for testing</p>
+  <pre>${yaml.replace(/</g, '&lt;').replace(/>/g, '&gt;')}</pre>
+</body>
+</html>`;
+
+    // Create the target directory and write the file
+    fs.mkdirSync(this.targetDir, { recursive: true });
+    fs.writeFileSync(path.join(this.targetDir, 'index.html'), html, 'utf-8');
+
+    return html;
+  }
+
+  async generate(asyncapi) {
+    return this.generateFromString(JSON.stringify(asyncapi, null, 2));
+  }
+}
+
+module.exports = MockGenerator;
+module.exports.default = MockGenerator;

package/test/configs/jest-base.config.ts

@@ -0,0 +1,19 @@
+import { JestConfigWithTsJest } from 'ts-jest';
+
+export const baseConfig: JestConfigWithTsJest = {
+  moduleFileExtensions: ['js', 'json', 'ts'],
+  rootDir: '../../',
+  transform: {
+    '^.+\\.(t|j)s$': 'ts-jest',
+  },
+  collectCoverageFrom: ['**/*.(t|j)s'],
+  coverageDirectory: './coverage',
+  testEnvironment: 'node',
+  moduleNameMapper: {
+    '#lib(|/.*)$': '<rootDir>/lib/$1',
+    '#sample(|/.*)$': '<rootDir>/sample/$1',
+    '#test(|/.*)$': '<rootDir>/test/$1',
+  },
+};
+
+export default baseConfig;

package/test/configs/jest-e2e.config.js

@@ -0,0 +1,7 @@
+// Forzamos ts-node desde aquí antes de importar la config real
+require('ts-node').register({
+  transpileOnly: true,
+});
+
+// Si usas `export default` en tu config.ts:
+module.exports = require('./jest-e2e.config.ts').default;

package/test/configs/jest-e2e.config.ts

@@ -0,0 +1,19 @@
+import { JestConfigWithTsJest } from 'ts-jest';
+import { baseConfig } from './jest-base.config';
+
+export const e2eConfig: JestConfigWithTsJest = {
+  ...baseConfig,
+  testRegex: '.\\.e2e-spec\\.ts$',
+  transform: {
+    '^.+\\.(t|j)s$': [
+      'ts-jest',
+      {
+        astTransformers: {
+          before: ['test/configs/jest-swagger-plugin.js'],
+        },
+      },
+    ],
+  },
+};
+
+export default e2eConfig;

package/test/configs/jest-swagger-plugin.js

@@ -0,0 +1,16 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const transformer = require('@nestjs/swagger/plugin');
+
+module.exports.name = 'nestjs-swagger-transformer';
+// you should change the version number anytime you change the configuration below - otherwise, jest will not detect changes
+module.exports.version = 1;
+
+module.exports.factory = (cs) => {
+  return transformer.before(
+    {
+      introspectComments: true,
+      dtoFileNameSuffix: ['.dto.ts', '.class.ts'],
+    },
+    cs.program, // "cs.tsCompiler.program" for older versions of Jest (<= v27)
+  );
+};

package/test/express.e2e-spec.ts

@@ -0,0 +1,64 @@
+import { NestFactory } from '@nestjs/core';
+import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
+import * as fs from 'fs/promises';
+import jsyaml from 'js-yaml';
+import request from 'supertest';
+import { AsyncApiModule } from '../src';
+import { AppModule } from '../sample/app.module';
+import { makeAsyncapiDocument } from '../sample/common';
+import { DOC_RELATIVE_PATH } from '../sample/constants';
+
+describe('Express AsyncAPI', () => {
+  let app: NestExpressApplication;
+
+  beforeAll(async () => {
+    app = await NestFactory.create<NestExpressApplication>(AppModule, new ExpressAdapter(), { logger: false });
+    const asyncapiDocument = await makeAsyncapiDocument(app);
+    await AsyncApiModule.setup(DOC_RELATIVE_PATH, app, asyncapiDocument);
+
+    await app.init();
+  });
+
+  it('should serve doc html', async () => {
+    const { text } = await request(app.getHttpServer())
+      .get(DOC_RELATIVE_PATH)
+      .expect(200)
+      .expect('Content-Type', /text\/html/);
+    const htmlSample = await fs.readFile('./misc/references/ref.html', {
+      encoding: 'utf8',
+    });
+    expect(text).toEqual(htmlSample);
+  });
+
+  it('should serve doc json', async () => {
+    const { text } = await request(app.getHttpServer())
+      .get(`${DOC_RELATIVE_PATH}-json`)
+      .expect(200)
+      .expect('Content-Type', /application\/json/);
+
+    const jsonFetched = JSON.parse(text);
+    const jsonReferenceSample = JSON.parse(
+      await fs.readFile('./misc/references/ref.json', {
+        encoding: 'utf8',
+      }),
+    );
+
+    expect(jsonFetched).toEqual(jsonReferenceSample);
+  });
+
+  it('should serve doc yaml', async () => {
+    const { text } = await request(app.getHttpServer())
+      .get(`${DOC_RELATIVE_PATH}-yaml`)
+      .expect(200)
+      .expect('Content-Type', /text\/yaml/);
+
+    const yamlFetched = jsyaml.load(text);
+    const yamlReferenceSample = jsyaml.load(
+      await fs.readFile('./misc/references/ref.yaml', {
+        encoding: 'utf8',
+      }),
+    );
+
+    expect(yamlFetched).toEqual(yamlReferenceSample);
+  });
+});