@heinhtet37/express-route-cache 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @mvs/express-route-cache
+
+Reusable Express middleware factories for route-level response caching and cache invalidation.
+
+This package is intended to be published independently from this repo. You can:
+
+1. `cd express-route-cache`
+2. `npm install`
+3. `npm publish`
+
+## Install
+
+```bash
+npm install @mvs/express-route-cache
+```
+
+## What it provides
+
+- `createRouteCache()` to create middleware factories
+- `createRedisStore()` for Redis-backed caching
+- `createMemoryStore()` for local development and tests
+
+## Basic usage
+
+```ts
+import { createRedisStore, createRouteCache } from "@mvs/express-route-cache";
+import redis from "./redis";
+
+const cache = createRouteCache({
+  store: createRedisStore({
+    client: redis,
+    defaultTtlSeconds: 300,
+  }),
+});
+
+export const checkUsersCache = cache.check({
+  varyHeaders: ["accept-language"],
+});
+
+export const setUsersCache = cache.capture();
+
+export const invalidateUsersCache = cache.invalidate({
+  patterns: (req) => [
+    "/api/users",
+    "/api/users?*",
+    `/api/users/${req.params.id}*`,
+  ],
+});
+```
+
+Then use it in your routes:
+
+```ts
+router.get(
+  "/users",
+  checkUsersCache,
+  setUsersCache,
+  async (req, res) => {
+    res.json(await userService.getAll());
+  }
+);
+
+router.patch(
+  "/users/:id",
+  invalidateUsersCache,
+  async (req, res) => {
+    res.json(await userService.update(req.params.id, req.body));
+  }
+);
+```
+
+## API
+
+### `createRouteCache({ store, logger, defaultTtlSeconds })`
+
+Returns:
+
+- `check(options)`
+- `capture(options)`
+- `invalidate(options)`
+- `get(key)`
+- `set(key, value, ttlSeconds?)`
+- `deleteByPatterns(patterns)`
+
+### `check(options)`
+
+Options:
+
+- `key`: custom cache key or `(req) => string`
+- `varyHeaders`: append selected request headers into the cache key
+- `shouldBypass`: skip lookup for selected requests
+- `hitHeader`: response header name for cache hit or miss, defaults to `x-cache`
+
+### `capture(options)`
+
+Options:
+
+- `ttlSeconds`: number or `(req, res, body) => number | undefined`
+- `shouldCache`: predicate to decide whether a response body should be cached
+
+### `invalidate(options)`
+
+Options:
+
+- `patterns`: array or `(req, res, body) => string[]`
+- `shouldInvalidate`: predicate to control invalidation
+- `onInvalidate`: async hook for audit logging or side effects
+
+### `createRedisStore({ client, defaultTtlSeconds, logger, scanCount })`
+
+The Redis client should expose:
+
+- `get`
+- `del`
+- one of `scan` or `keys`
+- one of `setex` or `set(..., "EX", ttl)`
+
+### `createMemoryStore({ defaultTtlSeconds })`
+
+Simple in-memory cache store for testing or local usage.
+
+## Publish
+
+```bash
+cd express-route-cache
+npm install
+npm publish
+```
+
+Because `publishConfig.access` is already set to `public`, npm will publish it as a public package.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { Request, RequestHandler, Response } from "express";
+export interface CacheStore {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    deleteByPatterns(patterns: string[]): Promise<number | void>;
+}
+export interface CacheLogger {
+    error?(message: string, meta?: unknown): void;
+    warn?(message: string, meta?: unknown): void;
+    info?(message: string, meta?: unknown): void;
+}
+type ValueResolver<T> = T | ((req: Request, res: Response, body?: unknown) => T);
+type MaybePromise<T> = T | Promise<T>;
+export interface CacheCheckOptions {
+    key?: string | ((req: Request) => string);
+    varyHeaders?: string[];
+    shouldBypass?: (req: Request) => boolean;
+    hitHeader?: string | false;
+}
+export interface CacheCaptureOptions {
+    ttlSeconds?: ValueResolver<number | undefined>;
+    shouldCache?: (req: Request, res: Response, body: unknown) => boolean;
+}
+export interface CacheInvalidateOptions {
+    patterns: string[] | ((req: Request, res: Response, body: unknown) => string[]);
+    shouldInvalidate?: (req: Request, res: Response, body: unknown) => boolean;
+    onInvalidate?: (req: Request, res: Response, body: unknown, patterns: string[]) => MaybePromise<void>;
+}
+export interface CreateRouteCacheOptions {
+    store: CacheStore;
+    logger?: CacheLogger;
+    defaultTtlSeconds?: number;
+}
+export declare function createRouteCache(options: CreateRouteCacheOptions): {
+    check(checkOptions?: CacheCheckOptions): RequestHandler;
+    capture(captureOptions?: CacheCaptureOptions): RequestHandler;
+    invalidate(invalidateOptions: CacheInvalidateOptions): RequestHandler;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number | undefined): Promise<void>;
+    deleteByPatterns(patterns: string[]): Promise<void>;
+};
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    setex?(key: string, ttlSeconds: number, value: string): Promise<unknown>;
+    set?(key: string, value: string, mode: "EX", ttlSeconds: number): Promise<unknown>;
+    keys?(pattern: string): Promise<string[]>;
+    scan?(cursor: string, tokenOne: "MATCH", pattern: string, tokenTwo: "COUNT", count: number): Promise<[string, string[]]>;
+    del(...keys: string[]): Promise<number>;
+}
+export interface CreateRedisStoreOptions {
+    client: RedisLikeClient;
+    defaultTtlSeconds?: number;
+    logger?: CacheLogger;
+    scanCount?: number;
+    deserialize?: <T>(value: string) => T;
+    serialize?: (value: unknown) => string;
+}
+export declare function createRedisStore(options: CreateRedisStoreOptions): CacheStore;
+export interface CreateMemoryStoreOptions {
+    defaultTtlSeconds?: number;
+}
+export declare function createMemoryStore(options?: CreateMemoryStoreOptions): CacheStore;
+export {};

