@akuma225/cache

NestJS Redis-based HTTP caching module with cache invalidation and tenant-aware key isolation.

Table of Contents

• Overview
• Quick Start (60 seconds)
• Installation
• Prerequisites
• Configuration
• Usage
• API
• Release Process
• Commit Convention
• Scripts
• Contributing
• Changelog
• License

Overview

@akuma225/cache helps you:

• cache HTTP responses with @Cacheable(),
• invalidate cache key groups with @InvalidateCache(),
• isolate cache keys per tenant for multi-tenant APIs,
• integrate Redis in a NestJS module with minimal setup.

Quick Start (60 seconds)

1. Install the package:

npm install @akuma225/cache

2. Register the module in your AppModule:

AkumaCacheModule.forRoot({
  host: '127.0.0.1',
  port: 6379,
  defaultTtl: 3600,
  // Enable these options only for multi-tenant APIs:
  // tenantAware: true,
  // tenantHeaderName: 'x-tenant-id',
  // tenantClaimPath: 'tenantId',
  // tenantFallback: 'global', // or 'reject'
});

3. Cache an endpoint:

@Get()
@Cacheable({ ttl: 300 })
async listUsers() {
  return this.usersService.findAll();
}

Installation

npm install @akuma225/cache

Prerequisites

• Node.js 18+
• NestJS 10+
• Reachable Redis instance

Configuration

import { Module } from '@nestjs/common';
import { AkumaCacheModule } from '@akuma225/cache';

@Module({
  imports: [
    AkumaCacheModule.forRoot({
      // Priority: url > host/port/password/db
      host: '127.0.0.1',
      port: 6379,
      // password: 'secret',
      // db: 0,
      // url: 'redis://localhost:6379',
      defaultTtl: 3600,
      verbose: false,
      connectTimeoutMs: 5000,
      maxInitRetries: 5,
      retryDelayMs: 250,
      failFastOnInit: false,
      // Enable tenant options only for multi-tenant APIs
      tenantAware: false,
      tenantHeaderName: 'x-tenant-id',
      tenantClaimPath: 'tenantId',
      tenantFallback: 'global',
    }),
  ],
})
export class AppModule {}

Async Configuration (forRootAsync)

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { AkumaCacheModule, AkumaCacheOptions } from '@akuma225/cache';

@Module({
  imports: [
    ConfigModule.forRoot(),
    AkumaCacheModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (configService: ConfigService): AkumaCacheOptions => {
        const config = configService.get<AkumaCacheOptions>('cache');
        if (!config) {
          throw new Error('Missing cache configuration');
        }
        return config;
      },
    }),
  ],
})
export class AppModule {}

Usage

When to enable tenant-aware mode

Use tenantAware: true when multiple organizations share one API and cache data must be strictly isolated across tenants.

Typical use cases:

• B2B SaaS applications with one tenant per customer,
• shared API runtime with logical tenant data separation,
• risk of cache key collisions across customers on the same routes.

Do not use tenant mode when:

• the API is single-tenant,
• the API is public and has no tenant concept,
• you intentionally need one shared global cache.

@Cacheable()

import { Controller, Get } from '@nestjs/common';
import { Cacheable } from '@akuma225/cache';

@Controller('users')
export class UsersController {
  @Get()
  @Cacheable({ ttl: 300 })
  async listUsers() {
    return this.usersService.findAll();
  }
}

Available options:

• ttl?: number - key TTL in seconds
• cachePrefix?: string - optional prefix added before the generated key
• scope?: 'tenant' | 'global' - route-level scope override
• tenantResolver?: (request) => string | undefined - route-level tenant resolver

@InvalidateCache()

import { Body, Controller, Post } from '@nestjs/common';
import { InvalidateCache } from '@akuma225/cache';

@Controller('users')
export class UsersController {
  @Post()
  @InvalidateCache(['users*'])
  async createUser(@Body() payload: unknown) {
    return this.usersService.create(payload);
  }
}

patterns are Redis glob patterns (not JavaScript regexes).

Useful examples:

• users* - keys starting with users
• *users* - keys containing users
• production-GET-/reference-data/sectors* - API namespace invalidation
• report-*-2026* - prefixed/versioned key family

Direct service usage

import { Injectable } from '@nestjs/common';
import { RedisCacheService } from '@akuma225/cache';

@Injectable()
export class ReferenceDataService {
  constructor(private readonly cacheService: RedisCacheService) {}

  async warmupSectors(): Promise<void> {
    await this.cacheService.cache('reference:sectors', { items: [] }, 300);
  }

  async refreshReferenceData(): Promise<void> {
    await this.cacheService.invalidate(['reference:*', 'public-reference:*']);
  }
}

API

AkumaCacheModule.forRoot(options)

Option	Type	Default
host	string	127.0.0.1
port	number	6379
password	string	undefined
db	number	undefined
url	string	undefined
defaultTtl	number	3600
verbose	boolean	false
connectTimeoutMs	number	5000
maxInitRetries	number	5
retryDelayMs	number	250
failFastOnInit	boolean	false
tenantAware	boolean	false
tenantResolver	(request) => string | undefined	undefined
tenantHeaderName	string	'x-tenant-id'
tenantClaimPath	string	'tenantId'
tenantFallback	'global' | 'reject'	'global'

AkumaCacheModule.register(options)

Non-global module registration (same options as forRoot).

Redis resilience

Option	Purpose	When to tune
connectTimeoutMs	Max time to establish Redis connection.	Increase for slower network paths (cloud, VPN, remote container).
maxInitRetries	Max retries during startup connection.	Increase when Redis starts later than API.
retryDelayMs	Base delay between retries (exponential backoff).	Increase to reduce pressure during outages.
failFastOnInit	If true, app fails when Redis is unavailable on boot.	Set true when cache is critical; keep false to maximize API availability.

Release Process

Releases are fully automated with semantic-release on pushes to master.

For each release run:

1. Commit history is analyzed using Conventional Commits.
2. Next version is calculated with Semantic Versioning:
   • fix: -> patch
   • feat: -> minor
   • feat!: or BREAKING CHANGE: -> major
3. CHANGELOG.md is updated automatically.
4. A GitHub Release is created with generated notes.
5. The package is published to npm.

Commit Convention

Use Conventional Commits so release automation can infer the correct version bump.

Examples:

• fix(cache): handle redis timeout fallback
• feat(module): add per-route tenant resolver
• feat!: remove deprecated options shape
• refactor(interceptor): simplify cache key composition
• docs(readme): clarify tenant-aware use cases

Scripts

npm run build
npm test
npm run test:coverage
npm run lint
npm run release:dry

Contributing

Contributions are welcome. See CONTRIBUTING.md for:

• development setup,
• commit format and examples,
• pull request checklist.

Changelog

See CHANGELOG.md.

License

MIT