Decorators

Caching Decorators

Define TypeScript caching strategies, eviction policies, cache updates, invalidation, and stampede protection with AxilJS semantic decorators.

4 min readUpdated DocumentationEdit this page
On this page9

Caching decorators define how method results are cached, updated, evicted, and protected from concurrent cache misses. They keep cache strategy separate from business logic while exposing the intended semantics to independent consumers.

@tCache

@tCache caches a method's return value under a specified key with a time-to-live (TTL).

TypeScript
TS
1import { tCache } from '@axiljs/decorator'
2
3@tCache({
4  key: (id) => `user:${id}`,
5  ttl: 60_000,
6  tags: ['users'],
7})
8async getUser(id: string) {
9  return this.userRepository.findById(id)
10}

Options

OptionTypeDescription
keystring | FunctionCache key
ttlnumberTime to live in milliseconds
tagsstring[]Tags used for group invalidation
conditionFunctionPredicate that determines whether the result should be cached

These options allow cache identity, expiration, grouping, and conditional caching to be declared independently of the method implementation.

@tCacheEvict

@tCacheEvict removes cached entries when the decorated method executes.

Use a specific key when a single cache entry must be removed:

TypeScript
TS
1@tCacheEvict({
2  key: (id) => `user:${id}`,
3})
4async updateUser(id: string) {
5  return this.userRepository.update(id)
6}

You can also evict entries associated with a tag:

TypeScript
TS
1@tCacheEvict({
2  tags: ['users'],
3})
4async deleteUser(id: string) {
5  return this.userRepository.delete(id)
6}

@tCachePut

@tCachePut updates the cache using the decorated method's return value.

TypeScript
TS
1@tCachePut({
2  key: (id) => `user:${id}`,
3  ttl: 60_000,
4})
5async refreshUser(id: string) {
6  return this.userRepository.findById(id)
7}

This expresses an explicit cache-refresh operation rather than relying on a cache read to populate the entry.

@tCacheInvalidate

@tCacheInvalidate invalidates all cache entries associated with the specified tags.

TypeScript
TS
1@tCacheInvalidate('products', 'categories')
2async bulkUpdate() {
3  await this.productRepository.updateMany()
4  await this.categoryRepository.updateMany()
5}

This is useful when one operation affects multiple cached resources and invalidating individual keys would be impractical.

@tCacheStampede

A cache stampede can occur when an expired or missing cache entry causes many concurrent requests to recompute the same expensive result.

@tCacheStampede declares how those concurrent misses should be handled:

TypeScript
TS
1@tCache({
2  key: (id) => `product:${id}`,
3  ttl: 60_000,
4})
5@tCacheStampede({
6  strategy: 'single-flight',
7})
8async getProduct(id: string) {
9  return this.productRepository.findById(id)
10}

AxilJS defines three stampede-protection strategies:

StrategyDescription
'single-flight'Coalesce concurrent cache misses into one call
'lock'Acquire a lock before recomputing the value
'stale-while-revalidate'Serve stale data while refreshing it in the background

Combining Cache Semantics

Caching decorators can be composed with HTTP and database semantics to describe the complete behavior of an operation.

TypeScript
TS
1@tHttp({ method: 'GET', path: '/products/:id' })
2@tCache({
3  key: (id) => `product:${id}`,
4  ttl: 300_000,
5  tags: ['products'],
6})
7@tCacheStampede({
8  strategy: 'single-flight',
9})
10@tDatabase({ operation: 'read' })
11async getProduct(@tParam('id') id: string) {
12  return this.productRepo.findById(id)
13}
14
15@tHttp({ method: 'PUT', path: '/products/:id' })
16@tCacheEvict({
17  key: (id) => `product:${id}`,
18  tags: ['products'],
19})
20@tDatabase({ operation: 'write' })
21async updateProduct(
22  @tParam('id') id: string,
23  @tBody() dto: UpdateDto,
24) {
25  return this.productRepo.update(id, dto)
26}

The first method declares a cached database read with single-flight stampede protection. The second declares a write that evicts the affected cache entry and associated product entries.

Choosing the Right Decorator

Use @tCache when the result should be cached with a key and TTL.

Use @tCacheEvict when an operation should remove existing cache entries.

Use @tCachePut when an operation should update the cache with its returned value.

Use @tCacheInvalidate when multiple entries should be invalidated through tags.

Use @tCacheStampede when concurrent cache misses could trigger expensive duplicate work.

These decorators describe cache intent. The actual cache implementation is handled by the consumer that interprets the metadata, keeping caching semantics separate from application business logic.

Reference

DecoratorPurpose
tCacheCache method results with a key and TTL
tCacheEvictRemove cached entries
tCachePutUpdate the cache with a method result
tCacheInvalidateInvalidate entries by tags
tCacheStampedeProtect against concurrent cache misses

Caching is one part of AxilJS's broader semantic decorator model. The decorator writes metadata; independent consumers interpret that metadata and implement the corresponding runtime behavior.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY