valkyries 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# valkyries
+
+Valkey utilities for Node.js services: cache helpers, Bloom filters, dynamic configuration, and sliding-window rate limiting.
+
+## Install
+
+```sh
+pnpm add valkyries @valkey/valkey-glide
+```
+
+`valkyries` is ESM-only and requires Node.js 24 or newer.
+
+## Valkey
+
+By default the package reads `VALKEY_URL`, falling back to `redis://localhost:6379`.
+
+Specialized URLs can split traffic by data type:
+
+```sh
+VALKEY_CACHE_URL=redis://localhost:6379
+VALKEY_RATE_LIMITER_URL=redis://localhost:6379
+VALKEY_DYNAMIC_CONFIG_URL=redis://localhost:6379
+```
+
+Bloom filters require Valkey with the Bloom module. For local development and CI, use Valkey Bundle:
+
+```sh
+docker run --rm -p 6379:6379 valkey/valkey-bundle:latest
+```
+
+## Cache
+
+```ts
+import { ValkeyCache } from "valkyries";
+
+const cache = new ValkeyCache({ prefix: "users", ttlSeconds: 300 });
+
+const getUser = cache.cacheGetByAny(async (id) => {
+  return await loadUserFromDatabase(id);
+});
+
+const user = await getUser("user_123");
+await cache.invalidateCacheGetByAny("user_123");
+```
+
+Cache keys are normalized with `trim().toLowerCase()`. Use `keySerializer` for composite keys.
+
+## Bloom Filters
+
+```ts
+import { ValkeyBloomFilter } from "valkyries";
+
+const filter = new ValkeyBloomFilter({
+  name: "users",
+  capacity: 1_000_000,
+  errorRate: 0.01,
+});
+
+await filter.ensureExists();
+await filter.add(["user_123"]);
+
+const maybeExists = await filter.existsIfReady("users:ready", "user_123");
+```
+
+`null` means the filter is missing or not ready and callers should fall back to the authoritative store.
+
+## Dynamic Config
+
+```ts
+import { DynamicConfig } from "valkyries";
+
+const flags = new DynamicConfig({
+  key: "feature-flags",
+  fieldTypes: { enabled: "boolean", sampleRate: "number" },
+  defaultFields: { enabled: false, sampleRate: 0 },
+});
+
+await flags.waitForInitialization();
+await flags.setField("enabled", true);
+```
+
+Dynamic config stores fields in a Valkey hash and publishes changes over pub/sub.
+
+## Rate Limiter
+
+```ts
+import { RateLimiter } from "valkyries";
+
+const limiter = new RateLimiter({ prefix: "login", ttlSeconds: 60 });
+const { limited, counts } = await limiter.addAndCheck(["ip:127.0.0.1"], 10);
+```
+
+`addAndCheck()` increments first and blocks when any post-add count is greater than or equal to the threshold.
+
+## Client Injection
+
+Every class accepts an optional `GlideClient` for tests or custom connection management:
+
+```ts
+import { GlideClient } from "@valkey/valkey-glide";
+import { ValkeyCache, glideConfigFromUrl } from "valkyries";
+
+const client = await GlideClient.createClient(glideConfigFromUrl("redis://localhost:6379"));
+const cache = new ValkeyCache({ prefix: "custom", ttlSeconds: 60, client });
+```
+
+Call `closeValkeyClients()` to close package-managed clients.
+
+## Documentation
+
+- [Configuration](docs/configuration.md)
+- [Clients](docs/clients.md)
+- [Cache](docs/cache.md)
+- [Bloom filters](docs/bloom-filters.md)
+- [Dynamic config](docs/dynamic-config.md)
+- [Rate limiter](docs/rate-limiter.md)
+- [Events and metrics](docs/events-and-metrics.md)
+- [Lua scripts](docs/lua-scripts.md)
+- [Testing and CI](docs/testing-and-ci.md)
+- [Migration guide](docs/migration.md)

