layercache 1.0.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "layercache",
+  "version": "1.0.0",
+  "description": "Unified multi-layer caching for Node.js with memory, Redis, stampede prevention, and invalidation helpers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "packages/nestjs/dist",
+    "examples",
+    "benchmarks"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "workspaces": [
+    "packages/nestjs"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "build:nestjs": "npm --workspace @cachestack/nestjs run build",
+    "build:all": "npm run build && npm run build:nestjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench:latency": "tsx benchmarks/latency.ts",
+    "bench:stampede": "tsx benchmarks/stampede.ts"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.0.0",
+    "async-mutex": "^0.4.1"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5.0.0"
+  },
+  "optionalDependencies": {
+    "ioredis": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.0",
+    "@nestjs/core": "^11.1.0",
+    "@types/node": "^22.15.2",
+    "ioredis": "^5.6.1",
+    "ioredis-mock": "^8.13.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3",
+    "vitest": "^1.6.1"
+  }
+}

package/packages/nestjs/dist/index.cjs

@@ -0,0 +1,571 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CACHE_STACK: () => CACHE_STACK,
+  CacheStackModule: () => CacheStackModule,
+  InjectCacheStack: () => InjectCacheStack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/constants.ts
+var CACHE_STACK = /* @__PURE__ */ Symbol("CACHE_STACK");
+
+// src/module.ts
+var import_common = require("@nestjs/common");
+
+// ../../src/CacheStack.ts
+var import_node_crypto = require("crypto");
+
+// ../../src/invalidation/PatternMatcher.ts
+var PatternMatcher = class {
+  static matches(pattern, value) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+    return regex.test(value);
+  }
+};
+
+// ../../src/invalidation/TagIndex.ts
+var TagIndex = class {
+  tagToKeys = /* @__PURE__ */ new Map();
+  keyToTags = /* @__PURE__ */ new Map();
+  knownKeys = /* @__PURE__ */ new Set();
+  async touch(key) {
+    this.knownKeys.add(key);
+  }
+  async track(key, tags) {
+    this.knownKeys.add(key);
+    if (tags.length === 0) {
+      return;
+    }
+    const existingTags = this.keyToTags.get(key);
+    if (existingTags) {
+      for (const tag of existingTags) {
+        this.tagToKeys.get(tag)?.delete(key);
+      }
+    }
+    const tagSet = new Set(tags);
+    this.keyToTags.set(key, tagSet);
+    for (const tag of tagSet) {
+      const keys = this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set();
+      keys.add(key);
+      this.tagToKeys.set(tag, keys);
+    }
+  }
+  async remove(key) {
+    this.knownKeys.delete(key);
+    const tags = this.keyToTags.get(key);
+    if (!tags) {
+      return;
+    }
+    for (const tag of tags) {
+      const keys = this.tagToKeys.get(tag);
+      if (!keys) {
+        continue;
+      }
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.tagToKeys.delete(tag);
+      }
+    }
+    this.keyToTags.delete(key);
+  }
+  async keysForTag(tag) {
+    return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
+  }
+  async matchPattern(pattern) {
+    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+  }
+  async clear() {
+    this.tagToKeys.clear();
+    this.keyToTags.clear();
+    this.knownKeys.clear();
+  }
+};
+
+// ../../node_modules/async-mutex/index.mjs
+var E_TIMEOUT = new Error("timeout while waiting for mutex to become available");
+var E_ALREADY_LOCKED = new Error("mutex already locked");
+var E_CANCELED = new Error("request for lock canceled");
+var __awaiter$2 = function(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+};
+var Semaphore = class {
+  constructor(_value, _cancelError = E_CANCELED) {
+    this._value = _value;
+    this._cancelError = _cancelError;
+    this._weightedQueues = [];
+    this._weightedWaiters = [];
+  }
+  acquire(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    return new Promise((resolve, reject) => {
+      if (!this._weightedQueues[weight - 1])
+        this._weightedQueues[weight - 1] = [];
+      this._weightedQueues[weight - 1].push({ resolve, reject });
+      this._dispatch();
+    });
+  }
+  runExclusive(callback, weight = 1) {
+    return __awaiter$2(this, void 0, void 0, function* () {
+      const [value, release] = yield this.acquire(weight);
+      try {
+        return yield callback(value);
+      } finally {
+        release();
+      }
+    });
+  }
+  waitForUnlock(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    return new Promise((resolve) => {
+      if (!this._weightedWaiters[weight - 1])
+        this._weightedWaiters[weight - 1] = [];
+      this._weightedWaiters[weight - 1].push(resolve);
+      this._dispatch();
+    });
+  }
+  isLocked() {
+    return this._value <= 0;
+  }
+  getValue() {
+    return this._value;
+  }
+  setValue(value) {
+    this._value = value;
+    this._dispatch();
+  }
+  release(weight = 1) {
+    if (weight <= 0)
+      throw new Error(`invalid weight ${weight}: must be positive`);
+    this._value += weight;
+    this._dispatch();
+  }
+  cancel() {
+    this._weightedQueues.forEach((queue) => queue.forEach((entry) => entry.reject(this._cancelError)));
+    this._weightedQueues = [];
+  }
+  _dispatch() {
+    var _a;
+    for (let weight = this._value; weight > 0; weight--) {
+      const queueEntry = (_a = this._weightedQueues[weight - 1]) === null || _a === void 0 ? void 0 : _a.shift();
+      if (!queueEntry)
+        continue;
+      const previousValue = this._value;
+      const previousWeight = weight;
+      this._value -= weight;
+      weight = this._value + 1;
+      queueEntry.resolve([previousValue, this._newReleaser(previousWeight)]);
+    }
+    this._drainUnlockWaiters();
+  }
+  _newReleaser(weight) {
+    let called = false;
+    return () => {
+      if (called)
+        return;
+      called = true;
+      this.release(weight);
+    };
+  }
+  _drainUnlockWaiters() {
+    for (let weight = this._value; weight > 0; weight--) {
+      if (!this._weightedWaiters[weight - 1])
+        continue;
+      this._weightedWaiters[weight - 1].forEach((waiter) => waiter());
+      this._weightedWaiters[weight - 1] = [];
+    }
+  }
+};
+var __awaiter$1 = function(thisArg, _arguments, P, generator) {
+  function adopt(value) {
+    return value instanceof P ? value : new P(function(resolve) {
+      resolve(value);
+    });
+  }
+  return new (P || (P = Promise))(function(resolve, reject) {
+    function fulfilled(value) {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function rejected(value) {
+      try {
+        step(generator["throw"](value));
+      } catch (e) {
+        reject(e);
+      }
+    }
+    function step(result) {
+      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    }
+    step((generator = generator.apply(thisArg, _arguments || [])).next());
+  });
+};
+var Mutex = class {
+  constructor(cancelError) {
+    this._semaphore = new Semaphore(1, cancelError);
+  }
+  acquire() {
+    return __awaiter$1(this, void 0, void 0, function* () {
+      const [, releaser] = yield this._semaphore.acquire();
+      return releaser;
+    });
+  }
+  runExclusive(callback) {
+    return this._semaphore.runExclusive(() => callback());
+  }
+  isLocked() {
+    return this._semaphore.isLocked();
+  }
+  waitForUnlock() {
+    return this._semaphore.waitForUnlock();
+  }
+  release() {
+    if (this._semaphore.isLocked())
+      this._semaphore.release();
+  }
+  cancel() {
+    return this._semaphore.cancel();
+  }
+};
+
+// ../../src/stampede/StampedeGuard.ts
+var StampedeGuard = class {
+  mutexes = /* @__PURE__ */ new Map();
+  async execute(key, task) {
+    const mutex = this.getMutex(key);
+    try {
+      return await mutex.runExclusive(task);
+    } finally {
+      if (!mutex.isLocked()) {
+        this.mutexes.delete(key);
+      }
+    }
+  }
+  getMutex(key) {
+    let mutex = this.mutexes.get(key);
+    if (!mutex) {
+      mutex = new Mutex();
+      this.mutexes.set(key, mutex);
+    }
+    return mutex;
+  }
+};
+
+// ../../src/CacheStack.ts
+var EMPTY_METRICS = () => ({
+  hits: 0,
+  misses: 0,
+  fetches: 0,
+  sets: 0,
+  deletes: 0,
+  backfills: 0,
+  invalidations: 0
+});
+var DebugLogger = class {
+  enabled;
+  constructor(enabled) {
+    this.enabled = enabled;
+  }
+  debug(message, context) {
+    if (!this.enabled) {
+      return;
+    }
+    const suffix = context ? ` ${JSON.stringify(context)}` : "";
+    console.debug(`[cachestack] ${message}${suffix}`);
+  }
+};
+var CacheStack = class {
+  constructor(layers, options = {}) {
+    this.layers = layers;
+    this.options = options;
+    if (layers.length === 0) {
+      throw new Error("CacheStack requires at least one cache layer.");
+    }
+    const debugEnv = process.env.DEBUG?.split(",").includes("cachestack:debug") ?? false;
+    this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
+    this.tagIndex = options.tagIndex ?? new TagIndex();
+    this.startup = this.initialize();
+  }
+  layers;
+  options;
+  stampedeGuard = new StampedeGuard();
+  metrics = EMPTY_METRICS();
+  instanceId = (0, import_node_crypto.randomUUID)();
+  startup;
+  unsubscribeInvalidation;
+  logger;
+  tagIndex;
+  async get(key, fetcher, options) {
+    await this.startup;
+    const hit = await this.getFromLayers(key, options);
+    if (hit.found) {
+      this.metrics.hits += 1;
+      return hit.value;
+    }
+    this.metrics.misses += 1;
+    if (!fetcher) {
+      return null;
+    }
+    const runFetch = async () => {
+      const secondHit = await this.getFromLayers(key, options);
+      if (secondHit.found) {
+        this.metrics.hits += 1;
+        return secondHit.value;
+      }
+      this.metrics.fetches += 1;
+      const fetched = await fetcher();
+      if (fetched === null || fetched === void 0) {
+        return null;
+      }
+      await this.set(key, fetched, options);
+      return fetched;
+    };
+    if (this.options.stampedePrevention === false) {
+      return runFetch();
+    }
+    return this.stampedeGuard.execute(key, runFetch);
+  }
+  async set(key, value, options) {
+    await this.startup;
+    await this.setAcrossLayers(key, value, options);
+    if (options?.tags) {
+      await this.tagIndex.track(key, options.tags);
+    } else {
+      await this.tagIndex.touch(key);
+    }
+    this.metrics.sets += 1;
+    this.logger.debug("set", { key, tags: options?.tags });
+    if (this.options.publishSetInvalidation !== false) {
+      await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "write" });
+    }
+  }
+  async delete(key) {
+    await this.startup;
+    await this.deleteKeys([key]);
+    await this.publishInvalidation({ scope: "key", keys: [key], sourceId: this.instanceId, operation: "delete" });
+  }
+  async clear() {
+    await this.startup;
+    await Promise.all(this.layers.map((layer) => layer.clear()));
+    await this.tagIndex.clear();
+    this.metrics.invalidations += 1;
+    this.logger.debug("clear");
+    await this.publishInvalidation({ scope: "clear", sourceId: this.instanceId, operation: "clear" });
+  }
+  async mget(entries) {
+    return Promise.all(entries.map((entry) => this.get(entry.key, entry.fetch, entry.options)));
+  }
+  async mset(entries) {
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.options)));
+  }
+  async invalidateByTag(tag) {
+    await this.startup;
+    const keys = await this.tagIndex.keysForTag(tag);
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
+  async invalidateByPattern(pattern) {
+    await this.startup;
+    const keys = await this.tagIndex.matchPattern(pattern);
+    await this.deleteKeys(keys);
+    await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
+  }
+  getMetrics() {
+    return { ...this.metrics };
+  }
+  resetMetrics() {
+    Object.assign(this.metrics, EMPTY_METRICS());
+  }
+  async disconnect() {
+    await this.startup;
+    await this.unsubscribeInvalidation?.();
+  }
+  async initialize() {
+    if (!this.options.invalidationBus) {
+      return;
+    }
+    this.unsubscribeInvalidation = await this.options.invalidationBus.subscribe(async (message) => {
+      await this.handleInvalidationMessage(message);
+    });
+  }
+  async getFromLayers(key, options) {
+    for (let index = 0; index < this.layers.length; index += 1) {
+      const layer = this.layers[index];
+      const value = await layer.get(key);
+      if (value === null) {
+        continue;
+      }
+      await this.tagIndex.touch(key);
+      await this.backfill(key, value, index - 1, options);
+      this.logger.debug("hit", { key, layer: layer.name });
+      return { found: true, value };
+    }
+    await this.tagIndex.remove(key);
+    this.logger.debug("miss", { key });
+    return { found: false, value: null };
+  }
+  async backfill(key, value, upToIndex, options) {
+    if (upToIndex < 0) {
+      return;
+    }
+    for (let index = 0; index <= upToIndex; index += 1) {
+      const layer = this.layers[index];
+      await layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl));
+      this.metrics.backfills += 1;
+      this.logger.debug("backfill", { key, layer: layer.name });
+    }
+  }
+  async setAcrossLayers(key, value, options) {
+    await Promise.all(
+      this.layers.map((layer) => layer.set(key, value, this.resolveTtl(layer.name, layer.defaultTtl, options?.ttl)))
+    );
+  }
+  resolveTtl(layerName, fallbackTtl, ttlOverride) {
+    if (ttlOverride === void 0) {
+      return fallbackTtl;
+    }
+    if (typeof ttlOverride === "number") {
+      return ttlOverride;
+    }
+    return ttlOverride[layerName] ?? fallbackTtl;
+  }
+  async deleteKeys(keys) {
+    if (keys.length === 0) {
+      return;
+    }
+    await Promise.all(
+      this.layers.map(async (layer) => {
+        if (layer.deleteMany) {
+          await layer.deleteMany(keys);
+          return;
+        }
+        await Promise.all(keys.map((key) => layer.delete(key)));
+      })
+    );
+    for (const key of keys) {
+      await this.tagIndex.remove(key);
+    }
+    this.metrics.deletes += keys.length;
+    this.metrics.invalidations += 1;
+    this.logger.debug("delete", { keys });
+  }
+  async publishInvalidation(message) {
+    if (!this.options.invalidationBus) {
+      return;
+    }
+    await this.options.invalidationBus.publish(message);
+  }
+  async handleInvalidationMessage(message) {
+    if (message.sourceId === this.instanceId) {
+      return;
+    }
+    const localLayers = this.layers.filter((layer) => layer.isLocal);
+    if (localLayers.length === 0) {
+      return;
+    }
+    if (message.scope === "clear") {
+      await Promise.all(localLayers.map((layer) => layer.clear()));
+      await this.tagIndex.clear();
+      return;
+    }
+    const keys = message.keys ?? [];
+    await Promise.all(
+      localLayers.map(async (layer) => {
+        if (layer.deleteMany) {
+          await layer.deleteMany(keys);
+          return;
+        }
+        await Promise.all(keys.map((key) => layer.delete(key)));
+      })
+    );
+    if (message.operation !== "write") {
+      for (const key of keys) {
+        await this.tagIndex.remove(key);
+      }
+    }
+  }
+};
+
+// src/module.ts
+var InjectCacheStack = () => (0, import_common.Inject)(CACHE_STACK);
+var CacheStackModule = class {
+  static forRoot(options) {
+    const provider = {
+      provide: CACHE_STACK,
+      useFactory: () => new CacheStack(options.layers, options.bridgeOptions)
+    };
+    return {
+      global: true,
+      module: CacheStackModule,
+      providers: [provider],
+      exports: [provider]
+    };
+  }
+};
+CacheStackModule = __decorateClass([
+  (0, import_common.Global)(),
+  (0, import_common.Module)({})
+], CacheStackModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CACHE_STACK,
+  CacheStackModule,
+  InjectCacheStack
+});

