Pub-Sub Window

A lightweight TypeScript library for event-driven communication in web applications using the browser's window object for publish-subscribe (pub/sub) patterns. This package provides implementations of Subscription and Publisher interfaces from @schorts/shared-kernel, enabling decoupled event handling across components.

Features

• Window-Based Pub/Sub: Leverages window.addEventListener and window.dispatchEvent for cross-component communication.
• Channel Support: Events are namespaced by channels (e.g., "channel:event") to avoid conflicts.
• TypeScript Support: Fully typed for better developer experience.
• Promise-Based Publishing: Asynchronous publishing with immediate resolution.
• Simple API: Easy to integrate into existing projects.

Installation

npm install --save @schorts/pub-sub-window

Usage

Basic Example

import { WindowSubscription, WindowPublisher } from '@schorts/window-pubsub';
// Create instances
const subscription = new WindowSubscription();
const publisher = new WindowPublisher();
// Connect (optional, as window is always available)
subscription.connect();
// Subscribe to an event on a channel
subscription.subscribe('myChannel', 'myEvent', (payload: any) => {
  console.log('Received:', payload);
});
// Publish an event
publisher.publish('myChannel', 'myEvent', { message: 'Hello, World!' });
// Unsubscribe from the channel
subscription.unsubscribe('myChannel');
// Disconnect (removes all subscriptions)
subscription.disconnect();

API

WindowSubscription

• connect(): Connects to the event system (no-op for window-based subscriptions).
• subscribe(channel: string, event: string, handler: (payload: any) => void): Subscribes to an event on a specific channel. The handler receives the event payload.
• unsubscribe(channel: string): Unsubscribes from all events on the specified channel.
• disconnect(): Disconnects and removes all subscriptions.

WindowPublisher

• publish(channel: string, event: string, payload: any): Promise<void>: Publishes an event with the given payload on the specified channel. Returns a promise that resolves immediately.

How It Works

• Publishing: Events are dispatched as CustomEvents on the window object with the event name formatted as "${channel}:${event}". The payload is stored in the event's detail property.
• Subscribing: Listeners are added to the window for the full event name. The handler is called with the payload extracted from e.detail.
• Type Safety: The subscription wrapper checks if the event is a CustomEvent to safely access the detail property.

Limitations

• Browser-Only: Designed for browser environments where window is available.
• Single Handler per Event/Channel: Currently supports one handler per event per channel. Multiple subscriptions to the same event/channel will overwrite the previous one.
• No Persistence: Events are not persisted; they are fire-and-forget.

License

LGPL