package/dist/bloom-filter/batching.d.mts

@@ -0,0 +1,3 @@
+export declare function luaBatchSize(batchSize: number): number;
+export declare function chunkItems(items: string[], batchSize?: number): Generator<string[]>;
+//# sourceMappingURL=batching.d.mts.map

package/dist/bloom-filter/batching.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching.d.mts","sourceRoot":"","sources":["../../bloom-filter/batching.mts"],"names":[],"mappings":"AAEA,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAiB,UAAU,CACzB,KAAK,EAAE,MAAM,EAAE,EACf,SAAS,GAAE,MAAmC,GAC7C,SAAS,CAAC,MAAM,EAAE,CAAC,CAUrB"}

package/dist/bloom-filter/batching.mjs

@@ -0,0 +1,18 @@
+import { LUA_UNPACK_BATCH_SIZE } from "./scripts.mjs";
+export function luaBatchSize(batchSize) {
+    return Math.min(batchSize, LUA_UNPACK_BATCH_SIZE);
+}
+export function* chunkItems(items, batchSize = luaBatchSize(items.length)) {
+    if (items.length === 0)
+        return;
+    if (items.length <= batchSize) {
+        yield items;
+        return;
+    }
+    for (let i = 0; i < items.length; i += batchSize) {
+        const chunk = items.slice(i, i + batchSize);
+        if (chunk.length > 0)
+            yield chunk;
+    }
+}
+//# sourceMappingURL=batching.mjs.map

package/dist/bloom-filter/batching.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching.mjs","sourceRoot":"","sources":["../../bloom-filter/batching.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,SAAS,CAAC,CAAC,UAAU,CACzB,KAAe,EACf,YAAoB,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC;IAE9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,KAAK,CAAC;QACZ,OAAO;IACT,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;QAC5C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,KAAK,CAAC;IACpC,CAAC;AACH,CAAC"}

package/dist/bloom-filter/lookups.d.mts

@@ -0,0 +1,6 @@
+import type { BloomFilterState } from "./types.mts";
+export declare function exists(state: BloomFilterState, item: string): Promise<boolean | null>;
+export declare function mexists(state: BloomFilterState, items: string[]): Promise<(boolean | null)[]>;
+export declare function existsIfReady(state: BloomFilterState, readyKey: string, item: string): Promise<boolean | null>;
+export declare function mexistsIfReady(state: BloomFilterState, readyKey: string, items: string[]): Promise<(boolean | null)[]>;
+//# sourceMappingURL=lookups.d.mts.map

package/dist/bloom-filter/lookups.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookups.d.mts","sourceRoot":"","sources":["../../bloom-filter/lookups.mts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,wBAAsB,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAiB3F;AAED,wBAAsB,OAAO,CAC3B,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAmB7B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAazB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAuB7B"}

package/dist/bloom-filter/lookups.mjs

