@nixxie-cms/cache 1.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+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/dist/declarations/src/InMemoryCache.d.ts

@@ -0,0 +1,22 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core';
+import type { InMemoryCacheConfig } from "./types.js";
+export declare class InMemoryCache implements NixxieCacheService {
+    private store;
+    private tagIndex;
+    private config;
+    private accessOrder;
+    constructor(config: InMemoryCacheConfig);
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePattern(pattern: string): Promise<void>;
+    deleteByTag(tag: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+    private touch;
+    private evict;
+    private enforceLru;
+}
+//# sourceMappingURL=InMemoryCache.d.ts.map

package/dist/declarations/src/InMemoryCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryCache.d.ts","sourceRoot":"../../../src","sources":["InMemoryCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAe;AAQlD,qBAAa,aAAc,YAAW,kBAAkB;IACtD,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAAe;gBAEtB,MAAM,EAAE,mBAAmB;IAIjC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAWrD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC;IAQvF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,UAAU;CAOnB"}

package/dist/declarations/src/RedisCache.d.ts

@@ -0,0 +1,24 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core';
+import type { RedisCacheConfig } from "./types.js";
+export declare class RedisCache implements NixxieCacheService {
+    private client;
+    private prefix;
+    private config;
+    constructor(config: RedisCacheConfig);
+    private k;
+    private tagKey;
+    /** Reverse index: the set of tags a given key currently belongs to. */
+    private keyTagsKey;
+    /** Remove `key` from every tag set it currently belongs to and drop its reverse-index record. */
+    private clearTagsFor;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    deletePattern(pattern: string): Promise<void>;
+    deleteByTag(tag: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T>;
+    clear(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=RedisCache.d.ts.map

package/dist/declarations/src/RedisCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisCache.d.ts","sourceRoot":"../../../src","sources":["RedisCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAe;AAuB/C,qBAAa,UAAW,YAAW,kBAAkB;IACnD,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,gBAAgB;IAOpC,OAAO,CAAC,CAAC;IAIT,OAAO,CAAC,MAAM;IAId,uEAAuE;IACvE,OAAO,CAAC,UAAU;IAIlB,iGAAiG;YACnF,YAAY;IASpB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAUrD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC;IAQvF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,8 @@
+import type { CacheConfig } from "./types.js";
+import { InMemoryCache } from "./InMemoryCache.js";
+import { RedisCache } from "./RedisCache.js";
+export declare function createCache(config: CacheConfig): InMemoryCache | RedisCache;
+export { InMemoryCache, RedisCache };
+export type { CacheConfig, InMemoryCacheConfig, RedisCacheConfig } from "./types.js";
+export type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAe;AAC1C,OAAO,EAAE,aAAa,EAAE,2BAAuB;AAC/C,OAAO,EAAE,UAAU,EAAE,wBAAoB;AAEzC,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAW3E;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAA;AACpC,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAe;AACjF,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/declarations/src/types.d.ts

@@ -0,0 +1,22 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core';
+export type { NixxieCacheService, NixxieCacheSetOptions };
+export type InMemoryCacheConfig = {
+    store: 'memory';
+    /** Maximum number of entries (LRU eviction when exceeded). Default: 1000 */
+    max?: number;
+    /** Default TTL in milliseconds for entries without an explicit TTL. Omit for no expiry. */
+    ttl?: number;
+};
+export type RedisCacheConfig = {
+    store: 'redis';
+    /** Redis connection URL: redis://[:password@]host[:port][/db] */
+    url: string;
+    /** Key prefix — all cache keys are stored as `{prefix}:{key}`. Default: 'nixxie:cache' */
+    prefix?: string;
+    /** Default TTL in milliseconds. Omit for no expiry. */
+    ttl?: number;
+    /** TLS options passed to ioredis */
+    tls?: boolean;
+};
+export type CacheConfig = InMemoryCacheConfig | RedisCacheConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/declarations/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"../../../src","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAEjF,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAA;AAEzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,QAAQ,CAAA;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,OAAO,CAAA;IACd,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAA;IACX,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,GAAG,CAAC,EAAE,OAAO,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,gBAAgB,CAAA"}

package/dist/nixxie-cms-cache.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1jYWNoZS5janMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4vZGVjbGFyYXRpb25zL3NyYy9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

package/dist/nixxie-cms-cache.cjs.js

@@ -0,0 +1,226 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _defineProperty = require('@babel/runtime/helpers/defineProperty');
+
+class InMemoryCache {
+  constructor(config) {
+    _defineProperty(this, "store", new Map());
+    _defineProperty(this, "tagIndex", new Map());
+    _defineProperty(this, "accessOrder", []);
+    this.config = config;
+  }
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.evict(key);
+      return undefined;
+    }
+    this.touch(key);
+    return entry.value;
+  }
+  async set(key, value, options) {
+    var _ref, _options$ttl, _options$tags;
+    const ttl = (_ref = (_options$ttl = options === null || options === void 0 ? void 0 : options.ttl) !== null && _options$ttl !== void 0 ? _options$ttl : this.config.ttl) !== null && _ref !== void 0 ? _ref : null;
+    const tags = (_options$tags = options === null || options === void 0 ? void 0 : options.tags) !== null && _options$tags !== void 0 ? _options$tags : [];
+    this.evict(key);
+    this.store.set(key, {
+      value,
+      expiresAt: ttl !== null ? Date.now() + ttl : null,
+      tags
+    });
+    for (const tag of tags) {
+      var _this$tagIndex$get;
+      const set = (_this$tagIndex$get = this.tagIndex.get(tag)) !== null && _this$tagIndex$get !== void 0 ? _this$tagIndex$get : new Set();
+      set.add(key);
+      this.tagIndex.set(tag, set);
+    }
+    this.accessOrder.push(key);
+    this.enforceLru();
+  }
+  async delete(key) {
+    this.evict(key);
+  }
+  async deletePattern(pattern) {
+    // Escape all regex metacharacters first, then translate the glob wildcards `*` and `?`.
+    // Otherwise keys containing `.`, `(`, `[`, `+`, etc. would over-match or throw a SyntaxError.
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp('^' + escaped.replace(/\\\*/g, '.*').replace(/\\\?/g, '.') + '$');
+    for (const key of [...this.store.keys()]) {
+      if (regex.test(key)) this.evict(key);
+    }
+  }
+  async deleteByTag(tag) {
+    const keys = this.tagIndex.get(tag);
+    if (!keys) return;
+    for (const key of [...keys]) {
+      this.evict(key);
+    }
+    this.tagIndex.delete(tag);
+  }
+  async has(key) {
+    return (await this.get(key)) !== undefined;
+  }
+  async wrap(key, fn, options) {
+    const cached = await this.get(key);
+    if (cached !== undefined) return cached;
+    const value = await fn();
+    await this.set(key, value, options);
+    return value;
+  }
+  async clear() {
+    this.store.clear();
+    this.tagIndex.clear();
+    this.accessOrder = [];
+  }
+  async close() {
+    // Nothing to close
+  }
+  touch(key) {
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+    this.accessOrder.push(key);
+  }
+  evict(key) {
+    const entry = this.store.get(key);
+    if (!entry) return;
+    for (const tag of entry.tags) {
+      var _this$tagIndex$get2;
+      (_this$tagIndex$get2 = this.tagIndex.get(tag)) === null || _this$tagIndex$get2 === void 0 || _this$tagIndex$get2.delete(key);
+    }
+    this.store.delete(key);
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+  }
+  enforceLru() {
+    var _this$config$max;
+    const max = (_this$config$max = this.config.max) !== null && _this$config$max !== void 0 ? _this$config$max : 1000;
+    while (this.store.size > max && this.accessOrder.length > 0) {
+      const oldest = this.accessOrder[0];
+      this.evict(oldest);
+    }
+  }
+}
+
+function getRedis() {
+  try {
+    return require('ioredis');
+  } catch {
+    throw new Error('ioredis is not installed. Run: npm install ioredis');
+  }
+}
+class RedisCache {
+  constructor(config) {
+    var _config$prefix;
+    this.config = config;
+    this.prefix = (_config$prefix = config.prefix) !== null && _config$prefix !== void 0 ? _config$prefix : 'nixxie:cache';
+    const Redis = getRedis();
+    this.client = new Redis(config.url, config.tls ? {
+      tls: {}
+    } : {});
+  }
+  k(key) {
+    return `${this.prefix}:${key}`;
+  }
+  tagKey(tag) {
+    return `${this.prefix}:tag:${tag}`;
+  }
+
+  /** Reverse index: the set of tags a given key currently belongs to. */
+  keyTagsKey(key) {
+    return `${this.prefix}:keytags:${key}`;
+  }
+
+  /** Remove `key` from every tag set it currently belongs to and drop its reverse-index record. */
+  async clearTagsFor(key) {
+    const ktKey = this.keyTagsKey(key);
+    const tags = await this.client.smembers(ktKey);
+    if (tags.length) {
+      await Promise.all(tags.map(t => this.client.srem(this.tagKey(t), key)));
+      await this.client.del(ktKey);
+    }
+  }
+  async get(key) {
+    const raw = await this.client.get(this.k(key));
+    if (raw === null) return undefined;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  async set(key, value, options) {
+    var _options$ttl, _options$tags;
+    const serialized = JSON.stringify(value);
+    const ttlMs = (_options$ttl = options === null || options === void 0 ? void 0 : options.ttl) !== null && _options$ttl !== void 0 ? _options$ttl : this.config.ttl;
+    const rKey = this.k(key);
+    const newTags = (_options$tags = options === null || options === void 0 ? void 0 : options.tags) !== null && _options$tags !== void 0 ? _options$tags : [];
+
+    // Drop any tag associations from a previous value so overwriting with different tags
+    // doesn't leave the key in stale tag sets (which would cause incorrect deleteByTag).
+    await this.clearTagsFor(key);
+    if (ttlMs !== undefined) {
+      await this.client.setex(rKey, Math.ceil(ttlMs / 1000), serialized);
+    } else {
+      await this.client.set(rKey, serialized);
+    }
+    if (newTags.length) {
+      await Promise.all(newTags.map(tag => this.client.sadd(this.tagKey(tag), key)));
+      await this.client.sadd(this.keyTagsKey(key), ...newTags);
+    }
+  }
+  async delete(key) {
+    await this.client.del(this.k(key));
+    await this.clearTagsFor(key);
+  }
+  async deletePattern(pattern) {
+    const keys = await this.client.keys(this.k(pattern));
+    if (keys.length) await this.client.del(...keys);
+  }
+  async deleteByTag(tag) {
+    const members = await this.client.smembers(this.tagKey(tag));
+    if (members.length) {
+      await this.client.del(...members.map(k => this.k(k)));
+      // Remove the deleted keys from all of their (possibly other) tag sets too.
+      await Promise.all(members.map(k => this.clearTagsFor(k)));
+    }
+    await this.client.del(this.tagKey(tag));
+  }
+  async has(key) {
+    return (await this.client.exists(this.k(key))) === 1;
+  }
+  async wrap(key, fn, options) {
+    const cached = await this.get(key);
+    if (cached !== undefined) return cached;
+    const value = await fn();
+    await this.set(key, value, options);
+    return value;
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.prefix}:*`);
+    if (keys.length) await this.client.del(...keys);
+  }
+  async close() {
+    await this.client.quit();
+  }
+}
+
+function createCache(config) {
+  switch (config.store) {
+    case 'memory':
+      return new InMemoryCache(config);
+    case 'redis':
+      return new RedisCache(config);
+    default:
+      {
+        const exhaustive = config;
+        throw new Error(`Unknown cache store: ${exhaustive.store}`);
+      }
+  }
+}
+
+exports.InMemoryCache = InMemoryCache;
+exports.RedisCache = RedisCache;
+exports.createCache = createCache;

package/dist/nixxie-cms-cache.esm.js

@@ -0,0 +1,220 @@
+import _defineProperty from '@babel/runtime/helpers/esm/defineProperty';
+
+class InMemoryCache {
+  constructor(config) {
+    _defineProperty(this, "store", new Map());
+    _defineProperty(this, "tagIndex", new Map());
+    _defineProperty(this, "accessOrder", []);
+    this.config = config;
+  }
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.evict(key);
+      return undefined;
+    }
+    this.touch(key);
+    return entry.value;
+  }
+  async set(key, value, options) {
+    var _ref, _options$ttl, _options$tags;
+    const ttl = (_ref = (_options$ttl = options === null || options === void 0 ? void 0 : options.ttl) !== null && _options$ttl !== void 0 ? _options$ttl : this.config.ttl) !== null && _ref !== void 0 ? _ref : null;
+    const tags = (_options$tags = options === null || options === void 0 ? void 0 : options.tags) !== null && _options$tags !== void 0 ? _options$tags : [];
+    this.evict(key);
+    this.store.set(key, {
+      value,
+      expiresAt: ttl !== null ? Date.now() + ttl : null,
+      tags
+    });
+    for (const tag of tags) {
+      var _this$tagIndex$get;
+      const set = (_this$tagIndex$get = this.tagIndex.get(tag)) !== null && _this$tagIndex$get !== void 0 ? _this$tagIndex$get : new Set();
+      set.add(key);
+      this.tagIndex.set(tag, set);
+    }
+    this.accessOrder.push(key);
+    this.enforceLru();
+  }
+  async delete(key) {
+    this.evict(key);
+  }
+  async deletePattern(pattern) {
+    // Escape all regex metacharacters first, then translate the glob wildcards `*` and `?`.
+    // Otherwise keys containing `.`, `(`, `[`, `+`, etc. would over-match or throw a SyntaxError.
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp('^' + escaped.replace(/\\\*/g, '.*').replace(/\\\?/g, '.') + '$');
+    for (const key of [...this.store.keys()]) {
+      if (regex.test(key)) this.evict(key);
+    }
+  }
+  async deleteByTag(tag) {
+    const keys = this.tagIndex.get(tag);
+    if (!keys) return;
+    for (const key of [...keys]) {
+      this.evict(key);
+    }
+    this.tagIndex.delete(tag);
+  }
+  async has(key) {
+    return (await this.get(key)) !== undefined;
+  }
+  async wrap(key, fn, options) {
+    const cached = await this.get(key);
+    if (cached !== undefined) return cached;
+    const value = await fn();
+    await this.set(key, value, options);
+    return value;
+  }
+  async clear() {
+    this.store.clear();
+    this.tagIndex.clear();
+    this.accessOrder = [];
+  }
+  async close() {
+    // Nothing to close
+  }
+  touch(key) {
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+    this.accessOrder.push(key);
+  }
+  evict(key) {
+    const entry = this.store.get(key);
+    if (!entry) return;
+    for (const tag of entry.tags) {
+      var _this$tagIndex$get2;
+      (_this$tagIndex$get2 = this.tagIndex.get(tag)) === null || _this$tagIndex$get2 === void 0 || _this$tagIndex$get2.delete(key);
+    }
+    this.store.delete(key);
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+  }
+  enforceLru() {
+    var _this$config$max;
+    const max = (_this$config$max = this.config.max) !== null && _this$config$max !== void 0 ? _this$config$max : 1000;
+    while (this.store.size > max && this.accessOrder.length > 0) {
+      const oldest = this.accessOrder[0];
+      this.evict(oldest);
+    }
+  }
+}
+
+function getRedis() {
+  try {
+    return require('ioredis');
+  } catch {
+    throw new Error('ioredis is not installed. Run: npm install ioredis');
+  }
+}
+class RedisCache {
+  constructor(config) {
+    var _config$prefix;
+    this.config = config;
+    this.prefix = (_config$prefix = config.prefix) !== null && _config$prefix !== void 0 ? _config$prefix : 'nixxie:cache';
+    const Redis = getRedis();
+    this.client = new Redis(config.url, config.tls ? {
+      tls: {}
+    } : {});
+  }
+  k(key) {
+    return `${this.prefix}:${key}`;
+  }
+  tagKey(tag) {
+    return `${this.prefix}:tag:${tag}`;
+  }
+
+  /** Reverse index: the set of tags a given key currently belongs to. */
+  keyTagsKey(key) {
+    return `${this.prefix}:keytags:${key}`;
+  }
+
+  /** Remove `key` from every tag set it currently belongs to and drop its reverse-index record. */
+  async clearTagsFor(key) {
+    const ktKey = this.keyTagsKey(key);
+    const tags = await this.client.smembers(ktKey);
+    if (tags.length) {
+      await Promise.all(tags.map(t => this.client.srem(this.tagKey(t), key)));
+      await this.client.del(ktKey);
+    }
+  }
+  async get(key) {
+    const raw = await this.client.get(this.k(key));
+    if (raw === null) return undefined;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  async set(key, value, options) {
+    var _options$ttl, _options$tags;
+    const serialized = JSON.stringify(value);
+    const ttlMs = (_options$ttl = options === null || options === void 0 ? void 0 : options.ttl) !== null && _options$ttl !== void 0 ? _options$ttl : this.config.ttl;
+    const rKey = this.k(key);
+    const newTags = (_options$tags = options === null || options === void 0 ? void 0 : options.tags) !== null && _options$tags !== void 0 ? _options$tags : [];
+
+    // Drop any tag associations from a previous value so overwriting with different tags
+    // doesn't leave the key in stale tag sets (which would cause incorrect deleteByTag).
+    await this.clearTagsFor(key);
+    if (ttlMs !== undefined) {
+      await this.client.setex(rKey, Math.ceil(ttlMs / 1000), serialized);
+    } else {
+      await this.client.set(rKey, serialized);
+    }
+    if (newTags.length) {
+      await Promise.all(newTags.map(tag => this.client.sadd(this.tagKey(tag), key)));
+      await this.client.sadd(this.keyTagsKey(key), ...newTags);
+    }
+  }
+  async delete(key) {
+    await this.client.del(this.k(key));
+    await this.clearTagsFor(key);
+  }
+  async deletePattern(pattern) {
+    const keys = await this.client.keys(this.k(pattern));
+    if (keys.length) await this.client.del(...keys);
+  }
+  async deleteByTag(tag) {
+    const members = await this.client.smembers(this.tagKey(tag));
+    if (members.length) {
+      await this.client.del(...members.map(k => this.k(k)));
+      // Remove the deleted keys from all of their (possibly other) tag sets too.
+      await Promise.all(members.map(k => this.clearTagsFor(k)));
+    }
+    await this.client.del(this.tagKey(tag));
+  }
+  async has(key) {
+    return (await this.client.exists(this.k(key))) === 1;
+  }
+  async wrap(key, fn, options) {
+    const cached = await this.get(key);
+    if (cached !== undefined) return cached;
+    const value = await fn();
+    await this.set(key, value, options);
+    return value;
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.prefix}:*`);
+    if (keys.length) await this.client.del(...keys);
+  }
+  async close() {
+    await this.client.quit();
+  }
+}
+
+function createCache(config) {
+  switch (config.store) {
+    case 'memory':
+      return new InMemoryCache(config);
+    case 'redis':
+      return new RedisCache(config);
+    default:
+      {
+        const exhaustive = config;
+        throw new Error(`Unknown cache store: ${exhaustive.store}`);
+      }
+  }
+}
+
+export { InMemoryCache, RedisCache, createCache };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nixxie-cms/cache",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-cache.cjs.js",
+  "module": "dist/nixxie-cms-cache.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-cache.cjs.js",
+      "module": "./dist/nixxie-cms-cache.esm.js",
+      "default": "./dist/nixxie-cms-cache.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "ioredis": "^5.3.2",
+    "@types/ioredis": "^4.28.10",
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "optionalDependencies": {
+    "ioredis": "^5.3.2"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/cache"
+  }
+}

package/src/InMemoryCache.ts

@@ -0,0 +1,122 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core'
+import type { InMemoryCacheConfig } from './types'
+
+type Entry = {
+  value: unknown
+  expiresAt: number | null
+  tags: string[]
+}
+
+export class InMemoryCache implements NixxieCacheService {
+  private store = new Map<string, Entry>()
+  private tagIndex = new Map<string, Set<string>>()
+  private config: InMemoryCacheConfig
+  private accessOrder: string[] = []
+
+  constructor(config: InMemoryCacheConfig) {
+    this.config = config
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const entry = this.store.get(key)
+    if (!entry) return undefined
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.evict(key)
+      return undefined
+    }
+    this.touch(key)
+    return entry.value as T
+  }
+
+  async set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void> {
+    const ttl = options?.ttl ?? this.config.ttl ?? null
+    const tags = options?.tags ?? []
+
+    this.evict(key)
+
+    this.store.set(key, {
+      value,
+      expiresAt: ttl !== null ? Date.now() + ttl : null,
+      tags,
+    })
+
+    for (const tag of tags) {
+      const set = this.tagIndex.get(tag) ?? new Set()
+      set.add(key)
+      this.tagIndex.set(tag, set)
+    }
+
+    this.accessOrder.push(key)
+    this.enforceLru()
+  }
+
+  async delete(key: string): Promise<void> {
+    this.evict(key)
+  }
+
+  async deletePattern(pattern: string): Promise<void> {
+    // Escape all regex metacharacters first, then translate the glob wildcards `*` and `?`.
+    // Otherwise keys containing `.`, `(`, `[`, `+`, etc. would over-match or throw a SyntaxError.
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const regex = new RegExp('^' + escaped.replace(/\\\*/g, '.*').replace(/\\\?/g, '.') + '$')
+    for (const key of [...this.store.keys()]) {
+      if (regex.test(key)) this.evict(key)
+    }
+  }
+
+  async deleteByTag(tag: string): Promise<void> {
+    const keys = this.tagIndex.get(tag)
+    if (!keys) return
+    for (const key of [...keys]) {
+      this.evict(key)
+    }
+    this.tagIndex.delete(tag)
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined
+  }
+
+  async wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T> {
+    const cached = await this.get<T>(key)
+    if (cached !== undefined) return cached
+    const value = await fn()
+    await this.set(key, value, options)
+    return value
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear()
+    this.tagIndex.clear()
+    this.accessOrder = []
+  }
+
+  async close(): Promise<void> {
+    // Nothing to close
+  }
+
+  private touch(key: string): void {
+    const idx = this.accessOrder.indexOf(key)
+    if (idx !== -1) this.accessOrder.splice(idx, 1)
+    this.accessOrder.push(key)
+  }
+
+  private evict(key: string): void {
+    const entry = this.store.get(key)
+    if (!entry) return
+    for (const tag of entry.tags) {
+      this.tagIndex.get(tag)?.delete(key)
+    }
+    this.store.delete(key)
+    const idx = this.accessOrder.indexOf(key)
+    if (idx !== -1) this.accessOrder.splice(idx, 1)
+  }
+
+  private enforceLru(): void {
+    const max = this.config.max ?? 1000
+    while (this.store.size > max && this.accessOrder.length > 0) {
+      const oldest = this.accessOrder[0]
+      this.evict(oldest)
+    }
+  }
+}

