$ show centrifugal/centrifuge-js
This repository is the official JavaScript/TypeScript client SDK for Centrifugo, a scalable real-time messaging server. It provides a robust, event-driven client (Centrifuge class) that manages persistent connections via multiple transports (WebSocket, SSE, HTTP stream, SockJS, WebTransport), handles token-based authentication and subscription authorization, and supports three subscription models: stream (standard channel), map (keyed data), and shared poll (polling with version tracking). The SDK also implements advanced features like automatic reconnection with exponential backoff, recovery from connection drops using offset/epoch, command batching for HTTP transports, and delta compression for efficient updates. The architecture is library-oriented with a clear separation of concerns: transport implementations are abstracted behind a common interface, the main client class manages connection state and dispatch ordering via a serial promise chain, and each subscription type extends a base class with its own state machine (stream, map three-phase, shared poll). The codebase is extensively tested with both unit tests (using a fake server) and integration tests against a real Centrifugo instance in Docker. The SDK is published on npm, supports CJS and ESM builds, and includes protobuf codec support. Notable patterns include a transport abstraction with dependency injection that allows easy addition of new transports, a serial dispatch chain ensuring ordered response processing, and a per-key publish debounce mechanism. The library is actively maintained with ongoing work on refactoring subscription types as documented in NEXT_MAJOR_SUBSCRIPTION_TYPES.md. The repository also demonstrates high craftsmanship in its comprehensive test coverage, graceful error handling, and careful handling of edge cases like stale tokens, network interruptions, and concurrent operations.
The LLM identified 3 files worth highlighting for reuse:
Implements the WebSocket transport with a consistent interface (initialize, close, send, supported, emulation) that all other transports (SSE, HTTP stream, SockJS, WebTransport) follow. The transport selection logic in the main client resolves transports from a config list or globalThis, with automatic fallback to the next supported transport on failure. This pattern is reusable in any real-time client SDK that needs to support multiple network protocols without coupling to a specific implementation.
The `_dispatchPromise` pattern chains reply processing in a serial promise, ensuring that replies from the server are processed in order without interleaving or race conditions. On any exception, `_dispatchFailed` stops the client cleanly and triggers reconnection. This pattern is a generic solution for ordered processing of asynchronous events and can be extracted to any system that needs to maintain strict message ordering over an event-driven interface.
The delta compression implementation uses the fossil library to compute and apply patches for map subscription updates. Each key-value pair is tracked with a previous value (`_prevValueMap`), and updates include an optional delta field that the client applies locally. The pattern demonstrates efficient wire format use and can be extracted as a standalone delta compression utility for any real-time key-value data synchronization problem.