@@ -0,0 +1,101 @@
+import { emitValkeyEvent } from "../events.mjs";
+import { handleValkeyError } from "../errors.mjs";
+import { luaBatchSize } from "./batching.mjs";
+import { bloomFilterExistsIfReadyScript, bloomFilterExistsScript, bloomFilterMexistsIfReadyScript, bloomFilterMexistsScript, } from "./scripts.mjs";
+import { normalizeBloomCheckResult } from "./results.mjs";
+export async function exists(state, item) {
+    try {
+        const result = await state.client.invokeScript(bloomFilterExistsScript, {
+            keys: [state.liveKey],
+            args: [item],
+        });
+        if (result === -1 || result === -1n) {
+            emitValkeyEvent("bloom-filter:exists", { name: state.name, item, result: null });
+            return null;
+        }
+        const boolResult = result === 1 || result === 1n;
+        emitValkeyEvent("bloom-filter:exists", { name: state.name, item, result: boolResult });
+        return boolResult;
+    }
+    catch (error) {
+        handleValkeyError(error);
+        return null;
+    }
+}
+export async function mexists(state, items) {
+    if (items.length === 0)
+        return [];
+    const batches = buildBatches(items, luaBatchSize(state.batchSize));
+    try {
+        const batchResults = await Promise.all(batches.map((batchItems) => state.client.invokeScript(bloomFilterMexistsScript, {
+            keys: [state.liveKey],
+            args: batchItems,
+        })));
+        const boolResults = normalizeBatchedResults(batches, batchResults);
+        emitValkeyEvent("bloom-filter:mexists", { name: state.name, items, results: boolResults });
+        return boolResults;
+    }
+    catch (error) {
+        handleValkeyError(error);
+        return items.map(() => null);
+    }
+}
+export async function existsIfReady(state, readyKey, item) {
+    try {
+        const result = await state.client.invokeScript(bloomFilterExistsIfReadyScript, {
+            keys: [readyKey, state.liveKey],
+            args: [item],
+        });
+        const normalized = normalizeBloomCheckResult(result);
+        emitValkeyEvent("bloom-filter:exists", { name: state.name, item, result: normalized });
+        return normalized;
+    }
+    catch (error) {
+        handleValkeyError(error);
+        return null;
+    }
+}
+export async function mexistsIfReady(state, readyKey, items) {
+    if (items.length === 0)
+        return [];
+    const batches = buildBatches(items, luaBatchSize(state.batchSize));
+    try {
+        const batchResults = await Promise.all(batches.map((batchItems) => state.client.invokeScript(bloomFilterMexistsIfReadyScript, {
+            keys: [readyKey, state.liveKey],
+            args: batchItems,
+        })));
+        const normalizedResults = normalizeBatchedResults(batches, batchResults);
+        emitValkeyEvent("bloom-filter:mexists", {
+            name: state.name,
+            items,
+            results: normalizedResults,
+        });
+        return normalizedResults;
+    }
+    catch (error) {
+        handleValkeyError(error);
+        return items.map(() => null);
+    }
+}
+function buildBatches(items, batchSize) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        batches.push(items.slice(i, i + batchSize));
+    }
+    return batches;
+}
+function normalizeBatchedResults(batches, batchResults) {
+    const boolResults = [];
+    for (let i = 0; i < batches.length; i++) {
+        const batchItems = batches[i];
+        const results = batchResults[i];
+        if (!Array.isArray(results)) {
+            boolResults.push(...batchItems.map(() => null));
+        }
+        else {
+            boolResults.push(...results.map(normalizeBloomCheckResult));
+        }
+    }
+    return boolResults;
+}
+//# sourceMappingURL=lookups.mjs.map

package/dist/bloom-filter/lookups.mjs.map

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

package/dist/bloom-filter/rebuilds.d.mts

@@ -0,0 +1,9 @@
+import type { BloomFilterState } from "./types.mts";
+export declare function rebuild(state: BloomFilterState, items: string[]): Promise<void>;
+export declare function rebuildFromStream(state: BloomFilterState, batches: AsyncIterable<string[]>, capacityOverride?: number): Promise<void>;
+export declare function deleteBloomFilter(state: BloomFilterState): Promise<void>;
+export declare function deleteWithAdditionalKeys(state: BloomFilterState, additionalKeys: string[]): Promise<void>;
+export declare function keyExists(state: BloomFilterState): Promise<boolean>;
+export declare function isReady(state: BloomFilterState, readyKey: string): Promise<boolean>;
+export declare function ensureExists(state: BloomFilterState, capacity?: number): Promise<void>;
+//# sourceMappingURL=rebuilds.d.mts.map

package/dist/bloom-filter/rebuilds.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuilds.d.mts","sourceRoot":"","sources":["../../bloom-filter/rebuilds.mts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,wBAAsB,OAAO,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUrF;AAED,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9E;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzE;AAED,wBAAsB,OAAO,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzF;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F"}

