valkyries 0.1.0

package/dist/cache/deletes.mjs

@@ -0,0 +1,44 @@
+import { cacheValkeyClient } from "../clients.mjs";
+import { emitValkeyEvent } from "../events.mjs";
+import { deleteKeysWithPrefix } from "../delete.mjs";
+import { normalizeCountResult } from "../utils.mjs";
+import { CACHE_NAMESPACE, INVALIDATION_MARKER_TTL_SECONDS, cacheDeleteWithInvalidationScript, } from "./constants.mjs";
+import { ValkeyCacheMutations } from "./mutations.mjs";
+export class ValkeyCacheDeletes extends ValkeyCacheMutations {
+    async delete(...keys) {
+        const serializedKeys = [];
+        const keyArray = keys.flatMap((key) => {
+            const serialized = this.toSerializedKey(key);
+            if (serialized === null)
+                return [];
+            serializedKeys.push(serialized);
+            return [this.getSerializedCacheKey(serialized)];
+        });
+        if (keyArray.length === 0)
+            return 0;
+        const invalidationKeys = serializedKeys.map((key) => this.getSerializedInvalidationKey(key));
+        const result = await this.client.invokeScript(cacheDeleteWithInvalidationScript, {
+            keys: [...keyArray, ...invalidationKeys],
+            args: [String(keyArray.length), String(INVALIDATION_MARKER_TTL_SECONDS)],
+        });
+        const count = normalizeCountResult(result);
+        emitValkeyEvent("cache:delete", { cacheName: this.prefix, keys: serializedKeys });
+        return count;
+    }
+    async deleteBySerializedKey(...serializedKeys) {
+        const keyArray = serializedKeys.map((key) => this.getSerializedCacheKey(key));
+        if (keyArray.length === 0)
+            return 0;
+        const count = await this.client.unlink(keyArray);
+        emitValkeyEvent("cache:delete", { cacheName: this.prefix, keys: serializedKeys });
+        return count;
+    }
+    invalidate() {
+        return ValkeyCacheDeletes.invalidate(this.prefix, this.client);
+    }
+    static async invalidate(prefix, client = cacheValkeyClient) {
+        await deleteKeysWithPrefix(client, prefix ? `${CACHE_NAMESPACE}:${prefix}:*` : `${CACHE_NAMESPACE}:*`);
+        emitValkeyEvent("cache:invalidate", { cacheName: prefix });
+    }
+}
+//# sourceMappingURL=deletes.mjs.map

