@heinhtet37/express-route-cache 0.1.0 → 0.2.0

package/README.md

@@ -1,31 +1,138 @@
-# @mvs/express-route-cache
+# @heinhtet37/express-route-cache
 
-Reusable Express middleware factories for route-level response caching and cache invalidation.
+Express route caching helpers for low-level control and practical resource-level DX.
 
-This package is intended to be published independently from this repo. You can:
+The original API still works:
 
-1. `cd express-route-cache`
-2. `npm install`
-3. `npm publish`
+- `createRouteCache`
+- `createRedisStore`
+- `createMemoryStore`
+- `check`
+- `capture`
+- `invalidate`
+
+This version adds:
+
+- `resource()` bundles for list/detail/variant routes
+- optional cache key `namespace`
+- optional tag-based invalidation
+- deterministic resource keys
+- lightweight TTL parsing like `"5m"` and `"1h"`
+- lightweight lifecycle events
 
 ## Install
 
 ```bash
-npm install @mvs/express-route-cache
+npm install @heinhtet37/express-route-cache
+```
+
+## Quick Start
+
+```ts
+import { createRedisStore, createRouteCache } from "@heinhtet37/express-route-cache";
+import redis from "./redis";
+
+const cache = createRouteCache({
+  store: createRedisStore({
+    client: redis,
+    defaultTtlSeconds: "5m",
+  }),
+  namespace: "mm-smart-pos",
+});
+
+const rolesCache = cache.resource({
+  basePath: "/api/v1/roles",
+  idParam: "id",
+  ttlSeconds: "5m",
+  variants: ["names"],
+});
+
+router.get("/", ...rolesCache.list(), async (_req, res) => {
+  res.json(await roleService.getAll());
+});
+
+router.get("/names", ...rolesCache.variant("names"), async (_req, res) => {
+  res.json(await roleService.getAllNames());
+});
+
+router.get("/:id", ...rolesCache.detail(), async (req, res) => {
+  res.json(await roleService.getById(req.params.id));
+});
+
+router.post("/", rolesCache.invalidateOnWrite(), async (req, res) => {
+  res.json(await roleService.create(req.body));
+});
+
+router.patch("/:id", rolesCache.invalidateOnWrite(), async (req, res) => {
+  res.json(await roleService.update(req.params.id, req.body));
+});
+
+router.delete("/:id", rolesCache.invalidateOnWrite(), async (req, res) => {
+  res.json(await roleService.remove(req.params.id));
+});
 ```
 
-## What it provides
+## Resource API
+
+`resource()` is the high-level DX API for common REST-style routes.
+
+```ts
+const usersCache = cache.resource({
+  basePath: "/api/users",
+  idParam: "id",
+  ttlSeconds: 300,
+  variants: ["names", "summary"],
+});
+```
 
-- `createRouteCache()` to create middleware factories
-- `createRedisStore()` for Redis-backed caching
-- `createMemoryStore()` for local development and tests
+### Read Bundles
 
-## Basic usage
+`list()` returns `[check, capture]` for the collection route.
 
 ```ts
-import { createRedisStore, createRouteCache } from "@mvs/express-route-cache";
-import redis from "./redis";
+router.get("/", ...usersCache.list(), handler);
+```
+
+`detail()` returns `[check, capture]` for `/:id`.
+
+```ts
+router.get("/:id", ...usersCache.detail(), handler);
+```
+
+`variant(name)` returns `[check, capture]` for custom read routes like `/names`.
+
+```ts
+router.get("/names", ...usersCache.variant("names"), handler);
+```
+
+### Write Invalidation
+
+`invalidateOnWrite()` invalidates the resource collection, query variants, configured variants, and the matching detail route when the write route has an `id` param.
+
+```ts
+router.post("/", usersCache.invalidateOnWrite(), handler);
+router.patch("/:id", usersCache.invalidateOnWrite(), handler);
+router.delete("/:id", usersCache.invalidateOnWrite(), handler);
+```
+
+You can extend invalidation with extra patterns or tags:
+
+```ts
+router.patch(
+  "/:id",
+  usersCache.invalidateOnWrite({
+    additionalPatterns: ["/api/dashboard*", "/api/summary*"],
+    additionalTags: ["dashboard"],
+  }),
+  handler
+);
+```
+
+## Low-Level API
 
+The original low-level API remains available for custom routes.
+
+```ts
 const cache = createRouteCache({
   store: createRedisStore({
     client: redis,
@@ -33,13 +140,15 @@ const cache = createRouteCache({
   }),
 });
 
-export const checkUsersCache = cache.check({
+const checkUsersCache = cache.check({
   varyHeaders: ["accept-language"],
 });
 
-export const setUsersCache = cache.capture();
+const captureUsersCache = cache.capture({
+  ttlSeconds: "5m",
+});
 
-export const invalidateUsersCache = cache.invalidate({
+const invalidateUsersCache = cache.invalidate({
   patterns: (req) => [
     "/api/users",
     "/api/users?*",
@@ -48,83 +157,138 @@ export const invalidateUsersCache = cache.invalidate({
 });
 ```
 
