Cache
Caches HTTP responses in the transformer chain. On a cache HIT, serves the stored response directly and stops the chain. On a MISS, wraps the respond function to intercept, cache, and forward the downstream response.
Setup
- Integrated
- Bundled
Install the package:
Configure in your code:
How it works
- A request arrives and the cache transformer checks its rules in order (first match wins)
- The cache key is built by joining the configured ingest fields (e.g.
method:path) - If the key exists in the store → HIT: respond immediately with the cached response and
X-Cache: HITheader, stop the chain - If the key is missing → MISS: wrap the respond function so the downstream response is intercepted, stored, and forwarded with
X-Cache: MISSheader - If no rule matches → event passes through unchanged
Settings
| Option | Type | Default | Description |
|---|---|---|---|
rules | CacheRule[] | — | Cache rules, evaluated in order (first match wins) |
maxSize | number | 10485760 (10 MB) | Maximum in-memory store size in bytes |
Rule configuration
Each rule specifies when to cache, what to use as the cache key, and how long to keep it:
| Option | Type | Description |
|---|---|---|
match | MatchExpression | '*' | Condition to evaluate against ingest, or '*' wildcard |
key | string[] | Ingest fields joined with : to form the cache key |
ttl | number | Time-to-live in seconds |
headers | Record<string, string> | Extra headers merged into both HIT and MISS responses |
Match operators
The cache transformer uses the same match expressions as the router, including all 8 operators, negation with not: true, and and/or combinators.
Examples
Cache GET requests by path
Different TTLs per path
Chain placement
Place the cache transformer before a responder in the chain. On HIT it stops the chain, skipping the responder entirely:
Custom store backend
By default the cache uses an in-memory store (@walkeros/store-memory) with LRU eviction and lazy TTL. You can inject a different store via env.store:
Any object with get(key): T | undefined and set(key, value, ttl?): void methods works as a store backend.
Behavior notes
- LRU eviction — when the store exceeds
maxSize, the least-recently-used entries are evicted first - Lazy TTL — expired entries are removed on the next lookup, not on a timer
- First match wins — rules are evaluated in order; only the first matching rule applies
- Empty key — if all key fields resolve to empty strings, the event passes through with a warning
- No respond function — the MISS wrapper still caches the response even without
env.respond(useful for pre-warming)
Next steps
- Router - Route events before caching
- Create your own - Build custom transformers