inray 0.0.2 → 0.0.3

package/dist/caching/src/utils/cache-tags.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Original library: @cacheable/utils (v2.4.2)
+ * - Copyright (c) Jared Wray
+ *
+ * Modified and integrated in "Inray":
+ * - Evgeniy Bushin
+ */
+/***/
+import type { Keyv } from '../keyValue/index.ts';
+/**
+ * Options for constructing a {@link CacheTags}.
+ * @typedef {Object} CacheTagsOptions
+ * @property {Keyv} store - The Keyv store used to persist tag versions and key snapshots.
+ * @property {string} [namespace] - An optional namespace that isolates this service's tags
+ * and keys from others sharing the same store. Defaults to `"default"`.
+ * @property {boolean} [enabled] - Whether the service is enabled. While disabled, every method
+ * is a no-op: read methods return their neutral value ({@link CacheTags.isKeyFresh} returns
+ * `true`, {@link CacheTags.isKeyStale} returns `false`, etc.) and writes are skipped. The
+ * service must be explicitly enabled to use tags. Defaults to `true`.
+ * @property {(error: unknown) => void} [onError] - Invoked with errors from non-blocking
+ * (fire-and-forget) operations, which cannot be thrown to the caller. Defaults to ignoring them.
+ */
+export type CacheTagsOptions = {
+    store: Keyv;
+    namespace?: string;
+    enabled?: boolean;
+    onError?: (error: unknown) => void;
+};
+/**
+ * Options for {@link CacheTags.setKeyTags}.
+ * @typedef {Object} SetKeyTagsOptions
+ * @property {number} [ttl] - Time-to-live in milliseconds for the key's tag snapshot. Should
+ * match the TTL of the cached value it tracks so the snapshot expires alongside it. If omitted,
+ * the snapshot does not expire.
+ * @property {boolean} [nonBlocking] - When `true`, the snapshot write is fire-and-forget:
+ * the call resolves immediately and failures are reported via the `onError` option.
+ */
+export type SetKeyTagsOptions = {
+    ttl?: number;
+    nonBlocking?: boolean;
+};
+/**
+ * Options for {@link CacheTags.removeKey} and {@link CacheTags.removeKeys}.
+ * @typedef {Object} RemoveKeysOptions
+ * @property {boolean} [nonBlocking] - When `true`, the removal is fire-and-forget:
+ * the call resolves immediately and failures are reported via the `onError` option.
+ */
+export type RemoveKeysOptions = {
+    nonBlocking?: boolean;
+};
+/**
+ * The metadata stored for a tagged key. It records the version of each tag at the moment the key
+ * was written, allowing {@link CacheTags.isKeyFresh} to detect later invalidations.
+ * @typedef {Object} KeyTagEntry
+ * @property {Record<string, number>} tags - A snapshot mapping each tag name to its version at set time.
+ */
+export type KeyTagEntry = {
+    tags: Record<string, number>;
+};
+/**
+ * Provides tag-based cache invalidation on top of any {@link Keyv} store. It is store-agnostic and
+ * requires no adapter changes.
+ *
+ * The service uses a lazy invalidation model rather than scanning and deleting keys. Each tag has a
+ * monotonically increasing version counter; {@link CacheTags.invalidateTag} simply increments
+ * it. When a key is tagged via {@link CacheTags.setKeyTags}, a snapshot of its tags' current
+ * versions is stored alongside it. {@link CacheTags.isKeyFresh} compares that snapshot against
+ * the live versions — if any tag has been incremented since, the key is considered stale. Stale
+ * entries are not deleted explicitly; they are expected to fall out of the cache via their TTL.
+ *
+ * This keeps invalidation constant-time regardless of how many keys reference a tag, at the cost of
+ * one additional `isKeyFresh` read per cache lookup.
+ *
+ * The service can be disabled via the `enabled` option or property so integrations pay no cost for
+ * untagged workloads: while disabled, every method is a no-op — reads return their neutral value
+ * and writes are skipped. The service must be explicitly enabled to use tags; it never enables
+ * itself, which keeps behavior consistent across distributed instances sharing a store.
+ *
+ * All metadata is written under a reserved prefix so it cannot collide with user keys:
+ * - `--cacheable--tags--:<namespace>:tag:<tag>` → integer version counter (stored without TTL).
+ * - `--cacheable--tags--:<namespace>:key:<key>` → the {@link KeyTagEntry} snapshot.
+ *
+ * Note: the read-version-then-write-snapshot sequence in `setKeyTags` is not atomic across
+ * processes. A concurrent `invalidateTag` running between the read and the write can leave a freshly
+ * written key referencing a stale version.
+ *
+ * @example
+ * ```typescript
+ * const cacheTags = new CacheTags({ store: new Keyv(), namespace: 'app' });
+ * await cacheTags.setKeyTags('user:42', ['users', 'org:7'], { ttl: 3600000 });
+ * await cacheTags.isKeyFresh('user:42'); // true
+ * await cacheTags.invalidateTag('users');
+ * await cacheTags.isKeyFresh('user:42'); // false
+ * ```
+ */
+export declare class CacheTags {
+    private readonly _store;
+    private readonly _namespace;
+    private _enabled;
+    private readonly _onError?;
+    /**
+     * Creates a new tag service.
+     * @param {CacheTagsOptions} options - The store, optional namespace, enabled state, and
+     * non-blocking error handler to use.
+     */
+    constructor(options: CacheTagsOptions);
+    /**
+     * The Keyv store backing this service.
+     * @returns {Keyv} The store provided to the constructor.
+     */
+    get store(): Keyv;
+    /**
+     * The namespace isolating this service's tags and keys within the store.
+     * @returns {string} The configured namespace, or `"default"` if none was provided.
+     */
+    get namespace(): string;
+    /**
+     * Whether the service is enabled. While disabled, every method is a no-op — read methods
+     * return their neutral value and writes are skipped — so integrations pay no extra store
+     * reads for untagged workloads. The service must be explicitly enabled to use tags; it never
+     * enables itself.
+     * @returns {boolean} Whether the service is enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Sets whether the service is enabled.
+     * @param {boolean} enabled Whether the service is enabled.
+     */
+    set enabled(enabled: boolean);
+    /**
+     * Builds the reserved store key under which a tag's version counter is stored.
+     * @param tag - The tag name.
+     * @returns {string} The namespaced store key for the tag's version.
+     */
+    private tagKey;
+    /**
+     * Builds the reserved store key under which a cache key's tag snapshot is stored.
+     * @param key - The cache key being tagged.
+     * @returns {string} The namespaced store key for the key's snapshot.
+     */
+    private keyEntryKey;
+    /**
+     * Builds the common prefix shared by every key-snapshot entry in this namespace. Used to filter
+     * key entries when iterating the store.
+     * @returns {string} The namespaced key-entry prefix.
+     */
+    private keyPrefix;
+    /**
+     * Reads the current version of a single tag.
+     * @param tag - The tag name.
+     * @returns {Promise<number>} The tag's version, or `0` if it has never been invalidated.
+     */
+    private getTagVersion;
+    /**
+     * Reads the current versions of multiple tags in a single batched store read.
+     * @param tags - The tag names to look up.
+     * @returns {Promise<number[]>} The versions in the same order as `tags`; entries that have never
+     * been invalidated resolve to `0`. Returns an empty array when `tags` is empty.
+     */
+    private getTagVersions;
+    /**
+     * Reports a fire-and-forget failure to the `onError` handler, if one was provided.
+     * @param error - The error raised by the non-blocking operation.
+     */
+    private handleNonBlockingError;
+    /**
+     * Reads the version snapshot of each tag and writes the key's tag snapshot to the store.
+     * @param key - The cache key to tag.
+     * @param tags - The tags to associate with the key.
+     * @param ttl - Time-to-live in milliseconds for the snapshot.
+     * @returns {Promise<void>} Resolves once the snapshot has been written.
+     */
+    private writeKeyTags;
+    /**
+     * Associates a cache key with a set of tags by recording a snapshot of each tag's current
+     * version. Call this whenever you write a fresh value to the cache. Duplicate tags are ignored.
+     * No-op while the service is disabled.
+     * @param key - The cache key to tag.
+     * @param tags - The tags to associate with the key.
+     * @param {SetKeyTagsOptions} [options] - Optional settings, such as a `ttl` for the snapshot or
+     * `nonBlocking` to fire-and-forget the write.
+     * @returns {Promise<void>} Resolves once the snapshot has been written, or immediately when
+     * `nonBlocking` is set.
+     */
+    setKeyTags(key: string, tags: string[], options?: SetKeyTagsOptions): Promise<void>;
+    /**
+     * Removes a key's tag snapshot. After this, {@link CacheTags.isKeyFresh} returns `false`
+     * for the key. Use when the cached value itself is deleted. No-op while the service is
+     * disabled.
+     * @param key - The cache key whose snapshot should be removed.
+     * @param {RemoveKeysOptions} [options] - Optional settings, such as `nonBlocking` to
+     * fire-and-forget the removal.
+     * @returns {Promise<void>} Resolves once the snapshot has been deleted, or immediately when
+     * `nonBlocking` is set.
+     */
+    removeKey(key: string, options?: RemoveKeysOptions): Promise<void>;
+    /**
+     * Removes multiple keys' tag snapshots in a single batched store delete. After this,
+     * {@link CacheTags.isKeyFresh} returns `false` for each key. An empty list is a no-op, as is
+     * the entire call while the service is disabled.
+     * @param keys - The cache keys whose snapshots should be removed.
+     * @param {RemoveKeysOptions} [options] - Optional settings, such as `nonBlocking` to
+     * fire-and-forget the removal.
+     * @returns {Promise<void>} Resolves once the snapshots have been deleted, or immediately when
+     * `nonBlocking` is set.
+     */
+    removeKeys(keys: string[], options?: RemoveKeysOptions): Promise<void>;
+    /**
+     * Determines whether a key's cached value can still be trusted. A key is fresh only when a
+     * snapshot exists for it and every tag in that snapshot still has the version it had at set time.
+     * A key with no tags is trivially fresh. Call this before returning a value from your cache.
+     * Always returns `true` while the service is disabled.
+     * @param key - The cache key to check.
+     * @returns {Promise<boolean>} `true` if the key is still fresh; `false` if it is unknown or any of
+     * its tags has been invalidated since the snapshot was taken.
+     */
+    isKeyFresh(key: string): Promise<boolean>;
+    /**
+     * Determines whether a key's cached value is known to be stale due to tag invalidation. This is
+     * the complement of {@link CacheTags.isKeyFresh} for tagged keys, but treats keys without a
+     * snapshot as not stale — making it safe to call for every cache lookup, including keys that were
+     * never tagged. Always returns `false` while the service is disabled.
+     * @param key - The cache key to check.
+     * @returns {Promise<boolean>} `true` only when a snapshot exists for the key and at least one of
+     * its tags has been invalidated since the snapshot was taken; `false` otherwise (including when
+     * the key has no snapshot).
+     */
+    isKeyStale(key: string): Promise<boolean>;
+    /**
+     * Determines which of the given keys are known to be stale due to tag invalidation, using two
+     * batched store reads regardless of how many keys are checked: one for the snapshots and one for
+     * the union of their tag versions. Keys without a snapshot are not considered stale. Returns an
+     * empty array while the service is disabled.
+     * @param keys - The cache keys to check.
+     * @returns {Promise<string[]>} The subset of `keys` whose snapshot references at least one tag
+     * that has been invalidated since the snapshot was taken.
+     */
+    getStaleKeys(keys: string[]): Promise<string[]>;
+    /**
+     * Returns the tags currently associated with a key. Returns `undefined` while the service is
+     * disabled.
+     * @param key - The cache key to look up.
+     * @returns {Promise<string[] | undefined>} The tag names from the key's snapshot, or `undefined`
+     * if the key has no snapshot.
+     */
+    getTags(key: string): Promise<string[] | undefined>;
+    /**
+     * Returns all cache keys whose snapshot references the given tag. This scans every key entry in
+     * the namespace via the Keyv iterator, making it an `O(N)` operation intended for debugging and
+     * tests rather than hot paths. Returns an empty array if the underlying store exposes no iterator
+     * or while the service is disabled.
+     * @param tag - The tag to search for.
+     * @returns {Promise<string[]>} The cache keys (with the reserved prefix stripped) referencing the tag.
+     */
+    getKeysByTag(tag: string): Promise<string[]>;
+    /**
+     * Invalidates a single tag by incrementing its version counter. Every key whose snapshot
+     * references this tag becomes stale immediately. Runs in constant time regardless of how many
+     * keys reference the tag. No-op while the service is disabled.
+     * @param tag - The tag to invalidate.
+     * @returns {Promise<string[]>} A single-element array containing the invalidated tag, or an
+     * empty array while the service is disabled.
+     */
+    invalidateTag(tag: string): Promise<string[]>;
+    /**
+     * Invalidates multiple tags by incrementing each of their version counters in a single batched
+     * store write. Duplicate tags are bumped once. An empty list is a no-op, as is the entire call
+     * while the service is disabled.
+     * @param tags - The tags to invalidate.
+     * @returns {Promise<string[]>} The `tags` argument as provided (including any duplicates), or
+     * an empty array while the service is disabled.
+     */
+    invalidateTags(tags: string[]): Promise<string[]>;
+}
+//# sourceMappingURL=cache-tags.d.ts.map