package/dist/index.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouteCache = createRouteCache;
+exports.createRedisStore = createRedisStore;
+exports.createMemoryStore = createMemoryStore;
+const ROUTE_CACHE_CONTEXT_KEY = "__routeCache";
+function getCacheContext(res) {
+    return res.locals?.[ROUTE_CACHE_CONTEXT_KEY];
+}
+function setCacheContext(res, context) {
+    res.locals[ROUTE_CACHE_CONTEXT_KEY] = context;
+}
+function normalizeHeaderValue(value) {
+    if (Array.isArray(value)) {
+        return value.join(",");
+    }
+    return value ?? "";
+}
+function escapeForRegex(input) {
+    return input.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function wildcardToRegExp(pattern) {
+    return new RegExp("^" + pattern.split("*").map(escapeForRegex).join(".*") + "$");
+}
+function buildCacheKey(req, varyHeaders = []) {
+    const suffix = varyHeaders
+        .map((headerName) => {
+        const normalized = headerName.toLowerCase();
+        const headerValue = normalizeHeaderValue(req.headers[normalized]);
+        return `${normalized}=${headerValue}`;
+    })
+        .filter((entry) => !entry.endsWith("="))
+        .join("&");
+    if (!suffix) {
+        return req.originalUrl;
+    }
+    const separator = req.originalUrl.includes("?") ? "&" : "?";
+    return `${req.originalUrl}${separator}${suffix}`;
+}
+function isSuccessfulStatus(statusCode) {
+    return statusCode >= 200 && statusCode < 300;
+}
+async function deletePatterns(store, patterns, logger) {
+    if (patterns.length === 0) {
+        return;
+    }
+    try {
+        await store.deleteByPatterns(patterns);
+    }
+    catch (error) {
+        logger?.error?.("Failed to invalidate cache patterns", error);
+    }
+}
+function createRouteCache(options) {
+    const { defaultTtlSeconds, logger, store } = options;
+    return {
+        check(checkOptions = {}) {
+            const { hitHeader = "x-cache", key, shouldBypass, varyHeaders = [], } = checkOptions;
+            return async (req, res, next) => {
+                if (shouldBypass?.(req)) {
+                    return next();
+                }
+                const cacheKey = typeof key === "function"
+                    ? key(req)
+                    : key ?? buildCacheKey(req, varyHeaders);
+                setCacheContext(res, { key: cacheKey });
+                try {
+                    const cachedBody = await store.get(cacheKey);
+                    if (cachedBody !== null) {
+                        if (hitHeader) {
+                            res.setHeader(hitHeader, "HIT");
+                        }
+                        res.json(cachedBody);
+                        return;
+                    }
+                    if (hitHeader) {
+                        res.setHeader(hitHeader, "MISS");
+                    }
+                    next();
+                }
+                catch (error) {
+                    logger?.error?.("Failed to read from cache store", error);
+                    next();
+                }
+            };
+        },
+        capture(captureOptions = {}) {
+            const { shouldCache, ttlSeconds } = captureOptions;
+            return (req, res, next) => {
+                const originalJson = res.json.bind(res);
+                res.json = ((body) => {
+                    const context = getCacheContext(res);
+                    if (context &&
+                        isSuccessfulStatus(res.statusCode) &&
+                        (shouldCache?.(req, res, body) ?? true)) {
+                        const resolvedTtl = typeof ttlSeconds === "function"
+                            ? ttlSeconds(req, res, body)
+                            : ttlSeconds ?? defaultTtlSeconds;
+                        store
+                            .set(context.key, body, {
+                            ttlSeconds: resolvedTtl,
+                        })
+                            .catch((error) => logger?.error?.("Failed to write response into cache store", error));
+                    }
+                    return originalJson(body);
+                });
+                next();
+            };
+        },
+        invalidate(invalidateOptions) {
+            const { onInvalidate, patterns, shouldInvalidate } = invalidateOptions;
+            return (req, res, next) => {
+                const originalJson = res.json.bind(res);
+                res.json = ((body) => {
+                    const resolvedPatterns = typeof patterns === "function"
+                        ? patterns(req, res, body)
+                        : patterns;
+                    if (isSuccessfulStatus(res.statusCode) &&
+                        (shouldInvalidate?.(req, res, body) ?? true)) {
+                        Promise.resolve(onInvalidate?.(req, res, body, resolvedPatterns))
+                            .then(() => deletePatterns(store, resolvedPatterns, logger))
+                            .catch((error) => logger?.error?.("Failed while running cache invalidation hook", error));
+                    }
+                    return originalJson(body);
+                });
+                next();
+            };
+        },
+        async get(key) {
+            return store.get(key);
+        },
+        async set(key, value, ttlSeconds = defaultTtlSeconds) {
+            await store.set(key, value, { ttlSeconds });
+        },
+        async deleteByPatterns(patterns) {
+            await deletePatterns(store, patterns, logger);
+        },
+    };
+}
+async function collectKeysForPattern(client, pattern, scanCount) {
+    if (client.scan) {
+        let cursor = "0";
+        const matchedKeys = new Set();
+        do {
+            const [nextCursor, keys] = await client.scan(cursor, "MATCH", pattern, "COUNT", scanCount);
+            cursor = nextCursor;
+            keys.forEach((key) => matchedKeys.add(key));
+        } while (cursor !== "0");
+        return [...matchedKeys];
+    }
+    if (client.keys) {
+        return client.keys(pattern);
+    }
+    throw new Error("Redis client must provide either scan() or keys() for pattern invalidation.");
+}
+function createRedisStore(options) {
+    const { client, defaultTtlSeconds = 60, deserialize = JSON.parse, logger, scanCount = 200, serialize = JSON.stringify, } = options;
+    return {
+        async get(key) {
+            const rawValue = await client.get(key);
+            return rawValue ? deserialize(rawValue) : null;
+        },
+        async set(key, value, setOptions) {
+            const ttlSeconds = setOptions?.ttlSeconds ?? defaultTtlSeconds;
+            const payload = serialize(value);
+            if (client.setex) {
+                await client.setex(key, ttlSeconds, payload);
+                return;
+            }
+            if (client.set) {
+                await client.set(key, payload, "EX", ttlSeconds);
+                return;
+            }
+            throw new Error("Redis client must provide either setex() or set(..., 'EX', ttl).");
+        },
+        async deleteByPatterns(patterns) {
+            const matchedKeys = await Promise.all(patterns.map((pattern) => collectKeysForPattern(client, pattern, scanCount)));
+            const uniqueKeys = [...new Set(matchedKeys.flat())];
+            if (uniqueKeys.length === 0) {
+                return 0;
+            }
+            const deletedCount = await client.del(...uniqueKeys);
+            logger?.info?.("Deleted cache keys", {
+                deletedCount,
+                patternCount: patterns.length,
+            });
+            return deletedCount;
+        },
+    };
+}
+function createMemoryStore(options = {}) {
+    const { defaultTtlSeconds = 60 } = options;
+    const entries = new Map();
+    return {
+        async get(key) {
+            const entry = entries.get(key);
+            if (!entry) {
+                return null;
+            }
+            if (Date.now() > entry.expiresAt) {
+                entries.delete(key);
+                return null;
+            }
+            return entry.value;
+        },
+        async set(key, value, setOptions) {
+            const ttlSeconds = setOptions?.ttlSeconds ?? defaultTtlSeconds;
+            entries.set(key, {
+                expiresAt: Date.now() + ttlSeconds * 1000,
+                value,
+            });
+        },
+        async deleteByPatterns(patterns) {
+            const matchers = patterns.map(wildcardToRegExp);
+            let deletedCount = 0;
+            for (const key of entries.keys()) {
+                if (matchers.some((matcher) => matcher.test(key))) {
+                    entries.delete(key);
+                    deletedCount += 1;
+                }
+            }
+            return deletedCount;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@heinhtet37/express-route-cache",
+    "version": "0.1.0",
+    "description": "Reusable Express route caching middleware for Node.js and TypeScript services.",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "require": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "express",
+        "cache",
+        "middleware",
+        "redis",
+        "typescript"
+    ],
+    "license": "MIT",
+    "peerDependencies": {
+        "express": "^4.21.0 || ^5.0.0"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.0",
+        "typescript": "^5.7.3"
+    }
+}