English | 한국어
Table of Contents
- 🎯 Decorator-based AOP — wrap any method, getter, or setter with reusable cross-cutting logic (caching, logging, retries, ...)
- 🧩 Plays nice with the IoC container — your aspect is a regular NestJS provider, so
@Injectanything you need - 🪶 Zero runtime magic — built on native decorators +
reflect-metadata, no code transformation step - ✅ NestJS 10 → 12 — one package, no major-version treadmill
- 🧬 Inheritance-aware — decorated methods keep working when called through a subclass
npm install @toss/nestjs-aop
pnpm add @toss/nestjs-aop
yarn add @toss/nestjs-aopRequirements: Node.js >= 22.12.0 · NestJS 10, 11 or 12 · ESM build. CommonJS apps can load it through
require(esm). CJS + TypeScript NodeNext needs TS >= 5.8;node16does not support this interop. Jest needs ESM mode +--experimental-vm-modules, or the tested Jest 30.4.2 CJS setup on Node >= 24.9 with the same flag. Upgrading from v2? See the migration guide.
export const CACHE = Symbol('CACHE');
export const Cache = (options?: CacheOptions) => createDecorator(CACHE, options);
@Aspect(CACHE)
export class CacheDecorator implements LazyDecorator<any, CacheOptions> {
constructor(private readonly cache: Cache) {}
wrap({ method, metadata: options }: WrapParams<any, CacheOptions>) {
return (...args: any[]) => {
const cached = this.cache.get(...args);
return cached ?? this.cache.set(method(...args), ...args);
};
}
}
@Injectable()
export class UserService {
@Cache({ ttl: 1000 })
findAll() {
// ...
}
}See Usage below for the full, step-by-step breakdown of how the pieces fit together.
@Module({
imports: [
// ...
AopModule,
],
})
export class AppModule {}export const CACHE_DECORATOR = Symbol('CACHE_DECORATOR');metadata is passed as the second argument to createDecorator and is made available in the WrapParams for the wrap method.
@Aspect(CACHE_DECORATOR)
export class CacheDecorator implements LazyDecorator<any, CacheOptions> {
constructor(private readonly cache: Cache) {}
wrap({ method, metadata: options }: WrapParams<any, CacheOptions>) {
return (...args: any) => {
let cachedValue = this.cache.get(...args);
if (!cachedValue) {
cachedValue = method(...args);
this.cache.set(cachedValue, ...args);
}
return cachedValue;
};
}
}@Module({
providers: [CacheDecorator],
})
export class CacheModule {}options can be obtained from the wrap method and used.
export const Cache = (options: CacheOptions) => createDecorator(CACHE_DECORATOR, options);export class SomeService {
@Cache({
// ...options(metadata value)
})
some() {
// ...
}
}createDecorator can also be applied to get/set accessors, and decorated methods or accessors are inherited correctly by subclasses.
class UserService {
private _name = 'John';
@Cache({ ttl: 1000 })
get name() {
return this._name.toUpperCase();
}
}- A decorator can be applied to a
getaccessor, asetaccessor, or a regular method — but not to a property that has both a getter and a setter. Split them into separate properties, or use a regular method instead. - A decorated method or accessor keeps working when called through a subclass instance.
If you’re testing with NestJS’s TestingModule, don’t forget to call the init method.
import { Test } from '@nestjs/testing';
const module = await Test.createTestingModule({
// ...
}).compile();
await module.init();We welcome contributions from everyone to this project. Read CONTRIBUTING.md for detailed contribution guide.
MIT © Viva Republica, Inc. See LICENSE for details.