package/dist/bloom-filter/rebuilds.mjs

@@ -0,0 +1,66 @@
+import { emitValkeyEvent } from "../events.mjs";
+import { handleValkeyError } from "../errors.mjs";
+import { chunkItems } from "./batching.mjs";
+import { bloomFilterEnsureExistsScript, bloomFilterReserveScript } from "./scripts.mjs";
+export async function rebuild(state, items) {
+    const { batchSize } = state;
+    await rebuildFromStream(state, (async function* () {
+        for (let i = 0; i < items.length; i += batchSize) {
+            yield items.slice(i, i + batchSize);
+        }
+    })());
+}
+export async function rebuildFromStream(state, batches, capacityOverride) {
+    const capacityToUse = capacityOverride ?? state.capacity;
+    await state.client.invokeScript(bloomFilterReserveScript, {
+        keys: [state.buildingKey],
+        args: [state.errorRate.toString(), capacityToUse.toString(), state.expansionRate.toString()],
+    });
+    try {
+        for await (const batch of batches) {
+            let previous = Promise.resolve();
+            for (const chunk of chunkItems(batch, state.batchSize)) {
+                previous = previous.then(async () => {
+                    await state.client.customCommand(["BF.MADD", state.buildingKey, ...chunk]);
+                    emitValkeyEvent("bloom-filter:add", { name: state.name, items: chunk });
+                });
+            }
+            await previous;
+        }
+        await state.client.rename(state.buildingKey, state.liveKey);
+    }
+    catch (error) {
+        await cleanupBuildingKey(state);
+        throw error;
+    }
+}
+export async function deleteBloomFilter(state) {
+    await state.client.unlink([state.liveKey, state.buildingKey]);
+}
+export async function deleteWithAdditionalKeys(state, additionalKeys) {
+    await state.client.unlink([state.liveKey, state.buildingKey, ...additionalKeys]);
+}
+export async function keyExists(state) {
+    const result = await state.client.customCommand(["EXISTS", state.liveKey]);
+    return result === 1 || result === 1n;
+}
+export async function isReady(state, readyKey) {
+    const result = await state.client.customCommand(["EXISTS", readyKey, state.liveKey]);
+    return result === 2 || result === 2n;
+}
+export async function ensureExists(state, capacity) {
+    const capacityToUse = capacity ?? state.capacity;
+    await state.client.invokeScript(bloomFilterEnsureExistsScript, {
+        keys: [state.liveKey],
+        args: [state.errorRate.toString(), capacityToUse.toString(), state.expansionRate.toString()],
+    });
+}
+async function cleanupBuildingKey(state) {
+    try {
+        await state.client.unlink([state.buildingKey]);
+    }
+    catch (cleanupError) {
+        handleValkeyError(cleanupError);
+    }
+}
+//# sourceMappingURL=rebuilds.mjs.map

package/dist/bloom-filter/rebuilds.mjs.map

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

package/dist/bloom-filter/results.d.mts

@@ -0,0 +1,3 @@
+export declare function normalizeBloomCheckResult(value: unknown): boolean | null;
+export declare function isBloomMissingKeyError(error: unknown): boolean;
+//# sourceMappingURL=results.d.mts.map

package/dist/bloom-filter/results.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.mts","sourceRoot":"","sources":["../../bloom-filter/results.mts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAMxE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAU9D"}

package/dist/bloom-filter/results.mjs

@@ -0,0 +1,23 @@
+export function normalizeBloomCheckResult(value) {
+    if (value === -1 || value === -1n)
+        return null;
+    if (value === null || value === undefined)
+        return null;
+    if (value === true || value === 1 || value === 1n)
+        return true;
+    if (value === false || value === 0 || value === 0n)
+        return false;
+    return null;
+}
+export function isBloomMissingKeyError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const message = error.message.toLowerCase();
+    if (!message.includes("bf.madd"))
+        return false;
+    return (message.includes("not found") ||
+        message.includes("does not exist") ||
+        message.includes("missing") ||
+        message.includes("no such key"));
+}
+//# sourceMappingURL=results.mjs.map

