Middleware
cacheControl
A compact yet powerful HTTP caching middleware for TezX — built for speed, clarity, and zero overhead. It automatically adds optimized Cache-Control, Expires, and optional Vary headers based on flexible, rule-driven logic.
Features
- Ultra-fast — optimized for V8 hot path (no
.find, no closures, no overhead). - Lightweight — pure TypeScript, ~1KB.
- Rule-based — dynamic cache rules depending on request patterns.
- Plug & play — integrates smoothly with your
Contextand middleware chain.
Installation
import { cacheControl } from "tezx/middleware";Usage Example
app.use(
cacheControl({
defaultSettings: {
maxAge: 3600, // 1 hour
scope: "public",
},
rules: [
{
condition: (ctx) => ctx.url.startsWith("/api/private"),
maxAge: 0,
scope: "private",
},
{
condition: (ctx) => ctx.url.includes("/images/"),
maxAge: 86400, // 1 day
scope: "public",
vary: ["Accept-Encoding"],
},
],
onError: (error, ctx) => {
return ctx.status(500).json(error.message);
},
})
);API Reference
cacheControl(options: CacheOptions): Middleware
Creates and returns a high-performance caching middleware.
Parameters
| Name | Type | Description |
|---|---|---|
defaultSettings | CacheSettings | Default caching policy applied when no rule matches. |
rules | CacheRule[] (optional) | Custom rule list. First matching rule is applied. |
onError | (error: Error, ctx: Context) => HttpBaseResponse (optional) | Custom middleware-level error handler. |
Type Definitions
export interface CacheRule {
/** Condition to determine if this rule applies */
condition: (ctx: Context) => boolean;
/** Max age in seconds */
maxAge: number;
/** Cache scope */
scope: "public" | "private";
/** Optional Vary header list */
vary?: string[];
}
export interface CacheSettings
extends Pick<CacheRule, "maxAge" | "scope" | "vary"> {}
export interface CacheOptions {
defaultSettings: CacheSettings;
rules?: readonly CacheRule[];
onError?: (error: Error, ctx: Context) => HttpBaseResponse;
}How It Works
-
Runs only on
GETandHEADrequests. -
Evaluates rules in order; the first match is used.
-
Falls back to
defaultSettingswhen no rule matches. -
Automatically sets:
Cache-ControlExpiresVary(if provided)
Error Handling
If an error occurs:
- It is wrapped in
Error. - If
onErroris provided, it is executed. - Otherwise, a default response is returned:
{ "error": "Cache middleware failed" }Recommended Patterns
| Scenario | Suggested Settings |
|---|---|
| Static assets | public, maxAge=86400 |
| Private API | private, maxAge=0 |
| Dynamic pages | public, maxAge=60 |
| Sensitive data | private, maxAge=0 |
Router Integration
app.use("/products", cacheControl({
defaultSettings: { maxAge: 600, scope: "public" },
}));