package/src/RedisCache.ts

@@ -0,0 +1,132 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core'
+import type { RedisCacheConfig } from './types'
+
+type RedisClient = {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string): Promise<unknown>
+  setex(key: string, seconds: number, value: string): Promise<unknown>
+  del(...keys: string[]): Promise<unknown>
+  keys(pattern: string): Promise<string[]>
+  exists(key: string): Promise<number>
+  smembers(key: string): Promise<string[]>
+  sadd(key: string, ...members: string[]): Promise<unknown>
+  srem(key: string, ...members: string[]): Promise<unknown>
+  quit(): Promise<unknown>
+}
+
+function getRedis(): new (url: string, options?: object) => RedisClient {
+  try {
+    return require('ioredis') as new (url: string, options?: object) => RedisClient
+  } catch {
+    throw new Error('ioredis is not installed. Run: npm install ioredis')
+  }
+}
+
+export class RedisCache implements NixxieCacheService {
+  private client: RedisClient
+  private prefix: string
+  private config: RedisCacheConfig
+
+  constructor(config: RedisCacheConfig) {
+    this.config = config
+    this.prefix = config.prefix ?? 'nixxie:cache'
+    const Redis = getRedis()
+    this.client = new Redis(config.url, config.tls ? { tls: {} } : {})
+  }
+
+  private k(key: string): string {
+    return `${this.prefix}:${key}`
+  }
+
+  private tagKey(tag: string): string {
+    return `${this.prefix}:tag:${tag}`
+  }
+
+  /** Reverse index: the set of tags a given key currently belongs to. */
+  private keyTagsKey(key: string): string {
+    return `${this.prefix}:keytags:${key}`
+  }
+
+  /** Remove `key` from every tag set it currently belongs to and drop its reverse-index record. */
+  private async clearTagsFor(key: string): Promise<void> {
+    const ktKey = this.keyTagsKey(key)
+    const tags = await this.client.smembers(ktKey)
+    if (tags.length) {
+      await Promise.all(tags.map(t => this.client.srem(this.tagKey(t), key)))
+      await this.client.del(ktKey)
+    }
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const raw = await this.client.get(this.k(key))
+    if (raw === null) return undefined
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as unknown as T
+    }
+  }
+
+  async set(key: string, value: unknown, options?: NixxieCacheSetOptions): Promise<void> {
+    const serialized = JSON.stringify(value)
+    const ttlMs = options?.ttl ?? this.config.ttl
+    const rKey = this.k(key)
+    const newTags = options?.tags ?? []
+
+    // Drop any tag associations from a previous value so overwriting with different tags
+    // doesn't leave the key in stale tag sets (which would cause incorrect deleteByTag).
+    await this.clearTagsFor(key)
+
+    if (ttlMs !== undefined) {
+      await this.client.setex(rKey, Math.ceil(ttlMs / 1000), serialized)
+    } else {
+      await this.client.set(rKey, serialized)
+    }
+
+    if (newTags.length) {
+      await Promise.all(newTags.map((tag: string) => this.client.sadd(this.tagKey(tag), key)))
+      await this.client.sadd(this.keyTagsKey(key), ...newTags)
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.del(this.k(key))
+    await this.clearTagsFor(key)
+  }
+
+  async deletePattern(pattern: string): Promise<void> {
+    const keys = await this.client.keys(this.k(pattern))
+    if (keys.length) await this.client.del(...keys)
+  }
+
+  async deleteByTag(tag: string): Promise<void> {
+    const members = await this.client.smembers(this.tagKey(tag))
+    if (members.length) {
+      await this.client.del(...members.map(k => this.k(k)))
+      // Remove the deleted keys from all of their (possibly other) tag sets too.
+      await Promise.all(members.map(k => this.clearTagsFor(k)))
+    }
+    await this.client.del(this.tagKey(tag))
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.client.exists(this.k(key))) === 1
+  }
+
+  async wrap<T>(key: string, fn: () => Promise<T>, options?: NixxieCacheSetOptions): Promise<T> {
+    const cached = await this.get<T>(key)
+    if (cached !== undefined) return cached
+    const value = await fn()
+    await this.set(key, value, options)
+    return value
+  }
+
+  async clear(): Promise<void> {
+    const keys = await this.client.keys(`${this.prefix}:*`)
+    if (keys.length) await this.client.del(...keys)
+  }
+
+  async close(): Promise<void> {
+    await this.client.quit()
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import type { CacheConfig } from './types'
+import { InMemoryCache } from './InMemoryCache'
+import { RedisCache } from './RedisCache'
+
+export function createCache(config: CacheConfig): InMemoryCache | RedisCache {
+  switch (config.store) {
+    case 'memory':
+      return new InMemoryCache(config)
+    case 'redis':
+      return new RedisCache(config)
+    default: {
+      const exhaustive: never = config
+      throw new Error(`Unknown cache store: ${(exhaustive as any).store}`)
+    }
+  }
+}
+
+export { InMemoryCache, RedisCache }
+export type { CacheConfig, InMemoryCacheConfig, RedisCacheConfig } from './types'
+export type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core'

package/src/types.ts

@@ -0,0 +1,25 @@
+import type { NixxieCacheService, NixxieCacheSetOptions } from '@nixxie-cms/core'
+
+export type { NixxieCacheService, NixxieCacheSetOptions }
+
+export type InMemoryCacheConfig = {
+  store: 'memory'
+  /** Maximum number of entries (LRU eviction when exceeded). Default: 1000 */
+  max?: number
+  /** Default TTL in milliseconds for entries without an explicit TTL. Omit for no expiry. */
+  ttl?: number
+}
+
+export type RedisCacheConfig = {
+  store: 'redis'
+  /** Redis connection URL: redis://[:password@]host[:port][/db] */
+  url: string
+  /** Key prefix — all cache keys are stored as `{prefix}:{key}`. Default: 'nixxie:cache' */
+  prefix?: string
+  /** Default TTL in milliseconds. Omit for no expiry. */
+  ttl?: number
+  /** TLS options passed to ioredis */
+  tls?: boolean
+}
+
+export type CacheConfig = InMemoryCacheConfig | RedisCacheConfig