evstream 1.0.2 → 1.0.3

package/src/adapters/pub-sub.ts

@@ -0,0 +1,88 @@
+import Redis, { RedisOptions } from 'ioredis'
+import { uid } from '../utils.js'
+
+/**
+ * Configuration options for EvRedisPubSub
+ */
+interface EvRedisPubSubOptions<T> {
+	/** Redis Pub/Sub channel name */
+	subject: string
+
+	/** Redis connection options */
+	options: RedisOptions
+
+	/** Optional initial message handler */
+	onMessage?: (message: T) => void
+}
+
+/**
+ * Redis-based Pub/Sub helper for cross-process communication.
+ *
+ * - Uses separate publisher and subscriber connections
+ * - Prevents self-message delivery using instance UID
+ * - Typed message payload via generics
+ */
+export class EvRedisPubSub<T = unknown> {
+	#subject: string
+	#pub: Redis
+	#sub: Redis
+	#instanceId: string
+	#onMessage?: (message: T) => void
+
+	constructor({ options, subject, onMessage }: EvRedisPubSubOptions<T>) {
+		this.#pub = new Redis(options)
+		this.#sub = new Redis(options)
+		this.#subject = subject
+		this.#onMessage = onMessage
+		this.#instanceId = uid({ prefix: subject, counter: Math.random() })
+
+		this.init()
+	}
+
+	/**
+	 * Initializes Redis subscriptions and listeners.
+	 */
+	private async init() {
+		this.#pub.on('error', () => {})
+		this.#sub.on('error', () => {})
+
+		await this.#sub.subscribe(this.#subject)
+
+		this.#sub.on('message', (_, raw) => {
+			try {
+				const data = JSON.parse(raw)
+
+				// Ignore messages from the same instance
+				if (data?.uid !== this.#instanceId) {
+					this.#onMessage?.(data.msg as T)
+				}
+			} catch {
+				// Ignore malformed payloads
+			}
+		})
+	}
+
+	/**
+	 * Publishes a message to the Redis channel.
+	 */
+	async send(msg: T) {
+		await this.#pub.publish(
+			this.#subject,
+			JSON.stringify({ uid: this.#instanceId, msg })
+		)
+	}
+
+	/**
+	 * Registers or replaces the message handler.
+	 */
+	onMessage(callback: (msg: T) => void) {
+		this.#onMessage = callback
+	}
+
+	/**
+	 * Gracefully closes Redis connections.
+	 */
+	async close() {
+		await Promise.all([this.#pub.quit(), this.#sub.quit()])
+	}
+}

package/src/adapters/redis.ts

@@ -1,53 +1,120 @@
-import Redis, { RedisOptions } from 'ioredis'
-
-import { EvStateAdapter } from '../types.js'
-
-export class EvRedisAdapter implements EvStateAdapter {
-	#pub: Redis
-	#sub: Redis
-	#listeners: Map<string, Set<(msg: any) => void>>
-
-	constructor(options?: RedisOptions) {
-		this.#pub = new Redis(options)
-		this.#sub = new Redis(options)
-		this.#listeners = new Map()
-
-		this.#sub.on('message', (channel, message) => {
-			const handlers = this.#listeners.get(channel)
-			if (handlers) {
-				let parsed: any
-				try {
-					parsed = JSON.parse(message)
-				} catch {
-					return
-				}
-				handlers.forEach((handler) => handler(parsed))
-			}
-		})
-	}
-
-	async publish(channel: string, message: any): Promise<void> {
-		await this.#pub.publish(channel, JSON.stringify(message))
-	}
-
-	async subscribe(
-		channel: string,
-		onMessage: (message: any) => void
-	): Promise<void> {
-		if (!this.#listeners.has(channel)) {
-			this.#listeners.set(channel, new Set())
-			await this.#sub.subscribe(channel)
-		}
-		this.#listeners.get(channel)!.add(onMessage)
-	}
-
-	async unsubscribe(channel: string): Promise<void> {
-		await this.#sub.unsubscribe(channel)
-		this.#listeners.delete(channel)
-	}
-
-	quit() {
-		this.#pub.quit()
-		this.#sub.quit()
-	}
-}
+import Redis, { RedisOptions } from 'ioredis'
+import { EvRedisPubSub } from './pub-sub.js'
+import { EvStateAdapter } from '../types.js'
+import { uid } from '../utils.js'
+
+/**
+ * Redis-based implementation of {@link EvStateAdapter}.
+ *
+ * This adapter enables distributed state updates using Redis Pub/Sub.
+ * It supports:
+ * - Channel-based subscriptions
+ * - Multiple listeners per channel
+ * - Self-message filtering via instance ID
+ *
+ * Designed to be used by EvState / EvStateManager for
+ * cross-process state synchronization.
+ */
+class EvRedisAdapter implements EvStateAdapter {
+	/** Publisher Redis client */
+	#pub: Redis
+
+	/** Subscriber Redis client */
+	#sub: Redis
+
+	/**
+	 * Channel → listeners mapping.
+	 * Each channel may have multiple local handlers.
+	 */
+	#listeners: Map<string, Set<(msg: any) => void>>
+
+	/** Unique identifier for this adapter instance */
+	#instanceId: string
+
+	/**
+	 * Creates a new Redis state adapter.
+	 *
+	 * @param options - Optional Redis connection options
+	 */
+	constructor(options?: RedisOptions) {
+		this.#pub = new Redis(options)
+		this.#sub = new Redis(options)
+		this.#listeners = new Map()
+		this.#instanceId = uid({ counter: Math.ceil(Math.random() * 100) })
+
+		this.#sub.on('message', (channel, message) => {
+			const handlers = this.#listeners.get(channel)
+			if (!handlers) return
+
+			let parsed: any
+			try {
+				parsed = JSON.parse(message)
+			} catch {
+				// Ignore malformed payloads
+				return
+			}
+
+			// Ignore messages published by this instance
+			if (parsed?.id === this.#instanceId) return
+
+			handlers.forEach((handler) => handler(parsed?.message))
+		})
+	}
+
+	/**
+	 * Publishes a message to a Redis channel.
+	 *
+	 * The payload is wrapped with the instance ID to
+	 * prevent self-delivery.
+	 *
+	 * @param channel - Redis channel name
+	 * @param message - Message payload
+	 */
+	async publish(channel: string, message: any): Promise<void> {
+		await this.#pub.publish(
+			channel,
+			JSON.stringify({ id: this.#instanceId, message })
+		)
+	}
+
+	/**
+	 * Subscribes to a Redis channel.
+	 *
+	 * Multiple listeners can be registered per channel.
+	 * The Redis subscription is created only once per channel.
+	 *
+	 * @param channel - Redis channel name
+	 * @param onMessage - Callback invoked on incoming messages
+	 */
+	async subscribe(
+		channel: string,
+		onMessage: (message: any) => void
+	): Promise<void> {
+		if (!this.#listeners.has(channel)) {
+			this.#listeners.set(channel, new Set())
+			await this.#sub.subscribe(channel)
+		}
+
+		this.#listeners.get(channel)!.add(onMessage)
+	}
+
+	/**
+	 * Unsubscribes from a Redis channel and removes all listeners.
+	 *
+	 * @param channel - Redis channel name
+	 */
+	async unsubscribe(channel: string): Promise<void> {
+		await this.#sub.unsubscribe(channel)
+		this.#listeners.delete(channel)
+	}
+
+	/**
+	 * Gracefully closes Redis connections.
+	 */
+	quit() {
+		this.#pub.quit()
+		this.#sub.quit()
+	}
+}
+
+export { EvRedisPubSub, EvRedisAdapter }