package/dist/cache/deletes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"deletes.mjs","sourceRoot":"","sources":["../../cache/deletes.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EACL,eAAe,EACf,+BAA+B,EAC/B,iCAAiC,GAClC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,OAAO,kBAA+B,SAAQ,oBAAuB;IACzE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAS;QACvB,MAAM,cAAc,GAAa,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YACpC,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,UAAU,KAAK,IAAI;gBAAE,OAAO,EAAE,CAAC;YACnC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACpC,MAAM,gBAAgB,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,4BAA4B,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7F,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,iCAAiC,EAAE;YAC/E,IAAI,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,gBAAgB,CAAC;YACxC,IAAI,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,+BAA+B,CAAC,CAAC;SACzE,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC3C,eAAe,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC;IACf,CAAC;IAES,KAAK,CAAC,qBAAqB,CAAC,GAAG,cAAwB;QAC/D,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACjD,eAAe,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,UAAU;QACR,OAAO,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,MAAM,GAAG,iBAAiB;QAChE,MAAM,oBAAoB,CACxB,MAAM,EACN,MAAM,CAAC,CAAC,CAAC,GAAG,eAAe,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,eAAe,IAAI,CACnE,CAAC;QACF,eAAe,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/cache/mutations.d.mts

@@ -0,0 +1,25 @@
+import { ValkeyCacheBatchRead } from "./batch-read.mts";
+export declare abstract class ValkeyCacheMutations<K = string> extends ValkeyCacheBatchRead<K> {
+    refreshById<T>(aliases: K[], fetchByKey: (key: K) => Promise<T | null | undefined>): Promise<T | null>;
+    set(key: K, value: unknown, ttl?: number): Promise<void>;
+    setBatch(entries: Array<{
+        key: K;
+        value: unknown;
+        ttl?: number;
+    }>): Promise<void>;
+    protected setBySerializedKey(serializedKey: string, value: unknown, ttl?: number): Promise<void>;
+    protected setBySerializedKeyIfNotInvalidated(serializedKey: string, value: unknown, ttl?: number): Promise<void>;
+    protected setBatchIfNotInvalidated(entries: Array<{
+        key: K;
+        value: unknown;
+        ttl?: number;
+    }>): Promise<void>;
+    private setSerializedValue;
+    private setSerializedEntriesIfNotInvalidated;
+    private collectRefreshAliases;
+    private serializeRefreshResult;
+    private withSerializedKeys;
+    private entryTtl;
+    private handleSerializationFailure;
+}
+//# sourceMappingURL=mutations.d.mts.map

package/dist/cache/mutations.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.mts","sourceRoot":"","sources":["../../cache/mutations.mts"],"names":[],"mappings":"AAMA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,8BAAsB,oBAAoB,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;IAC9E,WAAW,CAAC,CAAC,EACjB,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GACpD,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAkCpB,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM;IAMlC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;cA6BvE,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;cAUA,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;cASA,wBAAwB,CACtC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC;IAuBhB,OAAO,CAAC,kBAAkB;YAMZ,oCAAoC;IAoBlD,OAAO,CAAC,qBAAqB;YAYf,sBAAsB;IASpC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,0BAA0B;CAInC"}

package/dist/cache/mutations.mjs

@@ -0,0 +1,181 @@
+import { emitValkeyEvent } from "../events.mjs";
+import { Batch, TimeUnit } from "@valkey/valkey-glide";
+import { handleValkeyError } from "../errors.mjs";
+import { ValkeyCacheTypeError, durationInMilliseconds } from "../cache-utils.mjs";
+import { trackCacheCall } from "../cache-metrics.mjs";
+import { cacheSetIfNotInvalidatedScript } from "./constants.mjs";
+import { ValkeyCacheBatchRead } from "./batch-read.mjs";
+import { emitSetIfNotInvalidatedEvents } from "./set-if-not-invalidated-events.mjs";
+export class ValkeyCacheMutations extends ValkeyCacheBatchRead {
+    async refreshById(aliases, fetchByKey) {
+        const aliasState = this.collectRefreshAliases(aliases);
+        if (aliasState.firstValidAlias === null)
+            return null;
+        const start = process.hrtime.bigint();
+        try {
+            const result = await fetchByKey(aliasState.firstValidAlias);
+            const normalizedResult = result ?? null;
+            const serialized = await this.serializeRefreshResult(normalizedResult);
+            const ttl = normalizedResult === null ? this.nullTtl : this.ttl;
+            const batch = new Batch(false);
+            for (const key of aliasState.serializedKeys) {
+                batch.set(this.getSerializedCacheKey(key), serialized, {
+                    expiry: { type: TimeUnit.Seconds, count: ttl },
+                });
+            }
+            this.client
+                .exec(batch, false)
+                .then(() => {
+                emitValkeyEvent("cache:set", { cacheName: this.prefix, keys: aliasState.serializedKeys });
+            })
+                .catch(handleValkeyError);
+            return normalizedResult;
+        }
+        finally {
+            trackCacheCall({
+                cacheName: this.prefix,
+                batch: false,
+                hits: 0,
+                misses: 1,
+                bloomMisses: 0,
+                duration: durationInMilliseconds(start),
+            });
+        }
+    }
+    set(key, value, ttl) {
+        const serializedKey = this.toSerializedKey(key);
+        if (serializedKey === null)
+            return Promise.resolve();
+        return this.setBySerializedKey(serializedKey, value, ttl);
+    }
+    async setBatch(entries) {
+        const validEntries = this.withSerializedKeys(entries);
+        if (validEntries.length === 0)
+            return;
+        const serializationResults = await Promise.allSettled(validEntries.map((entry) => this.serializeValue(entry.value)));
+        const batch = new Batch(false);
+        const writtenKeys = [];
+        for (let i = 0; i < validEntries.length; i++) {
+            const result = serializationResults[i];
+            if (result.status === "rejected") {
+                this.handleSerializationFailure(result.reason);
+                continue;
+            }
+            const entry = validEntries[i];
+            batch.set(this.getSerializedCacheKey(entry.serializedKey), result.value, {
+                expiry: { type: TimeUnit.Seconds, count: this.entryTtl(entry) },
+            });
+            writtenKeys.push(entry.serializedKey);
+        }
+        if (writtenKeys.length === 0)
+            return;
+        this.client
+            .exec(batch, false)
+            .then(() => {
+            emitValkeyEvent("cache:set", { cacheName: this.prefix, keys: writtenKeys });
+        })
+            .catch(handleValkeyError);
+    }
+    async setBySerializedKey(serializedKey, value, ttl) {
+        try {
+            const serialized = await this.serializeValue(value);
+            await this.setSerializedValue(serializedKey, serialized, ttl);
+            emitValkeyEvent("cache:set", { cacheName: this.prefix, keys: [serializedKey] });
+        }
+        catch (cause) {
+            this.handleSerializationFailure(cause);
+        }
+    }
+    async setBySerializedKeyIfNotInvalidated(serializedKey, value, ttl) {
+        try {
+            const serialized = await this.serializeValue(value);
+            await this.setSerializedEntriesIfNotInvalidated([{ serializedKey, value: serialized, ttl }]);
+        }
+        catch (cause) {
+            this.handleSerializationFailure(cause);
+        }
+    }
+    async setBatchIfNotInvalidated(entries) {
+        const validEntries = this.withSerializedKeys(entries);
+        if (validEntries.length === 0)
+            return;
+        const serializationResults = await Promise.allSettled(validEntries.map((entry) => this.serializeValue(entry.value)));
+        const setEntries = [];
+        for (let i = 0; i < validEntries.length; i++) {
+            const result = serializationResults[i];
+            if (result.status === "rejected") {
+                this.handleSerializationFailure(result.reason);
+                continue;
+            }
+            const entry = validEntries[i];
+            setEntries.push({
+                serializedKey: entry.serializedKey,
+                value: result.value,
+                ttl: this.entryTtl(entry),
+            });
+        }
+        await this.setSerializedEntriesIfNotInvalidated(setEntries);
+    }
+    setSerializedValue(serializedKey, serialized, ttl) {
+        return this.client.set(this.getSerializedCacheKey(serializedKey), serialized, {
+            expiry: { type: TimeUnit.Seconds, count: ttl != null && ttl > 0 ? ttl : this.ttl },
+        });
+    }
+    async setSerializedEntriesIfNotInvalidated(entries) {
+        if (entries.length === 0)
+            return;
+        const keys = [
+            ...entries.map((entry) => this.getSerializedCacheKey(entry.serializedKey)),
+            ...entries.map((entry) => this.getSerializedInvalidationKey(entry.serializedKey)),
+        ];
+        const args = [String(entries.length)];
+        for (const entry of entries) {
+            args.push(String(entry.ttl != null && entry.ttl > 0 ? entry.ttl : this.ttl));
+            args.push(entry.value);
+        }
+        const results = await this.client.invokeScript(cacheSetIfNotInvalidatedScript, {
+            keys,
+            args,
+        });
+        emitSetIfNotInvalidatedEvents(this.prefix, entries, results);
+    }
+    collectRefreshAliases(aliases) {
+        let firstValidAlias = null;
+        const serializedKeySet = new Set();
+        for (const key of aliases) {
+            const serialized = this.toSerializedKey(key);
+            if (serialized === null)
+                continue;
+            firstValidAlias ??= key;
+            serializedKeySet.add(serialized);
+        }
+        return { firstValidAlias, serializedKeys: [...serializedKeySet] };
+    }
+    async serializeRefreshResult(value) {
+        try {
+            return await this.serializeValue(value);
+        }
+        catch (cause) {
+            if (cause instanceof ValkeyCacheTypeError)
+                throw cause;
+            throw new Error("ValkeyCache: failed to stringify and/or compress value", { cause });
+        }
+    }
+    withSerializedKeys(entries) {
+        return entries.flatMap((entry) => {
+            const serializedKey = this.toSerializedKey(entry.key);
+            return serializedKey !== null ? [{ ...entry, serializedKey }] : [];
+        });
+    }
+    entryTtl(entry) {
+        if (entry.ttl != null && entry.ttl > 0)
+            return entry.ttl;
+        return entry.value === null || entry.value === undefined ? this.nullTtl : this.ttl;
+    }
+    handleSerializationFailure(cause) {
+        if (cause instanceof ValkeyCacheTypeError)
+            throw cause;
+        handleValkeyError(cause instanceof Error ? cause : new Error(String(cause)));
+    }
+}
+//# sourceMappingURL=mutations.mjs.map

package/dist/cache/mutations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.mjs","sourceRoot":"","sources":["../../cache/mutations.mts"],"names":[],"mappings":"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"}

package/dist/cache/set-if-not-invalidated-events.d.mts

@@ -0,0 +1,4 @@
+export declare function emitSetIfNotInvalidatedEvents(prefix: string, entries: Array<{
+    serializedKey: string;
+}>, results: unknown): void;
+//# sourceMappingURL=set-if-not-invalidated-events.d.mts.map

package/dist/cache/set-if-not-invalidated-events.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-if-not-invalidated-events.d.mts","sourceRoot":"","sources":["../../cache/set-if-not-invalidated-events.mts"],"names":[],"mappings":"AAEA,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,KAAK,CAAC;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,EACzC,OAAO,EAAE,OAAO,QAoBjB"}

package/dist/cache/set-if-not-invalidated-events.mjs

@@ -0,0 +1,21 @@
+import { emitValkeyEvent } from "../events.mjs";
+export function emitSetIfNotInvalidatedEvents(prefix, entries, results) {
+    const writtenKeys = Array.isArray(results)
+        ? entries.flatMap((entry, index) => {
+            const result = results[index];
+            return result === 1 || result === 1n ? [entry.serializedKey] : [];
+        })
+        : entries.map((entry) => entry.serializedKey);
+    const skippedKeys = Array.isArray(results) && results.length === entries.length
+        ? entries.flatMap((entry, index) => {
+            const result = results[index];
+            return result === 0 || result === 0n ? [entry.serializedKey] : [];
+        })
+        : [];
+    if (writtenKeys.length > 0)
+        emitValkeyEvent("cache:set", { cacheName: prefix, keys: writtenKeys });
+    if (skippedKeys.length > 0) {
+        emitValkeyEvent("cache:set-skipped", { cacheName: prefix, keys: skippedKeys });
+    }
+}
+//# sourceMappingURL=set-if-not-invalidated-events.mjs.map

package/dist/cache/set-if-not-invalidated-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-if-not-invalidated-events.mjs","sourceRoot":"","sources":["../../cache/set-if-not-invalidated-events.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,UAAU,6BAA6B,CAC3C,MAAc,EACd,OAAyC,EACzC,OAAgB;IAEhB,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACxC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9B,OAAO,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,CAAC,CAAC;QACJ,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAChD,MAAM,WAAW,GACf,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;QACzD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9B,OAAO,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,CAAC,CAAC;QACJ,CAAC,CAAC,EAAE,CAAC;IACT,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QACxB,eAAe,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACzE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,eAAe,CAAC,mBAAmB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACjF,CAAC;AACH,CAAC"}

package/dist/cache/single-read.d.mts

@@ -0,0 +1,11 @@
+import type { ValkeyCacheResponse } from "../types.mts";
+import { ValkeyCacheStaleRefresh } from "./stale-refresh.mts";
+export declare abstract class ValkeyCacheSingleRead<K = string> extends ValkeyCacheStaleRefresh<K> {
+    cacheGetByAny<T>(fn: (key: K) => Promise<T | null | undefined>): (key: K) => Promise<T | null>;
+    invalidateCacheGetByAny(...keys: K[]): Promise<number>;
+    getKey(key: K): string;
+    get(key: K): ValkeyCacheResponse;
+    protected trackSingleRead(start: bigint, hits: number, misses: number, bloomMisses: number, serializedKey: string): void;
+    abstract delete(...keys: K[]): Promise<number>;
+}
+//# sourceMappingURL=single-read.d.mts.map

package/dist/cache/single-read.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-read.d.mts","sourceRoot":"","sources":["../../cache/single-read.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAIxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,8BAAsB,qBAAqB,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,uBAAuB,CAAC,CAAC,CAAC;IACxF,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,IAC9C,KAAK,CAAC,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA2C1C,uBAAuB,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE;IAIpC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM;IAMhB,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,mBAAmB;IAOtC,SAAS,CAAC,eAAe,CACvB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM;IAiBvB,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAC/C"}

package/dist/cache/single-read.mjs

@@ -0,0 +1,73 @@
+import { handleValkeyError } from "../errors.mjs";
+import { durationInMilliseconds } from "../cache-utils.mjs";
+import { trackCacheCall } from "../cache-metrics.mjs";
+import { ValkeyCacheStaleRefresh } from "./stale-refresh.mjs";
+export class ValkeyCacheSingleRead extends ValkeyCacheStaleRefresh {
+    cacheGetByAny(fn) {
+        return async (key) => {
+            const serializedKey = this.toSerializedKey(key);
+            if (serializedKey === null)
+                return null;
+            const start = process.hrtime.bigint();
+            let hits = 0;
+            let misses = 0;
+            let bloomMisses = 0;
+            try {
+                const { value: cached, ttlSecondsRemaining, bloomMiss, } = await this.getValueWithTtl(serializedKey);
+                if (bloomMiss) {
+                    bloomMisses = 1;
+                    return null;
+                }
+                const keyExists = ttlSecondsRemaining !== null && ttlSecondsRemaining !== -2;
+                if (cached !== null && cached !== undefined) {
+                    hits = 1;
+                    this.refreshStaleEntry(serializedKey, ttlSecondsRemaining, () => fn(key));
+                    return cached;
+                }
+                if (keyExists) {
+                    hits = 1;
+                    return null;
+                }
+                misses = 1;
+                const result = await fn(key);
+                if (result === undefined || result === null) {
+                    this.setBySerializedKeyIfNotInvalidated(serializedKey, null, this.nullTtl).catch(handleValkeyError);
+                    return null;
+                }
+                this.setBySerializedKeyIfNotInvalidated(serializedKey, result).catch(handleValkeyError);
+                return result;
+            }
+            finally {
+                this.trackSingleRead(start, hits, misses, bloomMisses, serializedKey);
+            }
+        };
+    }
+    invalidateCacheGetByAny(...keys) {
+        return this.delete(...keys);
+    }
+    getKey(key) {
+        const serializedKey = this.toSerializedKey(key);
+        if (serializedKey === null)
+            throw new Error(`ValkeyCache: invalid key: ${String(key)}`);
+        return this.getSerializedCacheKey(serializedKey);
+    }
+    async get(key) {
+        const serializedKey = this.toSerializedKey(key);
+        if (serializedKey === null)
+            return null;
+        const { value } = await this.getValueWithTtl(serializedKey);
+        return value;
+    }
+    trackSingleRead(start, hits, misses, bloomMisses, serializedKey) {
+        trackCacheCall({
+            cacheName: this.prefix,
+            batch: false,
+            hits,
+            misses,
+            bloomMisses,
+            duration: durationInMilliseconds(start),
+        });
+        this.emitCacheEvents(hits > 0 ? [serializedKey] : [], misses > 0 ? [serializedKey] : [], bloomMisses > 0 ? [serializedKey] : []);
+    }
+}
+//# sourceMappingURL=single-read.mjs.map

package/dist/cache/single-read.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-read.mjs","sourceRoot":"","sources":["../../cache/single-read.mts"],"names":[],"mappings":"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"}

package/dist/cache/stale-refresh.d.mts

@@ -0,0 +1,15 @@
+import { ValkeyCacheCore, type CacheEntry } from "./core.mts";
+export declare abstract class ValkeyCacheStaleRefresh<K = string> extends ValkeyCacheCore<K> {
+    protected refreshStaleBatchEntries<T>(serializedKeys: string[], keys: K[], entries: CacheEntry[], batchFn: (keys: K[]) => Promise<Array<T | null | undefined>>): void;
+    protected refreshStaleEntry(serializedKey: string, ttlSecondsRemaining: number | null, fetchValue: () => Promise<unknown>): void;
+    private markRefreshesPending;
+    private refreshBatch;
+    private refreshSingle;
+    protected abstract setBatchIfNotInvalidated(entries: Array<{
+        key: K;
+        value: unknown;
+        ttl?: number;
+    }>): Promise<void>;
+    protected abstract setBySerializedKeyIfNotInvalidated(serializedKey: string, value: unknown, ttl?: number): Promise<void>;
+}
+//# sourceMappingURL=stale-refresh.d.mts.map

package/dist/cache/stale-refresh.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-refresh.d.mts","sourceRoot":"","sources":["../../cache/stale-refresh.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE9D,8BAAsB,uBAAuB,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IAClF,SAAS,CAAC,wBAAwB,CAAC,CAAC,EAClC,cAAc,EAAE,MAAM,EAAE,EACxB,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE,UAAU,EAAE,EACrB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAkB9D,SAAS,CAAC,iBAAiB,CACzB,aAAa,EAAE,MAAM,EACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,EAClC,UAAU,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC;IASpC,OAAO,CAAC,oBAAoB;YAKd,YAAY;YAyBZ,aAAa;IAa3B,SAAS,CAAC,QAAQ,CAAC,wBAAwB,CACzC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC;IAEhB,SAAS,CAAC,QAAQ,CAAC,kCAAkC,CACnD,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;CACjB"}

package/dist/cache/stale-refresh.mjs

@@ -0,0 +1,70 @@
+import { handleValkeyError } from "../errors.mjs";
+import { ValkeyCacheCore } from "./core.mjs";
+export class ValkeyCacheStaleRefresh extends ValkeyCacheCore {
+    refreshStaleBatchEntries(serializedKeys, keys, entries, batchFn) {
+        const staleSerializedKeys = [];
+        const staleKeys = [];
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.value === null || entry.value === undefined)
+                continue;
+            if (!this.shouldRefreshTtl(entry.ttlSecondsRemaining))
+                continue;
+            if (this.refreshPromises.has(serializedKeys[i]))
+                continue;
+            staleSerializedKeys.push(serializedKeys[i]);
+            staleKeys.push(keys[i]);
+        }
+        if (staleSerializedKeys.length === 0)
+            return;
+        this.markRefreshesPending(staleSerializedKeys);
+        const refreshPromise = this.refreshBatch(staleSerializedKeys, staleKeys, batchFn);
+        refreshPromise.catch(handleValkeyError);
+    }
+    refreshStaleEntry(serializedKey, ttlSecondsRemaining, fetchValue) {
+        if (!this.shouldRefreshTtl(ttlSecondsRemaining))
+            return;
+        if (this.refreshPromises.has(serializedKey))
+            return;
+        this.refreshPromises.set(serializedKey, Promise.resolve());
+        const refreshPromise = this.refreshSingle(serializedKey, fetchValue);
+        refreshPromise.catch(handleValkeyError);
+    }
+    markRefreshesPending(serializedKeys) {
+        const sentinel = Promise.resolve();
+        for (const key of serializedKeys)
+            this.refreshPromises.set(key, sentinel);
+    }
+    async refreshBatch(serializedKeys, keys, batchFn) {
+        try {
+            const results = await batchFn(keys);
+            if (!Array.isArray(results) || results.length !== keys.length) {
+                handleValkeyError(new Error(`Stale batch refresh returned invalid result: expected array of ${keys.length} items, got ${Array.isArray(results) ? results.length : typeof results}`));
+                return;
+            }
+            const setEntries = keys.map((key, i) => {
+                const value = results[i] ?? null;
+                return { key, value, ttl: value === null ? this.nullTtl : undefined };
+            });
+            await this.setBatchIfNotInvalidated(setEntries);
+        }
+        finally {
+            for (const key of serializedKeys)
+                this.refreshPromises.delete(key);
+        }
+    }
+    async refreshSingle(serializedKey, fetchValue) {
+        try {
+            const result = await fetchValue();
+            if (result === undefined || result === null) {
+                await this.setBySerializedKeyIfNotInvalidated(serializedKey, null, this.nullTtl);
+                return;
+            }
+            await this.setBySerializedKeyIfNotInvalidated(serializedKey, result);
+        }
+        finally {
+            this.refreshPromises.delete(serializedKey);
+        }
+    }
+}
+//# sourceMappingURL=stale-refresh.mjs.map