package/packages/nestjs/dist/index.d.cts

@@ -0,0 +1,55 @@
+import { DynamicModule } from '@nestjs/common';
+
+declare const CACHE_STACK: unique symbol;
+
+interface CacheLayer {
+    readonly name: string;
+    readonly defaultTtl?: number;
+    readonly isLocal?: boolean;
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    deleteMany?(keys: string[]): Promise<void>;
+    keys?(): Promise<string[]>;
+}
+interface CacheLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+}
+interface CacheTagIndex {
+    touch(key: string): Promise<void>;
+    track(key: string, tags: string[]): Promise<void>;
+    remove(key: string): Promise<void>;
+    keysForTag(tag: string): Promise<string[]>;
+    matchPattern(pattern: string): Promise<string[]>;
+    clear(): Promise<void>;
+}
+interface InvalidationMessage {
+    scope: 'key' | 'keys' | 'clear';
+    sourceId: string;
+    keys?: string[];
+    operation?: 'write' | 'delete' | 'invalidate' | 'clear';
+}
+interface InvalidationBus {
+    subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
+    publish(message: InvalidationMessage): Promise<void>;
+}
+interface CacheStackOptions {
+    logger?: CacheLogger | boolean;
+    metrics?: boolean;
+    stampedePrevention?: boolean;
+    invalidationBus?: InvalidationBus;
+    tagIndex?: CacheTagIndex;
+    publishSetInvalidation?: boolean;
+}
+
+interface CacheStackModuleOptions {
+    layers: CacheLayer[];
+    bridgeOptions?: CacheStackOptions;
+}
+declare const InjectCacheStack: () => ParameterDecorator & PropertyDecorator;
+declare class CacheStackModule {
+    static forRoot(options: CacheStackModuleOptions): DynamicModule;
+}
+
+export { CACHE_STACK, CacheStackModule, type CacheStackModuleOptions, InjectCacheStack };