package/src/extensions/state-manager.ts

@@ -0,0 +1,186 @@
+import type { EvStreamManager } from '../manager.js'
+import type { EvRedisAdapter } from '../adapters/redis.js'
+import type { EvRedisPubSub } from '../adapters/pub-sub.js'
+import { EvState } from '../state.js'
+
+/**
+ * Options for creating an {@link EvStateManager}.
+ */
+interface EvStateManagerOptions {
+	/**
+	 * Stream manager responsible for managing client connections
+	 * and broadcasting state updates.
+	 */
+	manager: EvStreamManager
+
+	/**
+	 * Optional distributed state adapter (e.g. Redis).
+	 * Enables cross-process state propagation.
+	 */
+	adapter?: EvRedisAdapter
+
+	/**
+	 * Optional Pub/Sub instance used to synchronize
+	 * state creation and removal across instances.
+	 */
+	pubsub?: EvRedisPubSub
+}
+
+/**
+ * Manages a collection of named {@link EvState} instances.
+ *
+ * Responsibilities:
+ * - Create and cache state objects locally
+ * - Synchronize state lifecycle (create/remove) across processes
+ * - Bridge EvState with stream manager and adapters
+ *
+ * Internally, all state keys are converted to strings to remain
+ * Redis-safe and transport-friendly.
+ *
+ * @typeParam S - Mapping of state keys to their value types
+ */
+export class EvStateManager<S extends Record<string, any>> {
+	/**
+	 * Internal state registry.
+	 * Keyed by string channel name.
+	 */
+	#states = new Map<string, EvState<any>>()
+
+	/** Stream manager used by all states */
+	#manager: EvStreamManager
+
+	/** Optional distributed adapter */
+	#adapter?: EvRedisAdapter
+
+	/** Optional Pub/Sub synchronizer */
+	#pubsub?: EvRedisPubSub
+
+	/**
+	 * Creates a new state manager.
+	 *
+	 * @param options - Initialization options
+	 */
+	constructor({ manager, adapter, pubsub }: EvStateManagerOptions) {
+		this.#manager = manager
+		this.#adapter = adapter
+		this.#pubsub = pubsub
+
+		this.pubSubCallback = this.pubSubCallback.bind(this)
+
+		if (this.#pubsub) {
+			this.#pubsub.onMessage(this.pubSubCallback)
+		}
+	}
+
+	/**
+	 * Creates a state locally without emitting Pub/Sub events.
+	 *
+	 * @param channel - State channel name
+	 * @param initialValue - Initial state value
+	 */
+	private createLocalState(channel: string, initialValue: any): EvState<any> {
+		const state = new EvState({
+			channel,
+			initialValue,
+			manager: this.#manager,
+			adapter: this.#adapter,
+		})
+
+		this.#states.set(channel, state)
+		return state
+	}
+
+	/**
+	 * Removes a state locally without emitting Pub/Sub events.
+	 *
+	 * @param channel - State channel name
+	 */
+	private removeLocalState(channel: string) {
+		this.#states.delete(channel)
+	}
+
+	/**
+	 * Creates or returns an existing state.
+	 *
+	 * If Pub/Sub is enabled, the creation is broadcast
+	 * to other instances.
+	 *
+	 * @param key - State key
+	 * @param initialValue - Initial state value
+	 */
+	createState<K extends keyof S>(key: K, initialValue: S[K]): EvState<S[K]> {
+		const channel = String(key)
+
+		if (this.#states.has(channel)) {
+			return this.#states.get(channel)! as EvState<S[K]>
+		}
+
+		const state = this.createLocalState(channel, initialValue)
+
+		this.#pubsub?.send({
+			type: 'create',
+			channel,
+			initialValue,
+		})
+
+		return state as EvState<S[K]>
+	}
+
+	/**
+	 * Retrieves an existing state.
+	 *
+	 * @param key - State key
+	 */
+	getState<K extends keyof S>(key: K): EvState<S[K]> | undefined {
+		return this.#states.get(String(key)) as EvState<S[K]> | undefined
+	}
+
+	/**
+	 * Checks whether a state exists.
+	 *
+	 * @param key - State key
+	 */
+	hasState<K extends keyof S>(key: K): boolean {
+		return this.#states.has(String(key))
+	}
+
+	/**
+	 * Removes a state locally and propagates the removal
+	 * to other instances via Pub/Sub.
+	 *
+	 * @param key - State key
+	 */
+	removeState<K extends keyof S>(key: K) {
+		const channel = String(key)
+
+		this.removeLocalState(channel)
+
+		this.#pubsub?.send({
+			type: 'remove',
+			channel,
+		})
+	}
+
+	/**
+	 * Handles incoming Pub/Sub lifecycle events.
+	 *
+	 * @param msg - Pub/Sub message payload
+	 */
+	private pubSubCallback(msg: any) {
+		if (!msg || typeof msg.channel !== 'string') return
+
+		switch (msg.type) {
+			case 'create': {
+				if (!this.#states.has(msg.channel)) {
+					this.createLocalState(msg.channel, msg.initialValue)
+				}
+				break
+			}
+
+			case 'remove': {
+				this.removeLocalState(msg.channel)
+				break
+			}
+		}
+	}
+}