Skip to content

About

A way to gracefully apply AOP to nestjs

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

256 stars

Watchers

8 watching

Forks

Repository files navigation


Logo

@toss/nestjs-aop

A way to gracefully apply AOP to NestJS.
Use NestJS managed instances in any decorators gracefully.

npm version CI types downloads license stars


English | 한국어

Table of Contents
  1. Features
  2. Installation
  3. Quick Start
  4. Usage
  5. Getter, Setter and Inheritance Support
  6. Caveats
  7. References
  8. Contributing
  9. License

Features

  • 🎯 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 @Inject anything 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

Installation

npm install @toss/nestjs-aop
pnpm add @toss/nestjs-aop
yarn add @toss/nestjs-aop

Requirements: 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; node16 does 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.

Quick Start

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.

Usage

1. Import AopModule

@Module({
  imports: [
    // ...
    AopModule,
  ],
})
export class AppModule {}

2. Create symbol for LazyDecorator

export const CACHE_DECORATOR = Symbol('CACHE_DECORATOR');

3. Implement LazyDecorator using nestjs provider

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;
    };
  }
}

4. Add LazyDecoratorImpl to providers of module

@Module({
  providers: [CacheDecorator],
})
export class CacheModule {}

5. Create decorator that marks metadata of LazyDecorator

options can be obtained from the wrap method and used.

export const Cache = (options: CacheOptions) => createDecorator(CACHE_DECORATOR, options);

6. Use it!

export class SomeService {
  @Cache({
    // ...options(metadata value)
  })
  some() {
    // ...
  }
}

Getter, Setter and Inheritance Support

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 get accessor, a set accessor, 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.

Caveats

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();

References

Contributing

We welcome contributions from everyone to this project. Read CONTRIBUTING.md for detailed contribution guide.

License

MIT © Viva Republica, Inc. See LICENSE for details.

Toss

About

A way to gracefully apply AOP to nestjs

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

256 stars

Watchers

8 watching

Forks

Releases

Packages

Used by

Contributors

Languages