valkyries 0.6.2 → 0.8.0

package/README.md

@@ -88,6 +88,21 @@ await flags.setField("enabled", true);
 
 Dynamic config stores fields in a Valkey hash and publishes changes over pub/sub.
 
+## Channel Pub/Sub
+
+`valkyries/channel-pubsub` provides ephemeral, key-scoped pub/sub with caller-owned client
+configuration and lifecycle. It is not re-exported from the package root.
+
+```ts
+import { createChannelPubSub } from "valkyries/channel-pubsub";
+
+const events = createChannelPubSub<{ status: string }>("exports", {
+  clientConfig: { addresses: [{ host: "localhost", port: 6379 }] },
+});
+```
+
+See [Channel pub/sub](docs/channel-pubsub.md) for lifecycle and error-handling details.
+
 ## Rate Limiter
 
 ```ts
@@ -113,6 +128,45 @@ const cache = new ValkeyCache({ prefix: "custom", ttlSeconds: 60, client });
 
 Call `closeValkeyClients()` to close package-managed clients.
 
+## Scan and Unlink Keys
+
+Use `scanAndUnlinkKeys()` for cancellable, pattern-based cleanup with explicit scan and deletion
+counts:
+
+```ts
+import { scanAndUnlinkKeys } from "valkyries";
+
+const result = await scanAndUnlinkKeys(client, "cache:*", {
+  matches: (key) => Buffer.from(key).toString("utf8").startsWith("cache:users:"),
+  signal: abortController.signal,
+});
+```
+
+The result reports `scannedKeys`, `matchedKeys`, and keys confirmed removed by `UNLINK` as
+`unlinkedKeys`. `SCAN` is non-snapshot, so these counts can include duplicates or omit keys while
+the keyspace changes.
+
+## Expire Keys Without a TTL
+
+Use `expireKeysWithNoExpiry()` to apply a TTL only when matching keys still have no expiry:
+
+```ts
+import { expireKeysWithNoExpiry } from "valkyries";
+
+const result = await expireKeysWithNoExpiry(client, {
+  pattern: "cache:*",
+  ttl: 86_400,
+  shouldExpire: (key) => Buffer.from(key).toString("utf8").startsWith("cache:users:"),
+  signal: abortController.signal,
+  batchSize: 250,
+});
+```
+
+The result reports `scannedKeys`, `matchedKeys`, and `expiredKeys`. The helper uses `EXPIRE NX`,
+so it never replaces a TTL that was added concurrently. `SCAN` is non-snapshot, so counts can
+include duplicates or omit keys while the keyspace changes. `scanCount` is a SCAN hint, while
+`batchSize` independently bounds each EXPIRE pipeline.
+
 ## Documentation
 
 - [Configuration](docs/configuration.md)
@@ -121,6 +175,7 @@ Call `closeValkeyClients()` to close package-managed clients.
 - [Cache](docs/cache.md)
 - [Bloom filters](docs/bloom-filters.md)
 - [Dynamic config](docs/dynamic-config.md)
+- [Channel pub/sub](docs/channel-pubsub.md)
 - [Rate limiter](docs/rate-limiter.md)
 - [Idempotency keys](docs/idempotency-key.md)
 - [Conditional operations](docs/conditional-operations.md)

package/dist/channel-pubsub-internals.d.mts

@@ -0,0 +1,13 @@
+import type { GlideClient, GlideString } from "@valkey/valkey-glide";
+export declare function decrement(counts: Map<string, number>, key: string): void;
+export declare function removePending<T>(pending: Map<string, Set<T>>, key: string, state: T): void;
+export declare function getOrCreateSet<T>(map: Map<string, Set<T>>, key: string): Set<T>;
+export declare function removeHandler<T>(handlers: Map<string, Set<T>>, key: string, handler: T): void;
+export declare function serializeForPublish<T>(serialize: (value: T) => string, value: T, report: (error: unknown) => void): string;
+export declare function toError(error: unknown): Error;
+export declare function reportError(onError: ((error: Error) => void) | undefined, error: unknown): void;
+export declare function glideStringToString(value: GlideString): string;
+export declare function assertChannelPart(name: string, value: string): void;
+export declare function deliver<T>(handler: (value: T) => void, value: T, onError: (error: unknown) => void): void;
+export declare function closeSubscriberClient(client: GlideClient, pattern: string, timeoutMs: number, report: (error: unknown) => void): Promise<void>;
+//# sourceMappingURL=channel-pubsub-internals.d.mts.map

package/dist/channel-pubsub-internals.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-pubsub-internals.d.mts","sourceRoot":"","sources":["../channel-pubsub-internals.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAErE,wBAAgB,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAIxE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAK1F;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAM/E;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAK7F;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,EAC/B,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,MAAM,CAOR;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE7C;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAI/F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE9D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAInE;AAED,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAChC,IAAI,CAMN;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/channel-pubsub-internals.mjs

@@ -0,0 +1,82 @@
+export function decrement(counts, key) {
+    const count = (counts.get(key) ?? 1) - 1;
+    if (count <= 0)
+        counts.delete(key);
+    else
+        counts.set(key, count);
+}
+export function removePending(pending, key, state) {
+    const states = pending.get(key);
+    if (!states)
+        return;
+    states.delete(state);
+    if (states.size === 0)
+        pending.delete(key);
+}
+export function getOrCreateSet(map, key) {
+    const existing = map.get(key);
+    if (existing)
+        return existing;
+    const created = new Set();
+    map.set(key, created);
+    return created;
+}
+export function removeHandler(handlers, key, handler) {
+    const active = handlers.get(key);
+    if (!active)
+        return;
+    active.delete(handler);
+    if (active.size === 0)
+        handlers.delete(key);
+}
+export function serializeForPublish(serialize, value, report) {
+    try {
+        return serialize(value);
+    }
+    catch (error) {
+        report(error);
+        throw error;
+    }
+}
+export function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function reportError(onError, error) {
+    try {
+        onError?.(toError(error));
+    }
+    catch { }
+}
+export function glideStringToString(value) {
+    return typeof value === "string" ? value : value.toString();
+}
+export function assertChannelPart(name, value) {
+    if (value.length === 0 || /[?*[\]\\]/.test(value)) {
+        throw new Error(`${name} must be non-empty and cannot contain Valkey glob characters`);
+    }
+}
+export function deliver(handler, value, onError) {
+    try {
+        handler(value);
+    }
+    catch (error) {
+        onError(error);
+    }
+}
+export async function closeSubscriberClient(client, pattern, timeoutMs, report) {
+    try {
+        await client.punsubscribe(new Set([pattern]), timeoutMs);
+    }
+    catch (error) {
+        report(error);
+    }
+    finally {
+        try {
+            await Promise.resolve(client.close());
+        }
+        catch (error) {
+            report(error);
+        }
+    }
+}
+//# sourceMappingURL=channel-pubsub-internals.mjs.map

package/dist/channel-pubsub-internals.mjs.map

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

package/dist/channel-pubsub-types.d.mts

@@ -0,0 +1,24 @@
+import type { GlideClient } from "@valkey/valkey-glide";
+type GlideClientConfig = Parameters<typeof GlideClient.createClient>[0];
+export type ChannelPubSubHandler<T> = (value: T) => void;
+export type ChannelSubscription<T> = {
+    setHandler(handler: ChannelPubSubHandler<T> | null): void;
+    close(): Promise<void>;
+};
+export type ChannelPubSub<T> = {
+    publish(key: string, value: T): Promise<void>;
+    subscribe(key: string): Promise<ChannelSubscription<T>>;
+    closeSubscriber(): Promise<void>;
+    close(): Promise<void>;
+};
+export type ChannelPubSubOptions<T> = {
+    clientConfig: GlideClientConfig;
+    createClient?: (config: GlideClientConfig) => Promise<GlideClient>;
+    serialize?: (value: T) => string;
+    deserialize?: (value: string) => T;
+    closeSubscriberWhenIdle?: boolean;
+    subscriberCloseTimeoutMs?: number;
+    onError?: (error: Error) => void;
+};
+export {};
+//# sourceMappingURL=channel-pubsub-types.d.mts.map

package/dist/channel-pubsub-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-pubsub-types.d.mts","sourceRoot":"","sources":["../channel-pubsub-types.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEzD,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,UAAU,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,YAAY,EAAE,iBAAiB,CAAC;IAChC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACnE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IACnC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC,CAAC"}

package/dist/channel-pubsub-types.mjs

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

package/dist/channel-pubsub-types.mjs.map

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

package/dist/channel-pubsub.d.mts

@@ -0,0 +1,4 @@
+import type { ChannelPubSub, ChannelPubSubOptions } from "./channel-pubsub-types.mts";
+export type { ChannelPubSub, ChannelPubSubOptions, ChannelSubscription, } from "./channel-pubsub-types.mts";
+export declare function createChannelPubSub<T>(prefix: string, options: ChannelPubSubOptions<T>): ChannelPubSub<T>;
+//# sourceMappingURL=channel-pubsub.d.mts.map

package/dist/channel-pubsub.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-pubsub.d.mts","sourceRoot":"","sources":["../channel-pubsub.mts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,aAAa,EAEb,oBAAoB,EAErB,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAEpC,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,aAAa,CAAC,CAAC,CAAC,CAqKlB"}

package/dist/channel-pubsub.mjs

@@ -0,0 +1,184 @@
+import { GlideClient, GlideClientConfiguration } from "@valkey/valkey-glide";
+import { assertChannelPart, closeSubscriberClient, decrement, deliver, getOrCreateSet, glideStringToString, removePending, removeHandler, reportError, serializeForPublish, } from "./channel-pubsub-internals.mjs";
+export function createChannelPubSub(prefix, options) {
+    assertChannelPart("prefix", prefix);
+    if (options.clientConfig.pubsubSubscriptions) {
+        throw new Error("clientConfig cannot include pubsubSubscriptions");
+    }
+    const closeTimeoutMs = options.subscriberCloseTimeoutMs ?? 5_000;
+    if (!Number.isSafeInteger(closeTimeoutMs) || closeTimeoutMs <= 0) {
+        throw new Error("subscriberCloseTimeoutMs must be a positive safe integer");
+    }
+    const report = (error) => reportError(options.onError, error);
+    const serialize = options.serialize ?? ((value) => JSON.stringify(value));
+    const deserialize = options.deserialize ?? ((value) => JSON.parse(value));
+    const createClient = options.createClient ?? ((config) => GlideClient.createClient(config));
+    const pattern = `${prefix}:*`;
+    const handlers = new Map();
+    const pending = new Map();
+    const counts = new Map();
+    let publisher;
+    let subscriber;
+    let subscriberClose;
+    let ownerClose;
+    let closed = false;
+    const assertOpen = () => {
+        if (closed)
+            throw new Error("Channel pub/sub is closed");
+    };
+    const totalCount = () => [...counts.values()].reduce((total, count) => total + count, 0);
+    const shutdownSubscriber = () => {
+        if (subscriberClose)
+            return subscriberClose;
+        const current = subscriber;
+        subscriber = undefined;
+        if (!current)
+            return Promise.resolve();
+        const closePromise = (async () => {
+            try {
+                await closeSubscriberClient(await current, pattern, closeTimeoutMs, report);
+            }
+            catch (error) {
+                report(error);
+            }
+        })();
+        subscriberClose = closePromise;
+        void closePromise.finally(() => {
+            subscriberClose = undefined;
+        });
+        return closePromise;
+    };
+    const closeSubscriberIfIdle = () => {
+        return options.closeSubscriberWhenIdle && totalCount() === 0
+            ? shutdownSubscriber()
+            : Promise.resolve();
+    };
+    const getPublisher = () => {
+        publisher ??= createClient(options.clientConfig).catch((error) => {
+            publisher = undefined;
+            throw error;
+        });
+        return publisher;
+    };
+    const receive = (message) => {
+        const messageChannel = glideStringToString(message.channel);
+        if (!messageChannel.startsWith(`${prefix}:`))
+            return;
+        const key = messageChannel.slice(prefix.length + 1);
+        if (!counts.has(key))
+            return;
+        let value;
+        try {
+            value = deserialize(glideStringToString(message.message));
+        }
+        catch (error) {
+            report(error);
+            return;
+        }
+        const currentHandlers = new Set(handlers.get(key));
+        for (const entry of currentHandlers)
+            deliver(entry.handler, value, report);
+        for (const state of pending.get(key) ?? [])
+            state.buffer.push(value);
+    };
+    const getSubscriber = async () => {
+        if (subscriberClose)
+            await subscriberClose;
+        assertOpen();
+        subscriber ??= createClient({
+            ...options.clientConfig,
+            pubsubSubscriptions: {
+                channelsAndPatterns: {
+                    [GlideClientConfiguration.PubSubChannelModes.Pattern]: new Set([pattern]),
+                },
+                callback: receive,
+                context: undefined,
+            },
+        }).catch((error) => {
+            subscriber = undefined;
+            throw error;
+        });
+        return await subscriber;
+    };
+    return {
+        async publish(key, value) {
+            assertOpen();
+            assertChannelPart("key", key);
+            await (await getPublisher()).publish(serializeForPublish(serialize, value, report), `${prefix}:${key}`);
+        },
+        async subscribe(key) {
+            assertOpen();
+            assertChannelPart("key", key);
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+            const state = { buffer: [] };
+            let handler;
+            let closePromise;
+            getOrCreateSet(pending, key).add(state);
+            const rollback = async () => {
+                removePending(pending, key, state);
+                if (handler)
+                    removeHandler(handlers, key, handler);
+                decrement(counts, key);
+                await closeSubscriberIfIdle();
+            };
+            try {
+                await getSubscriber();
+                if (closed)
+                    throw new Error("Channel pub/sub is closed");
+            }
+            catch (error) {
+                await rollback();
+                throw error;
+            }
+            return {
+                setHandler(nextHandler) {
+                    if (closePromise)
+                        return;
+                    if (handler)
+                        removeHandler(handlers, key, handler);
+                    if (!nextHandler) {
+                        handler = undefined;
+                        getOrCreateSet(pending, key).add(state);
+                        return;
+                    }
+                    removePending(pending, key, state);
+                    handler = { handler: nextHandler };
+                    getOrCreateSet(handlers, key).add(handler);
+                    for (const value of state.buffer)
+                        deliver(nextHandler, value, report);
+                    state.buffer = [];
+                },
+                close() {
+                    closePromise ??= rollback();
+                    return closePromise;
+                },
+            };
+        },
+        closeSubscriber() {
+            if (totalCount() > 0) {
+                return Promise.reject(new Error("Cannot close subscriber while subscriptions are active"));
+            }
+            return shutdownSubscriber();
+        },
+        close() {
+            if (ownerClose)
+                return ownerClose;
+            closed = true;
+            ownerClose = (async () => {
+                await shutdownSubscriber();
+                const current = publisher;
+                publisher = undefined;
+                if (!current)
+                    return;
+                try {
+                    await Promise.resolve((await current).close());
+                }
+                catch (error) {
+                    report(error);
+                }
+            })();
+            return ownerClose;
+        },
+    };
+}
+//# sourceMappingURL=channel-pubsub.mjs.map

package/dist/channel-pubsub.mjs.map

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

package/dist/delete.d.mts

@@ -1,4 +1,12 @@
+import type { ScanAndUnlinkKeysOptions, ScanAndUnlinkKeysResult } from "./types.mts";
 import type { GlideClient } from "@valkey/valkey-glide";
 export declare function deleteKeysWithPrefix(client: GlideClient, pattern: string): Promise<void>;
 export declare function deleteKeysWithLiteralPrefixes(client: GlideClient, pattern: string, prefixes: readonly string[]): Promise<void>;
+/**
+ * Scans keys matching a Valkey pattern and unlinks keys accepted by an optional predicate.
+ *
+ * SCAN is non-snapshot: concurrent writes can make the returned counts include duplicates,
+ * omit keys, or differ from the number of keys that exist when this function returns.
+ */
+export declare function scanAndUnlinkKeys(client: GlideClient, pattern: string, { signal, matches }?: ScanAndUnlinkKeysOptions): Promise<ScanAndUnlinkKeysResult>;
 //# 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,EAAE,WAAW,EAAe,MAAM,sBAAsB,CAAC;AAIrE,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9F;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"delete.d.mts","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9F;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,EAAE,MAAM,EAAE,OAAoB,EAAE,GAAE,wBAA6B,GAC9D,OAAO,CAAC,uBAAuB,CAAC,CA4BlC"}

package/dist/delete.mjs

@@ -1,30 +1,47 @@
-import { Buffer } from "node:buffer";
 import { handleValkeyError } from "./errors.mjs";
+import { glideStringToString, scanKeyPages, throwIfAborted } from "./scan.mjs";
 const DEFAULT_SCAN_COUNT = 500;
 export async function deleteKeysWithPrefix(client, pattern) {
-    await scanAndUnlink(client, pattern);
+    await scanAndUnlinkKeys(client, pattern);
 }
 export async function deleteKeysWithLiteralPrefixes(client, pattern, prefixes) {
     const uniquePrefixes = [...new Set(prefixes)].filter((prefix) => typeof prefix === "string");
     if (uniquePrefixes.length === 0)
         return;
-    await scanAndUnlink(client, pattern, (key) => uniquePrefixes.some((prefix) => key.startsWith(prefix)));
+    await scanAndUnlinkKeys(client, pattern, {
+        matches: (key) => uniquePrefixes.some((prefix) => glideStringToString(key).startsWith(prefix)),
+    });
 }
-async function scanAndUnlink(client, pattern, matches = () => true) {
+/**
+ * Scans keys matching a Valkey pattern and unlinks keys accepted by an optional predicate.
+ *
+ * SCAN is non-snapshot: concurrent writes can make the returned counts include duplicates,
+ * omit keys, or differ from the number of keys that exist when this function returns.
+ */
+export async function scanAndUnlinkKeys(client, pattern, { signal, matches = () => true } = {}) {
     try {
-        let cursor = "0";
-        do {
-            const result = await client.scan(cursor, { match: pattern, count: DEFAULT_SCAN_COUNT });
-            cursor = result[0];
-            const keys = result[1]
-                .map((key) => (typeof key === "string" ? key : Buffer.from(key).toString("utf8")))
-                .filter(matches);
+        let scannedKeys = 0;
+        let matchedKeys = 0;
+        let unlinkedKeys = 0;
+        for await (const scanned of scanKeyPages(client, pattern, {
+            count: DEFAULT_SCAN_COUNT,
+            signal,
+        })) {
+            scannedKeys += scanned.length;
+            const keys = scanned.filter(matches);
+            throwIfAborted(signal);
+            matchedKeys += keys.length;
             if (keys.length > 0) {
-                await client.unlink(keys);
+                throwIfAborted(signal);
+                unlinkedKeys += await client.unlink(keys);
+                throwIfAborted(signal);
             }
-        } while (cursor !== "0");
+        }
+        return { scannedKeys, matchedKeys, unlinkedKeys };
     }
     catch (err) {
+        if (signal?.aborted && err === signal.reason)
+            throw err;
         handleValkeyError(err);
         throw err;
     }

package/dist/delete.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"delete.mjs","sourceRoot":"","sources":["../delete.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAmB,EAAE,OAAe;IAC7E,MAAM,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAAmB,EACnB,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,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAC3C,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CACxD,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,MAAmB,EACnB,OAAe,EACf,OAAO,GAA6B,GAAG,EAAE,CAAC,IAAI;IAE9C,IAAI,CAAC;QACH,IAAI,MAAM,GAAG,GAAG,CAAC;QAEjB,GAAG,CAAC;YACF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;YACxF,MAAM,GAAG,MAAM,CAAC,CAAC,CAAW,CAAC;YAC7B,MAAM,IAAI,GAAI,MAAM,CAAC,CAAC,CAAmB;iBACtC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;iBACjF,MAAM,CAAC,OAAO,CAAC,CAAC;YAEnB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"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;AAI/E,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAmB,EAAE,OAAe;IAC7E,MAAM,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAAmB,EACnB,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,MAAmB,EACnB,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"}

package/dist/expiry.d.mts

@@ -0,0 +1,10 @@
+import { type GlideClient } from "@valkey/valkey-glide";
+import type { ExpireKeysWithNoExpiryOptions, ExpireKeysWithNoExpiryResult } from "./types.mts";
+/**
+ * Sets a TTL only on matching keys that have no existing expiry.
+ *
+ * SCAN is non-snapshot: concurrent writes can make the returned counts include duplicates,
+ * omit keys, or differ from the number of keys that exist when this function returns.
+ */
+export declare function expireKeysWithNoExpiry(client: GlideClient, { pattern, ttl, shouldExpire, signal, scanCount, batchSize, }: ExpireKeysWithNoExpiryOptions): Promise<ExpireKeysWithNoExpiryResult>;
+//# sourceMappingURL=expiry.d.mts.map

package/dist/expiry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.d.mts","sourceRoot":"","sources":["../expiry.mts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,WAAW,EAAoB,MAAM,sBAAsB,CAAC;AAGhG,OAAO,KAAK,EAAE,6BAA6B,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAK/F;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,WAAW,EACnB,EACE,OAAO,EACP,GAAG,EACH,YAAyB,EACzB,MAAM,EACN,SAA8B,EAC9B,SAA8B,GAC/B,EAAE,6BAA6B,GAC/B,OAAO,CAAC,4BAA4B,CAAC,CAuBvC"}

package/dist/expiry.mjs

@@ -0,0 +1,70 @@
+import { Batch, ExpireOptions } from "@valkey/valkey-glide";
+import { handleValkeyError } from "./errors.mjs";
+import { scanKeyPages, throwIfAborted } from "./scan.mjs";
+const DEFAULT_SCAN_COUNT = 500;
+const DEFAULT_BATCH_SIZE = 500;
+/**
+ * Sets a TTL only on matching keys that have no existing expiry.
+ *
+ * SCAN is non-snapshot: concurrent writes can make the returned counts include duplicates,
+ * omit keys, or differ from the number of keys that exist when this function returns.
+ */
+export async function expireKeysWithNoExpiry(client, { pattern, ttl, shouldExpire = () => true, signal, scanCount = DEFAULT_SCAN_COUNT, batchSize = DEFAULT_BATCH_SIZE, }) {
+    validateExpirySweepOptions(ttl, scanCount, batchSize);
+    try {
+        let scannedKeys = 0;
+        let matchedKeys = 0;
+        let expiredKeys = 0;
+        for await (const scanned of scanKeyPages(client, pattern, { count: scanCount, signal })) {
+            scannedKeys += scanned.length;
+            const keys = scanned.filter(shouldExpire);
+            throwIfAborted(signal);
+            matchedKeys += keys.length;
+            expiredKeys += await expireKeys(client, keys, ttl, batchSize, signal);
+        }
+        return { scannedKeys, matchedKeys, expiredKeys };
+    }
+    catch (error) {
+        if (signal?.aborted && error === signal.reason)
+            throw error;
+        handleValkeyError(error);
+        throw error;
+    }
+}
+async function expireKeys(client, keys, ttl, batchSize, signal) {
+    let expiredKeys = 0;
+    for (let offset = 0; offset < keys.length; offset += batchSize) {
+        expiredKeys += await expireBatch(client, keys.slice(offset, offset + batchSize), ttl, signal);
+    }
+    return expiredKeys;
+}
+async function expireBatch(client, keys, ttl, signal) {
+    throwIfAborted(signal);
+    const batch = new Batch(false);
+    for (const key of keys) {
+        batch.expire(key, ttl, { expireOption: ExpireOptions.HasNoExpiry });
+    }
+    const results = await client.exec(batch, true);
+    throwIfAborted(signal);
+    if (!Array.isArray(results) || results.length !== keys.length) {
+        throw new Error("expireKeysWithNoExpiry: unexpected EXPIRE batch response");
+    }
+    let expiredKeys = 0;
+    for (const result of results) {
+        if (result === true)
+            expiredKeys += 1;
+    }
+    return expiredKeys;
+}
+function validateExpirySweepOptions(ttl, scanCount, batchSize) {
+    if (!Number.isSafeInteger(ttl) || ttl <= 0) {
+        throw new RangeError("expireKeysWithNoExpiry: ttl must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(scanCount) || scanCount <= 0) {
+        throw new RangeError("expireKeysWithNoExpiry: scanCount must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(batchSize) || batchSize <= 0) {
+        throw new RangeError("expireKeysWithNoExpiry: batchSize must be a positive safe integer");
+    }
+}
+//# sourceMappingURL=expiry.mjs.map

package/dist/expiry.mjs.map

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

package/dist/index.d.mts

@@ -13,5 +13,7 @@ export * from "./errors.mts";
 export * from "./key-normalization.mts";
 export * from "./cache-metrics.mts";
 export * from "./retry.mts";
-export type { RateLimiterAddAndCheckWindowsOptions, RateLimiterOptions, RateLimiterWindow, ValkeyBloomFilterOptions, ValkeyCacheOptions, ValkeyCacheMode, ValkeyCacheResponse, DynamicConfigField, DynamicConfigFieldType, DynamicConfigOptions, } from "./types.mts";
+export { scanAndUnlinkKeys } from "./delete.mts";
+export { expireKeysWithNoExpiry } from "./expiry.mts";
+export type { RateLimiterAddAndCheckWindowsOptions, RateLimiterOptions, RateLimiterWindow, ValkeyBloomFilterOptions, ValkeyCacheOptions, ValkeyCacheMode, ValkeyCacheResponse, DynamicConfigField, DynamicConfigFieldType, DynamicConfigOptions, 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,YAAY,EACV,oCAAoC,EACpC,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,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,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,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC"}

package/dist/index.mjs

@@ -13,4 +13,6 @@ export * from "./errors.mjs";
 export * from "./key-normalization.mjs";
 export * from "./cache-metrics.mjs";
 export * from "./retry.mjs";
+export { scanAndUnlinkKeys } from "./delete.mjs";
+export { expireKeysWithNoExpiry } from "./expiry.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"}
+{"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"}

package/dist/scan.d.mts

@@ -0,0 +1,10 @@
+import { type GlideClient, type GlideString } from "@valkey/valkey-glide";
+type ScanKeyPagesOptions = {
+    count: number;
+    signal?: AbortSignal;
+};
+export declare function scanKeyPages(client: GlideClient, pattern: string, { count, signal }: ScanKeyPagesOptions): AsyncGenerator<GlideString[]>;
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+export declare function glideStringToString(key: GlideString): string;
+export {};
+//# sourceMappingURL=scan.d.mts.map

package/dist/scan.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.mts","sourceRoot":"","sources":["../scan.mts"],"names":[],"mappings":"AACA,OAAO,EAAW,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnF,KAAK,mBAAmB,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,wBAAuB,YAAY,CACjC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,mBAAmB,GACrC,cAAc,CAAC,WAAW,EAAE,CAAC,CAa/B;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAEpE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAE5D"}

package/dist/scan.mjs

@@ -0,0 +1,24 @@
+import { Buffer } from "node:buffer";
+import { Decoder } from "@valkey/valkey-glide";
+export async function* scanKeyPages(client, pattern, { count, signal }) {
+    let cursor = "0";
+    do {
+        throwIfAborted(signal);
+        const [nextCursor, keys] = await client.scan(cursor, {
+            match: pattern,
+            count,
+            decoder: Decoder.Bytes,
+        });
+        throwIfAborted(signal);
+        cursor = glideStringToString(nextCursor);
+        yield keys;
+    } while (cursor !== "0");
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason;
+}
+export function glideStringToString(key) {
+    return typeof key === "string" ? key : Buffer.from(key).toString("utf8");
+}
+//# sourceMappingURL=scan.mjs.map

package/dist/scan.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.mjs","sourceRoot":"","sources":["../scan.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAsC,MAAM,sBAAsB,CAAC;AAOnF,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,YAAY,CACjC,MAAmB,EACnB,OAAe,EACf,EAAE,KAAK,EAAE,MAAM,EAAuB;IAEtC,IAAI,MAAM,GAAG,GAAG,CAAC;IACjB,GAAG,CAAC;QACF,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE;YACnD,KAAK,EAAE,OAAO;YACd,KAAK;YACL,OAAO,EAAE,OAAO,CAAC,KAAK;SACvB,CAAC,CAAC;QACH,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,MAAM,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC;IACb,CAAC,QAAQ,MAAM,KAAK,GAAG,EAAE;AAC3B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAA+B;IAC5D,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,MAAM,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAgB;IAClD,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC3E,CAAC"}

package/dist/types.d.mts

@@ -1,4 +1,40 @@
-import type { GlideClient } from "@valkey/valkey-glide";
+import type { GlideClient, GlideString } from "@valkey/valkey-glide";
+export type ScanAndUnlinkKeysOptions = {
+    /** Stops before or after each SCAN and UNLINK command boundary. */
+    signal?: AbortSignal;
+    /** Selects scanned string or Buffer keys to unlink. Defaults to every scanned key. */
+    matches?: (key: GlideString) => boolean;
+};
+export type ScanAndUnlinkKeysResult = {
+    /** Number of keys returned by SCAN, including any duplicates from its non-snapshot iteration. */
+    scannedKeys: number;
+    /** Number of scanned keys accepted by matches. */
+    matchedKeys: number;
+    /** Number of keys confirmed by UNLINK as removed. */
+    unlinkedKeys: number;
+};
+export type ExpireKeysWithNoExpiryOptions = {
+    /** Valkey SCAN pattern for keys to evaluate. */
+    pattern: string;
+    /** TTL in seconds to apply only where the key has no expiry. */
+    ttl: number;
+    /** Selects scanned string or Buffer keys to expire. Defaults to every scanned key. */
+    shouldExpire?: (key: GlideString) => boolean;
+    /** Stops before or after each SCAN and EXPIRE-batch command boundary. */
+    signal?: AbortSignal;
+    /** SCAN COUNT hint. Defaults to 500. */
+    scanCount?: number;
+    /** Maximum number of EXPIRE commands in one non-atomic pipeline. Defaults to 500. */
+    batchSize?: number;
+};
+export type ExpireKeysWithNoExpiryResult = {
+    /** Number of keys returned by SCAN, including any duplicates from its non-snapshot iteration. */
+    scannedKeys: number;
+    /** Number of scanned keys accepted by shouldExpire. */
+    matchedKeys: number;
+    /** Number of keys confirmed by EXPIRE NX as newly given a TTL. */
+    expiredKeys: number;
+};
 export type ValkeyClientsOption = {
     cacheClient?: GlideClient;
     rateLimiterClient?: GlideClient;

package/dist/types.d.mts.map

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

package/docs/api.md

@@ -7,6 +7,7 @@ This is the entry point for the public `valkyries` API. Detailed API documentati
 - [`ValkeyCache`](cache.md) - read-through cache helpers, direct get/set APIs, invalidation, stale refresh, and Bloom-filter integration.
 - [`ValkeyBloomFilter`](bloom-filters.md) - Bloom filter lookup, writes, readiness markers, streaming rebuilds, and key helpers.
 - [`DynamicConfig`](dynamic-config.md) - distributed runtime fields backed by Valkey hashes and pub/sub updates.
+- [Channel pub/sub](channel-pubsub.md) - ephemeral, caller-managed key-scoped pub/sub.
 - [`RateLimiter`](rate-limiter.md) - sliding-window rate limiting backed by sorted sets and Lua scripts.
 - [Idempotency keys](idempotency-key.md) - consume-once values and token-fenced idempotency-key lifecycle helpers.
 
@@ -29,6 +30,8 @@ import {
   getAndDelete,
   reserveIdempotencyKey,
   closeValkeyClients,
+  scanAndUnlinkKeys,
+  expireKeysWithNoExpiry,
 } from "valkyries";
 ```
 
