valkyries 0.1.0

package/dist/scripts/get-value-with-ttl.lua

@@ -0,0 +1,35 @@
+-- Get value with TTL operation (with optional bloom filter check)
+-- This script is read-only and is executed using the read client
+-- KEYS[1] = cache key (format: namespace:prefix:{serializedKey})
+-- ARGV[1] = bloom filter key (optional, empty string if not provided)
+-- Returns: {value, ttl_milliseconds, bloom_miss}
+-- Where ttl_milliseconds is -2 if key doesn't exist, -1 if no expiry, or milliseconds remaining
+-- bloom_miss is 1 if bloom filter says key definitely doesn't exist, 0 otherwise
+if #KEYS == 0 then
+  return {}
+end
+
+local cacheKey = KEYS[1]
+local bloomFilterKey = ARGV[1]
+-- Check bloom filter if provided and it exists
+if bloomFilterKey ~= '' then
+  local filterExists = redis.call('EXISTS', bloomFilterKey)
+  if filterExists == 1 then
+    -- Extract the entity key from inside {} (e.g., "cache:posts:{my-uuid}" -> "my-uuid")
+    local entityKey = cacheKey:match('{(.+)}')
+    if entityKey then
+      local bloomExists = redis.call('BF.EXISTS', bloomFilterKey, entityKey)
+      if bloomExists == 0 then
+        -- Bloom filter says this key definitely doesn't exist
+        return {false, -2, 1}
+      end
+    end
+  end
+end
+
+local value = redis.call('GET', cacheKey)
+if not value then
+  return {false, -2, 0}
+end
+local ttl = redis.call('PTTL', cacheKey)
+return {value, ttl, 0}

package/dist/scripts/get-values-with-ttl.lua

