Class ExternalDecoratorHandler

Handles detection and preservation of external/custom decorators.

Uses a blacklist approach:

Framework decorators (Angular, NestJS, TypeORM) are blacklisted
Everything else is considered external
Auto-detects external decorators from project
Caches results for performance

Performance:

Auto-detection: <5s for typical projects
Cache hit rate: >90%
Per-decorator check: <0.1ms

Compatibility:

Angular decorators (@Component, @Injectable, @Input, etc.)
NestJS decorators (@Controller, @Get, @Post, etc.)
TypeORM decorators (@Entity, @Column, @PrimaryGeneratedColumn, etc.)
Custom project decorators (auto-detected)

Index

Constructors

Methods

addFrameworkDecorators autoDetectDecorators clearCache getExternalDecorators isAutoDetected isExternalDecorator parseDecorators registerExternalDecorator

Constructors

constructor

new ExternalDecoratorHandler(): ExternalDecoratorHandler
Returns ExternalDecoratorHandler

Methods

addFrameworkDecorators

addFrameworkDecorators(decoratorNames: string[]): void
Add framework decorators to the blacklist.

Use this to extend the framework decorator blacklist for custom frameworks or additional framework decorators not included by default.
Parameters
- decoratorNames: string[]
  Framework decorator names to add to blacklist
Returns void
Example
```
// Add custom framework decorators
handler.addFrameworkDecorators(['CustomFrameworkDecorator', 'AnotherOne']);
```

autoDetectDecorators

autoDetectDecorators(projectRoot: string): Promise<Set<string>>
Auto-detect external decorators in the project.

Scans TypeScript files for decorators, filters out known framework decorators, and registers the rest as external decorators.

Algorithm:
1. Find all TypeScript files (excluding node_modules)
2. Parse decorators from each file
3. Filter out framework decorators (blacklist)
4. Register remaining decorators as external
5. Cache results per projectRoot
Performance:
- Typical project (500 files): 2-3s
- Large project (2000+ files): <5s
- Cached: <1ms
Parameters
- projectRoot: string
  Absolute path to project root
Returns Promise<Set<string>>
Set of detected external decorator names
Example
```
const handler = new ExternalDecoratorHandler();
const external = await handler.autoDetectDecorators('/path/to/project');
console.info(`Found ${external.size} external decorators:`, Array.from(external));
// Found 3 external decorators: ['PageComponent', 'RemoteFunction', 'RequiresPermission']
```

clearCache

clearCache(): void
Clear detection cache.

Use this to force re-detection on next autoDetectDecorators() call.

Returns void

getExternalDecorators

getExternalDecorators(): Map<string, ExternalDecoratorDefinition>
Get all detected external decorators.

Returns Map<string, ExternalDecoratorDefinition>
Map of external decorator names to definitions

isAutoDetected

isAutoDetected(): boolean
Check if auto-detection has been performed.

Returns boolean

isExternalDecorator

isExternalDecorator(decoratorName: string): boolean
Check if a decorator is external (not a framework decorator).

Performance: <0.1ms (Set lookup)
Parameters
- decoratorName: string
  Decorator name (without @)
Returns boolean
true if external, false if framework
Example
```
handler.isExternalDecorator('PageComponent'); // true
handler.isExternalDecorator('Component'); // false (Angular)
handler.isExternalDecorator('Controller'); // false (NestJS)
handler.isExternalDecorator('Entity'); // false (TypeORM)
```

parseDecorators

parseDecorators(node: Node): ParsedDecorator[]
Parse decorators on a node and classify as framework/external.

Returns parsed decorators with:
- isExternal: true if external/custom decorator
- isFramework: true if known framework decorator
- properties: extracted decorator arguments
- source: import source if detected
Performance: <1ms per node
Parameters
- node: Node
  ts-morph Node (ClassDeclaration, MethodDeclaration, PropertyDeclaration)
Returns ParsedDecorator[]
Array of parsed decorators with classification
Example
```
const decorators = handler.parseDecorators(classNode);

// Filter external decorators
const external = decorators.filter(d => d.isExternal);
console.info(`External: ${external.map(d => d.name).join(', ')}`);

// Filter framework decorators
const framework = decorators.filter(d => d.isFramework);
console.info(`Framework: ${framework.map(d => d.name).join(', ')}`);
```

registerExternalDecorator

registerExternalDecorator(definition: ExternalDecoratorDefinition): void
Register an external decorator manually.

Use this to override auto-detection or register decorators before detection.
Parameters
- definition: ExternalDecoratorDefinition
  External decorator definition
Returns void
Example
```
handler.registerExternalDecorator({
  name: 'CustomAuth',
  source: '@mycompany/auth',
  preserveDuringTransformation: true
});
```