@sygnl/subscriptions

Real-time event subscriptions via WebSocket with filtering and type-safe callbacks.

Built on top of @sygnl/talon for robust WebSocket management and @sygnl/event-schema for type definitions.

Features

• Real-time event subscriptions with server-sent updates
• Filter events by type, user, session, or custom criteria
• Type-safe callbacks with TypeScript support
• Built on battle-tested Talon WebSocket client
• Automatic reconnection and resubscription
• Multiple concurrent subscriptions with independent filters
• Lifecycle hooks (onConnect, onDisconnect, onError)

Installation

npm install @sygnl/subscriptions @sygnl/talon @sygnl/event-schema

Usage

Basic Subscription

import { SubscriptionManager } from '@sygnl/subscriptions';

const manager = new SubscriptionManager({
  url: 'wss://your-worker.workers.dev/subscribe',
});

await manager.connect();

// Subscribe to all events
manager.subscribe((event) => {
  console.log('Received event:', event);
});

Filtered Subscription

// Subscribe to specific event types
const unsubscribe = manager.subscribe(
  (event) => {
    console.log('Purchase:', event);
  },
  {
    filters: {
      eventTypes: ['purchase', 'subscription_started'],
      userId: 'user_123',
      minValue: 100,
    },
  }
);

// Later: unsubscribe
unsubscribe();

Lifecycle Hooks

manager.onConnect(() => {
  console.log('Connected to server');
});

manager.onDisconnect(() => {
  console.log('Disconnected from server');
});

manager.onError((error) => {
  console.error('Subscription error:', error);
});

API

SubscriptionManager

• connect(): Promise<void> - Connect to WebSocket server
• disconnect(): void - Disconnect from server
• subscribe<T>(callback, options?): () => void - Subscribe to events, returns unsubscribe function
• isConnected(): boolean - Check connection status
• getSubscriptionCount(): number - Get active subscription count
• onConnect(callback): () => void - Register connect handler
• onDisconnect(callback): () => void - Register disconnect handler
• onError(callback): () => void - Register error handler

Integration

Works seamlessly with other Sygnl packages:

• @sygnl/talon - WebSocket transport layer
• @sygnl/event-schema - Event type definitions
• @sygnl/identity-manager - User identity tracking

License

Copyright 2026 Edge Foundry, Inc.

Licensed under the Apache License, Version 2.0.