valkyries 0.9.0 → 0.10.0

package/README.md

@@ -126,7 +126,7 @@ const client = await GlideClient.createClient(glideConfigFromUrl("redis://localh
 const cache = new ValkeyCache({ prefix: "custom", ttlSeconds: 60, client });
 ```
 
-Call `closeValkeyClients()` to close package-managed clients.
+Call `closeValkeyClients()` to close package-managed clients. Pass `{ throwOnError: true }` to reject with an `AggregateError` if any close fails.
 
 ## Scan and Unlink Keys
 
@@ -146,6 +146,16 @@ The result reports `scannedKeys`, `matchedKeys`, and keys confirmed removed by `
 `unlinkedKeys`. `SCAN` is non-snapshot, so these counts can include duplicates or omit keys while
 the keyspace changes.
 
+Use `scanAndUnlinkKeyPrefixes()` to flush several literal prefixes serially. Prefixes are
+glob-escaped, later prefixes still run after a failure, and several failures are combined into an
+`AggregateError` that reports `unlinkedKeys`:
+
+```ts
+const { unlinkedKeys } = await scanAndUnlinkKeyPrefixes(client, ["cache:users:", "cache:teams:"], {
+  signal: abortController.signal,
+});
+```
+
 ## Expire Keys Without a TTL
 
 Use `expireKeysWithNoExpiry()` to apply a TTL only when matching keys still have no expiry:
@@ -181,6 +191,7 @@ include duplicates or omit keys while the keyspace changes. `scanCount` is a SCA
 - [Conditional operations](docs/conditional-operations.md)
 - [Events and metrics](docs/events-and-metrics.md)
 - [Lua scripts](docs/lua-scripts.md)
+- [Diagnostics](docs/diagnostics.md)
 - [Utilities](docs/utilities.md)
 - [Testing and CI](docs/testing-and-ci.md)
 - [Migration guide](docs/migration.md)

package/dist/delete.d.mts

@@ -8,4 +8,16 @@ export declare function deleteKeysWithLiteralPrefixes(client: ScanAndUnlinkKeysC
  * omit keys, or differ from the number of keys that exist when this function returns.
  */
 export declare function scanAndUnlinkKeys(client: ScanAndUnlinkKeysClient, pattern: string, { signal, matches }?: ScanAndUnlinkKeysOptions): Promise<ScanAndUnlinkKeysResult>;
+export type ScanAndUnlinkKeyPrefixesResult = {
+    unlinkedKeys: number;
+};
+/**
+ * Unlinks every key that starts with any of the literal prefixes, scanning one prefix at a time.
+ *
+ * Each prefix is glob-escaped, so `*`, `?`, `[`, `]` and `\` match literally. A failing prefix does
+ * not stop later prefixes. One failure is rethrown as-is; several are combined into an
+ * `AggregateError` with an `unlinkedKeys` property. Failures reach the Valkey error handler once,
+ * through `scanAndUnlinkKeys`. An aborted `signal` rethrows its exact reason immediately.
+ */
+export declare function scanAndUnlinkKeyPrefixes(client: ScanAndUnlinkKeysClient, prefixes: readonly string[], options?: ScanAndUnlinkKeysOptions): Promise<ScanAndUnlinkKeyPrefixesResult>;
 //# sourceMappingURL=delete.d.mts.map

package/dist/delete.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"delete.d.mts","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,EACf,EAAE,MAAM,EAAE,OAAoB,EAAE,GAAE,wBAA6B,GAC9D,OAAO,CAAC,uBAAuB,CAAC,CA4BlC"}
+{"version":3,"file":"delete.d.mts","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,MAAM,EACf,EAAE,MAAM,EAAE,OAAoB,EAAE,GAAE,wBAA6B,GAC9D,OAAO,CAAC,uBAAuB,CAAC,CA4BlC;AAED,MAAM,MAAM,8BAA8B,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAMtE;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,8BAA8B,CAAC,CAiCzC"}

package/dist/delete.mjs

@@ -46,4 +46,43 @@ export async function scanAndUnlinkKeys(client, pattern, { signal, matches = ()
         throw err;
     }
 }
+function escapeGlobLiteral(value) {
+    return value.replace(/[\\*?[\]]/g, "\\$&");
+}
+/**
+ * Unlinks every key that starts with any of the literal prefixes, scanning one prefix at a time.
+ *
+ * Each prefix is glob-escaped, so `*`, `?`, `[`, `]` and `\` match literally. A failing prefix does
+ * not stop later prefixes. One failure is rethrown as-is; several are combined into an
+ * `AggregateError` with an `unlinkedKeys` property. Failures reach the Valkey error handler once,
+ * through `scanAndUnlinkKeys`. An aborted `signal` rethrows its exact reason immediately.
+ */
+export async function scanAndUnlinkKeyPrefixes(client, prefixes, options = {}) {
+    for (const prefix of prefixes) {
+        if (typeof prefix !== "string" || prefix === "") {
+            throw new TypeError("scanAndUnlinkKeyPrefixes prefixes must be non-empty strings");
+        }
+    }
+    const { signal } = options;
+    const failures = [];
+    let unlinkedKeys = 0;
+    for (const prefix of new Set(prefixes)) {
+        throwIfAborted(signal);
+        try {
+            const result = await scanAndUnlinkKeys(client, `${escapeGlobLiteral(prefix)}*`, options);
+            unlinkedKeys += result.unlinkedKeys;
+        }
+        catch (err) {
+            if (signal?.aborted && err === signal.reason)
+                throw err;
+            failures.push(err);
+        }
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1) {
+        throw Object.assign(new AggregateError(failures, `${failures.length} prefix scans failed after unlinking ${unlinkedKeys} keys`), { unlinkedKeys });
+    }
+    return { unlinkedKeys };
+}
 //# sourceMappingURL=delete.mjs.map

package/dist/delete.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"delete.mjs","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAO/E,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAA+B,EAC/B,OAAe;IAEf,MAAM,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAA+B,EAC/B,OAAe,EACf,QAA2B;IAE3B,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,CAAU,QAAQ,CAAC,CAAC,CAAC,MAAM,CAC3D,CAAC,MAAM,EAAoB,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,CACzD,CAAC;IACF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAExC,MAAM,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE;QACvC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;KAC/F,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAA+B,EAC/B,OAAe,EACf,EAAE,MAAM,EAAE,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAA6B,EAAE;IAE/D,IAAI,CAAC;QACH,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE;YACxD,KAAK,EAAE,kBAAkB;YACzB,MAAM;SACP,CAAC,EAAE,CAAC;YACH,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;YAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACrC,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC;YAE3B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,cAAc,CAAC,MAAM,CAAC,CAAC;gBACvB,YAAY,IAAI,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC1C,cAAc,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,MAAM,EAAE,OAAO,IAAI,GAAG,KAAK,MAAM,CAAC,MAAM;YAAE,MAAM,GAAG,CAAC;QACxD,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"delete.mjs","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"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"}

package/dist/diagnostics.d.mts

@@ -0,0 +1,37 @@
+import { type GlideClient } from "@valkey/valkey-glide";
+export type ValkeyMemorySummary = {
+    usedMemoryBytes: number;
+    usedMemoryRssBytes: number;
+    usedMemoryPeakBytes: number;
+    maxmemoryBytes: number;
+    maxmemoryPolicy: string;
+    usedMemoryDatasetBytes: number | null;
+    lazyfreePendingObjects: number | null;
+    memFragmentationRatio: number | null;
+};
+export type DiagnosticsOptions = {
+    signal?: AbortSignal;
+};
+export type CountKeysByPrefixOptions = DiagnosticsOptions & {
+    /** SCAN COUNT hint per page. Defaults to 500. */
+    count?: number;
+};
+/**
+ * Parses `INFO memory` output (CRLF or LF, `#` section headers) into typed numbers.
+ * Throws when a required field is missing or any present numeric field is malformed.
+ */
+export declare function parseValkeyMemoryInfo(info: string): ValkeyMemorySummary;
+/** Runs `INFO memory` and parses it. Checks `signal` before and after the command. */
+export declare function getValkeyMemoryInfo(client: Pick<GlideClient, "info">, { signal }?: DiagnosticsOptions): Promise<ValkeyMemorySummary>;
+/**
+ * Rejects empty prefixes, a group named `unclassified`, and prefixes that overlap across
+ * groups (identical, or one a prefix of another), so every key belongs to at most one group.
+ */
+export declare function validateKeyPrefixRegistry(prefixes: Record<string, readonly string[]>): void;
+/**
+ * Counts keys per prefix group with bounded SCAN pages. Keys matching no prefix are counted as
+ * `unclassified`. SCAN is non-snapshot, so counts may include duplicates or miss keys written
+ * during the walk. `signal` is checked before and after each page.
+ */
+export declare function countKeysByPrefix<G extends string>(client: Pick<GlideClient, "scan">, prefixes: Record<G, readonly string[]>, { signal, count }?: CountKeysByPrefixOptions): Promise<Record<G | "unclassified", number>>;
+//# sourceMappingURL=diagnostics.d.mts.map

package/dist/diagnostics.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.mts","sourceRoot":"","sources":["../diagnostics.mts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMrE,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA4BF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAsBvE;AAED,sFAAsF;AACtF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EACjC,EAAE,MAAM,EAAE,GAAE,kBAAuB,GAClC,OAAO,CAAC,mBAAmB,CAAC,CAK9B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAAG,IAAI,CAmB3F;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EACtD,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EACjC,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,EACtC,EAAE,MAAM,EAAE,KAA0B,EAAE,GAAE,wBAA6B,GACpE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,cAAc,EAAE,MAAM,CAAC,CAAC,CAc7C"}

package/dist/diagnostics.mjs

@@ -0,0 +1,104 @@
+import { InfoOptions } from "@valkey/valkey-glide";
+import { glideStringToString, scanKeyPages, throwIfAborted } from "./scan.mjs";
+const DEFAULT_SCAN_COUNT = 500;
+const UNCLASSIFIED = "unclassified";
+function parseFields(info) {
+    const fields = new Map();
+    for (const raw of info.split("\n")) {
+        const line = raw.trim();
+        const separator = line.indexOf(":");
+        if (line.startsWith("#") || separator < 0)
+            continue;
+        fields.set(line.slice(0, separator), line.slice(separator + 1));
+    }
+    return fields;
+}
+function parseInteger(name, value) {
+    const parsed = Number(value);
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(parsed)) {
+        throw new Error(`INFO field ${name} is not a non-negative safe integer: ${value}`);
+    }
+    return parsed;
+}
+function parseRatio(name, value) {
+    if (!/^\d+(\.\d+)?$/.test(value) || !Number.isFinite(Number(value))) {
+        throw new Error(`INFO field ${name} is not a non-negative number: ${value}`);
+    }
+    return Number(value);
+}
+/**
+ * Parses `INFO memory` output (CRLF or LF, `#` section headers) into typed numbers.
+ * Throws when a required field is missing or any present numeric field is malformed.
+ */
+export function parseValkeyMemoryInfo(info) {
+    const fields = parseFields(info);
+    const required = (name) => {
+        const value = fields.get(name);
+        if (!value)
+            throw new Error(`INFO field ${name} is missing`);
+        return value;
+    };
+    const optional = (name, parse) => {
+        const value = fields.get(name);
+        return value === undefined ? null : parse(name, value);
+    };
+    return {
+        usedMemoryBytes: parseInteger("used_memory", required("used_memory")),
+        usedMemoryRssBytes: parseInteger("used_memory_rss", required("used_memory_rss")),
+        usedMemoryPeakBytes: parseInteger("used_memory_peak", required("used_memory_peak")),
+        maxmemoryBytes: parseInteger("maxmemory", required("maxmemory")),
+        maxmemoryPolicy: required("maxmemory_policy"),
+        usedMemoryDatasetBytes: optional("used_memory_dataset", parseInteger),
+        lazyfreePendingObjects: optional("lazyfree_pending_objects", parseInteger),
+        memFragmentationRatio: optional("mem_fragmentation_ratio", parseRatio),
+    };
+}
+/** Runs `INFO memory` and parses it. Checks `signal` before and after the command. */
+export async function getValkeyMemoryInfo(client, { signal } = {}) {
+    throwIfAborted(signal);
+    const info = await client.info([InfoOptions.Memory]);
+    throwIfAborted(signal);
+    return parseValkeyMemoryInfo(glideStringToString(info));
+}
+/**
+ * Rejects empty prefixes, a group named `unclassified`, and prefixes that overlap across
+ * groups (identical, or one a prefix of another), so every key belongs to at most one group.
+ */
+export function validateKeyPrefixRegistry(prefixes) {
+    const seen = [];
+    for (const [group, groupPrefixes] of Object.entries(prefixes)) {
+        if (group === UNCLASSIFIED)
+            throw new Error(`Prefix group name is reserved: ${group}`);
+        for (const prefix of groupPrefixes) {
+            if (prefix === "")
+                throw new Error(`Prefix group ${group} contains an empty prefix`);
+            const other = seen.find((entry) => entry.group !== group &&
+                (entry.prefix.startsWith(prefix) || prefix.startsWith(entry.prefix)));
+            if (other) {
+                throw new Error(`Prefix ${JSON.stringify(prefix)} in ${group} overlaps ${JSON.stringify(other.prefix)} in ${other.group}`);
+            }
+            seen.push({ group, prefix });
+        }
+    }
+}
+/**
+ * Counts keys per prefix group with bounded SCAN pages. Keys matching no prefix are counted as
+ * `unclassified`. SCAN is non-snapshot, so counts may include duplicates or miss keys written
+ * during the walk. `signal` is checked before and after each page.
+ */
+export async function countKeysByPrefix(client, prefixes, { signal, count = DEFAULT_SCAN_COUNT } = {}) {
+    validateKeyPrefixRegistry(prefixes);
+    const groups = Object.keys(prefixes);
+    const counts = { [UNCLASSIFIED]: 0 };
+    for (const group of groups)
+        counts[group] = 0;
+    for await (const keys of scanKeyPages(client, "*", { count, signal })) {
+        for (const key of keys) {
+            const name = glideStringToString(key);
+            const group = groups.find((g) => prefixes[g].some((prefix) => name.startsWith(prefix)));
+            counts[group ?? UNCLASSIFIED] += 1;
+        }
+    }
+    return counts;
+}
+//# sourceMappingURL=diagnostics.mjs.map