package/dist/bloom-filter/results.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.mjs","sourceRoot":"","sources":["../../bloom-filter/results.mts"],"names":[],"mappings":"AAAA,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,CACL,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAChC,CAAC;AACJ,CAAC"}

package/dist/bloom-filter/scripts.d.mts

@@ -0,0 +1,9 @@
+export declare const bloomFilterExistsScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterMexistsScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterExistsIfReadyScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterMexistsIfReadyScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterAddScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterReserveScript: import("@valkey/valkey-glide").Script;
+export declare const bloomFilterEnsureExistsScript: import("@valkey/valkey-glide").Script;
+export declare const LUA_UNPACK_BATCH_SIZE = 5000;
+//# sourceMappingURL=scripts.d.mts.map

package/dist/bloom-filter/scripts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.mts","sourceRoot":"","sources":["../../bloom-filter/scripts.mts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,uCAEnC,CAAC;AACF,eAAO,MAAM,wBAAwB,uCAEpC,CAAC;AACF,eAAO,MAAM,8BAA8B,uCAE1C,CAAC;AACF,eAAO,MAAM,+BAA+B,uCAE3C,CAAC;AACF,eAAO,MAAM,oBAAoB,uCAEhC,CAAC;AACF,eAAO,MAAM,wBAAwB,uCAEpC,CAAC;AACF,eAAO,MAAM,6BAA6B,uCAEzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,OAAQ,CAAC"}

package/dist/bloom-filter/scripts.mjs

@@ -0,0 +1,10 @@
+import { loadScript, registerScript } from "../scripts.mjs";
+export const bloomFilterExistsScript = registerScript(loadScript("bloom-filter-exists.lua", new URL("../", import.meta.url)));
+export const bloomFilterMexistsScript = registerScript(loadScript("bloom-filter-mexists.lua", new URL("../", import.meta.url)));
+export const bloomFilterExistsIfReadyScript = registerScript(loadScript("bloom-filter-exists-if-ready.lua", new URL("../", import.meta.url)));
+export const bloomFilterMexistsIfReadyScript = registerScript(loadScript("bloom-filter-mexists-if-ready.lua", new URL("../", import.meta.url)));
+export const bloomFilterAddScript = registerScript(loadScript("bloom-filter-add.lua", new URL("../", import.meta.url)));
+export const bloomFilterReserveScript = registerScript(loadScript("bloom-filter-reserve.lua", new URL("../", import.meta.url)));
+export const bloomFilterEnsureExistsScript = registerScript(loadScript("bloom-filter-ensure-exists.lua", new URL("../", import.meta.url)));
+export const LUA_UNPACK_BATCH_SIZE = 5_000;
+//# sourceMappingURL=scripts.mjs.map

package/dist/bloom-filter/scripts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.mjs","sourceRoot":"","sources":["../../bloom-filter/scripts.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,cAAc,CACnD,UAAU,CAAC,yBAAyB,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACvE,CAAC;AACF,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CACpD,UAAU,CAAC,0BAA0B,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACxE,CAAC;AACF,MAAM,CAAC,MAAM,8BAA8B,GAAG,cAAc,CAC1D,UAAU,CAAC,kCAAkC,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAChF,CAAC;AACF,MAAM,CAAC,MAAM,+BAA+B,GAAG,cAAc,CAC3D,UAAU,CAAC,mCAAmC,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACjF,CAAC;AACF,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAChD,UAAU,CAAC,sBAAsB,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACpE,CAAC;AACF,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CACpD,UAAU,CAAC,0BAA0B,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACxE,CAAC;AACF,MAAM,CAAC,MAAM,6BAA6B,GAAG,cAAc,CACzD,UAAU,CAAC,gCAAgC,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAC9E,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC"}

