Caching

HeronJS supports response caching for REST APIs through decorators and cache event handlers. This lets you cache route results, evict stale entries, and interact with the cache manually when needed.

Cache a REST endpoint

Use @Cacheable() on a route method to cache its response.


@Rest('/todos')
export class TodoRest {
    constructor(
        private readonly service: TodoService,
        @CacheEventLookup() readonly cacheEvent: CacheEventHandler,
    ) {}
 
    @Get({ uri: '/:id' })
    @Cacheable({
        ttl: 300,
        key: async (todo: TodoModel) => `/todos/${todo.id}`,
    })
    public async getTodoById(
        @Param('id') id: number,
        @Query('filter') filter?: string,
    ): Promise<any> {
        return this.service.getById(id);
    }
}

In this example:

ttl defines how long the cached value should live.
key defines how the cache key is generated.

If key is a function, it is used to build the cache key from the returned data. If key is a string, that value is used directly as the cache key.

Cacheable options

Parameter	Description	Note
`ttl`	Time to live for the cached value.	Uses the unit expected by the configured cache store.
`key`	A cache key string or async key builder.	When a function is used, it receives the route result.
`validate`	Validates the value before caching.	`undefined` and empty arrays are usually rejected by default.

Evict cached data

Use @Evict() when a route should clear related cache entries.

Supported patterns:

* clears all cached data.
/<uri>/* clears cached data for a specific URI group.


@Rest('/todos')
export class TodoRest {
    constructor(
        private readonly service: TodoService,
        @CacheLookup() readonly cacheStore: CacheStore,
        @CacheEventLookup() readonly cacheEvent: CacheEventHandler,
    ) {}
 
    @Post({ uri: '/' })
    @Evict({ key: '/todos/*' })
    public async create(@Body() body: any): Promise<any> {
        return this.service.create(body);
    }
}

This is useful when create, update, or delete operations should invalidate previously cached responses.

Work with the cache manually

For manual cache access, inject either:

@CacheEventLookup() to submit or evict cache entries through the event-driven cache handler.
@CacheLookup() to access the underlying CacheStore directly.


@Rest('/todos')
export class TodoRest {
    constructor(
        private readonly service: TodoService,
        @CacheLookup() readonly cacheStore: CacheStore,
        @CacheEventLookup() readonly cacheEvent: CacheEventHandler,
    ) {}
}

Use CacheEventHandler when you want to integrate with the framework’s cache events, and use CacheStore when you need lower-level access to the underlying cache implementation.