@@ -0,0 +1,81 @@
+-- Get values with TTL operation (handles multiple keys with optional bloom filter check)
+-- This script is read-only and is executed using the read client
+-- KEYS[1..n] = cache keys (format: namespace:prefix:{serializedKey})
+-- ARGV[1] = bloom filter key (optional, empty string if not provided)
+-- Returns: {value1, ttl1, bloom_miss1, value2, ttl2, bloom_miss2, ...}
+-- Where ttl is in milliseconds (-2 if key doesn't exist, -1 if no expiry)
+-- bloom_miss is 1 if bloom filter says key definitely doesn't exist, 0 otherwise
+if #KEYS == 0 then
+  return {}
+end
+
+local bloomFilterKey = ARGV[1]
+-- Step 1: Check bloom filter before MGET to avoid fetching known-missing keys.
+-- bloomResults[i] == 0: not in filter = bloom miss
+-- bloomResults[i] == nil: no entity key extracted, skip check = not a bloom miss
+-- bloomResults[i] == 1: in filter = not a bloom miss
+local bloomResults = {}
+if bloomFilterKey ~= '' then
+  local filterExists = redis.call('EXISTS', bloomFilterKey)
+  if filterExists == 1 then
+    local entityKeys = {}
+    local entityKeyIndices = {}
+    for i, key in ipairs(KEYS) do
+      local entityKey = key:match('{(.+)}')
+      if entityKey then
+        table.insert(entityKeys, entityKey)
+        table.insert(entityKeyIndices, i)
+      end
+    end
+    if #entityKeys > 0 then
+      local mexistsResults = redis.call('BF.MEXISTS', bloomFilterKey, unpack(entityKeys))
+      for j, result in ipairs(mexistsResults) do
+        bloomResults[entityKeyIndices[j]] = result
+      end
+    end
+  end
+end
+
+-- Step 2: Collect non-bloom-miss keys to fetch.
+local fetchIndices = {}
+local fetchKeys = {}
+for i, key in ipairs(KEYS) do
+  if bloomResults[i] ~= 0 then
+    table.insert(fetchIndices, i)
+    table.insert(fetchKeys, key)
+  end
+end
+
+-- Step 3: MGET only the non-bloom-miss keys.
+local fetched = {}
+if #fetchKeys > 0 then
+  fetched = redis.call('MGET', unpack(fetchKeys))
+end
+
+-- Map fetched values back to original indices.
+local valuesByIndex = {}
+for j, idx in ipairs(fetchIndices) do
+  valuesByIndex[idx] = fetched[j]
+end
+
+-- Step 4: Build response.
+local response = {}
+for i, key in ipairs(KEYS) do
+  if bloomResults[i] == 0 then
+    -- Bloom miss: key definitely doesn't exist, no MGET or PTTL needed
+    table.insert(response, false)
+    table.insert(response, -2)
+    table.insert(response, 1)
+  else
+    local value = valuesByIndex[i]
+    local ttl = -2
+    if value then
+      ttl = redis.call('PTTL', key)
+    end
+    table.insert(response, value)
+    table.insert(response, ttl)
+    table.insert(response, 0)
+  end
+end
+
+return response

package/dist/scripts/rate-limiter-add-and-check.lua

@@ -0,0 +1,34 @@
+-- Rate limiter add-and-check operation (atomic add + count in one roundtrip)
+-- KEYS[1..N]: the sorted set keys
+-- ARGV[1]: TTL in seconds
+-- ARGV[2..N+1]: random element strings (one per key)
+-- Returns array of counts after adding (same format as rate-limiter-get.lua)
+-- Uses server time to avoid client clock skew
+
+assert(#ARGV == #KEYS + 1, 'ARGV length mismatch: expected #KEYS + 1 (ttl + one random element per key)')
+
+local ttl = tonumber(ARGV[1])
+local currentTime = redis.call('TIME')
+local now = tonumber(currentTime[1]) * 1000 + tonumber(currentTime[2]) / 1000
+local minScore = now - (ttl * 1000)
+
+local response = {}
+for i, key in ipairs(KEYS) do
+  local randomElement = ARGV[1 + i]  -- ARGV[2] for KEYS[1], ARGV[3] for KEYS[2], etc.
+
+  -- Add the current timestamp as the score
+  redis.call('ZADD', key, now, randomElement)
+
+  -- Remove all scores older than the TTL
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', minScore)
+
+  -- Always expire the key after the TTL
+  redis.call('EXPIRE', key, ttl)
+
+  -- Count items in the current window (exclusive lower bound: ZREMRANGEBYSCORE already
+  -- removed entries <= minScore, so use '(' to match only entries that survived cleanup)
+  local count = redis.call('ZCOUNT', key, '(' .. minScore, now)
+  table.insert(response, count)
+end
+
+return response

package/dist/scripts/rate-limiter-add.lua

@@ -0,0 +1,26 @@
+-- Rate limiter add operation (handles multiple keys)
+-- KEYS[1..N]: the sorted set keys
+-- ARGV[1]: TTL in seconds
+-- ARGV[2..N+1]: random element strings (one per key)
+-- Uses server time to avoid client clock skew
+
+local ttl = tonumber(ARGV[1])
+local currentTime = redis.call('TIME')
+local now = tonumber(currentTime[1]) * 1000 + tonumber(currentTime[2]) / 1000
+local minScore = now - (ttl * 1000)
+
+for i, key in ipairs(KEYS) do
+  local randomElement = ARGV[1 + i]  -- ARGV[2] for KEYS[1], ARGV[3] for KEYS[2], etc.
+  
+  -- Add the current timestamp as the score
+  redis.call('ZADD', key, now, randomElement)
+  
+  -- Remove all scores older than the TTL (use -inf for clarity and correctness)
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', minScore)
+  
+  -- Always expire the key after the TTL
+  redis.call('EXPIRE', key, ttl)
+end
+
+return 1
+

package/dist/scripts/rate-limiter-get.lua

@@ -0,0 +1,22 @@
+-- Rate limiter get operation (handles multiple keys)
+-- NOTE: intentionally executed via rateLimiterValkeyClient (primary-only) to avoid
+-- replica lag causing stale counts that could allow rate limit bypasses.
+-- KEYS[1..N]: the sorted set keys
+-- ARGV[1]: TTL in seconds
+-- Uses server time to avoid client clock skew
+
+local ttl = tonumber(ARGV[1])
+local currentTime = redis.call('TIME')
+local now = tonumber(currentTime[1]) * 1000 + tonumber(currentTime[2]) / 1000
+local minScore = now - (ttl * 1000)
+local maxScore = now
+
+local response = {}
+for _, key in ipairs(KEYS) do
+  -- Use exclusive lower bound to match add-and-check.lua behavior at boundary
+  local count = redis.call('ZCOUNT', key, '(' .. minScore, maxScore)
+  table.insert(response, count)
+end
+
+return response
+

package/dist/scripts.d.mts

@@ -0,0 +1,4 @@
+import { Script } from "@valkey/valkey-glide";
+export declare function registerScript(code: string): Script;
+export declare function loadScript(relativePath: string, baseUrl: string | URL): string;
+//# sourceMappingURL=scripts.d.mts.map

package/dist/scripts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.mts","sourceRoot":"","sources":["../scripts.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAoB9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAG9E"}

package/dist/scripts.mjs

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { Script } from "@valkey/valkey-glide";
+const scriptRegistry = [];
+let releaseHookRegistered = false;
+function registerReleaseHook() {
+    if (releaseHookRegistered)
+        return;
+    releaseHookRegistered = true;
+    process.once("exit", () => {
+        for (const script of scriptRegistry) {
+            try {
+                script.release();
+            }
+            catch (err) {
+                // oxlint-disable-next-line no-console -- synchronous; onError queues async Sentry I/O which won't flush in an exit handler
+                console.error(err);
+            }
+        }
+    });
+}
+export function registerScript(code) {
+    registerReleaseHook();
+    const script = new Script(code);
+    scriptRegistry.push(script);
+    return script;
+}
+export function loadScript(relativePath, baseUrl) {
+    const fileUrl = new URL(`./scripts/${relativePath}`, baseUrl);
+    return readFileSync(fileUrl, "utf8");
+}
+//# sourceMappingURL=scripts.mjs.map

package/dist/scripts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.mjs","sourceRoot":"","sources":["../scripts.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,MAAM,cAAc,GAAa,EAAE,CAAC;AACpC,IAAI,qBAAqB,GAAG,KAAK,CAAC;AAElC,SAAS,mBAAmB;IAC1B,IAAI,qBAAqB;QAAE,OAAO;IAClC,qBAAqB,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACxB,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,2HAA2H;gBAC3H,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,mBAAmB,EAAE,CAAC;IACtB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IAChC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,YAAoB,EAAE,OAAqB;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,aAAa,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9D,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC"}

package/dist/shutdown.d.mts

@@ -0,0 +1,3 @@
+export declare const onGracefulShutdown: () => Promise<void>;
+export declare const closeValkeyClients: () => Promise<void>;
+//# sourceMappingURL=shutdown.d.mts.map

package/dist/shutdown.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.mts","sourceRoot":"","sources":["../shutdown.mts"],"names":[],"mappings":"AAMA,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,IAAI,CAkBvD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QApBa,OAAO,CAAC,IAAI,CAoBJ,CAAC"}

package/dist/shutdown.mjs

@@ -0,0 +1,27 @@
+import { urlsToClients, closeDynamicConfigValkeySubscriptionClient } from "./clients.mjs";
+import { dynamicConfigs } from "./dynamic-config.mjs";
+import { handleValkeyError } from "./errors.mjs";
+let shutdown = false;
+export const onGracefulShutdown = async () => {
+    if (shutdown)
+        return;
+    shutdown = true;
+    const configResults = await Promise.allSettled([...dynamicConfigs].map((config) => Promise.resolve().then(() => config.close())));
+    for (const result of configResults) {
+        if (result.status === "rejected")
+            handleValkeyError(toError(result.reason));
+    }
+    const results = await Promise.allSettled([
+        ...[...urlsToClients.values()].map((client) => Promise.resolve().then(() => client.close())),
+        closeDynamicConfigValkeySubscriptionClient(),
+    ]);
+    for (const result of results) {
+        if (result.status === "rejected")
+            handleValkeyError(toError(result.reason));
+    }
+};
+export const closeValkeyClients = onGracefulShutdown;
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+//# sourceMappingURL=shutdown.mjs.map

package/dist/shutdown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.mjs","sourceRoot":"","sources":["../shutdown.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,0CAA0C,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,IAAI,QAAQ,GAAG,KAAK,CAAC;AAErB,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,IAAmB,EAAE;IAC1D,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAEhB,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,UAAU,CAC5C,CAAC,GAAG,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAClF,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU;YAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QACvC,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC5F,0CAA0C,EAAE;KAC7C,CAAC,CAAC;IACH,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU;YAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAErD,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/types.d.mts

@@ -0,0 +1,76 @@
+import type { GlideClient } from "@valkey/valkey-glide";
+export type ValkeyClientsOption = {
+    cacheClient?: GlideClient;
+    rateLimiterClient?: GlideClient;
+    dynamicConfigClient?: GlideClient;
+};
+export type RateLimiterOptions = {
+    /** The prefix to use for the rate limiter */
+    prefix: string;
+    /** The TTL in seconds for the rate limiter */
+    ttlSeconds: number;
+    /** Optional Valkey client. Defaults to the package rate limiter client. */
+    client?: GlideClient;
+};
+export type ValkeyCacheOptions<K = string> = {
+    /** The prefix to use for the cache */
+    prefix: string;
+    /** The TTL in seconds for non-null values */
+    ttlSeconds: number;
+    /** The TTL in seconds for null values, defaults to ttlSeconds / 60 */
+    nullTtlSeconds?: number;
+    /** The mode to use: 'json' (default) for JSON serialization, 'text' for raw text storage, 'buffer' for Buffer storage */
+    mode?: "json" | "text" | "buffer";
+    /** Fraction of ttlSeconds representing the age threshold; values are stale when ttlSecondsRemaining < (1 - staleTtlAge) * ttlSeconds (0-1, defaults to 0.9) */
+    staleTtlAge?: number;
+    /** Optional bloom filter for negative lookups — skip DB calls for entities that definitely don't exist */
+    bloomFilter?: import("./bloom-filter.mts").ValkeyBloomFilter;
+    /** Optional runtime feature flag — if provided, called per-request; bloom filter is bypassed when it returns false */
+    bloomFilterEnabled?: () => boolean;
+    /** Optional Valkey client. Defaults to the package cache client. */
+    client?: GlideClient;
+} & (K extends string ? {
+    /**
+     * Converts a key to its string representation for cache storage.
+     * The returned string is automatically lowercased and trimmed before use.
+     * Defaults to `String(key)` for string keys.
+     */
+    keySerializer?: (key: K) => string;
+} : {
+    /**
+     * Converts a key to its string representation for cache storage.
+     * The returned string is automatically lowercased and trimmed before use.
+     */
+    keySerializer: (key: K) => string;
+});
+export type ValkeyCacheMode = "json" | "text" | "buffer";
+export type ValkeyCacheResponse = Promise<string | Buffer | Record<string, unknown> | null>;
+export type DynamicConfigField = string | number | boolean;
+export type DynamicConfigFieldType = "string" | "number" | "boolean";
+export type DynamicConfigOptions = {
+    /** The TTL in seconds until the values become stale and values are re-fetched */
+    staleTtlSeconds?: number | null;
+    /** The key of the hash to use for the distributed configuration */
+    key: string;
+    /** The fields and types of the hash to use for the distributed configuration */
+    fieldTypes: Record<string, DynamicConfigFieldType>;
+    /** The default field values if not set */
+    defaultFields: Record<string, DynamicConfigField>;
+    /** Optional Valkey client. Defaults to the package dynamic config client. */
+    client?: GlideClient;
+};
+export type ValkeyBloomFilterOptions = {
+    /** The name of the bloom filter (used for key prefixing) */
+    name: string;
+    /** The expected capacity (number of items) */
+    capacity: number;
+    /** The target error rate (0-1, e.g., 0.01 for 1%) */
+    errorRate: number;
+    /** The batch size for bulk operations (optional, defaults to 10,000; Lua paths clamp to 5,000) */
+    batchSize?: number;
+    /** The expansion rate for auto-growth (optional, defaults to 2) */
+    expansionRate?: number;
+    /** Optional Valkey client. Defaults to the package cache client. */
+    client?: GlideClient;
+};
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../types.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC,mBAAmB,CAAC,EAAE,WAAW,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,MAAM,IAAI;IAC3C,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,+JAA+J;IAC/J,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0GAA0G;IAC1G,WAAW,CAAC,EAAE,OAAO,oBAAoB,EAAE,iBAAiB,CAAC;IAC7D,sHAAsH;IACtH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC;IACnC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,CAAC,CAAC,SAAS,MAAM,GACjB;IACE;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;CACpC,GACD;IACE;;;OAGG;IACH,aAAa,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;CACnC,CAAC,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAE5F,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AACrE,MAAM,MAAM,oBAAoB,GAAG;IACjC,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACnD,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAClD,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC"}

package/dist/types.mjs

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

package/dist/types.mjs.map

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

package/dist/utils.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Utility functions for Valkey operations
+ */
+/**
+ * Normalizes TTL result from PTTL command
+ * PTTL returns milliseconds: -2 if key doesn't exist, -1 if no expiry, or milliseconds remaining
+ * Converts to seconds for internal use, preserving sentinel values
+ * valkey-glide returns number or bigint for TTL results
+ */
+export declare function normalizeTtlResult(value: unknown): number | null;
+/**
+ * Normalizes count result from Valkey operations (e.g., ZCOUNT)
+ * valkey-glide returns number or bigint for count results
+ */
+export declare function normalizeCountResult(result: unknown): number;
+//# sourceMappingURL=utils.d.mts.map

package/dist/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","sourceRoot":"","sources":["../utils.mts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWhE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAI5D"}

package/dist/utils.mjs

@@ -0,0 +1,35 @@
+/**
+ * Utility functions for Valkey operations
+ */
+/**
+ * Normalizes TTL result from PTTL command
+ * PTTL returns milliseconds: -2 if key doesn't exist, -1 if no expiry, or milliseconds remaining
+ * Converts to seconds for internal use, preserving sentinel values
+ * valkey-glide returns number or bigint for TTL results
+ */
+export function normalizeTtlResult(value) {
+    if (typeof value === "number") {
+        if (value === -2 || value === -1)
+            return value; // Preserve sentinel values
+        return Math.floor(value / 1000); // Convert milliseconds to seconds
+    }
+    if (typeof value === "bigint") {
+        const num = Number(value);
+        if (num === -2 || num === -1)
+            return num;
+        return Math.floor(num / 1000);
+    }
+    return null;
+}
+/**
+ * Normalizes count result from Valkey operations (e.g., ZCOUNT)
+ * valkey-glide returns number or bigint for count results
+ */
+export function normalizeCountResult(result) {
+    if (typeof result === "number")
+        return result;
+    if (typeof result === "bigint")
+        return Number(result);
+    return 0;
+}
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","sourceRoot":"","sources":["../utils.mts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,2BAA2B;QAC3E,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,kCAAkC;IACrE,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/docs/bloom-filters.md

@@ -0,0 +1,12 @@
+# Bloom Filters
+
+`ValkeyBloomFilter` wraps `BF.RESERVE`, `BF.MADD`, `BF.EXISTS`, and `BF.MEXISTS` with ready-key and zero-downtime rebuild helpers.
+
+Important behavior:
+
+- `exists()` and `mexists()` return `null` when the filter key is missing.
+- `existsIfReady()` and `mexistsIfReady()` also require an external ready marker.
+- `add()` writes to the live key and to the building key when a rebuild is active.
+- `rebuildFromStream()` builds under `bloom-filter:{name}:building` and renames it over the live key.
+
+Large Lua-backed calls are clamped to `LUA_UNPACK_BATCH_SIZE` to avoid Valkey Lua argument limits.

package/docs/cache.md

@@ -0,0 +1,19 @@
+# Cache
+
+`ValkeyCache` provides read-through helpers around Valkey keys named:
+
+```txt
+cache:{prefix}:{serializedKey}
+```
+
+Supported modes:
+
+- `json` stores JSON values and is the default.
+- `text` stores strings only.
+- `buffer` stores `Buffer` values only.
+
+Values larger than 2 KiB are gzip-compressed. Null results are cached with `nullTtlSeconds`, defaulting to `ttlSeconds / 60` with a minimum of 1 second.
+
+`cacheGetByAny()` and `cacheGetByAnyBatch()` protect against stale miss writes by setting short-lived invalidation markers during delete operations.
+
+Optional Bloom filter integration can skip authoritative-store calls for definite misses. If the Bloom filter is unavailable or not ready, cache reads fall back to the normal miss path.

package/docs/clients.md

@@ -0,0 +1,13 @@
+# Clients
+
+The package exports default clients for simple applications:
+
+- `cacheValkeyClient`
+- `rateLimiterValkeyClient`
+- `dynamicConfigValkeyClient`
+
+Connections are deduplicated by URL, read preference, and lazy-connect setting through `upsertValkeyClientByUrl()`.
+
+For libraries, tests, and multi-tenant services, pass a `GlideClient` directly to `ValkeyCache`, `ValkeyBloomFilter`, `DynamicConfig`, or `RateLimiter`.
+
+Use `closeValkeyClients()` or `onGracefulShutdown()` to close package-managed clients and the dynamic-config pub/sub connection.

package/docs/configuration.md

@@ -0,0 +1,16 @@
+# Configuration
+
+`VALKEY_URL` is the default URL for all package-managed clients.
+
+Specialized URLs override it:
+
+- `VALKEY_CACHE_URL`
+- `VALKEY_RATE_LIMITER_URL`
+- `VALKEY_DYNAMIC_CONFIG_URL`
+
+Redis-style URLs are supported:
+
+- `redis://localhost:6379`
+- `rediss://user:password@example.com:6380`
+
+The cache client uses `readFrom: "preferReplica"`. Rate limiter reads use `primary` to avoid replica lag. Dynamic config commands use `preferReplica`; pub/sub uses a dedicated eager connection.

package/docs/dynamic-config.md

@@ -0,0 +1,13 @@
+# Dynamic Config
+
+`DynamicConfig` stores runtime fields in a Valkey hash under:
+
+```txt
+dynamic-config:{key}
+```
+
+Fields are declared with `fieldTypes` and initialized from `defaultFields`. Missing defaults are written during initialization.
+
+Use `setField()` or `setFields()` to update values. Updates are written with a Lua script that performs `HSET` and `PUBLISH` in one roundtrip.
+
+Each instance subscribes to `dynamic-config:*` and applies matching field updates from pub/sub. Call `close()` in tests and shutdown paths to remove handlers and clear refresh timers.

package/docs/events-and-metrics.md

@@ -0,0 +1,15 @@
+# Events And Metrics
+
+Subscribe to `valkeyEvents` for observability.
+
+Events include cache hits/misses, cache writes/deletes, Bloom filter checks/writes, rate limiter operations, and `cache:call` metric payloads.
+
+Errors from background work are sent to the package error handler. Configure it with:
+
+```ts
+import { setValkeyErrorHandler } from "valkyries";
+
+setValkeyErrorHandler((error) => {
+  logger.error(error);
+});
+```

package/docs/lua-scripts.md

@@ -0,0 +1,7 @@
+# Lua Scripts
+
+Lua scripts live in `scripts/` and are copied to `dist/scripts/` during build.
+
+Use `loadScript()` and `registerScript()` for package scripts. Registered scripts are released on process exit.
+
+Scripts are used when operations must be atomic or when combining multiple Valkey commands into one roundtrip.

package/docs/migration.md

@@ -0,0 +1,74 @@
+# Migration Guide
+
+Use this guide when moving existing Valkey-backed cache, Bloom filter, dynamic config, or rate limiter code to `valkyries`.
+
+## Install
+
+```sh
+pnpm add valkyries @valkey/valkey-glide
+```
+
+`valkyries` is ESM-only and requires Node.js 24 or newer.
+
+## Update Imports
+
+Import public classes and helpers from `valkyries` instead of local application modules:
+
+```ts
+import { ValkeyCache, ValkeyBloomFilter, DynamicConfig, RateLimiter } from "valkyries";
+```
+
+Subpath imports are also available:
+
+```ts
+import { ValkeyCache } from "valkyries/cache";
+import { ValkeyBloomFilter } from "valkyries/bloom-filter";
+import { DynamicConfig } from "valkyries/dynamic-config";
+import { RateLimiter } from "valkyries/rate-limiter";
+```
+
+## Configure Connections
+
+The default connection URL is `VALKEY_URL`.
+
+Use specialized URLs when you want separate pools or clusters:
+
+```sh
+VALKEY_CACHE_URL=redis://localhost:6379
+VALKEY_RATE_LIMITER_URL=redis://localhost:6379
+VALKEY_DYNAMIC_CONFIG_URL=redis://localhost:6379
+```
+
+Every primary class also accepts a `client` option for explicit `GlideClient` ownership.
+
+## Review Removed Responsibilities
+
+`valkyries` contains only Valkey data-store primitives:
+
+- Cache helpers
+- Bloom filters
+- Dynamic configuration
+- Rate limiting
+- Shared Valkey clients, events, scripts, and shutdown helpers
+
+Queueing, job orchestration, service-specific metrics backends, and application-specific error reporting should stay in the consuming application.
+
+## Replace Application-Specific Hooks
+
+The package exposes generic hooks for behavior that applications usually customize:
+
+- `setValkeyErrorHandler(handler)` for error reporting
+- `valkeyEvents` / `emitValkeyEvent()` for event and metric collection
+- Per-class `client` options for custom connection lifecycle management
+
+## Validate
+
+Run the package checks locally with a Valkey Bundle instance:
+
+```sh
+docker run --rm -p 6379:6379 valkey/valkey-bundle:latest
+pnpm run typecheck
+pnpm run lint
+pnpm run build
+pnpm run test:coverage
+```

package/docs/rate-limiter.md

@@ -0,0 +1,17 @@
+# Rate Limiter
+
+`RateLimiter` uses sorted sets with server time to implement sliding windows.
+
+Key format:
+
+```txt
+rate-limiter:{prefix}:{id}
+```
+
+Use `addAndCheck(ids, threshold)` for request paths. It atomically adds an event, removes expired events, counts the current window, and returns:
+
+```ts
+{ counts: number[]; limited: boolean }
+```
+
+A threshold of `N` blocks the Nth request because the count is checked after incrementing.