package/dist/caching/src/utils/cache-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-tags.d.ts","sourceRoot":"","sources":["../../../../src/caching/src/utils/cache-tags.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,KAAK;AAEL,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAO;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA2B;IAErD;;;;OAIG;gBACS,OAAO,EAAE,gBAAgB;IAOrC;;;OAGG;IACH,IAAW,KAAK,IAAI,IAAI,CAEvB;IAED;;;OAGG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;;;OAMG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;OAGG;IACH,IAAW,OAAO,CAAC,OAAO,EAAE,OAAO,EAElC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAId;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAInB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;OAIG;YACW,aAAa;IAK3B;;;;;OAKG;YACW,cAAc;IAY5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAI9B;;;;;;OAMG;YACW,YAAY;IAY1B;;;;;;;;;;OAUG;IACU,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAehG;;;;;;;;;OASG;IACU,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/E;;;;;;;;;OASG;IACU,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnF;;;;;;;;OAQG;IACU,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBtD;;;;;;;;;OASG;IACU,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAStD;;;;;;;;OAQG;IACU,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwC5D;;;;;;OAMG;IACU,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC;IAahE;;;;;;;OAOG;IACU,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBzD;;;;;;;OAOG;IACU,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAU1D;;;;;;;OAOG;IACU,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAoB/D"}