package/dist/cache/stale-refresh.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-refresh.mjs","sourceRoot":"","sources":["../../cache/stale-refresh.mts"],"names":[],"mappings":"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"}

package/dist/cache-metrics.d.mts

@@ -0,0 +1,10 @@
+export type CacheCallMetric = {
+    cacheName: string;
+    batch: boolean;
+    hits: number;
+    misses: number;
+    bloomMisses: number;
+    duration: number;
+};
+export declare function trackCacheCall(metric: CacheCallMetric): void;
+//# sourceMappingURL=cache-metrics.d.mts.map

package/dist/cache-metrics.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-metrics.d.mts","sourceRoot":"","sources":["../cache-metrics.mts"],"names":[],"mappings":"AAEA,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAS5D"}

package/dist/cache-metrics.mjs

@@ -0,0 +1,12 @@
+import { emitValkeyEvent } from "./events.mjs";
+export function trackCacheCall(metric) {
+    emitValkeyEvent("cache:call", {
+        cacheName: metric.cacheName,
+        batch: metric.batch,
+        hits: metric.hits,
+        misses: metric.misses,
+        bloomMisses: metric.bloomMisses,
+        durationMs: metric.duration,
+    });
+}
+//# sourceMappingURL=cache-metrics.mjs.map

package/dist/cache-metrics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-metrics.mjs","sourceRoot":"","sources":["../cache-metrics.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAW/C,MAAM,UAAU,cAAc,CAAC,MAAuB;IACpD,eAAe,CAAC,YAAY,EAAE;QAC5B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,QAAQ;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/cache-utils.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Utilities for Valkey cache
+ */
+import type { ValkeyCacheMode } from "./types.mts";
+import type { GlideString } from "@valkey/valkey-glide";
+export declare class ValkeyCacheTypeError extends TypeError {
+    constructor(message: string);
+}
+export declare const durationInMilliseconds: (start: bigint) => number;
+/**
+ * Serialize a value for storage in Valkey cache
+ * Supports text, buffer, and JSON modes with automatic compression
+ */
+export declare function serializeValue(value: unknown, mode: ValkeyCacheMode): Promise<string | Buffer>;
+/**
+ * Decode a value from Valkey cache
+ * Handles decompression and parsing based on mode
+ */
+export declare function decodeValue(result: GlideString | null, mode: ValkeyCacheMode): Promise<string | Buffer | Record<string, unknown> | null>;
+//# sourceMappingURL=cache-utils.d.mts.map

