@ayepi/redis 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,108 @@
+# @ayepi/redis
+
+Redis backends for running ayepi on **more than one instance**, built for
+[ioredis](https://github.com/redis/ioredis). It ships **four** things:
+
+- **`redisBroker`** — a pub/sub [`Broker`](https://www.npmjs.com/package/@ayepi/core) so an
+  `emit` on one instance reaches subscribers on **every** instance (multi-pod event fanout,
+  no sticky sessions).
+- **`redisStore`** — a [`@ayepi/work`](https://www.npmjs.com/package/@ayepi/work) `Store`
+  (get/set with TTL, atomic `setIfNotExists` claim, atomic `increment`).
+- **`redisPubSub`** — a `@ayepi/work` `PubSub` (the same fanout as `redisBroker`, under the
+  work-port name so `{ store, pubsub }` reads cleanly).
+- **`redisCache`** — a [`@ayepi/cache`](https://www.npmjs.com/package/@ayepi/cache)
+  `CacheStore` so a response cache is shared across instances.
+
+Every Redis call in the store/cache is wrapped in `@ayepi/core`'s configurable `retry`, so a
+transient blip is absorbed rather than surfaced.
+
+```sh
+pnpm add @ayepi/redis @ayepi/core ioredis
+# add @ayepi/work and/or @ayepi/cache only if you use those backends (see below)
+```
+
+```ts
+import Redis from 'ioredis'
+import { implement, server } from '@ayepi/core'
+import { redisBroker } from '@ayepi/redis'
+
+const app = server(api, [implement(api).handlers(handlers)], {
+  broker: redisBroker(new Redis(process.env.REDIS_URL)),
+})
+```
+
+## How it works
+
+- **Dedicated subscriber connection.** A connection in subscribe mode can't run
+  other commands, so the broker subscribes on a *separate* connection
+  (`client.duplicate()` by default, or pass `opts.subscriber`); the original
+  `client` only publishes.
+- **Reconnect is handled by ioredis** — it auto-resubscribes after a reconnect,
+  so a network blip won't silently stop event delivery.
+- **Best-effort, ephemeral.** Redis pub/sub doesn't persist: a pod that's down
+  misses events. Ideal for live UI events (progress, presence, chat fanout). For
+  guaranteed delivery use a durable transport.
+
+## Options
+
+```ts
+redisBroker(client, {
+  channel: 'ayepi',          // pub/sub channel (all instances must agree)
+  subscriber: mySubClient,   // custom subscriber connection (default: client.duplicate())
+  onError: (err) => log(err) // publish/subscribe/connection errors
+})
+```
+
+## Work backend (`redisStore` + `redisPubSub`)
+
+A drop-in [`@ayepi/work`](https://www.npmjs.com/package/@ayepi/work) backend pairing — hand
+them to `createWork` alongside a durable queue (e.g. `sqsQueue` from `@ayepi/aws`):
+
+```ts
+import Redis from 'ioredis'
+import { redisStore, redisPubSub } from '@ayepi/redis'
+
+const redis = new Redis(process.env.REDIS_URL)
+createWork({ work, store: redisStore(redis), pubsub: redisPubSub(redis), queue })
+```
+
+- `redisStore(client, { prefix, retry, onError })` — `setIfNotExists` is `SET NX` (the atomic
+  CAS behind every claim/lease); `increment` is `INCRBY` (the group counter). Keys are
+  namespaced by `prefix` (default none).
+- `redisPubSub(client, opts?)` — same options and fanout as `redisBroker`; best-effort, used
+  to wake distributed waiters (the engine's store-poll covers a silent channel).
+
+`@ayepi/work` is an **optional, type-only peer dep** — only install it if you use these.
+
+## Cache store (`redisCache`)
+
+A [`@ayepi/cache`](https://www.npmjs.com/package/@ayepi/cache) `CacheStore` so the response
+cache is shared across instances:
+
+```ts
+import Redis from 'ioredis'
+import { cache } from '@ayepi/cache/server'
+import { redisCache } from '@ayepi/redis'
+
+const redis = new Redis(process.env.REDIS_URL)
+implement(api).middleware(cache.server(cached, { store: redisCache(redis), ttl: 30_000 }))
+```
+
+- `redisCache(client, { prefix, retry, onError, now })` — entries are JSON with a Redis `PX`
+  TTL derived from `entry.staleUntil` (dead entries self-evict); `clear`/`invalidate` `SCAN`
+  the `prefix` (default `'ayepi:cache:'`).
+
+`@ayepi/cache` is an **optional, type-only peer dep** — only install it if you use this.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-redis.md`](./ayepi-redis.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/redis) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,173 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+//#region src/backends.ts
+/**
+* # @ayepi/redis — work Store + cache store
+*
+* Redis implementations of the `@ayepi/work` {@link Store} port and the `@ayepi/cache`
+* `CacheStore`, plus the {@link redisPubSub} pairing. Every Redis call is wrapped in core's
+* {@link retry} (configurable per store) so a transient blip or a throttled reply is absorbed
+* rather than surfaced; a final failure fires `onError` and propagates.
+*
+* @module
+*/
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+function makeRun(opts) {
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
+	return (fn) => (0, _ayepi_core.retry)(fn, {
+		...opts.retry,
+		onError: (err) => report(err)
+	});
+}
+/**
+* A Redis-backed `@ayepi/work` {@link Store}: `get`/`set` (with `PX` TTL), `delete`,
+* `setIfNotExists` (`SET NX`, the CAS atom behind every claim), and `increment` (`INCRBY`,
+* the group counter). Pair with {@link redisPubSub} and a durable queue.
+*
+* @example
+* ```ts
+* import Redis from 'ioredis';
+* const c = new Redis(process.env.REDIS_URL);
+* createWork({ work, store: redisStore(c), pubsub: redisPubSub(c), queue: sqsQueue(...) });
+* ```
+*/
+function redisStore(client, opts = {}) {
+	const ns = opts.prefix ?? "";
+	const run = makeRun(opts);
+	return {
+		get: (key) => run(async () => await client.get(ns + key) ?? void 0),
+		set: (key, value, ttl) => run(async () => {
+			await (ttl !== void 0 ? client.set(ns + key, value, "PX", ttl) : client.set(ns + key, value));
+		}),
+		delete: (key) => run(async () => {
+			await client.del(ns + key);
+		}),
+		setIfNotExists: (key, value, ttl) => run(async () => {
+			return (ttl !== void 0 ? await client.set(ns + key, value, "PX", ttl, "NX") : await client.set(ns + key, value, "NX")) !== null;
+		}),
+		increment: (key, by, ttl) => run(async () => {
+			const v = await client.incrby(ns + key, by);
+			if (ttl !== void 0) await client.pexpire(ns + key, ttl);
+			return v;
+		})
+	};
+}
+/**
+* A Redis-backed `@ayepi/cache` `CacheStore`: entries are JSON with a Redis `PX` TTL set from
+* `entry.staleUntil` (so dead entries self-evict); `clear`/`invalidate` use `SCAN` over the
+* prefix. Hand it to `cache.server(def, { store: redisCache(client) })` for a cache shared
+* across instances.
+*/
+function redisCache(client, opts = {}) {
+	const ns = opts.prefix ?? "ayepi:cache:";
+	const now = opts.now ?? Date.now;
+	const run = makeRun(opts);
+	const scanKeys = async () => {
+		const keys = [];
+		let cursor = "0";
+		do {
+			const [next, batch] = await client.scan(cursor, "MATCH", `${ns}*`, "COUNT", 256);
+			keys.push(...batch);
+			cursor = next;
+		} while (cursor !== "0");
+		return keys;
+	};
+	return {
+		get: (key) => run(async () => {
+			const raw = await client.get(ns + key);
+			return raw ? JSON.parse(raw) : void 0;
+		}),
+		set: (key, entry) => run(async () => {
+			await client.set(ns + key, JSON.stringify(entry), "PX", Math.max(1, entry.staleUntil - now()));
+		}),
+		delete: (key) => run(async () => await client.del(ns + key) > 0),
+		clear: () => run(async () => {
+			const keys = await scanKeys();
+			if (keys.length) await client.del(...keys);
+		}),
+		invalidate: (pred) => run(async () => {
+			const remove = [];
+			for (const k of await scanKeys()) {
+				const raw = await client.get(k);
+				if (!raw) continue;
+				const e = JSON.parse(raw);
+				if (pred({
+					key: e.key,
+					method: e.method,
+					path: e.path,
+					storedAt: e.storedAt,
+					expires: e.expires,
+					staleUntil: e.staleUntil,
+					bytes: e.bytes
+				})) remove.push(k);
+			}
+			if (remove.length) await client.del(...remove);
+			return remove.length;
+		})
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Create a Redis pub/sub {@link Broker}.
+*
+* @param client - an ioredis connection used to `publish` (a dedicated subscriber
+*                 connection is derived via `client.duplicate()` unless you pass
+*                 `opts.subscriber`).
+*/
+function redisBroker(client, opts = {}) {
+	const channel = opts.channel ?? "ayepi";
+	const sub = opts.subscriber ?? client.duplicate();
+	const listeners = /* @__PURE__ */ new Set();
+	const onError = opts.onError;
+	let wired = false;
+	const wire = () => {
+		if (wired) return;
+		wired = true;
+		sub.on("message", (ch, message) => {
+			if (ch !== channel) return;
+			for (const l of listeners) try {
+				l(message);
+			} catch (err) {
+				onError?.(err);
+			}
+		});
+		if (onError) {
+			sub.on("error", onError);
+			client.on("error", onError);
+		}
+		Promise.resolve().then(() => sub.subscribe(channel)).catch((err) => onError?.(err));
+	};
+	return {
+		publish(message) {
+			return Promise.resolve().then(() => client.publish(channel, message)).then(() => void 0, (err) => {
+				onError?.(err);
+			});
+		},
+		subscribe(listener) {
+			wire();
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+/**
+* The `@ayepi/work` {@link PubSub} backed by Redis pub/sub — the same fanout as
+* {@link redisBroker} (the two ports are identical), exposed under the work-port name so
+* `{ store: redisStore(c), pubsub: redisPubSub(c) }` reads cleanly. Best-effort: it wakes
+* distributed waiters; the engine's store-poll fallback covers a silent channel.
+*/
+function redisPubSub(client, opts = {}) {
+	return redisBroker(client, opts);
+}
+//#endregion
+exports.redisBroker = redisBroker;
+exports.redisCache = redisCache;
+exports.redisPubSub = redisPubSub;
+exports.redisStore = redisStore;

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+import { Broker, RetryOptions } from "@ayepi/core";
+import { PubSub, Store } from "@ayepi/work";
+import { CacheStore } from "@ayepi/cache";
+
+//#region src/backends.d.ts
+
+/**
+ * The minimal command surface the store/cache use — `ioredis`'s `Redis` satisfies it
+ * structurally. (The pub/sub {@link redisBroker} uses a different, subscribe-mode surface.)
+ */
+interface RedisCommandClient {
+  get(key: string): Promise<string | null>;
+  /** `set(key, value)` / `set(key, value, 'PX', ttl)` / `set(key, value, 'NX')` — returns `'OK'` or `null`. */
+  set(key: string, value: string, ...args: (string | number)[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  incrby(key: string, increment: number): Promise<number>;
+  pexpire(key: string, ms: number): Promise<number>;
+  scan(cursor: string | number, ...args: (string | number)[]): Promise<[cursor: string, keys: string[]]>;
+}
+/** Shared resilience options. */
+interface ResilientOptions {
+  /** Key prefix/namespace. */
+  readonly prefix?: string;
+  /** Retry policy for each Redis call (see core `retry` — `attempts`/`base`/`factor`/`max`/`jitter`/…). */
+  readonly retry?: Omit<RetryOptions, 'errorResult'>;
+  /** Notified when a call fails after exhausting retries (the error then propagates). Off by default; must not throw. */
+  readonly onError?: (err: unknown) => void;
+}
+/** Options for {@link redisStore}. */
+interface RedisStoreOptions extends ResilientOptions {}
+/**
+ * A Redis-backed `@ayepi/work` {@link Store}: `get`/`set` (with `PX` TTL), `delete`,
+ * `setIfNotExists` (`SET NX`, the CAS atom behind every claim), and `increment` (`INCRBY`,
+ * the group counter). Pair with {@link redisPubSub} and a durable queue.
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * const c = new Redis(process.env.REDIS_URL);
+ * createWork({ work, store: redisStore(c), pubsub: redisPubSub(c), queue: sqsQueue(...) });
+ * ```
+ */
+declare function redisStore(client: RedisCommandClient, opts?: RedisStoreOptions): Store;
+/** Options for {@link redisCache}. */
+interface RedisCacheOptions extends ResilientOptions {
+  /** Clock for the stored TTL (default `Date.now`). */
+  readonly now?: () => number;
+}
+/**
+ * A Redis-backed `@ayepi/cache` `CacheStore`: entries are JSON with a Redis `PX` TTL set from
+ * `entry.staleUntil` (so dead entries self-evict); `clear`/`invalidate` use `SCAN` over the
+ * prefix. Hand it to `cache.server(def, { store: redisCache(client) })` for a cache shared
+ * across instances.
+ */
+declare function redisCache(client: RedisCommandClient, opts?: RedisCacheOptions): CacheStore;
+//#endregion
+//#region src/index.d.ts
+/**
+ * The minimal ioredis surface this broker uses. `ioredis`'s `Redis` satisfies it
+ * structurally; a compatible client (e.g. node-redis with matching method shapes)
+ * works too.
+ */
+interface RedisLike {
+  /** Publish a message to a channel; returns the number of receivers (or a promise of it). */
+  publish(channel: string, message: string): Promise<number> | number;
+  /** Subscribe the connection to one or more channels. */
+  subscribe(...channels: string[]): Promise<unknown> | unknown;
+  /** Unsubscribe the connection from one or more channels. */
+  unsubscribe(...channels: string[]): Promise<unknown> | unknown;
+  /** Create a second connection with the same options (used for the subscriber). */
+  duplicate(): RedisLike;
+  /** Listen for delivered messages. */
+  on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+  /** Listen for connection errors. */
+  on(event: 'error', listener: (error: Error) => void): unknown;
+}
+/** Options for {@link redisBroker}. */
+interface RedisBrokerOptions {
+  /** The pub/sub channel name (default `'ayepi'`). All instances must agree. */
+  readonly channel?: string;
+  /**
+   * The connection to subscribe on. Defaults to `client.duplicate()`. Provide one
+   * if you manage connections yourself — it must be dedicated to subscribing.
+   */
+  readonly subscriber?: RedisLike;
+  /** Notified on publish/subscribe/connection errors. */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * Create a Redis pub/sub {@link Broker}.
+ *
+ * @param client - an ioredis connection used to `publish` (a dedicated subscriber
+ *                 connection is derived via `client.duplicate()` unless you pass
+ *                 `opts.subscriber`).
+ */
+declare function redisBroker(client: RedisLike, opts?: RedisBrokerOptions): Broker;
+/**
+ * The `@ayepi/work` {@link PubSub} backed by Redis pub/sub — the same fanout as
+ * {@link redisBroker} (the two ports are identical), exposed under the work-port name so
+ * `{ store: redisStore(c), pubsub: redisPubSub(c) }` reads cleanly. Best-effort: it wakes
+ * distributed waiters; the engine's store-poll fallback covers a silent channel.
+ */
+declare function redisPubSub(client: RedisLike, opts?: RedisBrokerOptions): PubSub;
+//#endregion
+export { RedisBrokerOptions, type RedisCacheOptions, type RedisCommandClient, RedisLike, type RedisStoreOptions, redisBroker, redisCache, redisPubSub, redisStore };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { Broker, RetryOptions } from "@ayepi/core";
+import { PubSub, Store } from "@ayepi/work";
+import { CacheStore } from "@ayepi/cache";
+
+//#region src/backends.d.ts
+
+/**
+ * The minimal command surface the store/cache use — `ioredis`'s `Redis` satisfies it
+ * structurally. (The pub/sub {@link redisBroker} uses a different, subscribe-mode surface.)
+ */
+interface RedisCommandClient {
+  get(key: string): Promise<string | null>;
+  /** `set(key, value)` / `set(key, value, 'PX', ttl)` / `set(key, value, 'NX')` — returns `'OK'` or `null`. */
+  set(key: string, value: string, ...args: (string | number)[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  incrby(key: string, increment: number): Promise<number>;
+  pexpire(key: string, ms: number): Promise<number>;
+  scan(cursor: string | number, ...args: (string | number)[]): Promise<[cursor: string, keys: string[]]>;
+}
+/** Shared resilience options. */
+interface ResilientOptions {
+  /** Key prefix/namespace. */
+  readonly prefix?: string;
+  /** Retry policy for each Redis call (see core `retry` — `attempts`/`base`/`factor`/`max`/`jitter`/…). */
+  readonly retry?: Omit<RetryOptions, 'errorResult'>;
+  /** Notified when a call fails after exhausting retries (the error then propagates). Off by default; must not throw. */
+  readonly onError?: (err: unknown) => void;
+}
+/** Options for {@link redisStore}. */
+interface RedisStoreOptions extends ResilientOptions {}
+/**
+ * A Redis-backed `@ayepi/work` {@link Store}: `get`/`set` (with `PX` TTL), `delete`,
+ * `setIfNotExists` (`SET NX`, the CAS atom behind every claim), and `increment` (`INCRBY`,
+ * the group counter). Pair with {@link redisPubSub} and a durable queue.
+ *
+ * @example
+ * ```ts
+ * import Redis from 'ioredis';
+ * const c = new Redis(process.env.REDIS_URL);
+ * createWork({ work, store: redisStore(c), pubsub: redisPubSub(c), queue: sqsQueue(...) });
+ * ```
+ */
+declare function redisStore(client: RedisCommandClient, opts?: RedisStoreOptions): Store;
+/** Options for {@link redisCache}. */
+interface RedisCacheOptions extends ResilientOptions {
+  /** Clock for the stored TTL (default `Date.now`). */
+  readonly now?: () => number;
+}
+/**
+ * A Redis-backed `@ayepi/cache` `CacheStore`: entries are JSON with a Redis `PX` TTL set from
+ * `entry.staleUntil` (so dead entries self-evict); `clear`/`invalidate` use `SCAN` over the
+ * prefix. Hand it to `cache.server(def, { store: redisCache(client) })` for a cache shared
+ * across instances.
+ */
+declare function redisCache(client: RedisCommandClient, opts?: RedisCacheOptions): CacheStore;
+//#endregion
+//#region src/index.d.ts
+/**
+ * The minimal ioredis surface this broker uses. `ioredis`'s `Redis` satisfies it
+ * structurally; a compatible client (e.g. node-redis with matching method shapes)
+ * works too.
+ */
+interface RedisLike {
+  /** Publish a message to a channel; returns the number of receivers (or a promise of it). */
+  publish(channel: string, message: string): Promise<number> | number;
+  /** Subscribe the connection to one or more channels. */
+  subscribe(...channels: string[]): Promise<unknown> | unknown;
+  /** Unsubscribe the connection from one or more channels. */
+  unsubscribe(...channels: string[]): Promise<unknown> | unknown;
+  /** Create a second connection with the same options (used for the subscriber). */
+  duplicate(): RedisLike;
+  /** Listen for delivered messages. */
+  on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+  /** Listen for connection errors. */
+  on(event: 'error', listener: (error: Error) => void): unknown;
+}
+/** Options for {@link redisBroker}. */
+interface RedisBrokerOptions {
+  /** The pub/sub channel name (default `'ayepi'`). All instances must agree. */
+  readonly channel?: string;
+  /**
+   * The connection to subscribe on. Defaults to `client.duplicate()`. Provide one
+   * if you manage connections yourself — it must be dedicated to subscribing.
+   */
+  readonly subscriber?: RedisLike;
+  /** Notified on publish/subscribe/connection errors. */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * Create a Redis pub/sub {@link Broker}.
+ *
+ * @param client - an ioredis connection used to `publish` (a dedicated subscriber
+ *                 connection is derived via `client.duplicate()` unless you pass
+ *                 `opts.subscriber`).
+ */
+declare function redisBroker(client: RedisLike, opts?: RedisBrokerOptions): Broker;
+/**
+ * The `@ayepi/work` {@link PubSub} backed by Redis pub/sub — the same fanout as
+ * {@link redisBroker} (the two ports are identical), exposed under the work-port name so
+ * `{ store: redisStore(c), pubsub: redisPubSub(c) }` reads cleanly. Best-effort: it wakes
+ * distributed waiters; the engine's store-poll fallback covers a silent channel.
+ */
+declare function redisPubSub(client: RedisLike, opts?: RedisBrokerOptions): PubSub;
+//#endregion
+export { RedisBrokerOptions, type RedisCacheOptions, type RedisCommandClient, RedisLike, type RedisStoreOptions, redisBroker, redisCache, redisPubSub, redisStore };

package/dist/index.js

@@ -0,0 +1,169 @@
+import { retry } from "@ayepi/core";
+//#region src/backends.ts
+/**
+* # @ayepi/redis — work Store + cache store
+*
+* Redis implementations of the `@ayepi/work` {@link Store} port and the `@ayepi/cache`
+* `CacheStore`, plus the {@link redisPubSub} pairing. Every Redis call is wrapped in core's
+* {@link retry} (configurable per store) so a transient blip or a throttled reply is absorbed
+* rather than surfaced; a final failure fires `onError` and propagates.
+*
+* @module
+*/
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+function makeRun(opts) {
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
+	return (fn) => retry(fn, {
+		...opts.retry,
+		onError: (err) => report(err)
+	});
+}
+/**
+* A Redis-backed `@ayepi/work` {@link Store}: `get`/`set` (with `PX` TTL), `delete`,
+* `setIfNotExists` (`SET NX`, the CAS atom behind every claim), and `increment` (`INCRBY`,
+* the group counter). Pair with {@link redisPubSub} and a durable queue.
+*
+* @example
+* ```ts
+* import Redis from 'ioredis';
+* const c = new Redis(process.env.REDIS_URL);
+* createWork({ work, store: redisStore(c), pubsub: redisPubSub(c), queue: sqsQueue(...) });
+* ```
+*/
+function redisStore(client, opts = {}) {
+	const ns = opts.prefix ?? "";
+	const run = makeRun(opts);
+	return {
+		get: (key) => run(async () => await client.get(ns + key) ?? void 0),
+		set: (key, value, ttl) => run(async () => {
+			await (ttl !== void 0 ? client.set(ns + key, value, "PX", ttl) : client.set(ns + key, value));
+		}),
+		delete: (key) => run(async () => {
+			await client.del(ns + key);
+		}),
+		setIfNotExists: (key, value, ttl) => run(async () => {
+			return (ttl !== void 0 ? await client.set(ns + key, value, "PX", ttl, "NX") : await client.set(ns + key, value, "NX")) !== null;
+		}),
+		increment: (key, by, ttl) => run(async () => {
+			const v = await client.incrby(ns + key, by);
+			if (ttl !== void 0) await client.pexpire(ns + key, ttl);
+			return v;
+		})
+	};
+}
+/**
+* A Redis-backed `@ayepi/cache` `CacheStore`: entries are JSON with a Redis `PX` TTL set from
+* `entry.staleUntil` (so dead entries self-evict); `clear`/`invalidate` use `SCAN` over the
+* prefix. Hand it to `cache.server(def, { store: redisCache(client) })` for a cache shared
+* across instances.
+*/
+function redisCache(client, opts = {}) {
+	const ns = opts.prefix ?? "ayepi:cache:";
+	const now = opts.now ?? Date.now;
+	const run = makeRun(opts);
+	const scanKeys = async () => {
+		const keys = [];
+		let cursor = "0";
+		do {
+			const [next, batch] = await client.scan(cursor, "MATCH", `${ns}*`, "COUNT", 256);
+			keys.push(...batch);
+			cursor = next;
+		} while (cursor !== "0");
+		return keys;
+	};
+	return {
+		get: (key) => run(async () => {
+			const raw = await client.get(ns + key);
+			return raw ? JSON.parse(raw) : void 0;
+		}),
+		set: (key, entry) => run(async () => {
+			await client.set(ns + key, JSON.stringify(entry), "PX", Math.max(1, entry.staleUntil - now()));
+		}),
+		delete: (key) => run(async () => await client.del(ns + key) > 0),
+		clear: () => run(async () => {
+			const keys = await scanKeys();
+			if (keys.length) await client.del(...keys);
+		}),
+		invalidate: (pred) => run(async () => {
+			const remove = [];
+			for (const k of await scanKeys()) {
+				const raw = await client.get(k);
+				if (!raw) continue;
+				const e = JSON.parse(raw);
+				if (pred({
+					key: e.key,
+					method: e.method,
+					path: e.path,
+					storedAt: e.storedAt,
+					expires: e.expires,
+					staleUntil: e.staleUntil,
+					bytes: e.bytes
+				})) remove.push(k);
+			}
+			if (remove.length) await client.del(...remove);
+			return remove.length;
+		})
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* Create a Redis pub/sub {@link Broker}.
+*
+* @param client - an ioredis connection used to `publish` (a dedicated subscriber
+*                 connection is derived via `client.duplicate()` unless you pass
+*                 `opts.subscriber`).
+*/
+function redisBroker(client, opts = {}) {
+	const channel = opts.channel ?? "ayepi";
+	const sub = opts.subscriber ?? client.duplicate();
+	const listeners = /* @__PURE__ */ new Set();
+	const onError = opts.onError;
+	let wired = false;
+	const wire = () => {
+		if (wired) return;
+		wired = true;
+		sub.on("message", (ch, message) => {
+			if (ch !== channel) return;
+			for (const l of listeners) try {
+				l(message);
+			} catch (err) {
+				onError?.(err);
+			}
+		});
+		if (onError) {
+			sub.on("error", onError);
+			client.on("error", onError);
+		}
+		Promise.resolve().then(() => sub.subscribe(channel)).catch((err) => onError?.(err));
+	};
+	return {
+		publish(message) {
+			return Promise.resolve().then(() => client.publish(channel, message)).then(() => void 0, (err) => {
+				onError?.(err);
+			});
+		},
+		subscribe(listener) {
+			wire();
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+/**
+* The `@ayepi/work` {@link PubSub} backed by Redis pub/sub — the same fanout as
+* {@link redisBroker} (the two ports are identical), exposed under the work-port name so
+* `{ store: redisStore(c), pubsub: redisPubSub(c) }` reads cleanly. Best-effort: it wakes
+* distributed waiters; the engine's store-poll fallback covers a silent channel.
+*/
+function redisPubSub(client, opts = {}) {
+	return redisBroker(client, opts);
+}
+//#endregion
+export { redisBroker, redisCache, redisPubSub, redisStore };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@ayepi/redis",
+  "version": "0.1.0",
+  "description": "Redis backends for ayepi (ioredis) — pub/sub Broker, @ayepi/work Store + PubSub, and an @ayepi/cache store, all retry-wrapped",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/redis"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/redis#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "ioredis": "^5",
+    "@ayepi/work": "^0.1.0",
+    "@ayepi/core": "^0.1.0",
+    "@ayepi/cache": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@ayepi/work": {
+      "optional": true
+    },
+    "@ayepi/cache": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "ioredis": "^5.4.1",
+    "publint": "^0.3.0",
+    "testcontainers": "^10.13.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/cache": "0.1.0",
+    "@ayepi/work": "0.1.0",
+    "@ayepi/core": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "@ayepi/core",
+    "redis",
+    "ioredis",
+    "broker",
+    "pubsub",
+    "websocket"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "publint": "publint"
+  }
+}