package/dist/diagnostics.mjs.map

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

package/dist/index.d.mts

@@ -13,7 +13,9 @@ export * from "./errors.mts";
 export * from "./key-normalization.mts";
 export * from "./cache-metrics.mts";
 export * from "./retry.mts";
-export { scanAndUnlinkKeys } from "./delete.mts";
+export { scanAndUnlinkKeyPrefixes, scanAndUnlinkKeys } from "./delete.mts";
 export { expireKeysWithNoExpiry } from "./expiry.mts";
+export { countKeysByPrefix, getValkeyMemoryInfo, parseValkeyMemoryInfo, validateKeyPrefixRegistry, } from "./diagnostics.mts";
+export type { CountKeysByPrefixOptions, DiagnosticsOptions, ValkeyMemorySummary, } from "./diagnostics.mts";
 export type { RateLimiterAddAndCheckWindowsOptions, RateLimiterOptions, RateLimiterWindow, ValkeyBloomFilterOptions, ValkeyCacheOptions, ValkeyCacheMode, ValkeyCacheResponse, DynamicConfigField, DynamicConfigFieldType, DynamicConfigOptions, ScanAndUnlinkKeysClient, ScanAndUnlinkKeysOptions, ScanAndUnlinkKeysResult, ExpireKeysWithNoExpiryOptions, ExpireKeysWithNoExpiryResult, } from "./types.mts";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../index.mts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EACV,oCAAoC,EACpC,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../index.mts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,oCAAoC,EACpC,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC"}