package/dist/cache-utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-utils.d.mts","sourceRoot":"","sources":["../cache-utils.mts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,KAAG,MACF,CAAC;AAMtD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAsB1B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAwB3D"}

package/dist/cache-utils.mjs

@@ -0,0 +1,67 @@
+/**
+ * Utilities for Valkey cache
+ */
+import { gzip, gunzip } from "node:zlib";
+import { promisify } from "node:util";
+export class ValkeyCacheTypeError extends TypeError {
+    constructor(message) {
+        super(`ValkeyCache: ${message}`);
+        this.name = "ValkeyCacheTypeError";
+    }
+}
+export const durationInMilliseconds = (start) => Number(process.hrtime.bigint() - start) / 1_000_000;
+const COMPRESSION_THRESHOLD = 2 * 1024; // 2kb
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+/**
+ * Serialize a value for storage in Valkey cache
+ * Supports text, buffer, and JSON modes with automatic compression
+ */
+export async function serializeValue(value, mode) {
+    let serialized;
+    if (mode === "text") {
+        if (typeof value !== "string") {
+            throw new ValkeyCacheTypeError("text mode requires a string value");
+        }
+        serialized = value;
+    }
+    else if (mode === "buffer") {
+        if (!Buffer.isBuffer(value)) {
+            throw new ValkeyCacheTypeError("buffer mode requires a Buffer value");
+        }
+        serialized = value;
+    }
+    else {
+        serialized = JSON.stringify(value);
+    }
+    if (Buffer.byteLength(serialized) > COMPRESSION_THRESHOLD) {
+        serialized = await gzipAsync(serialized);
+    }
+    return serialized;
+}
+/**
+ * Decode a value from Valkey cache
+ * Handles decompression and parsing based on mode
+ */
+export async function decodeValue(result, mode) {
+    if (result === null)
+        return null;
+    if (!Buffer.isBuffer(result)) {
+        throw new ValkeyCacheTypeError(`Expected Buffer, got ${typeof result}`);
+    }
+    let buffer = result;
+    // Check if buffer is gzipped by looking for gzip magic number (0x1f 0x8b)
+    const isGzipped = buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
+    if (isGzipped) {
+        buffer = await gunzipAsync(buffer);
+    }
+    if (mode === "buffer") {
+        return buffer;
+    }
+    const text = buffer.toString("utf8");
+    if (mode === "text") {
+        return text;
+    }
+    return JSON.parse(text);
+}
+//# sourceMappingURL=cache-utils.mjs.map