@zudojs/cache 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Cache abstraction with a memory adapter, namespaced tags, locking, events, middleware, and metrics for Zudojs applications.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-cache](https://zudojs.oyinlola.site/docs/packages-cache) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-cache.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -74,6 +80,34 @@ await cache.withLock("import", runImport, { namespace: tenantId });
 In glob patterns, `*` matches within a single key segment and never crosses
 the `:` separator; `**` as a whole segment spans namespaces deliberately.
 
+An empty-string namespace is rejected with `CACHE_INVALID_KEY`, in the config
+and per call. A tenant id that failed to resolve to `""` can therefore never
+fall through to the unscoped global keyspace. Omit `namespace` to use that
+keyspace deliberately.
+
+## Tags across instances
+
+By default each `CacheService` keeps its tag mappings in process, so
+`invalidateByTag` only sees entries written by the same instance. Replicas that
+share one adapter must also share a tag store. Pass any `CacheTagStore`
+implementation (for example one backed by Redis sets) as `config.tagStore`:
+
+```typescript
+const tagStore = createTagStore(); // or your shared implementation
+const a = createCacheService({ adapter, config: { tagStore } });
+const b = createCacheService({ adapter, config: { tagStore } });
+
+await a.set("user.1", user, { tags: ["users"] });
+await b.invalidateByTag(["users"]); // clears the entry a wrote
+```
+
+## Serialization
+
+`JsonCacheSerializer` preserves `Date`, `BigInt`, `Map`, `Set` and `Uint8Array`
+by default and drops `__proto__`, `constructor` and `prototype` keys on read.
+A value with its own `$type` field (a domain discriminator) is ordinary data
+and reads back unchanged.
+
 ## Observability
 
 ```typescript

package/dist/cache.d.ts

@@ -25,6 +25,8 @@ export declare class CacheService implements CacheHealthChecker {
     private readonly store;
     private readonly keyBuilder;
     private readonly tagStore;
+    /** False when the tag store was injected and may be shared with peers. */
+    private readonly ownsTagStore;
     private readonly invalidation;
     private readonly lockManager;
     private readonly metrics;

package/dist/cache.js

@@ -15,9 +15,9 @@
  * patterns), so it can never widen an operation beyond its own tenant.
  */
 import { DEFAULT_LOCK_RETRY_DELAY_MS, DEFAULT_SEPARATOR, DEFAULT_TTL_MS, } from "./constants.js";
-import { DefaultKeyBuilder } from "./key-builder.js";
+import { assertNonEmptyNamespace, DefaultKeyBuilder } from "./key-builder.js";
 import { createCacheStore, DefaultCacheStore } from "./store.js";
-import { assertValidTag, createTagStore, InMemoryTagStore } from "./tags.js";
+import { assertValidTag, createTagStore } from "./tags.js";
 import { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
 import { CacheLockManager, createLockManager } from "./lock.js";
 import { createCacheMetrics, InMemoryCacheMetrics } from "./metrics.js";
@@ -27,6 +27,8 @@ export class CacheService {
     store;
     keyBuilder;
     tagStore;
+    /** False when the tag store was injected and may be shared with peers. */
+    ownsTagStore;
     invalidation;
     lockManager;
     metrics;
@@ -48,6 +50,7 @@ export class CacheService {
                 : DEFAULT_TTL_MS;
         this.serializer = options.config?.serializer ?? null;
         this.namespace = options.config?.namespace;
+        assertNonEmptyNamespace(this.namespace);
         this.separator = options.config?.separator ?? DEFAULT_SEPARATOR;
         this.metrics =
             options.config?.collectStats !== false ? createCacheMetrics() : null;
@@ -71,7 +74,8 @@ export class CacheService {
                         ? { namespace: options.config.namespace }
                         : {}),
                 });
-        this.tagStore = createTagStore();
+        this.tagStore = options.config?.tagStore ?? createTagStore();
+        this.ownsTagStore = options.config?.tagStore === undefined;
         // Route invalidation through the instrumented store so metrics and
         // events fire for invalidation-driven deletions too.
         this.invalidation = createInvalidationManager({
@@ -123,8 +127,14 @@ export class CacheService {
                     ? { metadata: options.metadata }
                     : {}),
             });
-            if (result.success && options?.tags && options.tags.length > 0)
-                await this.tagStore.add(fullKey, options.tags, this.tagScope(options));
+            if (result.success) {
+                // The entry now carries exactly the tags of this write. Mappings
+                // left over from an earlier write would let `invalidateByTag` on a
+                // tag the entry no longer has delete the new value.
+                await this.tagStore.removeKey?.(fullKey);
+                if (options?.tags && options.tags.length > 0)
+                    await this.tagStore.add(fullKey, options.tags, this.tagScope(options));
+            }
             return result;
         }
         catch (error) {
@@ -139,7 +149,7 @@ export class CacheService {
         const fullKey = this.keyBuilder.build(key, options);
         try {
             const result = await this.store.delete(fullKey);
-            this.tagStore.removeKey(fullKey);
+            await this.tagStore.removeKey?.(fullKey);
             return result;
         }
         catch (error) {
@@ -178,7 +188,7 @@ export class CacheService {
             const pattern = this.qualifyPattern(options.pattern ?? "*", options.namespace);
             try {
                 const result = await this.store.clear({ pattern });
-                this.purgeTagsMatching(pattern);
+                await this.purgeTagsMatching(pattern);
                 return result;
             }
             catch (error) {
@@ -189,7 +199,7 @@ export class CacheService {
         }
         try {
             const result = await this.store.clear();
-            this.tagStore.clear();
+            await this.tagStore.clear?.();
             return result;
         }
         catch (error) {
@@ -427,7 +437,10 @@ export class CacheService {
         // Drop service-local state so a reconnect does not resurrect stale
         // in-flight computations or tag mappings.
         this.inFlight.clear();
-        this.tagStore.clear();
+        // An injected store may be shared with other instances: their mappings
+        // are not this instance's to drop.
+        if (this.ownsTagStore)
+            await this.tagStore.clear?.();
     }
     /* ---- Internals ---- */
     async applyBatchOperation(operation, options) {
@@ -453,6 +466,7 @@ export class CacheService {
     /** The namespace scope applied to tag registrations and lookups. */
     tagScope(options) {
         const namespace = options?.namespace ?? this.namespace;
+        assertNonEmptyNamespace(namespace);
         return namespace !== undefined ? { namespace } : {};
     }
     qualifyPattern(pattern, namespace) {
@@ -461,11 +475,14 @@ export class CacheService {
         }
         return pattern;
     }
-    purgeTagsMatching(pattern) {
+    async purgeTagsMatching(pattern) {
+        const store = this.tagStore;
+        if (!store.trackedKeys || !store.removeKey)
+            return;
         const matches = createGlobMatcher(pattern, { separator: this.separator });
-        for (const key of this.tagStore.trackedKeys()) {
+        for (const key of await store.trackedKeys()) {
             if (matches(key))
-                this.tagStore.removeKey(key);
+                await store.removeKey(key);
         }
     }
     serialize(value) {

package/dist/invalidation.js

@@ -50,7 +50,7 @@ export class CacheInvalidationManager {
                 cleared++;
             // The key is gone from the cache, so every tag mapping it still has
             // (in any scope) is dead too.
-            this.tagStore.removeKey?.(key);
+            await this.tagStore.removeKey?.(key);
         }
         for (const tag of tags) {
             await this.tagStore.invalidate(tag, options);
@@ -97,7 +97,7 @@ export class CacheInvalidationManager {
      */
     async flushAll() {
         const result = await this.adapter.clear();
-        this.tagStore.clear?.();
+        await this.tagStore.clear?.();
         return result;
     }
 }

package/dist/key-builder.d.ts

@@ -10,6 +10,17 @@
  */
 import type { CacheKey, CacheKeyOptions, CacheNamespace } from "./types.js";
 import type { CacheKeyBuilder } from "./types-keys.js";
+/**
+ * Rejects an empty-string namespace.
+ *
+ * `""` is falsy, so it used to be dropped as "no namespace" and moved a
+ * tenant whose id failed to resolve into the shared global keyspace. A
+ * namespace is either absent (`undefined`) or a valid identity part.
+ *
+ * @param namespace - The namespace to check.
+ * @throws {CacheError} `CACHE_INVALID_KEY` when `namespace` is `""`.
+ */
+export declare function assertNonEmptyNamespace(namespace: CacheNamespace | undefined): void;
 /**
  * Default implementation of the `CacheKeyBuilder` contract.
  *

package/dist/key-builder.js

@@ -11,6 +11,21 @@
 import { CACHE_KEY_PATTERN, DEFAULT_PREFIX, DEFAULT_SEPARATOR, MAX_KEY_LENGTH, } from "./constants.js";
 import { cacheInvalidKeyError } from "./errors.js";
 import { assertValidPatternPart } from "./utils.js";
+/**
+ * Rejects an empty-string namespace.
+ *
+ * `""` is falsy, so it used to be dropped as "no namespace" and moved a
+ * tenant whose id failed to resolve into the shared global keyspace. A
+ * namespace is either absent (`undefined`) or a valid identity part.
+ *
+ * @param namespace - The namespace to check.
+ * @throws {CacheError} `CACHE_INVALID_KEY` when `namespace` is `""`.
+ */
+export function assertNonEmptyNamespace(namespace) {
+    if (namespace === "") {
+        throw cacheInvalidKeyError(namespace, "Cache namespace must not be empty. Omit it for the unscoped keyspace.");
+    }
+}
 /* -------------------------------------------------------------------------- */
 /* Default Key Builder                                                        */
 /* -------------------------------------------------------------------------- */
@@ -26,6 +41,7 @@ export class DefaultKeyBuilder {
     constructor(options) {
         this.globalPrefix = options?.prefix ?? DEFAULT_PREFIX;
         this.globalSeparator = options?.separator ?? DEFAULT_SEPARATOR;
+        assertNonEmptyNamespace(options?.namespace);
         this.currentNamespace = options?.namespace;
     }
     build(key, options) {
@@ -39,7 +55,7 @@ export class DefaultKeyBuilder {
         if (prefix) {
             parts.push(prefix);
         }
-        if (namespace) {
+        if (namespace !== undefined) {
             parts.push(namespace);
         }
         parts.push(key);
@@ -68,7 +84,7 @@ export class DefaultKeyBuilder {
         const identityParts = [];
         if (prefix)
             identityParts.push(prefix);
-        if (namespace)
+        if (namespace !== undefined)
             identityParts.push(namespace);
         for (const part of identityParts)
             this.validatePart(part, separator);

package/dist/lock.js

@@ -203,8 +203,18 @@ export class CacheLockManager {
         // `release()` returning false is the one signal that the lease expired or
         // was taken over mid-critical-section. Surfacing it is the whole point of
         // minting a fencing token. An error thrown by `fn` still wins, so the
-        // real cause is never masked.
-        const released = await lock.release();
+        // real cause is never masked — including by `release()` itself throwing
+        // (a distributed store that is down). The release error is then attached
+        // to the thrown error as a non-enumerable `suppressed` property.
+        let released = false;
+        try {
+            released = await lock.release();
+        }
+        catch (releaseError) {
+            if (failed)
+                throw attachSuppressed(failure, releaseError);
+            throw releaseError;
+        }
         if (failed)
             throw failure;
         if (!released || leaseLost) {
@@ -219,6 +229,25 @@ export class CacheLockManager {
         return value;
     }
 }
+/**
+ * Record a secondary error on the primary one without replacing it, mirroring
+ * `SuppressedError.suppressed`. Only an extensible object that does not
+ * already carry `suppressed` is annotated; the primary is returned either way.
+ */
+function attachSuppressed(primary, secondary) {
+    if (typeof primary === "object" &&
+        primary !== null &&
+        Object.isExtensible(primary) &&
+        !Object.hasOwn(primary, "suppressed")) {
+        Object.defineProperty(primary, "suppressed", {
+            value: secondary,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return primary;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/serializer.d.ts

@@ -9,13 +9,17 @@ import type { CacheSerializer } from "./types.js";
 /**
  * Strips prototype-polluting own keys from a freshly deserialized value.
  *
- * This is defence in depth at the trust boundary: a cached payload can come
- * from a shared backing store, a restored backup, or another writer, so the
- * bytes are not necessarily ones this process serialized. `@zudojs/errors`'
- * sibling `@zudojs/serialization` accepts an `allowUnsafeKeys` option but
- * the published build does not implement it, and `JSON.parse` leaves
- * `__proto__` as a genuine own property — which re-triggers the setter on
- * any later spread or `Object.assign`. Both routes are closed here.
+ * A cached payload can come from a shared backing store, a restored backup,
+ * or another writer, so the bytes are not necessarily ones this process
+ * serialized. `JSON.parse` leaves `__proto__` as a genuine own property,
+ * which re-triggers the setter on any later spread or `Object.assign`.
+ *
+ * The key list is `SCHEMA_FORBIDDEN_KEYS` from `@zudojs/constants`.
+ *
+ * `JsonCacheSerializer` needs this only for `preserveTypes: false`: on the
+ * type-preserving path `@zudojs/serialization` already drops these keys
+ * (`allowUnsafeKeys: false`), but its plain-JSON fast path returns
+ * `JSON.parse` output untouched.
  */
 export declare function stripUnsafeKeys<T>(value: T): T;
 /**

package/dist/serializer.js

@@ -5,21 +5,25 @@
  * to and from storable representations. Delegates to @zudojs/serialization
  * for the actual JSON serialization with type preservation.
  */
+import { SCHEMA_FORBIDDEN_KEYS } from "@zudojs/constants";
 import { JSONSerializer } from "@zudojs/serialization";
 /* -------------------------------------------------------------------------- */
 /* Prototype-pollution hardening                                              */
 /* -------------------------------------------------------------------------- */
-const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 /**
  * Strips prototype-polluting own keys from a freshly deserialized value.
  *
- * This is defence in depth at the trust boundary: a cached payload can come
- * from a shared backing store, a restored backup, or another writer, so the
- * bytes are not necessarily ones this process serialized. `@zudojs/errors`'
- * sibling `@zudojs/serialization` accepts an `allowUnsafeKeys` option but
- * the published build does not implement it, and `JSON.parse` leaves
- * `__proto__` as a genuine own property — which re-triggers the setter on
- * any later spread or `Object.assign`. Both routes are closed here.
+ * A cached payload can come from a shared backing store, a restored backup,
+ * or another writer, so the bytes are not necessarily ones this process
+ * serialized. `JSON.parse` leaves `__proto__` as a genuine own property,
+ * which re-triggers the setter on any later spread or `Object.assign`.
+ *
+ * The key list is `SCHEMA_FORBIDDEN_KEYS` from `@zudojs/constants`.
+ *
+ * `JsonCacheSerializer` needs this only for `preserveTypes: false`: on the
+ * type-preserving path `@zudojs/serialization` already drops these keys
+ * (`allowUnsafeKeys: false`), but its plain-JSON fast path returns
+ * `JSON.parse` output untouched.
  */
 export function stripUnsafeKeys(value) {
     const seen = new Set();
@@ -46,7 +50,7 @@ export function stripUnsafeKeys(value) {
             return;
         }
         for (const key of Object.getOwnPropertyNames(obj)) {
-            if (UNSAFE_KEYS.has(key)) {
+            if (SCHEMA_FORBIDDEN_KEYS.has(key)) {
                 Reflect.deleteProperty(obj, key);
                 continue;
             }
@@ -106,14 +110,15 @@ export class JsonCacheSerializer {
         });
     }
     deserialize(value) {
+        // Not `strict`: strict mode throws on any `$type` the registry does not
+        // know, so a domain object carrying a `$type` discriminator could be
+        // written but never read back, poisoning its key. An unknown tag is
+        // ordinary data.
         const parsed = this.inner.deserialize(value, {
             preserveTypes: this.preserveTypes,
-            // Stated at the call site even though the published sibling build
-            // ignores them; `stripUnsafeKeys` enforces the intent regardless.
-            strict: true,
             allowUnsafeKeys: false,
         });
-        return stripUnsafeKeys(parsed);
+        return this.preserveTypes ? parsed : stripUnsafeKeys(parsed);
     }
 }
 /* -------------------------------------------------------------------------- */

package/dist/types-config.d.ts

@@ -3,6 +3,7 @@ import type { CacheTTL } from "./types-values.js";
 import type { CacheMiddleware } from "./types-metrics.js";
 import type { CacheSerializer } from "./types-health.js";
 import type { CacheLockStore } from "./types-lock.js";
+import type { CacheTagStore } from "./types-tags.js";
 export interface CacheConfig {
     readonly enabled?: boolean;
     readonly defaultTtl?: CacheTTL;
@@ -45,6 +46,14 @@ export interface CacheConfig {
      * processes.
      */
     readonly lockStore?: CacheLockStore;
+    /**
+     * Tag store backing `set({ tags })` and `invalidateByTag`. Defaults to a
+     * fresh in-process store per service, which means tag invalidation only
+     * sees entries written by the same instance. Replicas sharing one adapter
+     * (one Redis) must share a tag store too, e.g. one backed by Redis sets.
+     * An injected store is never flushed by `disconnect()`.
+     */
+    readonly tagStore?: CacheTagStore;
 }
 /**
  * Error codes set by errors this package constructs directly. Every member

package/dist/types-tags.d.ts

@@ -14,9 +14,20 @@ export interface CacheTagStore {
     remove(key: CacheKey, tags: readonly CacheTag[], options?: CacheTagOptions): Promise<void>;
     getKeys(tag: CacheTag, options?: CacheTagOptions): Promise<readonly CacheKey[]>;
     invalidate(tag: CacheTag, options?: CacheTagOptions): Promise<CacheClearResult>;
-    /** Removes all tag mappings for a key, across every namespace. */
-    removeKey?(key: CacheKey): void;
-    /** Removes all tag mappings. */
-    clear?(): void;
+    /**
+     * Removes all tag mappings for a key, across every namespace.
+     *
+     * May be async: `CacheService` awaits it, so a shared (e.g. Redis-backed)
+     * store can complete the removal before the write is reported.
+     */
+    removeKey?(key: CacheKey): void | Promise<void>;
+    /** Removes all tag mappings. May be async. */
+    clear?(): void | Promise<void>;
+    /**
+     * Every key that currently has at least one tag mapping. Used to drop the
+     * mappings of keys removed by a pattern clear; when absent, those mappings
+     * are left for the next write or tag invalidation of the key.
+     */
+    trackedKeys?(): readonly CacheKey[] | Promise<readonly CacheKey[]>;
 }
 //# sourceMappingURL=types-tags.d.ts.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/cache",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Caching primitives, abstractions, and adapters for the Zudojs framework.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -20,9 +24,10 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/serialization": "1.0.0"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/serialization": "1.1.0",
+    "@zudojs/types": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",