package/dist/bloom-filter/types.d.mts

@@ -0,0 +1,12 @@
+import type { GlideClient } from "@valkey/valkey-glide";
+export type BloomFilterState = {
+    name: string;
+    capacity: number;
+    errorRate: number;
+    expansionRate: number;
+    batchSize: number;
+    liveKey: string;
+    buildingKey: string;
+    client: GlideClient;
+};
+//# sourceMappingURL=types.d.mts.map

package/dist/bloom-filter/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../bloom-filter/types.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC"}

package/dist/bloom-filter/types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/bloom-filter/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../../bloom-filter/types.mts"],"names":[],"mappings":""}

package/dist/bloom-filter/writes.d.mts

@@ -0,0 +1,5 @@
+import type { BloomFilterState } from "./types.mts";
+export declare function add(state: BloomFilterState, items: string[]): Promise<void>;
+export declare function addOrThrow(state: BloomFilterState, items: string[]): Promise<void>;
+export declare function addStream(state: BloomFilterState, batches: AsyncIterable<string[]>): Promise<void>;
+//# sourceMappingURL=writes.d.mts.map

package/dist/bloom-filter/writes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writes.d.mts","sourceRoot":"","sources":["../../bloom-filter/writes.mts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,wBAAgB,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3E;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxF;AAED,wBAAsB,SAAS,CAC7B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/bloom-filter/writes.mjs

@@ -0,0 +1,54 @@
+import { emitValkeyEvent } from "../events.mjs";
+import { handleValkeyError } from "../errors.mjs";
+import { chunkItems, luaBatchSize } from "./batching.mjs";
+import { bloomFilterAddScript } from "./scripts.mjs";
+export function add(state, items) {
+    if (items.length === 0)
+        return Promise.resolve();
+    return Promise.all(addCommands(state, items))
+        .then((results) => {
+        if (results.some(wroteFilter)) {
+            emitValkeyEvent("bloom-filter:add", { name: state.name, items });
+        }
+    })
+        .catch(handleValkeyError);
+}
+export async function addOrThrow(state, items) {
+    if (items.length === 0)
+        return;
+    const results = await Promise.all(addCommands(state, items));
+    if (results.some(wroteFilter)) {
+        emitValkeyEvent("bloom-filter:add", { name: state.name, items });
+    }
+}
+export async function addStream(state, batches) {
+    for await (const batch of batches) {
+        let previous = Promise.resolve();
+        for (const chunk of chunkItems(batch, luaBatchSize(state.batchSize))) {
+            previous = previous.then(async () => {
+                const result = await state.client.invokeScript(bloomFilterAddScript, {
+                    keys: [state.liveKey, state.buildingKey],
+                    args: chunk,
+                });
+                if (wroteFilter(result)) {
+                    emitValkeyEvent("bloom-filter:add", { name: state.name, items: chunk });
+                }
+            });
+        }
+        await previous;
+    }
+}
+function addCommands(state, items) {
+    const cmds = [];
+    for (const chunk of chunkItems(items, luaBatchSize(state.batchSize))) {
+        cmds.push(state.client.invokeScript(bloomFilterAddScript, {
+            keys: [state.liveKey, state.buildingKey],
+            args: chunk,
+        }));
+    }
+    return cmds;
+}
+function wroteFilter(result) {
+    return result === 1 || result === 1n;
+}
+//# sourceMappingURL=writes.mjs.map

package/dist/bloom-filter/writes.mjs.map

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

package/dist/bloom-filter.d.mts