package/dist/caching/src/utils/cache-tags.js

@@ -0,0 +1,407 @@
+/**
+ * Original library: @cacheable/utils (v2.4.2)
+ * - Copyright (c) Jared Wray
+ *
+ * Modified and integrated in "Inray":
+ * - Evgeniy Bushin
+ */
+/***/
+/**
+ * Prefix applied to every store key written by the service so its metadata cannot collide with
+ * user-supplied cache keys.
+ */
+const RESERVED_PREFIX = '--cacheable--tags--';
+/** Namespace used when none is supplied to the constructor. */
+const DEFAULT_NAMESPACE = 'default';
+/**
+ * Provides tag-based cache invalidation on top of any {@link Keyv} store. It is store-agnostic and
+ * requires no adapter changes.
+ *
+ * The service uses a lazy invalidation model rather than scanning and deleting keys. Each tag has a
+ * monotonically increasing version counter; {@link CacheTags.invalidateTag} simply increments
+ * it. When a key is tagged via {@link CacheTags.setKeyTags}, a snapshot of its tags' current
+ * versions is stored alongside it. {@link CacheTags.isKeyFresh} compares that snapshot against
+ * the live versions — if any tag has been incremented since, the key is considered stale. Stale
+ * entries are not deleted explicitly; they are expected to fall out of the cache via their TTL.
+ *
+ * This keeps invalidation constant-time regardless of how many keys reference a tag, at the cost of
+ * one additional `isKeyFresh` read per cache lookup.
+ *
+ * The service can be disabled via the `enabled` option or property so integrations pay no cost for
+ * untagged workloads: while disabled, every method is a no-op — reads return their neutral value
+ * and writes are skipped. The service must be explicitly enabled to use tags; it never enables
+ * itself, which keeps behavior consistent across distributed instances sharing a store.
+ *
+ * All metadata is written under a reserved prefix so it cannot collide with user keys:
+ * - `--cacheable--tags--:<namespace>:tag:<tag>` → integer version counter (stored without TTL).
+ * - `--cacheable--tags--:<namespace>:key:<key>` → the {@link KeyTagEntry} snapshot.
+ *
+ * Note: the read-version-then-write-snapshot sequence in `setKeyTags` is not atomic across
+ * processes. A concurrent `invalidateTag` running between the read and the write can leave a freshly
+ * written key referencing a stale version.
+ *
+ * @example
+ * ```typescript
+ * const cacheTags = new CacheTags({ store: new Keyv(), namespace: 'app' });
+ * await cacheTags.setKeyTags('user:42', ['users', 'org:7'], { ttl: 3600000 });
+ * await cacheTags.isKeyFresh('user:42'); // true
+ * await cacheTags.invalidateTag('users');
+ * await cacheTags.isKeyFresh('user:42'); // false
+ * ```
+ */
+export class CacheTags {
+    _store;
+    _namespace;
+    _enabled;
+    _onError;
+    /**
+     * Creates a new tag service.
+     * @param {CacheTagsOptions} options - The store, optional namespace, enabled state, and
+     * non-blocking error handler to use.
+     */
+    constructor(options) {
+        this._store = options.store;
+        this._namespace = options.namespace ?? DEFAULT_NAMESPACE;
+        this._enabled = options.enabled ?? true;
+        this._onError = options.onError;
+    }
+    /**
+     * The Keyv store backing this service.
+     * @returns {Keyv} The store provided to the constructor.
+     */
+    get store() {
+        return this._store;
+    }
+    /**
+     * The namespace isolating this service's tags and keys within the store.
+     * @returns {string} The configured namespace, or `"default"` if none was provided.
+     */
+    get namespace() {
+        return this._namespace;
+    }
+    /**
+     * Whether the service is enabled. While disabled, every method is a no-op — read methods
+     * return their neutral value and writes are skipped — so integrations pay no extra store
+     * reads for untagged workloads. The service must be explicitly enabled to use tags; it never
+     * enables itself.
+     * @returns {boolean} Whether the service is enabled.
+     */
+    get enabled() {
+        return this._enabled;
+    }
+    /**
+     * Sets whether the service is enabled.
+     * @param {boolean} enabled Whether the service is enabled.
+     */
+    set enabled(enabled) {
+        this._enabled = enabled;
+    }
+    /**
+     * Builds the reserved store key under which a tag's version counter is stored.
+     * @param tag - The tag name.
+     * @returns {string} The namespaced store key for the tag's version.
+     */
+    tagKey(tag) {
+        return `${RESERVED_PREFIX}:${this._namespace}:tag:${tag}`;
+    }
+    /**
+     * Builds the reserved store key under which a cache key's tag snapshot is stored.
+     * @param key - The cache key being tagged.
+     * @returns {string} The namespaced store key for the key's snapshot.
+     */
+    keyEntryKey(key) {
+        return `${RESERVED_PREFIX}:${this._namespace}:key:${key}`;
+    }
+    /**
+     * Builds the common prefix shared by every key-snapshot entry in this namespace. Used to filter
+     * key entries when iterating the store.
+     * @returns {string} The namespaced key-entry prefix.
+     */
+    keyPrefix() {
+        return `${RESERVED_PREFIX}:${this._namespace}:key:`;
+    }
+    /**
+     * Reads the current version of a single tag.
+     * @param tag - The tag name.
+     * @returns {Promise<number>} The tag's version, or `0` if it has never been invalidated.
+     */
+    async getTagVersion(tag) {
+        const version = await this._store.get(this.tagKey(tag));
+        return typeof version === 'number' ? version : 0;
+    }
+    /**
+     * Reads the current versions of multiple tags in a single batched store read.
+     * @param tags - The tag names to look up.
+     * @returns {Promise<number[]>} The versions in the same order as `tags`; entries that have never
+     * been invalidated resolve to `0`. Returns an empty array when `tags` is empty.
+     */
+    async getTagVersions(tags) {
+        if (tags.length === 0) {
+            return [];
+        }
+        const tagKeys = tags.map((tag) => this.tagKey(tag));
+        const raw = await this._store.get(tagKeys);
+        return tags.map((_, i) => {
+            const value = raw?.[i];
+            return typeof value === 'number' ? value : 0;
+        });
+    }
+    /**
+     * Reports a fire-and-forget failure to the `onError` handler, if one was provided.
+     * @param error - The error raised by the non-blocking operation.
+     */
+    handleNonBlockingError(error) {
+        this._onError?.(error);
+    }
+    /**
+     * Reads the version snapshot of each tag and writes the key's tag snapshot to the store.
+     * @param key - The cache key to tag.
+     * @param tags - The tags to associate with the key.
+     * @param ttl - Time-to-live in milliseconds for the snapshot.
+     * @returns {Promise<void>} Resolves once the snapshot has been written.
+     */
+    async writeKeyTags(key, tags, ttl) {
+        const uniqueTags = [...new Set(tags)];
+        const versions = await this.getTagVersions(uniqueTags);
+        const snapshot = {};
+        for (let i = 0; i < uniqueTags.length; i++) {
+            snapshot[uniqueTags[i]] = versions[i];
+        }
+        const entry = { tags: snapshot };
+        await this._store.set(this.keyEntryKey(key), entry, ttl);
+    }
+    /**
+     * Associates a cache key with a set of tags by recording a snapshot of each tag's current
+     * version. Call this whenever you write a fresh value to the cache. Duplicate tags are ignored.
+     * No-op while the service is disabled.
+     * @param key - The cache key to tag.
+     * @param tags - The tags to associate with the key.
+     * @param {SetKeyTagsOptions} [options] - Optional settings, such as a `ttl` for the snapshot or
+     * `nonBlocking` to fire-and-forget the write.
+     * @returns {Promise<void>} Resolves once the snapshot has been written, or immediately when
+     * `nonBlocking` is set.
+     */
+    async setKeyTags(key, tags, options) {
+        if (!this._enabled) {
+            return;
+        }
+        const work = this.writeKeyTags(key, tags, options?.ttl);
+        if (options?.nonBlocking) {
+            work.catch((error) => {
+                this.handleNonBlockingError(error);
+            });
+            return;
+        }
+        await work;
+    }
+    /**
+     * Removes a key's tag snapshot. After this, {@link CacheTags.isKeyFresh} returns `false`
+     * for the key. Use when the cached value itself is deleted. No-op while the service is
+     * disabled.
+     * @param key - The cache key whose snapshot should be removed.
+     * @param {RemoveKeysOptions} [options] - Optional settings, such as `nonBlocking` to
+     * fire-and-forget the removal.
+     * @returns {Promise<void>} Resolves once the snapshot has been deleted, or immediately when
+     * `nonBlocking` is set.
+     */
+    async removeKey(key, options) {
+        await this.removeKeys([key], options);
+    }
+    /**
+     * Removes multiple keys' tag snapshots in a single batched store delete. After this,
+     * {@link CacheTags.isKeyFresh} returns `false` for each key. An empty list is a no-op, as is
+     * the entire call while the service is disabled.
+     * @param keys - The cache keys whose snapshots should be removed.
+     * @param {RemoveKeysOptions} [options] - Optional settings, such as `nonBlocking` to
+     * fire-and-forget the removal.
+     * @returns {Promise<void>} Resolves once the snapshots have been deleted, or immediately when
+     * `nonBlocking` is set.
+     */
+    async removeKeys(keys, options) {
+        if (!this._enabled || keys.length === 0) {
+            return;
+        }
+        const entryKeys = keys.map((key) => this.keyEntryKey(key));
+        const work = this._store.deleteMany(entryKeys);
+        if (options?.nonBlocking) {
+            work.catch((error) => {
+                this.handleNonBlockingError(error);
+            });
+            return;
+        }
+        await work;
+    }
+    /**
+     * Determines whether a key's cached value can still be trusted. A key is fresh only when a
+     * snapshot exists for it and every tag in that snapshot still has the version it had at set time.
+     * A key with no tags is trivially fresh. Call this before returning a value from your cache.
+     * Always returns `true` while the service is disabled.
+     * @param key - The cache key to check.
+     * @returns {Promise<boolean>} `true` if the key is still fresh; `false` if it is unknown or any of
+     * its tags has been invalidated since the snapshot was taken.
+     */
+    async isKeyFresh(key) {
+        if (!this._enabled) {
+            return true;
+        }
+        const entry = await this._store.get(this.keyEntryKey(key));
+        if (!entry?.tags) {
+            return false;
+        }
+        const tags = Object.keys(entry.tags);
+        const currentVersions = await this.getTagVersions(tags);
+        for (let i = 0; i < tags.length; i++) {
+            if (currentVersions[i] !== entry.tags[tags[i]]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Determines whether a key's cached value is known to be stale due to tag invalidation. This is
+     * the complement of {@link CacheTags.isKeyFresh} for tagged keys, but treats keys without a
+     * snapshot as not stale — making it safe to call for every cache lookup, including keys that were
+     * never tagged. Always returns `false` while the service is disabled.
+     * @param key - The cache key to check.
+     * @returns {Promise<boolean>} `true` only when a snapshot exists for the key and at least one of
+     * its tags has been invalidated since the snapshot was taken; `false` otherwise (including when
+     * the key has no snapshot).
+     */
+    async isKeyStale(key) {
+        if (!this._enabled) {
+            return false;
+        }
+        const staleKeys = await this.getStaleKeys([key]);
+        return staleKeys.length > 0;
+    }
+    /**
+     * Determines which of the given keys are known to be stale due to tag invalidation, using two
+     * batched store reads regardless of how many keys are checked: one for the snapshots and one for
+     * the union of their tag versions. Keys without a snapshot are not considered stale. Returns an
+     * empty array while the service is disabled.
+     * @param keys - The cache keys to check.
+     * @returns {Promise<string[]>} The subset of `keys` whose snapshot references at least one tag
+     * that has been invalidated since the snapshot was taken.
+     */
+    async getStaleKeys(keys) {
+        if (!this._enabled || keys.length === 0) {
+            return [];
+        }
+        const entryKeys = keys.map((key) => this.keyEntryKey(key));
+        const entries = await this._store.get(entryKeys);
+        const tagSet = new Set();
+        for (const entry of entries) {
+            if (entry?.tags) {
+                for (const tag of Object.keys(entry.tags)) {
+                    tagSet.add(tag);
+                }
+            }
+        }
+        const tags = [...tagSet];
+        const versions = await this.getTagVersions(tags);
+        const currentVersions = new Map();
+        for (let i = 0; i < tags.length; i++) {
+            currentVersions.set(tags[i], versions[i]);
+        }
+        const staleKeys = [];
+        for (const [i, entry] of entries.entries()) {
+            if (!entry?.tags) {
+                continue;
+            }
+            for (const [tag, version] of Object.entries(entry.tags)) {
+                if (currentVersions.get(tag) !== version) {
+                    staleKeys.push(keys[i]);
+                    break;
+                }
+            }
+        }
+        return staleKeys;
+    }
+    /**
+     * Returns the tags currently associated with a key. Returns `undefined` while the service is
+     * disabled.
+     * @param key - The cache key to look up.
+     * @returns {Promise<string[] | undefined>} The tag names from the key's snapshot, or `undefined`
+     * if the key has no snapshot.
+     */
+    async getTags(key) {
+        if (!this._enabled) {
+            return undefined;
+        }
+        const entry = await this._store.get(this.keyEntryKey(key));
+        if (!entry?.tags) {
+            return undefined;
+        }
+        return Object.keys(entry.tags);
+    }
+    /**
+     * Returns all cache keys whose snapshot references the given tag. This scans every key entry in
+     * the namespace via the Keyv iterator, making it an `O(N)` operation intended for debugging and
+     * tests rather than hot paths. Returns an empty array if the underlying store exposes no iterator
+     * or while the service is disabled.
+     * @param tag - The tag to search for.
+     * @returns {Promise<string[]>} The cache keys (with the reserved prefix stripped) referencing the tag.
+     */
+    async getKeysByTag(tag) {
+        const result = [];
+        if (!this._enabled) {
+            return result;
+        }
+        const prefix = this.keyPrefix();
+        const iterator = this._store.iterator?.(this._store.namespace);
+        if (!iterator) {
+            return result;
+        }
+        for await (const [storedKey, value] of iterator) {
+            if (typeof storedKey !== 'string' || !storedKey.startsWith(prefix)) {
+                continue;
+            }
+            const entry = value;
+            if (entry?.tags && Object.hasOwn(entry.tags, tag)) {
+                result.push(storedKey.slice(prefix.length));
+            }
+        }
+        return result;
+    }
+    /**
+     * Invalidates a single tag by incrementing its version counter. Every key whose snapshot
+     * references this tag becomes stale immediately. Runs in constant time regardless of how many
+     * keys reference the tag. No-op while the service is disabled.
+     * @param tag - The tag to invalidate.
+     * @returns {Promise<string[]>} A single-element array containing the invalidated tag, or an
+     * empty array while the service is disabled.
+     */
+    async invalidateTag(tag) {
+        if (!this._enabled) {
+            return [];
+        }
+        const current = await this.getTagVersion(tag);
+        await this._store.set(this.tagKey(tag), current + 1);
+        return [tag];
+    }
+    /**
+     * Invalidates multiple tags by incrementing each of their version counters in a single batched
+     * store write. Duplicate tags are bumped once. An empty list is a no-op, as is the entire call
+     * while the service is disabled.
+     * @param tags - The tags to invalidate.
+     * @returns {Promise<string[]>} The `tags` argument as provided (including any duplicates), or
+     * an empty array while the service is disabled.
+     */
+    async invalidateTags(tags) {
+        if (!this._enabled) {
+            return [];
+        }
+        const uniqueTags = [...new Set(tags)];
+        if (uniqueTags.length === 0) {
+            return tags;
+        }
+        const versions = await this.getTagVersions(uniqueTags);
+        const kvPairs = [];
+        for (let i = 0; i < uniqueTags.length; i++) {
+            kvPairs.push({ key: this.tagKey(uniqueTags[i]), value: versions[i] + 1 });
+        }
+        await this._store.setMany(kvPairs);
+        return tags;
+    }
+}
+//# sourceMappingURL=cache-tags.js.map