layercache 1.0.0

package/dist/index.js

@@ -0,0 +1,622 @@
+// src/CacheStack.ts
+import { randomUUID } from "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();
+  }
+};
+
+// src/stampede/StampedeGuard.ts
+import { Mutex } from "async-mutex";
+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 = 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/invalidation/RedisInvalidationBus.ts
+var RedisInvalidationBus = class {
+  channel;
+  publisher;
+  subscriber;
+  constructor(options) {
+    this.publisher = options.publisher;
+    this.subscriber = options.subscriber ?? options.publisher.duplicate();
+    this.channel = options.channel ?? "cachestack:invalidation";
+  }
+  async subscribe(handler) {
+    const listener = async (_channel, payload) => {
+      const message = JSON.parse(payload);
+      await handler(message);
+    };
+    this.subscriber.on("message", listener);
+    await this.subscriber.subscribe(this.channel);
+    return async () => {
+      this.subscriber.off("message", listener);
+      await this.subscriber.unsubscribe(this.channel);
+    };
+  }
+  async publish(message) {
+    await this.publisher.publish(this.channel, JSON.stringify(message));
+  }
+};
+
+// src/invalidation/RedisTagIndex.ts
+var RedisTagIndex = class {
+  client;
+  prefix;
+  scanCount;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "cachestack:tag-index";
+    this.scanCount = options.scanCount ?? 100;
+  }
+  async touch(key) {
+    await this.client.sadd(this.knownKeysKey(), key);
+  }
+  async track(key, tags) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.sadd(this.knownKeysKey(), key);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    pipeline.del(keyTagsKey);
+    if (tags.length > 0) {
+      pipeline.sadd(keyTagsKey, ...tags);
+      for (const tag of new Set(tags)) {
+        pipeline.sadd(this.tagKeysKey(tag), key);
+      }
+    }
+    await pipeline.exec();
+  }
+  async remove(key) {
+    const keyTagsKey = this.keyTagsKey(key);
+    const existingTags = await this.client.smembers(keyTagsKey);
+    const pipeline = this.client.pipeline();
+    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.del(keyTagsKey);
+    for (const tag of existingTags) {
+      pipeline.srem(this.tagKeysKey(tag), key);
+    }
+    await pipeline.exec();
+  }
+  async keysForTag(tag) {
+    return this.client.smembers(this.tagKeysKey(tag));
+  }
+  async matchPattern(pattern) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.sscan(
+        this.knownKeysKey(),
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        this.scanCount
+      );
+      cursor = nextCursor;
+      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+    } while (cursor !== "0");
+    return matches;
+  }
+  async clear() {
+    const indexKeys = await this.scanIndexKeys();
+    if (indexKeys.length === 0) {
+      return;
+    }
+    await this.client.del(...indexKeys);
+  }
+  async scanIndexKeys() {
+    const matches = [];
+    let cursor = "0";
+    const pattern = `${this.prefix}:*`;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys);
+    } while (cursor !== "0");
+    return matches;
+  }
+  knownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  keyTagsKey(key) {
+    return `${this.prefix}:key:${encodeURIComponent(key)}`;
+  }
+  tagKeysKey(tag) {
+    return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
+  }
+};
+
+// src/layers/MemoryLayer.ts
+var MemoryLayer = class {
+  name;
+  defaultTtl;
+  isLocal = true;
+  maxSize;
+  entries = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.name = options.name ?? "memory";
+    this.defaultTtl = options.ttl;
+    this.maxSize = options.maxSize ?? 1e3;
+  }
+  async get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (this.isExpired(entry)) {
+      this.entries.delete(key);
+      return null;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+  async set(key, value, ttl = this.defaultTtl) {
+    this.entries.delete(key);
+    this.entries.set(key, {
+      value,
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null
+    });
+    while (this.entries.size > this.maxSize) {
+      const oldestKey = this.entries.keys().next().value;
+      if (!oldestKey) {
+        break;
+      }
+      this.entries.delete(oldestKey);
+    }
+  }
+  async delete(key) {
+    this.entries.delete(key);
+  }
+  async deleteMany(keys) {
+    for (const key of keys) {
+      this.entries.delete(key);
+    }
+  }
+  async clear() {
+    this.entries.clear();
+  }
+  async keys() {
+    this.pruneExpired();
+    return [...this.entries.keys()];
+  }
+  pruneExpired() {
+    for (const [key, entry] of this.entries.entries()) {
+      if (this.isExpired(entry)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+  isExpired(entry) {
+    return entry.expiresAt !== null && entry.expiresAt <= Date.now();
+  }
+};
+
+// src/serialization/JsonSerializer.ts
+var JsonSerializer = class {
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  deserialize(payload) {
+    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
+    return JSON.parse(normalized);
+  }
+};
+
+// src/layers/RedisLayer.ts
+var RedisLayer = class {
+  name;
+  defaultTtl;
+  isLocal = false;
+  client;
+  serializer;
+  prefix;
+  allowUnprefixedClear;
+  scanCount;
+  constructor(options) {
+    this.client = options.client;
+    this.defaultTtl = options.ttl;
+    this.name = options.name ?? "redis";
+    this.serializer = options.serializer ?? new JsonSerializer();
+    this.prefix = options.prefix ?? "";
+    this.allowUnprefixedClear = options.allowUnprefixedClear ?? false;
+    this.scanCount = options.scanCount ?? 100;
+  }
+  async get(key) {
+    const payload = await this.client.getBuffer(this.withPrefix(key));
+    if (payload === null) {
+      return null;
+    }
+    return this.serializer.deserialize(payload);
+  }
+  async set(key, value, ttl = this.defaultTtl) {
+    const payload = this.serializer.serialize(value);
+    const normalizedKey = this.withPrefix(key);
+    if (ttl && ttl > 0) {
+      await this.client.set(normalizedKey, payload, "EX", ttl);
+      return;
+    }
+    await this.client.set(normalizedKey, payload);
+  }
+  async delete(key) {
+    await this.client.del(this.withPrefix(key));
+  }
+  async deleteMany(keys) {
+    if (keys.length === 0) {
+      return;
+    }
+    await this.client.del(...keys.map((key) => this.withPrefix(key)));
+  }
+  async clear() {
+    if (!this.prefix && !this.allowUnprefixedClear) {
+      throw new Error("RedisLayer.clear() requires a prefix or allowUnprefixedClear=true to avoid deleting unrelated keys.");
+    }
+    const keys = await this.keys();
+    if (keys.length > 0) {
+      await this.deleteMany(keys);
+    }
+  }
+  async keys() {
+    const pattern = `${this.prefix}*`;
+    const keys = await this.scanKeys(pattern);
+    if (!this.prefix) {
+      return keys;
+    }
+    return keys.map((key) => key.slice(this.prefix.length));
+  }
+  async scanKeys(pattern) {
+    const matches = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      matches.push(...keys);
+    } while (cursor !== "0");
+    return matches;
+  }
+  withPrefix(key) {
+    return `${this.prefix}${key}`;
+  }
+};
+
+// src/serialization/MsgpackSerializer.ts
+import { decode, encode } from "@msgpack/msgpack";
+var MsgpackSerializer = class {
+  serialize(value) {
+    return Buffer.from(encode(value));
+  }
+  deserialize(payload) {
+    const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    return decode(normalized);
+  }
+};
+export {
+  CacheStack,
+  JsonSerializer,
+  MemoryLayer,
+  MsgpackSerializer,
+  PatternMatcher,
+  RedisInvalidationBus,
+  RedisLayer,
+  RedisTagIndex,
+  StampedeGuard,
+  TagIndex
+};

package/examples/express-api/index.ts

@@ -0,0 +1,27 @@
+import express from 'express'
+import Redis from 'ioredis'
+import { CacheStack, MemoryLayer, RedisLayer } from '../../src'
+
+const redis = new Redis(process.env.REDIS_URL)
+const cache = new CacheStack([
+  new MemoryLayer({ ttl: 30, maxSize: 5_000 }),
+  new RedisLayer({ client: redis, ttl: 300 })
+])
+
+const app = express()
+
+app.get('/users/:id', async (req, res) => {
+  const user = await cache.get(`user:${req.params.id}`, async () => {
+    return {
+      id: Number(req.params.id),
+      name: `User ${req.params.id}`,
+      source: 'db'
+    }
+  }, {
+    tags: ['user', `user:${req.params.id}`]
+  })
+
+  res.json(user)
+})
+
+app.listen(3000)

package/examples/nestjs-module/app.module.ts

@@ -0,0 +1,18 @@
+import { Module } from '@nestjs/common'
+import Redis from 'ioredis'
+import { MemoryLayer, RedisLayer } from '../../src'
+import { CacheStackModule } from '../../packages/nestjs/src'
+
+const redis = new Redis(process.env.REDIS_URL)
+
+@Module({
+  imports: [
+    CacheStackModule.forRoot({
+      layers: [
+        new MemoryLayer({ ttl: 20 }),
+        new RedisLayer({ client: redis, ttl: 300 })
+      ]
+    })
+  ]
+})
+export class AppModule {}

package/examples/nextjs-api-routes/route.ts

@@ -0,0 +1,19 @@
+import Redis from 'ioredis'
+import { CacheStack, MemoryLayer, RedisLayer } from '../../src'
+
+const redis = new Redis(process.env.REDIS_URL)
+const cache = new CacheStack([
+  new MemoryLayer({ ttl: 15 }),
+  new RedisLayer({ client: redis, ttl: 120 })
+])
+
+export async function GET(_request: Request, context: { params: { id: string } }): Promise<Response> {
+  const data = await cache.get(`user:${context.params.id}`, async () => {
+    return {
+      id: Number(context.params.id),
+      cachedAt: new Date().toISOString()
+    }
+  })
+
+  return Response.json(data)
+}