NestJS Cacheable

A flexible, powerful caching solution for NestJS applications. Unlike @nestjs-cache-manager, it uses cacheable as the cache solution.

Features

• Cache Decorators: Simplify caching with decorators like @Cacheable, @CacheEvict, and @CachePut.
• Backend Flexibility: Supports multiple cache stores, including:
  • Redis
  • Etcd
  • Valkey
  • Memcached
  • etc. For more stores, see Keyv Storage Adapters

Installation

# Using npm
npm install @maxlz/nestjs-cacheable cacheable

# Using yarn
yarn add @maxlz/nestjs-cacheable cacheable

# Using pnpm
pnpm add @maxlz/nestjs-cacheable cacheable

Getting Started

register module

You can use CacheModule.register or CacheModule.registerAsync to register a cache module.

• CacheModule.register(options?)

import { Module } from '@nestjs/common';
import { CacheModule } from '@maxlz/nestjs-cacheable';

@Module({
  imports: [CacheModule.register({ ttl: '30m' }) ]
})
export class AppModule {}

If you do not set primary and secondary, the memory cache will be used by default.

CacheModule.register options:

| options | type | default | description | |-------------|---------|---------|---| | isGlobal? | boolean | false | Set a global module |

CacheModule.register other options refer to cacheable options.

• CacheModule.registerAsync(options?)

import { Module } from '@nestjs/common';
import { CacheModule } from '@maxlz/nestjs-cacheable';

@Module({
  imports: [
    CacheModule.registerAsync({
      useFactory: () => ({
        ttl: '30m',
      }),
    }),
  ],
})
export class AppModule {}

CacheModule.registerAsync options:

| options | type | default | description | |-------------------|----------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | isGlobal? | boolean | false | Set a global module | | extraProviders? | Provider[] | [] | Extra providers. Injected into the class as an additional provider. For details, please refer to async-register-extra-providers test case | | useFactory? | () => CacheableOptions | / | | | useClass? | implements CacheOptionsFactory | / | |

CacheableOptions.

Decorators

Decorators can enhance the method, provide the ability to cache the results of the method and delete the cache. You can use decorators in your service.

• @Cacheable

Cache method results. Check the cache before executing the method. If the value of the corresponding key can be obtained from the cache, return this value. If there is no value of the corresponding key in the cache, execute the method and store the return result of the method in the cache.

import { Cacheable } from '@maxlz/nestjs-cacheable';

class ExampleService {
  @Cacheable<typeof ExampleService.prototype.getUser>({
    name: 'users',
    ttl: 60,
    key: ({ args }) => args[0],
    condition: ({ result }) => result !== null,
  })
  async getUser(id: number): Promise<User> {
    return await this.userRepository.findOne(id);
  }
}

@Cacheable options:

| options | type | default | description | |--------------|------------------------------|---------|---------------------------------------------------------------------------------------------------------------------| | name | string | \ | The cache name. | | key? | string \| (args) => string | \ | The cache key. It can be generated by method parameters and method name. | | ttl? | number \| string | \ | The cache time-to-live. ttl | | condition? | (args) => boolean | \ | The caching conditions of the method. The return value of the method will be cached only if the conditions are met. |

key function args:

| options | type | description | |----------|----------|-----------------------| | args | Array | The method arguments. | | method | string | The method name. |

condition function args:

| options | type | description | |----------|---------------------------------------------|----------------------------------| | args | Array | The method arguments. | | method | string \| symbol | The method name. | | result | The result type depends on the generic type | The return result of the method. |

If you don't need to use the method parameters and the method return results in the process of using Cacheable, you can not provide a generic type.

import { Cacheable } from '@maxlz/nestjs-cacheable';

class ExampleService {
  @Cacheable({
    name: 'users',
    ttl: 60,
    key: ({ method }) => String(method)
  })
  async getUser(id: number): Promise<User> {
    return await this.userRepository.findOne(id);
  }
}

• @CachePut

Cache method results .Unlike @Cacheable, it does not check the cache before the method is executed.

import { CachePut } from '@maxlz/nestjs-cacheable';

class ExampleService {
  @CachePut<typeof ExampleService.prototype.setUser>({
    name: 'users',
    ttl: 60,
    key: ({ args }) => args[0],
    condition: ({ result }) => result !== null,
  })
  async setUser(id: number): Promise<User> {
    return await this.userRepository.create(id);
  }
}

@CachePut and @Cacheable have the same options.

• @CacheEvict

Delete a single cache value by key, or delete cache values in batches by name.

import { CacheEvict } from '@maxlz/nestjs-cacheable';

class ExampleService {
  @CacheEvict<typeof ExampleService.prototype.removeUser>({
    name: 'users',
    key: ({ args }) => args[0],
  })
  async removeUser(id: number): Promise<void> {
    await this.userRepository.delete(id);
  }

  @CacheEvict({
    name: 'users',
    allEntries: true,
    beforeInvocation: true,
  })
  async clearAllUsers(): Promise<void> {
    await this.userRepository.clear();
  }
}

@CacheEvict options:

| options | type | default | description | |---------------------|------------------------------|---------|--------------------------------------------------------------------------| | name | string | \ | The cache name. | | key? | string \| (args) => string | \ | The cache key. It can be generated by method parameters and method name. | | allEntries? | boolean | false | Delete all cached values prefixed with name. |
| beforeInvocation? | boolean | false | Delete the cache before the method is executed. |

key function args:

| options | type | description | |-----------|---------------------------------------------|--------------------------------------------------------------------------------------| | args | Array | The method arguments. | | method | string \| symbol | The method name. | | result? | The result type depends on the generic type | The return result of the method. The result can only be used if allEntries is false. |

License

MIT license