package/dist/index.mjs

@@ -13,6 +13,7 @@ export * from "./errors.mjs";
 export * from "./key-normalization.mjs";
 export * from "./cache-metrics.mjs";
 export * from "./retry.mjs";
-export { scanAndUnlinkKeys } from "./delete.mjs";
+export { scanAndUnlinkKeyPrefixes, scanAndUnlinkKeys } from "./delete.mjs";
 export { expireKeysWithNoExpiry } from "./expiry.mjs";
+export { countKeysByPrefix, getValkeyMemoryInfo, parseValkeyMemoryInfo, validateKeyPrefixRegistry, } from "./diagnostics.mjs";
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../index.mts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../index.mts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC"}

package/dist/retry.d.mts

@@ -33,10 +33,10 @@ export type RetryValkeyOperationOptions = {
  */
 export declare function retryValkeyOperation<T>(fn: () => Promise<T>, options?: RetryValkeyOperationOptions): Promise<T>;
 export type RetrySaturationErrorOptions = {
-    /** Maximum number of attempts (default: 3). */
+    /** Maximum number of attempts (default: `VALKEY_INFLIGHT_RETRY_ATTEMPTS`, or 3). */
     attempts?: number;
     /**
-     * Minimum milliseconds between attempts (default: 1000).
+     * Minimum milliseconds between attempts (default: `VALKEY_INFLIGHT_RETRY_DELAY_MS`, or 1000).
      * Actual delay is jittered in [delayMs, delayMs * 5] to spread concurrent retriers.
      */
     delayMs?: number;
@@ -45,6 +45,10 @@ export type RetrySaturationErrorOptions = {
  * Retries a Valkey operation only on inflight-saturation rejections
  * (`Reached maximum inflight requests`), with jittered delay in [delayMs, delayMs*5].
  *
+ * When `attempts` / `delayMs` are omitted they default to `config.inflight_retry_attempts` /
+ * `config.inflight_retry_delay_ms` (`VALKEY_INFLIGHT_RETRY_ATTEMPTS` /
+ * `VALKEY_INFLIGHT_RETRY_DELAY_MS`); explicit options take precedence.
+ *
  * All other errors are rethrown immediately. Use this at internal command boundaries
  * so callers don't need to wrap each call site.
  *

package/dist/retry.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.mts","sourceRoot":"","sources":["../retry.mts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"retry.d.mts","sourceRoot":"","sources":["../retry.mts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/retry.mjs

@@ -1,4 +1,5 @@
 import { randomInt } from "node:crypto";
+import { config } from "./config.mjs";
 /**
  * Substring patterns that identify transient Valkey / Glide errors which are safe to retry.
  * These originate from the @valkey/valkey-glide native Rust core.
@@ -72,6 +73,10 @@ export async function retryValkeyOperation(fn, options) {
  * Retries a Valkey operation only on inflight-saturation rejections
  * (`Reached maximum inflight requests`), with jittered delay in [delayMs, delayMs*5].
  *
+ * When `attempts` / `delayMs` are omitted they default to `config.inflight_retry_attempts` /
+ * `config.inflight_retry_delay_ms` (`VALKEY_INFLIGHT_RETRY_ATTEMPTS` /
+ * `VALKEY_INFLIGHT_RETRY_DELAY_MS`); explicit options take precedence.
+ *
  * All other errors are rethrown immediately. Use this at internal command boundaries
  * so callers don't need to wrap each call site.
  *
@@ -80,8 +85,8 @@ export async function retryValkeyOperation(fn, options) {
  */
 export function retrySaturationError(fn, options) {
     return retryValkeyOperation(fn, {
-        attempts: options?.attempts,
-        delayMs: options?.delayMs,
+        attempts: options?.attempts ?? config.inflight_retry_attempts,
+        delayMs: options?.delayMs ?? config.inflight_retry_delay_ms,
         shouldRetry: isSaturationError,
         jitter: true,
     });

package/dist/retry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"retry.mjs","sourceRoot":"","sources":["../retry.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,mCAAmC;IACnC,mBAAmB;IACnB,mBAAmB;IACnB,mBAAmB;IACnB,4BAA4B;CAC7B,CAAC;AAEF,MAAM,kBAAkB,GAAG,mCAAmC,CAAC;AAE/D;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AACpD,CAAC;AAgBD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAoB,EACpB,OAAqC;IAErC,MAAM,EACJ,QAAQ,GAAG,CAAC,EACZ,OAAO,GAAG,IAAI,EACd,WAAW,GAAG,sBAAsB,EACpC,MAAM,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1C,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YACrC,SAAS,GAAG,KAAK,CAAC;YAClB,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBACtF,oFAAoF;gBACpF,qFAAqF;gBACrF,uFAAuF;gBACvF,yFAAyF;gBACzF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;oBAClC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBAC1C,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;gBACnB,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC;AAYD;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAAoB,EACpB,OAAqC;IAErC,OAAO,oBAAoB,CAAC,EAAE,EAAE;QAC9B,QAAQ,EAAE,OAAO,EAAE,QAAQ;QAC3B,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,WAAW,EAAE,iBAAiB;QAC9B,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"retry.mjs","sourceRoot":"","sources":["../retry.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,mCAAmC;IACnC,mBAAmB;IACnB,mBAAmB;IACnB,mBAAmB;IACnB,4BAA4B;CAC7B,CAAC;AAEF,MAAM,kBAAkB,GAAG,mCAAmC,CAAC;AAE/D;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AACpD,CAAC;AAgBD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAoB,EACpB,OAAqC;IAErC,MAAM,EACJ,QAAQ,GAAG,CAAC,EACZ,OAAO,GAAG,IAAI,EACd,WAAW,GAAG,sBAAsB,EACpC,MAAM,GAAG,KAAK,GACf,GAAG,OAAO,IAAI,EAAE,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1C,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YACrC,SAAS,GAAG,KAAK,CAAC;YAClB,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBACtF,oFAAoF;gBACpF,qFAAqF;gBACrF,uFAAuF;gBACvF,yFAAyF;gBACzF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;oBAClC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBAC1C,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;gBACnB,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC;AAYD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAAoB,EACpB,OAAqC;IAErC,OAAO,oBAAoB,CAAC,EAAE,EAAE;QAC9B,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,uBAAuB;QAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC,uBAAuB;QAC3D,WAAW,EAAE,iBAAiB;QAC9B,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/shutdown.d.mts

@@ -1,3 +1,21 @@
+export interface CloseValkeyClientsOptions {
+    /**
+     * Reject with an `AggregateError` after every close has settled if any close failed.
+     * Failures are still reported to `handleValkeyError`. Defaults to `false`.
+     */
+    throwOnError?: boolean;
+}
+/**
+ * Closes every live `DynamicConfig`, then every package-managed client and the
+ * dynamic-config subscription client. Closing `dynamicConfigs` beforehand is unnecessary.
+ *
+ * Shutdown runs once per module instance. Later calls are no-ops that resolve immediately,
+ * even if they pass `throwOnError` and an earlier call did not (or the first run failed).
+ */
+export declare const closeValkeyClients: (options?: CloseValkeyClientsOptions) => Promise<void>;
+/**
+ * Same as `closeValkeyClients()` but takes no arguments, so it is safe to pass directly as a
+ * signal or lifecycle callback that supplies its own arguments. Never rejects on close failures.
+ */
 export declare const onGracefulShutdown: () => Promise<void>;
-export declare const closeValkeyClients: typeof onGracefulShutdown;
 //# sourceMappingURL=shutdown.d.mts.map

package/dist/shutdown.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.mts","sourceRoot":"","sources":["../shutdown.mts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,IAAI,CAgBvD,CAAC;AAEF,eAAO,MAAM,kBAAkB,2BAAqB,CAAC"}
+{"version":3,"file":"shutdown.d.mts","sourceRoot":"","sources":["../shutdown.mts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,aAAoB,yBAAyB,KAAG,OAAO,CAAC,IAAI,CA0B1F,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAAO,CAAC,IAAI,CAAyB,CAAC"}

package/dist/shutdown.mjs

@@ -15,25 +15,41 @@ const safeClose = (obj) => {
         return Promise.reject(error);
     }
 };
-export const onGracefulShutdown = async () => {
+/**
+ * Closes every live `DynamicConfig`, then every package-managed client and the
+ * dynamic-config subscription client. Closing `dynamicConfigs` beforehand is unnecessary.
+ *
+ * Shutdown runs once per module instance. Later calls are no-ops that resolve immediately,
+ * even if they pass `throwOnError` and an earlier call did not (or the first run failed).
+ */
+export const closeValkeyClients = async (options) => {
     if (shutdown)
         return;
     shutdown = true;
-    const configResults = await Promise.allSettled([...dynamicConfigs].map(safeClose));
-    for (const result of configResults) {
-        if (result.status === "rejected")
-            handleValkeyError(toError(result.reason));
-    }
-    const results = await Promise.allSettled([
+    const errors = [];
+    const report = (results) => {
+        for (const result of results) {
+            if (result.status === "rejected") {
+                const error = toError(result.reason);
+                errors.push(error);
+                handleValkeyError(error);
+            }
+        }
+    };
+    report(await Promise.allSettled([...dynamicConfigs].map(safeClose)));
+    report(await Promise.allSettled([
         ...Array.from(urlsToClients.values(), safeClose),
         closeDynamicConfigValkeySubscriptionClient(),
-    ]);
-    for (const result of results) {
-        if (result.status === "rejected")
-            handleValkeyError(toError(result.reason));
+    ]));
+    if (options?.throwOnError && errors.length > 0) {
+        throw new AggregateError(errors, "Valkey shutdown failed");
     }
 };
-export const closeValkeyClients = onGracefulShutdown;
+/**
+ * Same as `closeValkeyClients()` but takes no arguments, so it is safe to pass directly as a
+ * signal or lifecycle callback that supplies its own arguments. Never rejects on close failures.
+ */
+export const onGracefulShutdown = () => closeValkeyClients();
 function toError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }

package/dist/shutdown.mjs.map

@@ -1 +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;;;;GAIG;AACH,MAAM,SAAS,GAAG,CAAC,GAA6B,EAAE,EAAE;IAClD,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC,CAAC;AAEF,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,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IACnF,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,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC;QAChD,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"}
+{"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;;;;GAIG;AACH,MAAM,SAAS,GAAG,CAAC,GAA6B,EAAE,EAAE;IAClD,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC,CAAC;AAUF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EAAE,OAAmC,EAAiB,EAAE;IAC7F,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAEhB,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAG,CAAC,OAAwC,EAAE,EAAE;QAC1D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACnB,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,CACJ,MAAM,OAAO,CAAC,UAAU,CAAC;QACvB,GAAG,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC;QAChD,0CAA0C,EAAE;KAC7C,CAAC,CACH,CAAC;IAEF,IAAI,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAkB,EAAE,CAAC,kBAAkB,EAAE,CAAC;AAE5E,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/docs/api.md

@@ -17,6 +17,7 @@ This is the entry point for the public `valkyries` API. Detailed API documentati
 - [Events and metrics](events-and-metrics.md) - `valkeyEvents`, cache metrics, event payloads, and error handling hooks.
 - [Lua scripts](lua-scripts.md) - packaged Lua scripts and script-loading helpers.
 - [Configuration](configuration.md) - environment variables and connection behavior.
+- [Diagnostics](diagnostics.md) - `INFO memory` parsing and cancellable prefix key counting.
 - [Utilities](utilities.md) - key and Valkey result normalization helpers.
 
 ## Package Entry Points
@@ -31,6 +32,7 @@ import {
   reserveIdempotencyKey,
   closeValkeyClients,
   scanAndUnlinkKeys,
+  scanAndUnlinkKeyPrefixes,
   expireKeysWithNoExpiry,
 } from "valkyries";
 ```

package/docs/clients.md

@@ -10,7 +10,7 @@ Connections are deduplicated by URL, read preference, and lazy-connect setting t
 
 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.
+Use `closeValkeyClients()` (or the argument-free `onGracefulShutdown()`) to close package-managed clients and the dynamic-config pub/sub connection.
 
 ## Default Clients
 
@@ -102,8 +102,20 @@ Registers or removes handlers that receive dynamic-config pub/sub messages.
 ## Shutdown
 
 ```ts
-closeValkeyClients(): Promise<void>
+closeValkeyClients(options?: { throwOnError?: boolean }): Promise<void>
 onGracefulShutdown(): Promise<void>
 ```
 
-Both exports point to the same idempotent shutdown function. It closes all live dynamic configs, package-managed clients, and the dynamic-config subscription client.
+`closeValkeyClients()` closes all live dynamic configs first, then package-managed clients and the dynamic-config subscription client. Closing `dynamicConfigs` yourself before calling it is unnecessary. `onGracefulShutdown()` runs the same sequence but takes no arguments, so it is safe to pass directly as a signal or lifecycle callback.
+
+By default, close failures are reported to `handleValkeyError` and the promise always resolves. With `throwOnError: true`, failures are still reported to `handleValkeyError`; after every close has settled, the promise rejects with `new AggregateError(errors, "Valkey shutdown failed")`.
+
+```ts
+try {
+  await closeValkeyClients({ throwOnError: true });
+} catch (error) {
+  if (error instanceof AggregateError) process.exitCode = 1;
+}
+```
+
+Shutdown runs once per process. Repeated calls are no-ops that resolve immediately, including a later call that passes `throwOnError: true` after an earlier call without it: it neither re-closes anything nor reports the earlier failures.

package/docs/configuration.md

@@ -14,3 +14,7 @@ Redis-style URLs are supported:
 - `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.
+
+## Saturation retries
+
+`VALKEY_INFLIGHT_RETRY_ATTEMPTS` (default `3`) and `VALKEY_INFLIGHT_RETRY_DELAY_MS` (default `1000`) set how internal command boundaries retry commands the client rejects locally with `Reached maximum inflight requests`. The exported `retrySaturationError(fn, options?)` uses the same values when `options.attempts` / `options.delayMs` are omitted; explicit options take precedence. Delays are jittered in `[delayMs, delayMs * 5]`.

package/docs/diagnostics.md

@@ -0,0 +1,50 @@
+# Diagnostics
+
+Read-only helpers for inspecting memory and keyspace usage. Choosing a client, checking deployment
+topology, and naming groups are left to the caller.
+
+## `parseValkeyMemoryInfo(info)`
+
+```ts
+parseValkeyMemoryInfo(info: string): ValkeyMemorySummary
+```
+
+Parses `INFO memory` text (`key:value` lines, `#` section headers, LF or CRLF). Throws when
+`used_memory`, `used_memory_rss`, `used_memory_peak`, `maxmemory`, or `maxmemory_policy` is missing,
+or when an integer field is not a non-negative safe integer. `usedMemoryDatasetBytes`,
+`lazyfreePendingObjects`, and `memFragmentationRatio` are `null` when absent, but still throw when
+present and malformed.
+
+## `getValkeyMemoryInfo(client, options?)`
+
+```ts
+getValkeyMemoryInfo(
+  client: Pick<GlideClient, "info">,
+  options?: { signal?: AbortSignal },
+): Promise<ValkeyMemorySummary>
+```
+
+Runs `INFO memory` and parses it. The signal is checked before and after the command.
+
+## `countKeysByPrefix(client, prefixes, options?)`
+
+```ts
+import { countKeysByPrefix } from "valkyries";
+
+const counts = await countKeysByPrefix(
+  client,
+  { cache: ["cache:"], sessions: ["session:", "sess:"] },
+  { signal, count: 500 },
+);
+// { cache: 12, sessions: 3, unclassified: 40 }
+```
+
+Walks the keyspace with bounded `SCAN` pages (`count` defaults to 500) and checks `signal` before and
+after each page, including the last. Keys matching no prefix are counted as `unclassified`. SCAN is
+non-snapshot, so counts can include duplicates or miss keys written during the walk. The registry is
+validated first.
+
+## `validateKeyPrefixRegistry(prefixes)`
+
+Throws for empty prefixes, a group named `unclassified`, and prefixes that overlap across groups
+(identical, or one a prefix of another), so every key belongs to at most one group.

package/docs/utilities.md

@@ -24,6 +24,25 @@ from the keys that exist when the call returns. The optional `signal` is checked
 every SCAN and UNLINK boundary; its exact abort reason is rethrown without reporting it to the
 configured Valkey error handler.
 
+## `scanAndUnlinkKeyPrefixes(client, prefixes, options)`
+
+```ts
+scanAndUnlinkKeyPrefixes(
+  client: ScanAndUnlinkKeysClient,
+  prefixes: readonly string[],
+  options?: ScanAndUnlinkKeysOptions, // { signal?, matches? }
+): Promise<{ unlinkedKeys: number }>
+```
+
+Runs `scanAndUnlinkKeys` serially for each distinct prefix, glob-escaping `*`, `?`, `[`, `]`, and
+`\` and appending `*`, so a prefix matches only keys that literally start with it. An empty or
+non-string prefix throws a `TypeError` before any scan starts.
+
+A failing prefix does not stop later prefixes. One failure is rethrown as-is; two or more are
+combined into an `AggregateError` whose message and `unlinkedKeys` property report the keys already
+removed. Failures reach the configured Valkey error handler once, from `scanAndUnlinkKeys`. The
+`signal` is checked before each prefix, and its exact abort reason is rethrown immediately.
+
 ## `expireKeysWithNoExpiry(client, options)`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valkyries",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Valkey utilities for caches, bloom filters, dynamic configuration, and rate limiting.",
   "homepage": "https://github.com/jonathanong/valkyries#readme",
   "bugs": {
@@ -70,7 +70,7 @@
     "@types/node": "^26.1.0",
     "@vitest/coverage-v8": "^5.0.0",
     "github-actionlint": "^1.7.12",
-    "oxfmt": "^0.70.0",
+    "oxfmt": "^0.71.0",
     "oxlint": "^1.65.0",
     "oxlint-tsgolint": "^7.0.2001",
     "tsx": "^4.22.1",