@@ -40,5 +43,6 @@ Supported subpath exports:
 - `valkyries/dynamic-config`
 - `valkyries/idempotency-key`
 - `valkyries/rate-limiter`
+- `valkyries/channel-pubsub`
 
 `valkyries` is ESM-only and requires Node.js 24 or newer.

package/docs/channel-pubsub.md

@@ -0,0 +1,59 @@
+# Channel Pub/Sub
+
+`createChannelPubSub()` creates a dedicated publisher and pattern subscriber for messages scoped by
+an application-defined prefix and key. It is an ephemeral delivery primitive: messages are not
+persisted, and subscribers do not receive messages published before their Valkey subscription is
+active.
+
+## Import
+
+```ts
+import { createChannelPubSub, type ChannelSubscription } from "valkyries/channel-pubsub";
+```
+
+This subpath is intentionally not exported from `valkyries`; importing it never initializes a
+package-managed client.
+
+## Create a channel
+
+```ts
+const events = createChannelPubSub<{ state: string }>("exports", {
+  clientConfig: { addresses: [{ host: "localhost", port: 6379 }] },
+  onError: (error) => logger.error(error),
+});
+```
+
+`clientConfig` is passed to `GlideClient.createClient()`. Supply `createClient` to own connection
+creation, for example when an application injects clients in tests. `serialize` and `deserialize`
+default to JSON. `onError` receives codec, handler, and subscriber-shutdown failures; publish and
+initial subscriber-connection failures reject their calling promise.
+
+`clientConfig` must not include `pubsubSubscriptions`; this API owns the subscriber's pattern and
+callback. `onError` failures are contained so consumer and cleanup isolation is preserved.
+
+Prefixes and keys must be non-empty and cannot contain Valkey glob characters (`?`, `*`, `[`, `]`,
+or `\`). This prevents a prefix from widening the subscriber pattern unintentionally.
+
+`closeSubscriberWhenIdle` closes the subscriber when the final subscription closes. Set
+`subscriberCloseTimeoutMs` to a positive safe integer to bound its `PUNSUBSCRIBE` request; it
+defaults to `5000`.
+
+## Use and close
+
+```ts
+const subscription: ChannelSubscription<{ state: string }> = await events.subscribe(exportId);
+subscription.setHandler((event) => send(event));
+await events.publish(exportId, { state: "ready" });
+await subscription.close();
+await events.close();
+```
+
+Subscriptions buffer messages received before a handler is installed and replay them when it is.
+Multiple subscriptions for one key each receive the message. Calling `setHandler()` replaces the
+previous handler. Both subscription `close()` and owner `close()` are idempotent. Owner `close()`
+also closes the lazy publisher; future `publish()` and `subscribe()` calls reject.
+
+`closeSubscriber()` closes only an idle subscriber connection. It rejects while subscriptions are
+active, preventing live handles from silently losing delivery. `close()` is the explicit owner
+shutdown operation and closes active subscriptions' connection safely; it coalesces concurrent
+callers until cleanup completes.

package/docs/utilities.md

@@ -2,6 +2,54 @@
 
 These normalization helpers are exported from the package root.
 
+## `scanAndUnlinkKeys(client, pattern, options)`
+
+```ts
+scanAndUnlinkKeys(
+  client: GlideClient,
+  pattern: string,
+  options?: {
+    signal?: AbortSignal;
+    matches?: (key: GlideString) => boolean;
+  },
+): Promise<{ scannedKeys: number; matchedKeys: number; unlinkedKeys: number }>
+```
+
+Scans with `COUNT 500`, unlinks every scanned key accepted by `matches`, and returns the number of
+keys scanned, predicate-matched, and confirmed removed by `UNLINK`. Keys are provided to `matches`
+and `UNLINK` as their original string or `Buffer` `GlideString` values.
+
+`SCAN` is non-snapshot: concurrent writes can make counts include duplicates, omit keys, or differ
+from the keys that exist when the call returns. The optional `signal` is checked before and after
+every SCAN and UNLINK boundary; its exact abort reason is rethrown without reporting it to the
+configured Valkey error handler.
+
+## `expireKeysWithNoExpiry(client, options)`
+
+```ts
+expireKeysWithNoExpiry(
+  client: GlideClient,
+  options: {
+    pattern: string;
+    ttl: number;
+    shouldExpire?: (key: GlideString) => boolean;
+    signal?: AbortSignal;
+    scanCount?: number;
+    batchSize?: number;
+  },
+): Promise<{ scannedKeys: number; matchedKeys: number; expiredKeys: number }>
+```
+
+Scans matching keys and pipelines `EXPIRE NX` commands for every key accepted by `shouldExpire`.
+`EXPIRE NX` atomically sets the TTL only when a key has no existing expiry, so a concurrent TTL
+change is never overwritten. `scanCount` defaults to 500 as a SCAN hint. `batchSize` separately
+defaults to 500 and bounds one non-atomic pipeline.
+
+`SCAN` is non-snapshot: concurrent writes can make counts include duplicates, omit keys, or differ
+from the keys that exist when the call returns. The optional `signal` is checked before and after
+each SCAN and EXPIRE-batch boundary; its exact abort reason is rethrown without reporting it to the
+configured Valkey error handler.
+
 ## `normalizeKey(key)`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valkyries",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Valkey utilities for caches, bloom filters, dynamic configuration, and rate limiting.",
   "homepage": "https://github.com/jonathanong/valkyries#readme",
   "bugs": {
@@ -32,6 +32,11 @@
       "import": "./dist/cache.mjs",
       "default": "./dist/cache.mjs"
     },
+    "./channel-pubsub": {
+      "types": "./dist/channel-pubsub.d.mts",
+      "import": "./dist/channel-pubsub.mjs",
+      "default": "./dist/channel-pubsub.mjs"
+    },
     "./conditional": {
       "types": "./dist/conditional.d.mts",
       "import": "./dist/conditional.mjs",
@@ -65,9 +70,9 @@
     "@types/node": "^26.1.0",
     "@vitest/coverage-v8": "^4.1.6",
     "github-actionlint": "^1.7.12",
-    "oxfmt": "^0.59.0",
+    "oxfmt": "^0.63.0",
     "oxlint": "^1.65.0",
-    "oxlint-tsgolint": "^0.25.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "tsx": "^4.22.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.6"