layercache 1.4.0 → 2.1.0

package/dist/{chunk-7KMKQ6QZ.js → chunk-6X7NV5BG.js}

@@ -151,9 +151,15 @@ var RedisTagIndex = class {
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -171,6 +177,9 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -182,9 +191,15 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     let cursor = "0";
     const tagKey = this.tagKeysKey(tag);
@@ -196,6 +211,9 @@ var RedisTagIndex = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -208,6 +226,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -222,9 +243,15 @@ var RedisTagIndex = class {
       } while (cursor !== "0");
     }
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -244,6 +271,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -265,6 +295,9 @@ var RedisTagIndex = class {
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {

package/dist/{chunk-FFZCC7EQ.js → chunk-IVX6ABFX.js}

@@ -12,6 +12,9 @@ var MemoryLayer = class {
   onEvict;
   entries = /* @__PURE__ */ new Map();
   cleanupTimer;
+  /**
+   * Creates an in-memory cache layer.
+   */
   constructor(options = {}) {
     this.name = options.name ?? "memory";
     this.defaultTtl = options.ttl;
@@ -25,10 +28,16 @@ var MemoryLayer = class {
       this.cleanupTimer.unref?.();
     }
   }
+  /**
+   * Reads and unwraps a fresh value from memory.
+   */
   async get(key) {
     const value = await this.getEntry(key);
     return unwrapStoredValue(value);
   }
+  /**
+   * Reads the raw stored value or envelope from memory.
+   */
   async getEntry(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -47,12 +56,21 @@ var MemoryLayer = class {
     }
     return entry.value;
   }
+  /**
+   * Reads many raw entries from memory.
+   */
   async getMany(keys) {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
+  /**
+   * Writes many entries to memory.
+   */
   async setMany(entries) {
     await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
+  /**
+   * Stores a value in memory using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
     this.entries.set(key, {
@@ -65,6 +83,9 @@ var MemoryLayer = class {
       this.evict();
     }
   }
+  /**
+   * Returns true when the key exists and has not expired.
+   */
   async has(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -76,6 +97,9 @@ var MemoryLayer = class {
     }
     return true;
   }
+  /**
+   * Returns remaining TTL in milliseconds, or null when absent or non-expiring.
+   */
   async ttl(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -90,40 +114,67 @@ var MemoryLayer = class {
     }
     return Math.max(0, Math.ceil(entry.expiresAt - Date.now()));
   }
+  /**
+   * Returns the number of currently retained, non-expired entries.
+   */
   async size() {
     this.pruneExpired();
     return this.entries.size;
   }
+  /**
+   * Deletes a key from memory.
+   */
   async delete(key) {
     this.entries.delete(key);
   }
+  /**
+   * Deletes multiple keys from memory.
+   */
   async deleteMany(keys) {
     for (const key of keys) {
       this.entries.delete(key);
     }
   }
+  /**
+   * Removes all entries from memory.
+   */
   async clear() {
     this.entries.clear();
   }
+  /**
+   * Health check hook that always succeeds for the in-process layer.
+   */
   async ping() {
     return true;
   }
+  /**
+   * Stops the cleanup timer, when one is active.
+   */
   async dispose() {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * Returns all currently retained, non-expired keys.
+   */
   async keys() {
     this.pruneExpired();
     return [...this.entries.keys()];
   }
+  /**
+   * Visits all currently retained, non-expired keys.
+   */
   async forEachKey(visitor) {
     this.pruneExpired();
     for (const key of this.entries.keys()) {
       await visitor(key);
     }
   }
+  /**
+   * Exports memory entries for process-local snapshots.
+   */
   exportState() {
     this.pruneExpired();
     return [...this.entries.entries()].map(([key, entry]) => ({
@@ -132,6 +183,9 @@ var MemoryLayer = class {
       expiresAt: entry.expiresAt
     }));
   }
+  /**
+   * Imports entries previously produced by `exportState()`.
+   */
   importState(entries) {
     for (const entry of entries) {
       if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
@@ -202,10 +256,16 @@ var TagIndex = class {
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
@@ -226,17 +286,29 @@ var TagIndex = class {
       this.tagToKeys.set(tag, keys);
     }
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     this.removeKey(key);
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     for (const key of this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()) {
       await visitor(key);
     }
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -246,6 +318,9 @@ var TagIndex = class {
     this.collectFromNode(node, prefix, matches);
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -253,20 +328,32 @@ var TagIndex = class {
     }
     await this.visitFromNode(node, prefix, visitor);
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
     const matches = /* @__PURE__ */ new Set();
     this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
     return [...matches];
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     const matches = await this.matchPattern(pattern);
     for (const key of matches) {
       await visitor(key);
     }
   }
+  /**
+   * Clears all tag and known-key index state.
+   */
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();

package/dist/cli.cjs

@@ -227,9 +227,15 @@ var RedisTagIndex = class {
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -247,6 +253,9 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -258,9 +267,15 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     let cursor = "0";
     const tagKey = this.tagKeysKey(tag);
@@ -272,6 +287,9 @@ var RedisTagIndex = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -284,6 +302,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -298,9 +319,15 @@ var RedisTagIndex = class {
       } while (cursor !== "0");
     }
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
     const matches = [];
     for (const knownKeysKey of this.knownKeysKeys()) {
@@ -320,6 +347,9 @@ var RedisTagIndex = class {
     }
     return matches;
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     for (const knownKeysKey of this.knownKeysKeys()) {
       let cursor = "0";
@@ -341,6 +371,9 @@ var RedisTagIndex = class {
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   validateCacheKey,
   validatePattern,
   validateTag
-} from "./chunk-7KMKQ6QZ.js";
+} from "./chunk-6X7NV5BG.js";
 import {
   isStoredValueEnvelope,
   resolveStoredValue