Cache

@talosjs/cache gives you one interface, ICache, with two backends sitting behind it: the filesystem and Redis. Both expose the same methods (get, set, delete, deleteByPrefix, has, clear), so code you wrote against the filesystem keeps working after you point it at Redis. Values are JSON-serialized for you, and any key can carry a TTL. A few things worth knowing up front: get<T>() and set<T>() thread your value type through serialization, so reads come back typed. TTLs are in seconds and per-key. deleteByPrefix() wipes a whole group of related keys at once, while clear() empties everything. And you register a cache class with a decorator, then pull it out of the container wherever you need it.

How it works

You pick a backend (or write your own) and register it. Reads and writes go through the ICache methods, and the backend takes care of serialization, namespacing, and expiration.

Method	Purpose
`get<T>(key)`	Return the value or `undefined` if missing/expired.
`set<T>(key, value, ttl?)`	Store a value, optionally expiring after `ttl` seconds.
`delete(key)`	Remove one key; returns whether it existed.
`deleteByPrefix(prefix)`	Remove every key starting with `prefix`; returns the count.
`has(key)`	Whether a live (non-expired) key exists.
`clear()`	Remove everything.

The built-in backends differ in where data lives, not in how you call them:

Backend	Best for	Distribution
`FilesystemCache`	Local development, single-instance caches	One machine (disk)
`RedisCache`	Production caches shared across instances	Shared (TCP)

A TTL of 0 (or omitted) means the entry never expires. Redis backends namespace every key (default cache:) to avoid collisions on a shared instance.

Environment variables

Variable	Backend	Required	Purpose
`CACHE_REDIS_URL`	`RedisCache`	Yes (unless passed in config)	Connection string, e.g. `redis://localhost:6379`. Missing throws `CacheException` (`URL_REQUIRED`).

FilesystemCache needs no environment variables; it defaults to a .cache directory in the working directory.

CACHE_REDIS_URL=redis://localhost:6379

Usage

The API is the same regardless of backend.

import { RedisCache } from "@talosjs/cache";
import { container } from "@talosjs/container";

const cache = container.get(RedisCache);

// Store with a 5-minute TTL
await cache.set("user:123", { name: "John", age: 30 }, 300);

// Read back with a type
const user = await cache.get<{ name: string; age: number }>("user:123");

// Existence and removal
await cache.has("user:123"); // true
await cache.delete("user:123"); // true

// Bulk removal by prefix
const removed = await cache.deleteByPrefix("user:"); // number cleared

A common pattern is read-through caching: serve from the cache, fall back to the source on a miss, then populate it for next time.

const key = `user:${id}`;
let user = await cache.get<User>(key);

if (!user) {
  user = await userRepository.findById(id);
  await cache.set(key, user, 300); // cache for 5 minutes
}

Invalidate on writes so callers never read stale data:

await userRepository.update(id, data);
await cache.delete(`user:${id}`);
await cache.deleteByPrefix(`user:${id}:`); // related derived keys

Decorator and usage

`@decorator.cache()`

Registers a cache class with the container. It accepts an optional scope (defaults to singleton). Use it to register a built-in backend under your own name, or a custom backend that implements ICache.

import { decorator } from "@talosjs/cache";
import { RedisCache } from "@talosjs/cache";

@decorator.cache()
export class SessionCache extends RedisCache {}

Resolve it from the container and inject it where needed:

import { inject } from "@talosjs/container";

export class SessionService {
  constructor(@inject(SessionCache) private readonly cache: SessionCache) {}
}

Exceptions

The component throws CacheException when a backend is misconfigured or an operation fails. It carries a machine-readable key, a human-readable message, and a data object.

Key	When
`URL_REQUIRED`	`RedisCache` is created without a connection string or `CACHE_REDIS_URL`.
`MAX_SIZE_EXCEEDED`	A `FilesystemCache` value exceeds the maximum file size (10MB by default).

import { CacheException } from "@talosjs/cache";

try {
  await cache.set("key", value);
} catch (error) {
  if (error instanceof CacheException) {
    logger.error(`Cache error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

A few habits that pay off

Pick a stable key scheme such as user:123 or session:abc. The structure isn’t cosmetic — it’s what lets deleteByPrefix() find and clear related entries later. Give volatile data an explicit TTL. Anything derived or fetched from elsewhere should expire on its own so a stale value can’t linger forever, and invalidate the key whenever its source changes. For derived keys, pair delete() with a deleteByPrefix() to catch the rest. Keep stored values JSON-friendly. They round-trip through JSON.stringify/JSON.parse, so class instances, functions, and circular references won’t survive the trip. Treat a cache read as best-effort, too: on a miss, go to the source of truth rather than assuming the key is there. Choosing a backend is mostly an environment decision. Filesystem is fine for local work; Redis is the one you want when several instances share a cache. The calling code doesn’t change either way. And in a custom backend, throw CacheException with a constant key and stash the variable detail in data.

CLI command

Scaffold a cache adapter and its test file with the generator. It writes the class under modules/<module>/src/cache/<Name>Cache.ts and installs @talosjs/cache if it is missing.

# Interactive: prompts for the name
talos cache:create

# Provide the name
talos cache:create --name=Session

# Target a module and overwrite
talos cache:create --name=Session --module=auth --override

Option	Description	Default
`--name`	Cache class name. The `Cache` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class starts as an ICache stub, ready for you to implement each method against your backend:

import { CacheException, decorator } from "@talosjs/cache";
import type { ICache } from "@talosjs/cache";

@decorator.cache()
export class SessionCache implements ICache {
  public async get<T = unknown>(key: string): Promise<T | undefined> {
    throw new CacheException(`Failed to get key "${key}": Not implemented`);
  }

  public async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
    throw new CacheException(`Failed to set key "${key}": Not implemented`);
  }

  public async delete(key: string): Promise<boolean> {
    throw new CacheException(`Failed to delete key "${key}": Not implemented`);
  }

  public async has(key: string): Promise<boolean> {
    throw new CacheException(`Failed to check if key "${key}" exists: Not implemented`);
  }
}

See cache:create for the full command reference.

Use with Claude and Codex

The generator ships a matching cache:create skill. It runs the scaffold and then guides your AI agent through completing the adapter — implementing get, set, delete, and has against a real backend and wiring up its client. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language — it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a cache adapter for user sessions backed by Redis with a 30 minute TTL.

talos agent:skills:create

Then ask Codex in natural language — it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a cache adapter for user sessions backed by Redis with a 30 minute TTL.

For example, the prompt above maps to cache:create --name=Session, then implements the ICache methods against a Redis client.

Getting Started

AI

Framework

Command Line

How it works

Environment variables

Usage

Decorator and usage

`@decorator.cache()`

Exceptions

A few habits that pay off

CLI command

Use with Claude and Codex

​How it works

​Environment variables

​Usage

​Decorator and usage

​@decorator.cache()

​Exceptions

​A few habits that pay off

​CLI command

​Use with Claude and Codex

How it works

Environment variables

Usage

Decorator and usage

`@decorator.cache()`

Exceptions

A few habits that pay off

CLI command

Use with Claude and Codex