Packages

@xtaskjs/cache

Memory and Redis-backed cache models, method decorators, runtime inspection, and browser cache policies.

npm install @xtaskjs/cache reflect-metadata Package path: packages/cache

Overview

What this package owns in the runtime

Cache adds application-level data caching and client-facing HTTP cache control to xtaskjs. It registers named cache models, exposes injectable repositories and services, layers method decorators for cache read/write behavior, and can publish browser cache headers plus operational endpoints from the same package.

What it provides

configureCache() centralizes default driver, TTL, namespace, Redis connection options, and shared HTTP cache defaults.
CacheModel(), Cacheable(), CachePut(), and CacheEvict() cover model registration plus read-through, write-through, and eviction flows.
CacheService, CacheRepository, and CacheAdminService are injectable for direct entry access, runtime inspection, and admin operations.
BrowserCache(), CacheView(), NoStore(), NoCache(), VaryBy(), and HttpCacheService handle Cache-Control, ETag, Last-Modified, and Vary headers.

How it fits

Initialized automatically by @xtaskjs/core when the package is installed and configureCache()/registerCacheModel() have been called.
Supports in-memory stores by default and Redis-backed models when the redis client package is available.
Demonstrated by the 12-cache_app, 13-cache_redis_app, 14-http_cache_web_app, and 15-fastify_http_cache_web_app samples.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

Caching

5/5

Operations

5/5

HTTP Delivery

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Configure package defaults, register cache models, and optionally export a cache management controller so storage and HTTP policy behavior are known before requests arrive.

During CreateApplication()

The cache lifecycle manager publishes CacheService, CacheAdminService, model repositories, and HttpCacheService into the container while connecting Redis-backed stores when configured.

During app.close()

Connected stores and runtime cache state are released automatically so in-memory and Redis-backed caches shut down with the rest of the application.

API Surface

Representative exports from the upstream package

Configuration and models

configureCache
registerCacheModel
CacheSettings
CacheModel

Repository and services

CacheRepository
CacheService
CacheAdminService
InjectCacheService
InjectCacheRepository

HTTP caching and management

HttpCacheService
InjectHttpCacheService
CacheResponse
BrowserCache
CacheView
NoStore
NoCache
VaryBy
createCacheManagementController
InjectCacheAdminService

Lifecycle surface

InjectCacheLifecycleManager
initializeCacheIntegration
shutdownCacheIntegration
resetCacheIntegration

Usage

Typical adoption flow

1. Configure models and defaults

Use configureCache() and CacheModel() to define namespace, driver selection, TTL behavior, Redis connectivity, and shared HTTP cache defaults once near app startup.

2. Apply method decorators and injection

Use Cacheable, CachePut, and CacheEvict on DI-managed services, then inject CacheRepository or CacheService when you need direct entry reads, writes, or inspection.

3. Expose client and operator controls

Apply BrowserCache, CacheView, NoStore, NoCache, and VaryBy to routes, and publish createCacheManagementController() when operators need runtime cache inspection endpoints.

Example

Reference snippet

Model caching plus browser cache control

import { Controller, Get, Param } from "@xtaskjs/common";
import { Service } from "@xtaskjs/core";
import {
  BrowserCache,
  CacheModel,
  CacheRepository,
  Cacheable,
  InjectCacheRepository,
  configureCache,
  createCacheManagementController,
} from "@xtaskjs/cache";

configureCache({
  defaultDriver: "memory",
  defaultTtl: "45s",
  namespace: "catalog",
  httpCacheDefaults: { visibility: "public", maxAge: "2m", etag: true },
});

@CacheModel({ name: "products", ttl: "45s" })
export class ProductCacheModel {}

export const CacheManagementController = createCacheManagementController({
  path: "/ops/cache",
});

@Service()
export class CatalogService {
  constructor(
    @InjectCacheRepository(ProductCacheModel)
    private readonly products: CacheRepository<any>
  ) {}

  @Cacheable({ model: ProductCacheModel, key: (id: string) => id })
  async getProduct(id: string) {
    return { id, generatedAt: new Date().toISOString() };
  }
}

@Controller("/products")
export class CatalogController {
  constructor(private readonly catalog: CatalogService) {}

  @BrowserCache({ staleWhileRevalidate: "30s" })
  @Get(":id")
  show(@Param("id") id: string) {
    return this.catalog.getProduct(id);
  }
}

Samples

Official samples to inspect next

Reference samples: 12-cache_app, 13-cache_redis_app, 14-http_cache_web_app, 15-fastify_http_cache_web_app