feat: add node decorator processor system for dynamic OpenAPI schema extensions

This commit introduces a new node decorator processor system that allows
dynamic extension of OpenAPI schemas through custom decorators. The system
enables third-party services to inject custom metadata into generated
OpenAPI specifications.

Author: Volodymyr Malyhin

.github/workflows/runTestsOnPush.yml

@@ -1,22 +1,28 @@
-on: [push, pull_request]
+on:
+    push:
+        branches:
+            - master
+        tags-ignore:
+            - '**'
+    pull_request:
+        branches:
+            - '**'
+
 name: Build and Test
 jobs:
   build:
     name: Build
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        node-version: [12, 14, 16, 17]
-        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@master
 
       - name: Setup Node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 17
           cache: yarn
+          cache-dependency-path: '**/yarn.lock'
 
       - name: Install Yarn
         run: npm install -g yarn

.gitignore

@@ -7,3 +7,5 @@ customRoutes.ts
 *.swp
 yarn-error.log
 tsconfig.tsbuildinfo
+.history/
+.vscode/

.vscode/launch.json

@@ -2,6 +2,7 @@ import * as mm from 'minimatch';
 import * as ts from 'typescript';
 import { importClassesFromDirectories } from '../utils/importClassesFromDirectories';
 import { ControllerGenerator } from './controllerGenerator';
+import { NodeDecoratorProcessor } from './types/nodeDecoratorProcessor';
 import { GenerateMetadataError } from './exceptions';
 import { Tsoa } from '@namecheap/tsoa-runtime';
 import { TypeResolver } from './typeResolver';
@@ -10,12 +11,14 @@ import { SecurityGenerator } from './securityGenerator';
 
 export interface MetadataGeneratorOptions {
   securityGenerator?: SecurityGenerator;
+  customDecoratorProcessors?: Record<string, NodeDecoratorProcessor>;
 }
 
 export class MetadataGenerator {
   public readonly controllerNodes = new Array<ts.ClassDeclaration>();
   public readonly typeChecker: ts.TypeChecker;
   public readonly securityGenerator: SecurityGenerator | undefined;
+  public readonly customDecoratorProcessors: Record<string, NodeDecoratorProcessor> | undefined;
 
   private readonly program: ts.Program;
   private referenceTypeMap: Tsoa.ReferenceTypeMap = {};
@@ -27,6 +30,7 @@ export class MetadataGenerator {
     this.typeChecker = this.program.getTypeChecker();
 
     this.securityGenerator = generatorOptions?.securityGenerator;
+    this.customDecoratorProcessors = generatorOptions?.customDecoratorProcessors;
   }
 
   public Generate(): Tsoa.Metadata {

.vscode/settings.json

@@ -11,6 +11,7 @@ import { ParameterGenerator } from './parameterGenerator';
 import { Tsoa } from '@namecheap/tsoa-runtime';
 import { TypeResolver } from './typeResolver';
 import { getHeaderType } from '../utils/headerTypeHelpers';
+import { DecoratorProcessorContext } from './types/nodeDecoratorProcessor';
 
 export class MethodGenerator {
   private method: 'options' | 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head';
@@ -54,7 +55,7 @@ export class MethodGenerator {
     const additionalResponses = parameters.filter((p): p is Tsoa.ResParameter => p.in === 'res');
     responses.push(...additionalResponses);
 
-    return {
+    const methodMetadata: Tsoa.Method = {
       extensions: this.getExtensions(),
       deprecated: this.getIsDeprecated(),
       description: getJSDocDescription(this.node),
@@ -73,6 +74,10 @@ export class MethodGenerator {
       tags: this.getTags(),
       type,
     };
+
+    this.processCustomDecorators(methodMetadata);
+
+    return methodMetadata;
   }
 
   private buildParameters() {
@@ -353,4 +358,26 @@ export class MethodGenerator {
     }
     return;
   }
+
+  private processCustomDecorators(methodMetadata: Tsoa.Method): void {
+    if (!this.current.customDecoratorProcessors) {
+      return;
+    }
+
+    for (const [decoratorName, processor] of Object.entries(this.current.customDecoratorProcessors)) {
+      const decorators = getDecorators(this.node, identifier => identifier.text === decoratorName);
+
+      for (const decorator of decorators) {
+        try {
+          const context: DecoratorProcessorContext = {
+            methodObject: methodMetadata,
+            decoratorArguments: getDecoratorValues(decorator, this.current.typeChecker),
+          };
+          processor(context);
+        } catch (error) {
+          throw new GenerateMetadataError(`Error in custom decorator processor for '${decoratorName}'`);
+        }
+      }
+    }
+  }
 }

.vscode/tasks.json

@@ -0,0 +1,8 @@
+import { Tsoa } from '@namecheap/tsoa-runtime';
+
+export interface DecoratorProcessorContext {
+  methodObject: Tsoa.Method;
+  decoratorArguments: any[];
+}
+
+export type NodeDecoratorProcessor = (context: DecoratorProcessorContext) => void;

packages/cli/src/metadataGeneration/metadataGenerator.ts

@@ -0,0 +1,11 @@
+import { Route, Get, Controller } from '@namecheap/tsoa-runtime';
+import { RateLimitByUserId } from './rateLimitDecorator';
+
+@Route('rateLimit')
+export class RateLimitController extends Controller {
+  @Get('test')
+  @RateLimitByUserId(100, 60)
+  public async getRateLimitedResource(): Promise<string> {
+    return 'This is a rate-limited resource';
+  }
+}

packages/cli/src/metadataGeneration/methodGenerator.ts

@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+import { NodeDecoratorProcessor, DecoratorProcessorContext } from '../../../packages/cli/src/metadataGeneration/types/nodeDecoratorProcessor';
+
+export function RateLimitByUserId(limit: number, timeWindow: number, description?: string): MethodDecorator {
+  return (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    const metadataKey = Symbol('tsoa:rate-limit-by-user-id');
+    Reflect.defineMetadata(
+      metadataKey,
+      {
+        limit,
+        timeWindow,
+        description: description || `${limit} requests per ${timeWindow} seconds per user`,
+      },
+      descriptor.value,
+    );
+
+    return descriptor;
+  };
+}
+
+export const RateLimitByUserIdProcessor: NodeDecoratorProcessor = (context: DecoratorProcessorContext) => {
+  const { methodObject, decoratorArguments } = context;
+
+  const limit = decoratorArguments[0] as number;
+  const timeWindow = decoratorArguments[1] as number;
+  const description = decoratorArguments[2] as string;
+
+  if (!methodObject.extensions) {
+    methodObject.extensions = [];
+  }
+
+  methodObject.extensions.push({
+    key: 'x-rate-limit-by-user-id',
+    value: {
+      limit: limit || 100,
+      timeWindow: timeWindow || 60,
+      description: description || `${limit || 100} requests per ${timeWindow || 60} seconds per user`,
+    },
+  });
+};