@@ -0,0 +1,90 @@
+import type { ValkeyBloomFilterOptions } from "./types.mts";
+export { LUA_UNPACK_BATCH_SIZE } from "./bloom-filter/scripts.mts";
+export { isBloomMissingKeyError, normalizeBloomCheckResult } from "./bloom-filter/results.mts";
+export declare class ValkeyBloomFilter {
+    private name;
+    private capacity;
+    private errorRate;
+    private expansionRate;
+    private batchSize;
+    private liveKey;
+    private buildingKey;
+    private client;
+    constructor(options: ValkeyBloomFilterOptions);
+    /**
+     * BF.EXISTS — check if a single item may be in the filter.
+     * Returns null if filter doesn't exist (caller should fall back to DB).
+     * Single roundtrip via Lua script (EXISTS + BF.EXISTS combined).
+     */
+    exists(item: string): Promise<boolean | null>;
+    /**
+     * BF.MEXISTS — check multiple items in the filter.
+     * Returns null per-item if filter doesn't exist (caller should fall back to DB).
+     * Single roundtrip via Lua script (EXISTS + BF.MEXISTS combined).
+     */
+    mexists(items: string[]): Promise<(boolean | null)[]>;
+    /**
+     * BF.EXISTS guarded by a deterministic readiness key.
+     * Returns null when the ready marker or filter is absent, so callers fall back
+     * to their authoritative store instead of trusting an empty/partial filter.
+     */
+    existsIfReady(readyKey: string, item: string): Promise<boolean | null>;
+    /**
+     * BF.MEXISTS guarded by a deterministic readiness key.
+     * Returns null per item when the ready marker or filter is absent.
+     */
+    mexistsIfReady(readyKey: string, items: string[]): Promise<(boolean | null)[]>;
+    /**
+     * Add items to bloom filter using BF.MADD. Returns a Promise that resolves when all
+     * batches are written (errors are logged via onError, not thrown).
+     * Items are chunked at batchSize to avoid hitting Valkey argument-count limits.
+     * Each chunk is a single Lua round-trip that also writes to buildingKey if an
+     * active rebuild is in progress, so entries are not silently dropped when
+     * rebuildFromStream renames buildingKey → liveKey.
+     *
+     * If neither the live key nor the building key exists (e.g. during the window
+     * between worker startup and backfill completion), add() is a no-op. This prevents
+     * BF.MADD from auto-creating an under-provisioned filter that would cause false
+     * negatives in cache reads. See backfill-bloom-filter.mts for the warmup design.
+     */
+    add(items: string[]): Promise<void>;
+    /**
+     * Add items to bloom filter — same as add(), but throws on error instead of absorbing via onError.
+     * Use when the caller needs to detect failures and take corrective action (e.g. clearing readiness).
+     */
+    addOrThrow(items: string[]): Promise<void>;
+    /**
+     * Awaitable add — streams batches from an AsyncIterable and BF.MADDs each batch.
+     * Use for large-dataset population to avoid loading everything into memory.
+     * Unlike add(), errors are propagated (not absorbed via onError).
+     */
+    addStream(batches: AsyncIterable<string[]>): Promise<void>;
+    /**
+     * Rebuild the filter from a complete item list. Uses building key and atomic rename.
+     * Only deletes the building key at start (not the live key).
+     */
+    rebuild(items: string[]): Promise<void>;
+    /**
+     * Rebuild the filter from an async iterable of item batches. Uses building key and atomic rename.
+     * Only deletes the building key at start (not the live key).
+     * @param capacityOverride - Optional capacity for this rebuild, such as 2x the current row count.
+     */
+    rebuildFromStream(batches: AsyncIterable<string[]>, capacityOverride?: number): Promise<void>;
+    delete(): Promise<void>;
+    deleteWithAdditionalKeys(additionalKeys: string[]): Promise<void>;
+    keyExists(): Promise<boolean>;
+    isReady(readyKey: string): Promise<boolean>;
+    getKey(): string;
+    getBuildingKey(): string;
+    getConfig(): {
+        name: string;
+        capacity: number;
+        errorRate: number;
+        batchSize: number;
+        liveKey: string;
+        buildingKey: string;
+    };
+    ensureExists(capacity?: number): Promise<void>;
+    private state;
+}
+//# sourceMappingURL=bloom-filter.d.mts.map