-Then use it in your routes:
+## Namespace Support
+
+`namespace` prefixes internal cache keys and tag identifiers without forcing consumers to rewrite their patterns.
 
 ```ts
-router.get(
-  "/users",
-  checkUsersCache,
-  setUsersCache,
-  async (req, res) => {
-    res.json(await userService.getAll());
-  }
-);
+const cache = createRouteCache({
+  store,
+  namespace: "mm-smart-pos",
+});
 
-router.patch(
-  "/users/:id",
-  invalidateUsersCache,
-  async (req, res) => {
-    res.json(await userService.update(req.params.id, req.body));
-  }
-);
+await cache.set("/roles", { ok: true }, 300);
+await cache.deleteByPatterns(["/roles"]);
+```
+
+With a namespace configured, `"/roles"` becomes an internal key like `"mm-smart-pos::/roles"`, but callers can still use the simple public key.
+
+## Tag Support
+
+Tag invalidation is optional.
+
+- `createMemoryStore()` supports tags out of the box.
+- `createRedisStore()` supports tags when the Redis client provides `sadd`, `srem`, `smembers`, and `expire`.
+- Pattern invalidation continues to work either way.
+
+Low-level tag example:
+
+```ts
+const checkUsersCache = cache.check({ key: "/api/users" });
+
+const captureUsersCache = cache.capture({
+  tags: ["users", "admin-dashboard"],
+});
+
+const invalidateUsersByTag = cache.invalidate({
+  tags: ["users"],
+});
 ```
 
-## API
+Resource bundles automatically attach resource-level tags, and `invalidateOnWrite()` uses both patterns and tags when available.
 
-### `createRouteCache({ store, logger, defaultTtlSeconds })`
+## TTL Values
 
-Returns:
+TTL values can be numbers or simple strings:
 
-- `check(options)`
-- `capture(options)`
-- `invalidate(options)`
-- `get(key)`
-- `set(key, value, ttlSeconds?)`
-- `deleteByPatterns(patterns)`
+- `300`
+- `"300"`
+- `"5m"`
+- `"1h"`
+- `"1d"`
 
-### `check(options)`
+This works with:
 
-Options:
+- `defaultTtlSeconds`
+- `capture({ ttlSeconds })`
+- `resource({ ttlSeconds })`
+- `set(key, value, ttl)`
 
-- `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`
+## Events
 
-### `capture(options)`
+You can subscribe to lightweight lifecycle events:
 
-Options:
+- `hit`
+- `miss`
+- `set`
+- `invalidate`
+- `error`
 
-- `ttlSeconds`: number or `(req, res, body) => number | undefined`
-- `shouldCache`: predicate to decide whether a response body should be cached
+```ts
+const cache = createRouteCache({
+  store,
+  events: {
+    hit: ({ key }) => console.log("cache hit", key),
+    miss: ({ key }) => console.log("cache miss", key),
+    set: ({ key, ttlSeconds }) => console.log("cache set", key, ttlSeconds),
+    invalidate: ({ patterns, tags }) => console.log("cache invalidate", patterns, tags),
+    error: ({ operation, error }) => console.error("cache error", operation, error),
+  },
+});
+```
 
-### `invalidate(options)`
+## Redis Store
 
-Options:
+```ts
+import Redis from "ioredis";
+import { createRedisStore } from "@heinhtet37/express-route-cache";
 
-- `patterns`: array or `(req, res, body) => string[]`
-- `shouldInvalidate`: predicate to control invalidation
-- `onInvalidate`: async hook for audit logging or side effects
+const client = new Redis();
 
-### `createRedisStore({ client, defaultTtlSeconds, logger, scanCount })`
+const store = createRedisStore({
+  client,
+  defaultTtlSeconds: "5m",
+});
+```
 
-The Redis client should expose:
+For pattern invalidation, the Redis client must provide:
 
 - `get`
 - `del`
 - one of `scan` or `keys`
 - one of `setex` or `set(..., "EX", ttl)`
 
-### `createMemoryStore({ defaultTtlSeconds })`
+For tag invalidation, the Redis client should also provide:
+
+- `sadd`
+- `srem`
+- `smembers`
+- `expire`
+
+## Memory Store
+
+```ts
+import { createMemoryStore } from "@heinhtet37/express-route-cache";
+
+const store = createMemoryStore({
+  defaultTtlSeconds: "1m",
+});
+```
+
+The memory store is useful for local development and tests. It also supports tag invalidation.
+
+## Notes And Tradeoffs
 
-Simple in-memory cache store for testing or local usage.
+- The old API is still supported and unchanged for normal usage.
+- The new `resource()` API is intentionally opinionated around list/detail/variant patterns.
+- Resource invalidation automatically covers configured variants only. If you use extra variant names, either include them in `variants` or add `additionalPatterns`.
+- Tag invalidation is additive. It does not replace pattern invalidation.
+- Redis tag invalidation uses extra metadata keys to track tag membership. This keeps the public API simple at the cost of slightly more write work per cached entry.
 
-## Publish
+## Tests
 
 ```bash
-cd express-route-cache
-npm install
-npm publish
+npm test
 ```
 
-Because `publishConfig.access` is already set to `public`, npm will publish it as a public package.
+That runs a package build and then the Node test suite in `tests/`.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Request, RequestHandler, Response } from "express";
+export type TtlValue = number | string;
 export interface CacheStore {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, value: T, options?: {
@@ -6,11 +7,48 @@ export interface CacheStore {
     }): Promise<void>;
     deleteByPatterns(patterns: string[]): Promise<number | void>;
 }
