@mastra/valkey-streams 0.0.0 → 0.5.0

package/dist/index.cjs

@@ -0,0 +1,751 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let crypto = require("crypto");
+let _mastra_core_events = require("@mastra/core/events");
+let _valkey_valkey_glide = require("@valkey/valkey-glide");
+//#region src/client.ts
+const text = (value) => Buffer.isBuffer(value) ? value.toString() : String(value);
+var ValkeyMulti = class {
+	getClient;
+	#batch = new _valkey_valkey_glide.Batch(true);
+	constructor(getClient) {
+		this.getClient = getClient;
+	}
+	xAdd(key, id, fields, options = {}) {
+		const args = ["XADD", key];
+		if (options.TRIM) args.push("MAXLEN", "~", String(options.TRIM.threshold));
+		args.push(id, ...Object.entries(fields).flat());
+		this.#batch.customCommand(args);
+		return this;
+	}
+	pExpire(key, ttl) {
+		this.#batch.customCommand([
+			"PEXPIRE",
+			key,
+			String(ttl)
+		]);
+		return this;
+	}
+	xGroupCreate(key, group, id, options = {}) {
+		this.#batch.xgroupCreate(key, group, id, { mkStream: options.MKSTREAM });
+		return this;
+	}
+	async exec() {
+		return await (await this.getClient()).exec(this.#batch, true, { decoder: _valkey_valkey_glide.Decoder.String }) ?? [];
+	}
+};
+var ValkeyStreamsClient = class {
+	options;
+	#client;
+	constructor(options) {
+		this.options = options;
+	}
+	get isOpen() {
+		return this.#client !== void 0;
+	}
+	on(_event, _listener) {
+		return this;
+	}
+	async connect() {
+		await this.getClient();
+	}
+	async quit() {
+		(await this.getClient()).close();
+	}
+	multi() {
+		return new ValkeyMulti(() => this.getClient());
+	}
+	async command(args) {
+		return (await this.getClient()).customCommand(args, { decoder: _valkey_valkey_glide.Decoder.String });
+	}
+	async xAdd(key, id, fields, options = {}) {
+		const args = ["XADD", key];
+		if (options.TRIM) args.push("MAXLEN", "~", String(options.TRIM.threshold));
+		args.push(id, ...Object.entries(fields).flat());
+		return text(await this.command(args));
+	}
+	async pExpire(key, ttl) {
+		return Number(await this.command([
+			"PEXPIRE",
+			key,
+			String(ttl)
+		]));
+	}
+	async xGroupCreate(key, group, id, options = {}) {
+		return (await this.getClient()).xgroupCreate(key, group, id, { mkStream: options.MKSTREAM });
+	}
+	async xGroupDestroy(key, group) {
+		return Number(await this.command([
+			"XGROUP",
+			"DESTROY",
+			key,
+			group
+		]));
+	}
+	async xReadGroup(group, consumer, streams, options = {}) {
+		return (await (await this.getClient()).xreadgroup(group, consumer, Object.fromEntries(streams.map((stream) => [stream.key, stream.id])), {
+			count: options.COUNT,
+			block: options.BLOCK,
+			decoder: _valkey_valkey_glide.Decoder.String
+		}))?.map((stream) => ({
+			name: text(stream.key),
+			messages: Object.entries(stream.value ?? {}).map(([id, fields]) => ({
+				id,
+				message: Object.fromEntries(fields?.map(([field, value]) => [text(field), text(value)]) ?? [])
+			}))
+		})) ?? null;
+	}
+	async xAutoClaim(key, group, consumer, minIdle, start, options = {}) {
+		const result = await (await this.getClient()).xautoclaim(key, group, consumer, minIdle, start, {
+			count: options.COUNT,
+			decoder: _valkey_valkey_glide.Decoder.String
+		});
+		return {
+			nextId: text(result[0]),
+			messages: Object.entries(result[1] ?? {}).map(([id, fields]) => ({
+				id,
+				message: Object.fromEntries(fields.map(([field, value]) => [text(field), text(value)]))
+			}))
+		};
+	}
+	async xAck(key, group, id) {
+		return (await this.getClient()).xack(key, group, [id]);
+	}
+	async del(key) {
+		return Number(await this.command(["DEL", key]));
+	}
+	async set(key, value, options = {}) {
+		const args = [
+			"SET",
+			key,
+			value
+		];
+		if (options.NX) args.push("NX");
+		if (options.PX) args.push("PX", String(options.PX));
+		const result = await this.command(args);
+		return result === null ? null : text(result);
+	}
+	async get(key) {
+		const result = await this.command(["GET", key]);
+		return result === null ? null : text(result);
+	}
+	async eval(script, options) {
+		return Number(await this.command([
+			"EVAL",
+			script,
+			String(options.keys.length),
+			...options.keys,
+			...options.arguments
+		]));
+	}
+	getClient() {
+		if (!this.#client) {
+			const { url, ...configuration } = this.options;
+			const parsed = url ? new URL(url) : void 0;
+			this.#client = _valkey_valkey_glide.GlideClient.createClient({
+				...configuration,
+				addresses: configuration.addresses ?? [{
+					host: parsed?.hostname ?? "localhost",
+					port: Number(parsed?.port || 6379)
+				}],
+				credentials: configuration.credentials ?? (parsed?.password ? {
+					username: parsed.username || "default",
+					password: parsed.password
+				} : void 0),
+				databaseId: configuration.databaseId ?? (parsed?.pathname ? Number(parsed.pathname.slice(1) || 0) : void 0)
+			});
+		}
+		return this.#client;
+	}
+};
+const createClient = (options) => new ValkeyStreamsClient(options);
+//#endregion
+//#region src/index.ts
+/**
+* Flatten an error into searchable text. node-redis MULTI failures throw a
+* `MultiErrorReply` whose own message is just "N commands failed…" — the real
+* per-command errors (e.g. BUSYGROUP) live in `err.replies`, so those are
+* folded in too.
+*/
+function errorText(err) {
+	const parts = [err instanceof Error ? err.message : String(err)];
+	if (err instanceof Error && "replies" in err && Array.isArray(err.replies)) parts.push(...err.replies.map((r) => String(r)));
+	return parts.join("; ");
+}
+var ValkeyStreamsPubSub = class extends _mastra_core_events.PubSub {
+	get supportedModes() {
+		return ["pull"];
+	}
+	get supportsOffsets() {
+		return false;
+	}
+	onUnsupportedOffset(offset) {
+		this.#logger?.warn?.(`valkey-streams: numeric replay offset ${offset} is unsupported; falling back to full replay`);
+	}
+	#writeClient;
+	#connectOptions;
+	#keyPrefix;
+	#blockMs;
+	#maxStreamLength;
+	#streamIdleTtlMs;
+	#reclaimIntervalMs;
+	#reclaimIdleMs;
+	#maxDeliveryAttempts;
+	#logger;
+	#subscriptions = /* @__PURE__ */ new Map();
+	#cbIds = /* @__PURE__ */ new WeakMap();
+	#pendingPublishes = /* @__PURE__ */ new Set();
+	#localCallbacks = /* @__PURE__ */ new Map();
+	#closed = false;
+	constructor(options = {}) {
+		super();
+		const url = options.url ?? options.valkeyOptions?.url ?? "valkey://localhost:6379";
+		this.#connectOptions = {
+			...options.valkeyOptions,
+			url
+		};
+		this.#writeClient = createClient(this.#connectOptions);
+		this.#logger = options.logger;
+		this.#attachErrorLogger(this.#writeClient, "write");
+		this.#keyPrefix = options.keyPrefix ?? "mastra:topic";
+		this.#blockMs = options.blockMs ?? 1e3;
+		this.#maxStreamLength = options.maxStreamLength ?? 1e4;
+		const ttl = options.streamIdleTtlMs ?? 0;
+		if (!Number.isInteger(ttl) || ttl < 0) throw new Error(`valkey-streams: streamIdleTtlMs must be a non-negative integer (milliseconds), got ${ttl}`);
+		this.#streamIdleTtlMs = ttl;
+		this.#reclaimIntervalMs = options.reclaimIntervalMs ?? 3e4;
+		this.#reclaimIdleMs = options.reclaimIdleMs ?? 6e4;
+		const cap = options.maxDeliveryAttempts ?? 5;
+		if (cap === 0) {
+			options.logger?.warn?.("valkey-streams: maxDeliveryAttempts=0 is treated as Infinity for back-compat; pass Infinity to disable the cap explicitly.");
+			this.#maxDeliveryAttempts = Infinity;
+		} else if (cap < 0 || Number.isNaN(cap)) throw new Error(`valkey-streams: maxDeliveryAttempts must be >= 1 or Infinity, got ${cap}`);
+		else this.#maxDeliveryAttempts = cap;
+	}
+	/**
+	* Attach the `'error'` listener node-redis requires on every client. Without
+	* one, a mid-life socket close makes the client emit an unhandled `'error'`,
+	* which (per EventEmitter semantics) throws from inside ValkeySocket's error
+	* handler BEFORE the built-in reconnect is scheduled — the process gets an
+	* uncaughtException and the client is left permanently un-reconnected
+	* (isOpen=true, isReady=false), hanging every subsequent command. Merely
+	* having a listener lets node-redis's own reconnect run.
+	*
+	* Logged at warn so operators can see connection churn, throttled to one line
+	* per 30s per client: node-redis re-emits `'error'` roughly every 500ms while
+	* a server is unreachable, and with one reader client per subscription an
+	* outage would otherwise flood the logs with thousands of identical lines.
+	*/
+	#attachErrorLogger(client, role, extra = {}) {
+		let lastWarnAt = 0;
+		client.on("error", (err) => {
+			const now = Date.now();
+			if (now - lastWarnAt < 3e4) return;
+			lastWarnAt = now;
+			this.#logger?.warn?.(`valkey-streams: ${role} client connection error (node-redis will reconnect)`, {
+				...extra,
+				err: err instanceof Error ? err.message : err
+			});
+		});
+	}
+	#subKey(topic, cb) {
+		let cbId = this.#cbIds.get(cb);
+		if (!cbId) {
+			cbId = (0, crypto.randomUUID)();
+			this.#cbIds.set(cb, cbId);
+		}
+		return `${topic}::${cbId}`;
+	}
+	/** Lazily connect the shared writer client. Idempotent. */
+	async #ensureWriterConnected() {
+		if (this.#writeClient.isOpen) return;
+		await this.#writeClient.connect();
+	}
+	#streamKey(topic) {
+		return `${this.#keyPrefix}:${topic}`;
+	}
+	async publish(topic, event, options) {
+		if (this.#closed) throw new Error("ValkeyStreamsPubSub: cannot publish on closed client");
+		if (options?.localOnly) {
+			const localEvent = {
+				...event,
+				id: (0, crypto.randomUUID)(),
+				createdAt: /* @__PURE__ */ new Date(),
+				deliveryAttempt: event.deliveryAttempt ?? 1
+			};
+			this.#deliverLocal(topic, localEvent);
+			return;
+		}
+		await this.#ensureWriterConnected();
+		const id = (0, crypto.randomUUID)();
+		const createdAt = /* @__PURE__ */ new Date();
+		const payload = {
+			...event,
+			id,
+			createdAt,
+			deliveryAttempt: event.deliveryAttempt ?? 1
+		};
+		const xaddOptions = {};
+		if (this.#maxStreamLength > 0) xaddOptions.TRIM = {
+			strategy: "MAXLEN",
+			strategyModifier: "~",
+			threshold: this.#maxStreamLength
+		};
+		const streamKey = this.#streamKey(topic);
+		const promise = this.#streamIdleTtlMs > 0 ? this.#writeClient.multi().xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions).pExpire(streamKey, this.#streamIdleTtlMs).exec().then((replies) => {
+			if (Number(replies[1]) !== 1) this.#logger?.warn?.("valkey-streams: PEXPIRE inside publish MULTI did not apply", {
+				streamKey,
+				reply: String(replies[1])
+			});
+		}) : this.#writeClient.xAdd(streamKey, "*", { event: JSON.stringify(payload) }, xaddOptions);
+		this.#pendingPublishes.add(promise);
+		try {
+			await promise;
+		} finally {
+			this.#pendingPublishes.delete(promise);
+		}
+	}
+	async subscribe(topic, cb, options) {
+		if (this.#closed) throw new Error("ValkeyStreamsPubSub: cannot subscribe on closed client");
+		const key = this.#subKey(topic, cb);
+		if (this.#subscriptions.has(key)) return;
+		let localBucket = this.#localCallbacks.get(topic);
+		if (!localBucket) {
+			localBucket = /* @__PURE__ */ new Set();
+			this.#localCallbacks.set(topic, localBucket);
+		}
+		localBucket.add(cb);
+		await this.#ensureWriterConnected();
+		const isGrouped = !!options?.group;
+		const group = options?.group ?? `__fanout-${(0, crypto.randomUUID)()}`;
+		const consumer = `${group}-${(0, crypto.randomUUID)()}`;
+		const streamKey = this.#streamKey(topic);
+		const groupAnchor = options?.startFrom === "latest" ? "$" : "0";
+		try {
+			if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xGroupCreate(streamKey, group, groupAnchor, { MKSTREAM: true }).pExpire(streamKey, this.#streamIdleTtlMs).exec();
+			else await this.#writeClient.xGroupCreate(streamKey, group, groupAnchor, { MKSTREAM: true });
+		} catch (err) {
+			if (!errorText(err).includes("BUSYGROUP")) throw err;
+			this.#logger?.debug?.("valkey-streams: consumer group already exists", {
+				topic,
+				group
+			});
+		}
+		const readClient = createClient(this.#connectOptions);
+		this.#attachErrorLogger(readClient, "read", { topic });
+		await readClient.connect();
+		const sub = {
+			cb,
+			topic,
+			streamKey,
+			group,
+			consumer,
+			isGrouped,
+			groupAnchor,
+			lastId: void 0,
+			readClient,
+			stopped: false,
+			loop: void 0,
+			reclaimTimer: void 0
+		};
+		this.#subscriptions.set(key, sub);
+		sub.loop = this.#runReadLoop(sub);
+		this.#startReclaimLoop(sub);
+	}
+	/**
+	* Periodically run XAUTOCLAIM against this subscription's group so that
+	* messages a crashed/stuck consumer read but never acked get redelivered to
+	* a live sibling. Runs only for grouped subscriptions — fan-out groups are
+	* private to one consumer, so there's no sibling to claim from.
+	*/
+	#startReclaimLoop(sub) {
+		if (this.#reclaimIntervalMs <= 0) return;
+		if (!sub.isGrouped) return;
+		const tick = async () => {
+			if (sub.stopped || this.#closed) return;
+			try {
+				const messages = (await this.#writeClient.xAutoClaim(sub.streamKey, sub.group, sub.consumer, this.#reclaimIdleMs, "0-0", { COUNT: 100 }))?.messages ?? [];
+				for (const entry of messages) {
+					if (sub.stopped || this.#closed) return;
+					if (!entry) continue;
+					await this.#deliverMessage(sub, entry.id, entry.message);
+				}
+			} catch (err) {
+				this.#logger?.debug?.("valkey-streams: XAUTOCLAIM failed", {
+					topic: sub.topic,
+					group: sub.group,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+			if (sub.stopped || this.#closed) return;
+			sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+		};
+		sub.reclaimTimer = setTimeout(tick, this.#reclaimIntervalMs);
+	}
+	async unsubscribe(topic, cb) {
+		const localBucket = this.#localCallbacks.get(topic);
+		if (localBucket) {
+			localBucket.delete(cb);
+			if (localBucket.size === 0) this.#localCallbacks.delete(topic);
+		}
+		const key = this.#subKey(topic, cb);
+		const sub = this.#subscriptions.get(key);
+		if (!sub) return;
+		this.#subscriptions.delete(key);
+		sub.stopped = true;
+		if (sub.reclaimTimer) {
+			clearTimeout(sub.reclaimTimer);
+			sub.reclaimTimer = void 0;
+		}
+		try {
+			await sub.readClient.quit();
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: reader quit failed", {
+				topic: sub.topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+		if (sub.loop) try {
+			await sub.loop;
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: read loop exited with error", {
+				topic: sub.topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+		if (!sub.isGrouped) try {
+			await this.#writeClient.xGroupDestroy(sub.streamKey, sub.group);
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: xGroupDestroy failed", {
+				topic: sub.topic,
+				group: sub.group,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
+	async flush() {
+		if (this.#pendingPublishes.size > 0) await Promise.allSettled([...this.#pendingPublishes]);
+	}
+	/**
+	* Delete a topic's stream, and with it every consumer group on that stream.
+	* This is the Valkey implementation of the optional `clearTopic` hook that
+	* consumers (e.g. `DurableAgent`) call to free a topic once its lifecycle is
+	* over — without it, a persistent backend accumulates every finished run's
+	* stream until Valkey exhausts its memory.
+	*
+	* Because it removes events for ALL consumers and destroys their groups, only
+	* call it once nothing will read the topic again. A subscriber still attached
+	* when the stream is deleted recovers on its own (the read loop recreates the
+	* group on NOGROUP) but will have missed the deleted entries.
+	*
+	* Best-effort and non-throwing: callers commonly invoke this fire-and-forget
+	* (`void clearTopic(...)`), so a rejection would surface as an
+	* unhandledRejection. Failures are swallowed and logged; the `streamIdleTtlMs`
+	* backstop (when configured) reclaims anything a failed delete leaves behind.
+	*/
+	async clearTopic(topic) {
+		if (this.#closed) return;
+		try {
+			await this.#ensureWriterConnected();
+			await this.#writeClient.del(this.#streamKey(topic));
+			for (const sub of this.#subscriptions.values()) if (sub.topic === topic) {
+				sub.lastId = void 0;
+				sub.groupAnchor = "0";
+			}
+		} catch (err) {
+			this.#logger?.warn?.("valkey-streams: clearTopic failed", {
+				topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
+	/**
+	* Lease key used in Valkey. Distinct prefix from streams so leases and
+	* streams can't collide on key namespace.
+	*/
+	#leaseKey(key) {
+		return `${this.#keyPrefix}:lease:${key}`;
+	}
+	/**
+	* Atomic claim via SET NX PX. Idempotent for the same owner: if the
+	* current value is already this owner, we refresh the TTL instead of
+	* failing. Cross-process callers race here; Valkey serializes them.
+	*/
+	async acquireLease(key, owner, ttlMs) {
+		if (this.#closed) return { acquired: false };
+		await this.#ensureWriterConnected();
+		const redisKey = this.#leaseKey(key);
+		if (await this.#writeClient.set(redisKey, owner, {
+			NX: true,
+			PX: ttlMs
+		}) === "OK") return {
+			acquired: true,
+			owner
+		};
+		if (await this.#writeClient.eval(`
+      local current = redis.call("GET", KEYS[1])
+      if current == ARGV[1] then
+        redis.call("PEXPIRE", KEYS[1], ARGV[2])
+        return 1
+      end
+      return 0
+    `, {
+			keys: [redisKey],
+			arguments: [owner, String(ttlMs)]
+		}) === 1) return {
+			acquired: true,
+			owner
+		};
+		return {
+			acquired: false,
+			owner: await this.#writeClient.get(redisKey) ?? void 0
+		};
+	}
+	async getLeaseOwner(key) {
+		if (this.#closed) return void 0;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.get(this.#leaseKey(key)) ?? void 0;
+	}
+	/**
+	* Release only if we still own it. Implemented as GET+DEL with a Lua
+	* script so the check-and-delete is atomic against concurrent renewals
+	* from other processes.
+	*/
+	async releaseLease(key, owner) {
+		if (this.#closed) return;
+		await this.#ensureWriterConnected();
+		await this.#writeClient.eval(`
+      if redis.call("GET", KEYS[1]) == ARGV[1] then
+        return redis.call("DEL", KEYS[1])
+      else
+        return 0
+      end
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [owner]
+		});
+	}
+	/**
+	* Extend the TTL only if we still own the lease. Returns false if the
+	* lease was lost (expired or another owner took it).
+	*/
+	async renewLease(key, owner, ttlMs) {
+		if (this.#closed) return false;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.eval(`
+      if redis.call("GET", KEYS[1]) == ARGV[1] then
+        return redis.call("PEXPIRE", KEYS[1], ARGV[2])
+      else
+        return 0
+      end
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [owner, String(ttlMs)]
+		}) === 1;
+	}
+	/**
+	* Atomically hand the lease from `fromOwner` to `toOwner`, refreshing the
+	* TTL to the full `ttlMs`, without the key ever going empty.
+	*
+	* Implemented as a single Lua script (GET == fromOwner -> SET toOwner PX)
+	* so a racing process cannot win the key between a release and a re-acquire.
+	* Returns false if `fromOwner` no longer holds the lease (expired or taken),
+	* in which case the caller should fall back to a fresh `acquireLease`.
+	*/
+	async transferLease(key, fromOwner, toOwner, ttlMs) {
+		if (this.#closed) return false;
+		await this.#ensureWriterConnected();
+		return await this.#writeClient.eval(`
+      if redis.call("GET", KEYS[1]) == ARGV[1] then
+        redis.call("SET", KEYS[1], ARGV[2], "PX", ARGV[3])
+        return 1
+      else
+        return 0
+      end
+    `, {
+			keys: [this.#leaseKey(key)],
+			arguments: [
+				fromOwner,
+				toOwner,
+				String(ttlMs)
+			]
+		}) === 1;
+	}
+	/**
+	* Disconnect all clients and stop all subscription loops.
+	*/
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		const subs = [...this.#subscriptions.values()];
+		await Promise.all(subs.map((sub) => this.unsubscribe(sub.topic, sub.cb)));
+		this.#localCallbacks.clear();
+		if (this.#writeClient.isOpen) try {
+			await this.#writeClient.quit();
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: writer quit failed", { err: err instanceof Error ? err.message : err });
+		}
+	}
+	async #runReadLoop(sub) {
+		while (!sub.stopped) {
+			let result;
+			try {
+				result = await sub.readClient.xReadGroup(sub.group, sub.consumer, [{
+					key: sub.streamKey,
+					id: ">"
+				}], {
+					COUNT: 10,
+					BLOCK: this.#blockMs
+				});
+			} catch (err) {
+				if (sub.stopped) return;
+				const msg = err instanceof Error ? err.message : String(err);
+				if (msg.includes("NOGROUP")) {
+					const recoveryAnchor = sub.lastId ?? sub.groupAnchor;
+					try {
+						if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xGroupCreate(sub.streamKey, sub.group, recoveryAnchor, { MKSTREAM: true }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
+						else await this.#writeClient.xGroupCreate(sub.streamKey, sub.group, recoveryAnchor, { MKSTREAM: true });
+						this.#logger?.debug?.("valkey-streams: recreated consumer group after NOGROUP", {
+							topic: sub.topic,
+							group: sub.group
+						});
+					} catch (recreateErr) {
+						const rmsg = errorText(recreateErr);
+						if (!rmsg.includes("BUSYGROUP")) this.#logger?.debug?.("valkey-streams: consumer group re-create failed", {
+							topic: sub.topic,
+							err: rmsg
+						});
+					}
+				} else this.#logger?.debug?.("valkey-streams: xReadGroup failed", {
+					topic: sub.topic,
+					group: sub.group,
+					err: msg
+				});
+				await new Promise((r) => setTimeout(r, 100));
+				continue;
+			}
+			if (!result || result.length === 0) continue;
+			for (const stream of result) for (const entry of stream.messages) {
+				if (sub.stopped) return;
+				sub.lastId = entry.id;
+				await this.#deliverMessage(sub, entry.id, entry.message);
+			}
+		}
+	}
+	async #deliverMessage(sub, streamId, fields) {
+		let event;
+		try {
+			event = JSON.parse(fields.event ?? "{}");
+			if (typeof event.createdAt === "string") event.createdAt = new Date(event.createdAt);
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: malformed payload, dropping", {
+				topic: sub.topic,
+				streamId,
+				err: err instanceof Error ? err.message : err
+			});
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (ackErr) {
+				this.#logger?.debug?.("valkey-streams: xAck after malformed payload failed", {
+					topic: sub.topic,
+					err: ackErr instanceof Error ? ackErr.message : ackErr
+				});
+			}
+			return;
+		}
+		let settled = false;
+		const ack = async () => {
+			if (settled) return;
+			settled = true;
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (err) {
+				this.#logger?.debug?.("valkey-streams: ack cleanup failed", {
+					topic: sub.topic,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+		};
+		const nack = async () => {
+			if (settled) return;
+			settled = true;
+			const attempt = event.deliveryAttempt ?? 1;
+			if (attempt >= this.#maxDeliveryAttempts) {
+				this.#logger?.warn?.("valkey-streams: dropping event after max delivery attempts", {
+					topic: sub.topic,
+					eventType: event.type,
+					eventId: event.id,
+					attempt,
+					max: this.#maxDeliveryAttempts
+				});
+				try {
+					await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+				} catch (err) {
+					this.#logger?.debug?.("valkey-streams: ack on dropped poison message failed", {
+						topic: sub.topic,
+						err: err instanceof Error ? err.message : err
+					});
+				}
+				return;
+			}
+			const next = {
+				...event,
+				deliveryAttempt: attempt + 1
+			};
+			try {
+				if (this.#streamIdleTtlMs > 0) await this.#writeClient.multi().xAdd(sub.streamKey, "*", { event: JSON.stringify(next) }).pExpire(sub.streamKey, this.#streamIdleTtlMs).exec();
+				else await this.#writeClient.xAdd(sub.streamKey, "*", { event: JSON.stringify(next) });
+			} catch (err) {
+				this.#logger?.warn?.("valkey-streams: nack republish failed; leaving original pending for reclaim", {
+					topic: sub.topic,
+					eventId: event.id,
+					err: err instanceof Error ? err.message : err
+				});
+				settled = false;
+				return;
+			}
+			try {
+				await this.#writeClient.xAck(sub.streamKey, sub.group, streamId);
+			} catch (err) {
+				this.#logger?.debug?.("valkey-streams: xAck after nack failed", {
+					topic: sub.topic,
+					err: err instanceof Error ? err.message : err
+				});
+			}
+		};
+		try {
+			const result = sub.cb(event, ack, nack);
+			if (result && typeof result.catch === "function") result.catch(async () => {
+				await nack();
+			});
+		} catch {
+			await nack();
+		}
+	}
+	#deliverLocal(topic, event) {
+		const callbacks = this.#localCallbacks.get(topic);
+		if (!callbacks || callbacks.size === 0) return;
+		for (const cb of callbacks) this.#invokeLocalCallback(topic, event, cb);
+	}
+	#invokeLocalCallback(topic, event, cb) {
+		const ack = async () => {};
+		const nack = async () => {};
+		try {
+			const result = cb(event, ack, nack);
+			if (result && typeof result.catch === "function") result.catch((err) => {
+				this.#logger?.debug?.("valkey-streams: local subscriber rejected", {
+					topic,
+					err: err instanceof Error ? err.message : err
+				});
+			});
+		} catch (err) {
+			this.#logger?.debug?.("valkey-streams: local subscriber threw", {
+				topic,
+				err: err instanceof Error ? err.message : err
+			});
+		}
+	}
+};
+//#endregion
+exports.ValkeyStreamsPubSub = ValkeyStreamsPubSub;
+
+//# sourceMappingURL=index.cjs.map