+export interface TaggableCacheStore extends CacheStore {
+    addTags?(key: string, tags: string[], options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    deleteByTags?(tags: 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;
 }
+export interface CacheEvents {
+    hit?(event: {
+        key: string;
+        req: Request;
+    }): void;
+    miss?(event: {
+        key: string;
+        req: Request;
+    }): void;
+    set?(event: {
+        key: string;
+        ttlSeconds?: number;
+        req: Request;
+        body: unknown;
+        tags?: string[];
+    }): void;
+    invalidate?(event: {
+        req?: Request;
+        patterns?: string[];
+        tags?: string[];
+        deletedCount?: number;
+    }): void;
+    error?(event: {
+        req?: Request;
+        key?: string;
+        patterns?: string[];
+        tags?: string[];
+        operation: "get" | "set" | "invalidate" | "hook" | "tag";
+        error: unknown;
+    }): void;
+}
 type ValueResolver<T> = T | ((req: Request, res: Response, body?: unknown) => T);
 type MaybePromise<T> = T | Promise<T>;
 export interface CacheCheckOptions {
@@ -20,26 +58,68 @@ export interface CacheCheckOptions {
     hitHeader?: string | false;
 }
 export interface CacheCaptureOptions {
-    ttlSeconds?: ValueResolver<number | undefined>;
+    ttlSeconds?: ValueResolver<TtlValue | undefined>;
     shouldCache?: (req: Request, res: Response, body: unknown) => boolean;
+    tags?: ValueResolver<string[] | undefined>;
 }
 export interface CacheInvalidateOptions {
-    patterns: string[] | ((req: Request, res: Response, body: unknown) => string[]);
+    patterns?: string[] | ((req: Request, res: Response, body: unknown) => string[]);
+    tags?: string[] | ((req: Request, res: Response, body: unknown) => string[]);
+    shouldInvalidate?: (req: Request, res: Response, body: unknown) => boolean;
+    onInvalidate?: (req: Request, res: Response, body: unknown, details: {
+        patterns: string[];
+        tags: string[];
+    }) => MaybePromise<void>;
+}
+export interface ResourceReadOptions {
+    ttlSeconds?: TtlValue;
+    varyHeaders?: string[];
+    shouldBypass?: (req: Request) => boolean;
+    hitHeader?: string | false;
+    shouldCache?: (req: Request, res: Response, body: unknown) => boolean;
+    tags?: ValueResolver<string[] | undefined>;
+}
+export interface ResourceInvalidateOptions {
+    additionalPatterns?: string[] | ((req: Request, res: Response, body: unknown) => string[]);
+    additionalTags?: 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>;
+    onInvalidate?: (req: Request, res: Response, body: unknown, details: {
+        patterns: string[];
+        tags: string[];
+    }) => MaybePromise<void>;
+}
+export interface RouteCacheResourceOptions {
+    basePath: string;
+    idParam?: string;
+    ttlSeconds?: TtlValue;
+    variants?: string[];
+    varyHeaders?: string[];
+    hitHeader?: string | false;
+    shouldBypass?: (req: Request) => boolean;
+    shouldCache?: (req: Request, res: Response, body: unknown) => boolean;
+}
+export interface RouteCacheResource {
+    list(options?: ResourceReadOptions): [RequestHandler, RequestHandler];
+    detail(options?: ResourceReadOptions): [RequestHandler, RequestHandler];
+    variant(name: string, options?: ResourceReadOptions): [RequestHandler, RequestHandler];
+    invalidateOnWrite(options?: ResourceInvalidateOptions): RequestHandler;
 }
 export interface CreateRouteCacheOptions {
     store: CacheStore;
     logger?: CacheLogger;
-    defaultTtlSeconds?: number;
+    defaultTtlSeconds?: TtlValue;
+    namespace?: string;
+    events?: CacheEvents;
 }
 export declare function createRouteCache(options: CreateRouteCacheOptions): {
     check(checkOptions?: CacheCheckOptions): RequestHandler;
     capture(captureOptions?: CacheCaptureOptions): RequestHandler;
     invalidate(invalidateOptions: CacheInvalidateOptions): RequestHandler;
+    resource(resourceOptions: RouteCacheResourceOptions): RouteCacheResource;
     get<T>(key: string): Promise<T | null>;
-    set<T>(key: string, value: T, ttlSeconds?: number | undefined): Promise<void>;
+    set<T>(key: string, value: T, ttlSeconds?: TtlValue | undefined): Promise<void>;
     deleteByPatterns(patterns: string[]): Promise<void>;
+    deleteByTags(tags: string[]): Promise<void>;
 };
 export interface RedisLikeClient {
     get(key: string): Promise<string | null>;
@@ -48,18 +128,22 @@ export interface RedisLikeClient {
     keys?(pattern: string): Promise<string[]>;
     scan?(cursor: string, tokenOne: "MATCH", pattern: string, tokenTwo: "COUNT", count: number): Promise<[string, string[]]>;
     del(...keys: string[]): Promise<number>;
+    sadd?(key: string, ...members: string[]): Promise<number>;
+    srem?(key: string, ...members: string[]): Promise<number>;
+    smembers?(key: string): Promise<string[]>;
+    expire?(key: string, seconds: number): Promise<number>;
 }
 export interface CreateRedisStoreOptions {
     client: RedisLikeClient;
-    defaultTtlSeconds?: number;
+    defaultTtlSeconds?: TtlValue;
     logger?: CacheLogger;
     scanCount?: number;
     deserialize?: <T>(value: string) => T;
     serialize?: (value: unknown) => string;
 }
-export declare function createRedisStore(options: CreateRedisStoreOptions): CacheStore;
+export declare function createRedisStore(options: CreateRedisStoreOptions): TaggableCacheStore;
 export interface CreateMemoryStoreOptions {
-    defaultTtlSeconds?: number;
+    defaultTtlSeconds?: TtlValue;
 }
-export declare function createMemoryStore(options?: CreateMemoryStoreOptions): CacheStore;
+export declare function createMemoryStore(options?: CreateMemoryStoreOptions): TaggableCacheStore;
 export {};

package/dist/index.js

@@ -4,6 +4,8 @@ exports.createRouteCache = createRouteCache;
 exports.createRedisStore = createRedisStore;
 exports.createMemoryStore = createMemoryStore;
 const ROUTE_CACHE_CONTEXT_KEY = "__routeCache";
+const REDIS_TAG_PREFIX = "__route_cache_tag__:";
+const REDIS_KEY_TAG_PREFIX = "__route_cache_key_tags__:";
 function getCacheContext(res) {
     return res.locals?.[ROUTE_CACHE_CONTEXT_KEY];
 }
@@ -22,6 +24,55 @@ function escapeForRegex(input) {
 function wildcardToRegExp(pattern) {
     return new RegExp("^" + pattern.split("*").map(escapeForRegex).join(".*") + "$");
 }
+function normalizePath(input) {
+    if (!input) {
+        return "/";
+    }
+    if (input === "/") {
+        return "/";
+    }
+    return input.endsWith("/") ? input.slice(0, -1) : input;
+}
+function stableSerialize(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableSerialize(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries
+            .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableSerialize(entryValue)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function buildDeterministicQuerySuffix(query) {
+    if (!query ||
+        typeof query !== "object" ||
+        Array.isArray(query) ||
+        Object.keys(query).length === 0) {
+        return "";
+    }
+    return `?${stableSerialize(query)}`;
+}
+function buildHeaderSuffix(req, varyHeaders = []) {
+    if (varyHeaders.length === 0) {
+        return "";
+    }
+    const serializedHeaders = varyHeaders
+        .map((headerName) => headerName.toLowerCase())
+        .sort((left, right) => left.localeCompare(right))
+        .map((headerName) => [
+        headerName,
+        normalizeHeaderValue(req.headers[headerName]),
+    ])
+        .filter(([, value]) => value !== "");
+    if (serializedHeaders.length === 0) {
+        return "";
+    }
+    return `#headers=${stableSerialize(Object.fromEntries(serializedHeaders))}`;
+}
 function buildCacheKey(req, varyHeaders = []) {
     const suffix = varyHeaders
         .map((headerName) => {
@@ -37,32 +88,260 @@ function buildCacheKey(req, varyHeaders = []) {
     const separator = req.originalUrl.includes("?") ? "&" : "?";
     return `${req.originalUrl}${separator}${suffix}`;
 }
+function buildResourceKey(kind, req, options) {
+    const { basePath, detailId, variantName, varyHeaders = [] } = options;
+    let routePath = normalizePath(basePath);
+    let routeLabel = `resource:${kind}`;
+    if (kind === "detail") {
+        routePath = `${routePath}/${detailId ?? ""}`;
+    }
+    if (kind === "variant") {
+        routePath = `${routePath}/${variantName ?? ""}`;
+        routeLabel = `${routeLabel}:${variantName ?? "unknown"}`;
+    }
+    return `${routeLabel}:${routePath}${buildDeterministicQuerySuffix(req.query)}${buildHeaderSuffix(req, varyHeaders)}`;
+}
+function parseTtl(ttlSeconds) {
+    if (ttlSeconds === undefined) {
+        return undefined;
+    }
+    if (typeof ttlSeconds === "number") {
+        if (!Number.isFinite(ttlSeconds) || ttlSeconds < 0) {
+            throw new Error("TTL must be a finite non-negative number.");
+        }
+        return ttlSeconds;
+    }
+    const normalized = ttlSeconds.trim().toLowerCase();
+    if (/^\d+$/.test(normalized)) {
+        return Number(normalized);
+    }
+    const matched = normalized.match(/^(\d+)(s|m|h|d)$/);
+    if (!matched) {
+        throw new Error(`Invalid TTL value "${ttlSeconds}". Use numbers or strings like "5m" and "1h".`);
+    }
+    const amount = Number(matched[1]);
+    const unit = matched[2];
+    switch (unit) {
+        case "s":
+            return amount;
+        case "m":
+            return amount * 60;
+        case "h":
+            return amount * 60 * 60;
+        case "d":
+            return amount * 60 * 60 * 24;
+        default:
+            return amount;
+    }
+}
 function isSuccessfulStatus(statusCode) {
     return statusCode >= 200 && statusCode < 300;
 }
+function getRouteParamValue(value) {
+    if (Array.isArray(value)) {
+        return value[0] ?? "";
+    }
+    return value ?? "";
+}
+function normalizeNamespace(namespace) {
+    return namespace?.trim() ? namespace.trim() : undefined;
+}
+function hasNamespacePrefix(value, namespace) {
+    return Boolean(namespace) && value.startsWith(`${namespace}::`);
+}
+function applyNamespace(value, namespace) {
+    if (!namespace || hasNamespacePrefix(value, namespace)) {
+        return value;
+    }
+    return `${namespace}::${value}`;
+}
+function normalizePatterns(patterns, namespace) {
+    return patterns.map((pattern) => applyNamespace(pattern, namespace));
+}
+function normalizeTags(tags, namespace) {
+    return tags.map((tag) => applyNamespace(`tag:${tag}`, namespace));
+}
+function uniqueValues(values) {
+    return [...new Set(values.filter((value) => value.length > 0))];
+}
+function safeEmitError(events, logger, event) {
+    try {
+        events?.error?.(event);
+    }
+    catch (hookError) {
+        logger?.error?.("Cache event hook failed", hookError);
+    }
+}
+function safeEmit(emitter, logger, eventName, payload, events) {
+    if (!emitter) {
+        return;
+    }
+    try {
+        emitter(payload);
+    }
+    catch (error) {
+        logger?.error?.(`Cache ${eventName} hook failed`, error);
+        safeEmitError(events, logger, {
+            operation: "hook",
+            error,
+        });
+    }
+}
 async function deletePatterns(store, patterns, logger) {
     if (patterns.length === 0) {
-        return;
+        return 0;
     }
     try {
-        await store.deleteByPatterns(patterns);
+        const deletedCount = await store.deleteByPatterns(patterns);
+        return deletedCount ?? 0;
     }
     catch (error) {
         logger?.error?.("Failed to invalidate cache patterns", error);
+        throw error;
     }
 }
-function createRouteCache(options) {
-    const { defaultTtlSeconds, logger, store } = options;
+async function deleteTags(store, tags, logger) {
+    const tagStore = store;
+    if (tags.length === 0) {
+        return 0;
+    }
+    if (!tagStore.deleteByTags) {
+        logger?.warn?.("Cache store does not support tag invalidation. Falling back to pattern invalidation only.");
+        return 0;
+    }
+    try {
+        const deletedCount = await tagStore.deleteByTags(tags);
+        return deletedCount ?? 0;
+    }
+    catch (error) {
+        logger?.error?.("Failed to invalidate cache tags", error);
+        throw error;
+    }
+}
+async function deleteCacheEntries(store, options, logger) {
+    const patterns = uniqueValues(options.patterns ?? []);
+    const tags = uniqueValues(options.tags ?? []);
+    const patternDeletes = await deletePatterns(store, patterns, logger);
+    const tagDeletes = await deleteTags(store, tags, logger);
     return {
+        deletedCount: patternDeletes + tagDeletes,
+        patterns,
+        tags,
+    };
+}
+function buildResourceBaseTag(basePath) {
+    return `resource:${normalizePath(basePath)}`;
+}
+function resolveResourceTags(basePath, kind, input) {
+    const resourceBaseTag = buildResourceBaseTag(basePath);
+    if (kind === "list") {
+        return [resourceBaseTag, `${resourceBaseTag}:list`];
+    }
+    if (kind === "detail") {
+        return [
+            resourceBaseTag,
+            `${resourceBaseTag}:detail:${input.detailId ?? ""}`,
+        ];
+    }
+    return [
+        resourceBaseTag,
+        `${resourceBaseTag}:variant:${input.variantName ?? "unknown"}`,
+    ];
+}
+function resolveMaybeValue(value, req, res, body) {
+    return typeof value === "function"
+        ? value(req, res, body)
+        : value;
+}
+function buildResourceInvalidationPatterns(options, req) {
+    const normalizedBasePath = normalizePath(options.basePath);
+    const patterns = [
+        `resource:list:${normalizedBasePath}`,
+        `resource:list:${normalizedBasePath}?*`,
+        `resource:list:${normalizedBasePath}#*`,
+        `resource:list:${normalizedBasePath}?*#*`,
+    ];
+    for (const variantName of options.variants) {
+        const variantPath = `${normalizedBasePath}/${variantName}`;
+        patterns.push(`resource:variant:${variantName}:${variantPath}`, `resource:variant:${variantName}:${variantPath}?*`, `resource:variant:${variantName}:${variantPath}#*`, `resource:variant:${variantName}:${variantPath}?*#*`);
+    }
+    const detailId = getRouteParamValue(req.params?.[options.idParam]);
+    if (detailId) {
+        const detailPath = `${normalizedBasePath}/${detailId}`;
+        patterns.push(`resource:detail:${detailPath}`, `resource:detail:${detailPath}?*`, `resource:detail:${detailPath}#*`, `resource:detail:${detailPath}?*#*`);
+    }
+    return uniqueValues(patterns);
+}
+function buildResourceInvalidationTags(options, req) {
+    const resourceBaseTag = buildResourceBaseTag(options.basePath);
+    const tags = [resourceBaseTag, `${resourceBaseTag}:list`];
+    for (const variantName of options.variants) {
+        tags.push(`${resourceBaseTag}:variant:${variantName}`);
+    }
+    const detailId = getRouteParamValue(req.params?.[options.idParam]);
+    if (detailId) {
+        tags.push(`${resourceBaseTag}:detail:${detailId}`);
+    }
+    return uniqueValues(tags);
+}
+function createRouteCache(options) {
+    const { defaultTtlSeconds, events, logger, namespace: inputNamespace, store, } = options;
+    const namespace = normalizeNamespace(inputNamespace);
+    function buildNamespacedKey(value) {
+        return applyNamespace(value, namespace);
+    }
+    function buildNamespacedPatterns(patterns) {
+        return normalizePatterns(patterns, namespace);
+    }
+    function buildNamespacedTags(tags) {
+        return normalizeTags(tags, namespace);
+    }
+    function resolveTtl(ttlValue, fallback) {
+        return parseTtl(ttlValue ?? fallback);
+    }
+    function resolveInvalidatePayload(invalidateOptions, req, res, body) {
+        const resolvedPatterns = uniqueValues(invalidateOptions.patterns
+            ? resolveMaybeValue(invalidateOptions.patterns, req, res, body)
+            : []);
+        const resolvedTags = uniqueValues(invalidateOptions.tags
+            ? resolveMaybeValue(invalidateOptions.tags, req, res, body)
+            : []);
+        return {
+            patterns: buildNamespacedPatterns(resolvedPatterns),
+            tags: buildNamespacedTags(resolvedTags),
+        };
+    }
+    function createReadBundle(keyBuilder, defaultReadOptions, defaultTagsBuilder) {
+        const readOptions = defaultReadOptions ?? {};
+        return [
+            api.check({
+                key: (req) => buildNamespacedKey(keyBuilder(req, readOptions.varyHeaders ?? [])),
+                shouldBypass: readOptions.shouldBypass,
+                hitHeader: readOptions.hitHeader ?? "x-cache",
+            }),
+            api.capture({
+                ttlSeconds: readOptions.ttlSeconds ?? defaultTtlSeconds,
+                shouldCache: readOptions.shouldCache,
+                tags: (req, res, body) => uniqueValues([
+                    ...defaultTagsBuilder(req),
+                    ...(readOptions.tags
+                        ? resolveMaybeValue(readOptions.tags, req, res, body) ?? []
+                        : []),
+                ]),
+            }),
+        ];
+    }
+    const api = {
         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"
+                const rawKey = typeof key === "function"
                     ? key(req)
                     : key ?? buildCacheKey(req, varyHeaders);
+                const cacheKey = buildNamespacedKey(rawKey);
                 setCacheContext(res, { key: cacheKey });
                 try {
                     const cachedBody = await store.get(cacheKey);
@@ -70,22 +349,30 @@ function createRouteCache(options) {
                         if (hitHeader) {
                             res.setHeader(hitHeader, "HIT");
                         }
+                        safeEmit(events?.hit, logger, "hit", { key: cacheKey, req }, events);
                         res.json(cachedBody);
                         return;
                     }
                     if (hitHeader) {
                         res.setHeader(hitHeader, "MISS");
                     }
+                    safeEmit(events?.miss, logger, "miss", { key: cacheKey, req }, events);
                     next();
                 }
                 catch (error) {
                     logger?.error?.("Failed to read from cache store", error);
+                    safeEmitError(events, logger, {
+                        req,
+                        key: cacheKey,
+                        operation: "get",
+                        error,
+                    });
                     next();
                 }
             };
         },
         capture(captureOptions = {}) {
-            const { shouldCache, ttlSeconds } = captureOptions;
+            const { shouldCache, tags, ttlSeconds } = captureOptions;
             return (req, res, next) => {
                 const originalJson = res.json.bind(res);
                 res.json = ((body) => {
@@ -93,14 +380,45 @@ function createRouteCache(options) {
                     if (context &&
                         isSuccessfulStatus(res.statusCode) &&
                         (shouldCache?.(req, res, body) ?? true)) {
-                        const resolvedTtl = typeof ttlSeconds === "function"
+                        const resolvedTtl = resolveTtl(typeof ttlSeconds === "function"
                             ? ttlSeconds(req, res, body)
-                            : ttlSeconds ?? defaultTtlSeconds;
-                        store
+                            : ttlSeconds, defaultTtlSeconds);
+                        const resolvedTags = uniqueValues(tags
+                            ? resolveMaybeValue(tags, req, res, body) ?? []
+                            : []);
+                        const normalizedTags = buildNamespacedTags(resolvedTags);
+                        void store
                             .set(context.key, body, {
                             ttlSeconds: resolvedTtl,
                         })
-                            .catch((error) => logger?.error?.("Failed to write response into cache store", error));
+                            .then(async () => {
+                            const tagStore = store;
+                            if (normalizedTags.length > 0 && tagStore.addTags) {
+                                await tagStore.addTags(context.key, normalizedTags, {
+                                    ttlSeconds: resolvedTtl,
+                                });
+                            }
+                            else if (normalizedTags.length > 0) {
+                                logger?.warn?.("Cache store does not support tag indexing. Tags were ignored.");
+                            }
+                            safeEmit(events?.set, logger, "set", {
+                                key: context.key,
+                                ttlSeconds: resolvedTtl,
+                                req,
+                                body,
+                                tags: normalizedTags,
+                            }, events);
+                        })
+                            .catch((error) => {
+                            logger?.error?.("Failed to write response into cache store", error);
+                            safeEmitError(events, logger, {
+                                req,
+                                key: context.key,
+                                tags: normalizedTags,
+                                operation: normalizedTags.length > 0 ? "tag" : "set",
+                                error,
+                            });
+                        });
                     }
                     return originalJson(body);
                 });
@@ -108,34 +426,137 @@ function createRouteCache(options) {
             };
         },
         invalidate(invalidateOptions) {
-            const { onInvalidate, patterns, shouldInvalidate } = invalidateOptions;
+            const { onInvalidate, 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;
+                    const resolvedInvalidation = resolveInvalidatePayload(invalidateOptions, req, res, body);
                     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));
+                        Promise.resolve(onInvalidate?.(req, res, body, {
+                            patterns: resolvedInvalidation.patterns,
+                            tags: resolvedInvalidation.tags,
+                        }))
+                            .then(() => deleteCacheEntries(store, resolvedInvalidation, logger))
+                            .then((result) => {
+                            safeEmit(events?.invalidate, logger, "invalidate", {
+                                req,
+                                patterns: result.patterns,
+                                tags: result.tags,
+                                deletedCount: result.deletedCount,
+                            }, events);
+                        })
+                            .catch((error) => {
+                            logger?.error?.("Failed while running cache invalidation hook", error);
+                            safeEmitError(events, logger, {
+                                req,
+                                patterns: resolvedInvalidation.patterns,
+                                tags: resolvedInvalidation.tags,
+                                operation: "invalidate",
+                                error,
+                            });
+                        });
                     }
                     return originalJson(body);
                 });
                 next();
             };
         },
+        resource(resourceOptions) {
+            const { basePath, hitHeader = "x-cache", idParam = "id", shouldBypass, shouldCache, ttlSeconds, variants = [], varyHeaders = [], } = resourceOptions;
+            function mergeReadOptions(readOptions) {
+                return {
+                    ttlSeconds: readOptions?.ttlSeconds ?? ttlSeconds,
+                    varyHeaders: readOptions?.varyHeaders ?? varyHeaders,
+                    shouldBypass: readOptions?.shouldBypass ?? shouldBypass,
+                    hitHeader: readOptions?.hitHeader ?? hitHeader,
+                    shouldCache: readOptions?.shouldCache ?? shouldCache,
+                    tags: readOptions?.tags,
+                };
+            }
+            return {
+                list(readOptions) {
+                    const mergedOptions = mergeReadOptions(readOptions);
+                    return createReadBundle((req, varyHeaderList) => buildResourceKey("list", req, {
+                        basePath,
+                        varyHeaders: varyHeaderList,
+                    }), mergedOptions, () => resolveResourceTags(basePath, "list", {}));
+                },
+                detail(readOptions) {
+                    const mergedOptions = mergeReadOptions(readOptions);
+                    return createReadBundle((req, varyHeaderList) => buildResourceKey("detail", req, {
+                        basePath,
+                        detailId: getRouteParamValue(req.params?.[idParam]),
+                        varyHeaders: varyHeaderList,
+                    }), mergedOptions, (req) => resolveResourceTags(basePath, "detail", {
+                        detailId: getRouteParamValue(req.params?.[idParam]),
+                    }));
+                },
+                variant(name, readOptions) {
+                    const mergedOptions = mergeReadOptions(readOptions);
+                    return createReadBundle((req, varyHeaderList) => buildResourceKey("variant", req, {
+                        basePath,
+                        variantName: name,
+                        varyHeaders: varyHeaderList,
+                    }), mergedOptions, () => resolveResourceTags(basePath, "variant", {
+                        variantName: name,
+                    }));
+                },
+                invalidateOnWrite(invalidateOptions = {}) {
+                    return api.invalidate({
+                        patterns: (req, res, body) => [
+                            ...buildResourceInvalidationPatterns({
+                                basePath,
+                                idParam,
+                                variants,
+                            }, req),
+                            ...(invalidateOptions.additionalPatterns
+                                ? resolveMaybeValue(invalidateOptions.additionalPatterns, req, res, body)
+                                : []),
+                        ],
+                        tags: (req, res, body) => [
+                            ...buildResourceInvalidationTags({
+                                basePath,
+                                idParam,
+                                variants,
+                            }, req),
+                            ...(invalidateOptions.additionalTags
+                                ? resolveMaybeValue(invalidateOptions.additionalTags, req, res, body)
+                                : []),
+                        ],
+                        shouldInvalidate: invalidateOptions.shouldInvalidate,
+                        onInvalidate: invalidateOptions.onInvalidate,
+                    });
+                },
+            };
+        },
         async get(key) {
-            return store.get(key);
+            return store.get(buildNamespacedKey(key));
         },
         async set(key, value, ttlSeconds = defaultTtlSeconds) {
-            await store.set(key, value, { ttlSeconds });
+            const resolvedTtl = resolveTtl(ttlSeconds, defaultTtlSeconds);
+            await store.set(buildNamespacedKey(key), value, {
+                ttlSeconds: resolvedTtl,
+            });
         },
         async deleteByPatterns(patterns) {
-            await deletePatterns(store, patterns, logger);
+            const result = await deleteCacheEntries(store, { patterns: buildNamespacedPatterns(patterns) }, logger);
+            safeEmit(events?.invalidate, logger, "invalidate", {
+                patterns: result.patterns,
+                tags: result.tags,
+                deletedCount: result.deletedCount,
+            }, events);
+        },
+        async deleteByTags(tags) {
+            const result = await deleteCacheEntries(store, { tags: buildNamespacedTags(tags) }, logger);
+            safeEmit(events?.invalidate, logger, "invalidate", {
+                patterns: result.patterns,
+                tags: result.tags,
+                deletedCount: result.deletedCount,
+            }, events);
         },
     };
+    return api;
 }
 async function collectKeysForPattern(client, pattern, scanCount) {
     if (client.scan) {
@@ -153,15 +574,40 @@ async function collectKeysForPattern(client, pattern, scanCount) {
     }
     throw new Error("Redis client must provide either scan() or keys() for pattern invalidation.");
 }
+function createRedisTagSetKey(tag) {
+    return `${REDIS_TAG_PREFIX}${tag}`;
+}
+function createRedisKeyTagSetKey(key) {
+    return `${REDIS_KEY_TAG_PREFIX}${key}`;
+}
+function hasRedisTagSupport(client) {
+    return Boolean(client.sadd && client.srem && client.smembers && client.expire);
+}
 function createRedisStore(options) {
     const { client, defaultTtlSeconds = 60, deserialize = JSON.parse, logger, scanCount = 200, serialize = JSON.stringify, } = options;
+    const resolvedDefaultTtl = parseTtl(defaultTtlSeconds) ?? 60;
+    async function cleanupRedisTagRefs(keys) {
+        if (!hasRedisTagSupport(client) || keys.length === 0) {
+            return;
+        }
+        for (const key of keys) {
+            const keyTagSetKey = createRedisKeyTagSetKey(key);
+            const tags = await client.smembers(keyTagSetKey);
+            if (tags.length > 0) {
+                for (const tag of tags) {
+                    await client.srem(createRedisTagSetKey(tag), key);
+                }
+            }
+            await client.del(keyTagSetKey);
+        }
+    }
     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 ttlSeconds = setOptions?.ttlSeconds ?? resolvedDefaultTtl;
             const payload = serialize(value);
             if (client.setex) {
                 await client.setex(key, ttlSeconds, payload);
@@ -179,6 +625,7 @@ function createRedisStore(options) {
             if (uniqueKeys.length === 0) {
                 return 0;
             }
+            await cleanupRedisTagRefs(uniqueKeys);
             const deletedCount = await client.del(...uniqueKeys);
             logger?.info?.("Deleted cache keys", {
                 deletedCount,
@@ -186,11 +633,69 @@ function createRedisStore(options) {
             });
             return deletedCount;
         },
+        async addTags(key, tags, addTagOptions) {
+            if (!hasRedisTagSupport(client) || tags.length === 0) {
+                return;
+            }
+            const ttlSeconds = addTagOptions?.ttlSeconds ?? resolvedDefaultTtl;
+            const keyTagSetKey = createRedisKeyTagSetKey(key);
+            await client.sadd(keyTagSetKey, ...tags);
+            await client.expire(keyTagSetKey, ttlSeconds);
+            for (const tag of tags) {
+                const tagSetKey = createRedisTagSetKey(tag);
+                await client.sadd(tagSetKey, key);
+                await client.expire(tagSetKey, ttlSeconds);
+            }
+        },
+        async deleteByTags(tags) {
+            if (!hasRedisTagSupport(client) || tags.length === 0) {
+                return 0;
+            }
+            const keys = new Set();
+            for (const tag of tags) {
+                const matchedKeys = await client.smembers(createRedisTagSetKey(tag));
+                matchedKeys.forEach((key) => keys.add(key));
+            }
+            const uniqueKeys = [...keys];
+            if (uniqueKeys.length === 0) {
+                return 0;
+            }
+            await cleanupRedisTagRefs(uniqueKeys);
+            const deletedCount = await client.del(...uniqueKeys);
+            for (const tag of tags) {
+                await client.del(createRedisTagSetKey(tag));
+            }
+            return deletedCount;
+        },
     };
 }
 function createMemoryStore(options = {}) {
     const { defaultTtlSeconds = 60 } = options;
+    const resolvedDefaultTtl = parseTtl(defaultTtlSeconds) ?? 60;
     const entries = new Map();
+    const tagIndex = new Map();
+    const keyTags = new Map();
+    function removeKeyFromTagIndexes(key) {
+        const tags = keyTags.get(key);
+        if (!tags) {
+            return;
+        }
+        for (const tag of tags) {
+            const keys = tagIndex.get(tag);
+            if (!keys) {
+                continue;
+            }
+            keys.delete(key);
+            if (keys.size === 0) {
+                tagIndex.delete(tag);
+            }
+        }
+        keyTags.delete(key);
+    }
+    function deleteKey(key) {
+        entries.delete(key);
+        removeKeyFromTagIndexes(key);
+    }
     return {
         async get(key) {
             const entry = entries.get(key);
@@ -198,13 +703,13 @@ function createMemoryStore(options = {}) {
                 return null;
             }
             if (Date.now() > entry.expiresAt) {
-                entries.delete(key);
+                deleteKey(key);
                 return null;
             }
             return entry.value;
         },
         async set(key, value, setOptions) {
-            const ttlSeconds = setOptions?.ttlSeconds ?? defaultTtlSeconds;
+            const ttlSeconds = setOptions?.ttlSeconds ?? resolvedDefaultTtl;
             entries.set(key, {
                 expiresAt: Date.now() + ttlSeconds * 1000,
                 value,
@@ -213,13 +718,40 @@ function createMemoryStore(options = {}) {
         async deleteByPatterns(patterns) {
             const matchers = patterns.map(wildcardToRegExp);
             let deletedCount = 0;
-            for (const key of entries.keys()) {
+            for (const key of [...entries.keys()]) {
                 if (matchers.some((matcher) => matcher.test(key))) {
-                    entries.delete(key);
+                    deleteKey(key);
                     deletedCount += 1;
                 }
             }
             return deletedCount;
         },
+        async addTags(key, tags) {
+            if (!entries.has(key) || tags.length === 0) {
+                return;
+            }
+            const nextTags = keyTags.get(key) ?? new Set();
+            for (const tag of tags) {
+                nextTags.add(tag);
+                const keysForTag = tagIndex.get(tag) ?? new Set();
+                keysForTag.add(key);
+                tagIndex.set(tag, keysForTag);
+            }
+            keyTags.set(key, nextTags);
+        },
+        async deleteByTags(tags) {
+            const keys = new Set();
+            for (const tag of tags) {
+                const taggedKeys = tagIndex.get(tag);
+                if (!taggedKeys) {
+                    continue;
+                }
+                taggedKeys.forEach((key) => keys.add(key));
+            }
+            for (const key of keys) {
+                deleteKey(key);
+            }
+            return keys.size;
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heinhtet37/express-route-cache",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Reusable Express route caching middleware for Node.js and TypeScript services.",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -19,6 +19,7 @@
     "scripts": {
         "build": "tsc -p tsconfig.json",
         "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+        "test": "npm run build && node --test tests/**/*.test.js",
         "prepublishOnly": "npm run clean && npm run build"
     },
     "publishConfig": {