centrifuge 5.5.2 → 5.6.0

package/README.md

@@ -1,7 +1,7 @@
 This SDK provides a client to connect to [Centrifugo](https://github.com/centrifugal/centrifugo) or any [Centrifuge-based](https://github.com/centrifugal/centrifuge) server using pure WebSocket or one of the alternative transports (HTTP-streaming, SSE/EventSource, experimental WebTransport) from web browser, ReactNative, or NodeJS environments.
 
 > [!IMPORTANT]  
-> This library behaves according to a common [Centrifigo SDK spec](https://centrifugal.dev/docs/transports/client_api). It's recommended to read that before starting to work with this SDK as the spec covers common SDK behavior - describes client and subscription state transitions, main options and methods. Then proceed with this readme for more specifics about `centrifuge-js`.
+> This library behaves according to a common [Centrifugo SDK spec](https://centrifugal.dev/docs/transports/client_api). It's recommended to read that before starting to work with this SDK as the spec covers common SDK behavior - describes client and subscription state transitions, main options and methods. Then proceed with this readme for more specifics about `centrifuge-js`.
 
 The features implemented by this SDK can be found in [SDK feature matrix](https://centrifugal.dev/docs/transports/client_sdk#sdk-feature-matrix).
 
@@ -23,6 +23,9 @@ The features implemented by this SDK can be found in [SDK feature matrix](https:
     * [Subscription token](#subscription-token)
     * [Subscription options](#subscription-options)
 * [Subscription management API](#subscription-management-api)
+* [Stream subscriptions with `getState`](#stream-subscriptions-with-getstate)
+* [Map subscriptions (experimental)](#map-subscriptions-experimental)
+* [Shared poll subscriptions (experimental)](#shared-poll-subscriptions-experimental)
 * [Message batching](#message-batching)
 * [Server-side subscriptions](#server-side-subscriptions)
 * [Protobuf support](#protobuf-support)
@@ -46,13 +49,13 @@ And then in your project:
 import { Centrifuge } from 'centrifuge';
 ```
 
-In browser, you can import SDK from CDN (replace `5.0.0` with a concrete version number you want to use, see [releases](https://github.com/centrifugal/centrifuge-js/releases)):
+In browser, you can import SDK from [unpkg](https://app.unpkg.com/centrifuge@latest) CDN (replace `5.0.0` with a concrete version number you want to use, see [releases](https://github.com/centrifugal/centrifuge-js/releases)):
 
 ```html
 <script src="https://unpkg.com/centrifuge@5.0.0/dist/centrifuge.js"></script>
 ```
 
-See also [centrifuge-js on cdnjs](https://cdnjs.com/libraries/centrifuge). Note that `centrifuge-js` browser builds target [ES6](https://caniuse.com/es6).
+See also [centrifuge-js on jsdelivr](https://www.jsdelivr.com/package/npm/centrifuge). Note that `centrifuge-js` browser builds target [ES6](https://caniuse.com/es6).
 
 **By default, library works with JSON only**, if you want to send binary payloads go to [Protobuf support](#protobuf-support) section to see how to import client with Protobuf support.
 
@@ -850,6 +853,56 @@ removeSubscription allows removing Subcription from the internal registry.
 
  Get a map with all current client-side subscriptions registered in the client.
 
+## Stream subscriptions with `getState`
+
+For positioned/recoverable stream channels, the SDK can call an app-supplied `getState` callback that loads the application's current state from its own source of truth (database, API, etc.) and returns the corresponding stream position. The SDK subscribes with recovery from that position, so any publications committed after the state was read arrive as `publication` events. This is the "app-owned state" pattern — Centrifugo delivers only change events, your database stays the canonical store.
+
+The SDK invokes `getState`:
+
+* on the initial subscribe (no saved position);
+* on reconnect **only when server recovery fails** (server returns error 112 — unrecoverable position).
+
+On a successful recovery, `getState` is **not** called — the SDK has a valid position and missed publications arrive as events.
+
+Inside the callback, **read the stream position first, then read your data** so the position is a lower bound. Recovered publications may overlap data already loaded in `getState`; this is safe for idempotent updates, otherwise deduplicate by `offset`. See `SubscriptionOptions.getState` JSDoc for the full contract.
+
+Requires **Centrifugo >= v6.8.0**.
+
+References:
+
+* Blog post — [Transactional publishing for stream subscriptions with PostgreSQL](https://centrifugal.dev/blog/2026/05/15/pg-stream-broker-benefits)
+* Example — [pg_stream_broker kitchen orders demo](https://github.com/centrifugal/examples/tree/master/v6/pg_stream_broker)
+
+## Map subscriptions (experimental)
+
+A **map subscription** delivers a real-time key-value collection whose lifecycle is managed by Centrifugo: clients receive a complete snapshot on subscribe, catch up on missed key changes after disconnects, and observe live per-key updates. Typical use cases include cursor positions, lobby members, feature flags, scoreboards, and per-key presence (`map_clients` / `map_users`).
+
+Use `Centrifuge.newMapSubscription(channel, options?)` to create one. The variants `newMapClientsSubscription` and `newMapUsersSubscription` produce presence-style map subscriptions backed by `$clients:*` / `$users:*` channels. The returned `MapSubscription` emits a `sync` event whenever a fresh snapshot is delivered — on the initial subscribe, and again only when the SDK rebuilds state from scratch (e.g. after an unrecoverable position with the default `from_scratch` strategy). Every individual key change (set or remove) — both during live operation and on successful recovery after a disconnect — arrives as an `update` event; on successful recovery `sync` is suppressed because the application's existing snapshot is still valid. Call `publish(key, data)` / `remove(key)` to mutate.
+
+> [!WARNING]
+> Map subscriptions are **experimental** and require **Centrifugo >= v6.8.0**. The shape and behavior may change in a backwards-incompatible way in subsequent minor releases as the feature stabilizes.
+
+References:
+
+* Server docs — [Map subscriptions](https://centrifugal.dev/docs/server/map_subscriptions)
+* PRO enhancements — [Map subscriptions (PRO)](https://centrifugal.dev/docs/pro/map_subscriptions)
+* Blog series — Map subscriptions Part 1 (synchronized key-value state and presence) and Part 2 (PostgreSQL map broker with transactional publishing)
+
+## Shared poll subscriptions (experimental)
+
+A **shared poll subscription** moves polling from clients to Centrifugo: clients register their interest in specific keys, and Centrifugo polls the backend once per configurable interval on behalf of everyone, fanning the changes back out. Backend load scales with the number of unique tracked items rather than the number of connected clients. Typical use cases include vote counts, prices, view counts, live scores, and configuration sync.
+
+Use `Centrifuge.newSharedPollSubscription(channel, options?)`, then call `track(keys)` / `untrack(keys)` on the returned `SharedPollSubscription` to manage the interest set. Provide the `getSignature` callback in options to authorize tracked keys via per-key HMAC signatures (replayed on reconnect and refreshed on signature TTL). The subscription emits an `update` event per item whenever the backend reports a new version, including synthetic `removed: true` events when the server revokes a key.
+
+> [!WARNING]
+> Shared poll subscriptions are **experimental** and require **Centrifugo >= v6.8.0**. The shape and behavior may change in a backwards-incompatible way in subsequent minor releases as the feature stabilizes.
+
+References:
+
+* Server docs — [Shared poll subscriptions](https://centrifugal.dev/docs/server/shared_poll)
+* PRO enhancements — [Shared poll (PRO)](https://centrifugal.dev/docs/pro/shared_poll)
+* Blog post — [Shared poll subscriptions: O(unique items) polling with low-latency updates](https://centrifugal.dev/blog/2026/05/12/shared-poll-subscriptions)
+
 ## Message batching
 
 There is also a command batching support. It allows to send several commands to a server in one request - may be especially useful when connection established via one of HTTP-based transports.

package/build/centrifuge.d.ts

@@ -1,5 +1,20 @@
-import { Subscription } from './subscription';
-import { State, Options, SubscriptionState, ClientEvents, TypedEventEmitter, RpcResult, SubscriptionOptions, HistoryOptions, HistoryResult, PublishResult, PresenceResult, PresenceStatsResult, TransportEndpoint } from './types';
+import { Subscription, BaseSubscription as _BaseSubscription } from './subscription';
+import { State, Options, SubscriptionState, ClientEvents, TypedEventEmitter, RpcResult, SubscriptionOptions, MapSubscriptionOptions, MapSubscriptionEvents, BaseSubscriptionEvents, SharedPollSubscriptionOptions, SharedPollSubscriptionEvents, SharedPollTrackItem, HistoryOptions, HistoryResult, PublishResult, PresenceResult, PresenceStatsResult, TransportEndpoint } from './types';
+/** Common methods shared by all subscription types. */
+type CommonSurface = Pick<_BaseSubscription, 'channel' | 'state' | 'type' | 'subscribe' | 'unsubscribe' | 'ready' | 'presence' | 'presenceStats' | 'setData' | 'deltaStats'>;
+/** Common subscription surface — use for mixed-type registries. */
+export type BaseSubscription = CommonSurface & TypedEventEmitter<BaseSubscriptionEvents>;
+/** Map subscription: publish/remove + narrowed map events. */
+export type MapSubscription = CommonSurface & Pick<_BaseSubscription, 'setTagsFilter'> & {
+    publish(key: string, data: any): Promise<PublishResult>;
+    remove(key: string): Promise<PublishResult>;
+} & TypedEventEmitter<MapSubscriptionEvents>;
+/** Shared poll subscription: track/untrack + narrowed shared poll events. */
+export type SharedPollSubscription = CommonSurface & {
+    track(keysOrItems: string[] | SharedPollTrackItem[], signature?: string): void;
+    untrack(keys: string[]): void;
+    trackedKeys(): Set<string>;
+} & TypedEventEmitter<SharedPollSubscriptionEvents>;
 export declare class UnauthorizedError extends Error {
     constructor(message: any);
 }
@@ -53,14 +68,57 @@ export declare class Centrifuge extends Centrifuge_base {
      * one subscription per channel per client this method throws if client already has
      * channel subscription in internal registry.
      * */
-    newSubscription(channel: string, options?: Partial<SubscriptionOptions>): Subscription;
+    newSubscription(channel: string, options?: SubscriptionOptions): Subscription;
+    /** newMapSubscription allocates new map Subscription to a channel. Since server only allows
+     * one subscription per channel per client this method throws if client already has
+     * channel subscription in internal registry.
+     *
+     * Experimental. Requires Centrifugo >= v6.8.0. API may change in a backwards-incompatible
+     * way in subsequent minor releases. */
+    newMapSubscription(channel: string, options?: MapSubscriptionOptions): MapSubscription;
+    /** Create a map subscription for observing individual connections (clients presence).
+     * Each entry has key=clientId and contains full ClientInfo.
+     * Use this to track connections per channel.
+     * The channel should be the full presence channel name (e.g., "$clients:games").
+     *
+     * Experimental. Requires Centrifugo >= v6.8.0. API may change in a backwards-incompatible
+     * way in subsequent minor releases. */
+    newMapClientsSubscription(channel: string, options?: MapSubscriptionOptions): MapSubscription;
+    /** Create a map subscription for observing unique users (users presence).
+     * Each entry has key=userId (no ClientInfo stored).
+     * User entries expire via TTL, providing debounce for quick reconnects.
+     * The channel should be the full presence channel name (e.g., "$users:games").
+     *
+     * Experimental. Requires Centrifugo >= v6.8.0. API may change in a backwards-incompatible
+     * way in subsequent minor releases. */
+    newMapUsersSubscription(channel: string, options?: MapSubscriptionOptions): MapSubscription;
+    /** newSharedPollSubscription allocates a new shared poll Subscription to a channel.
+     * Shared poll subscriptions use server-side polling to aggregate interest sets
+     * and deliver periodic updates with version tracking. Track items after subscribing
+     * using the track() method on the returned Subscription.
+     *
+     * Experimental. Requires Centrifugo >= v6.8.0. API may change in a backwards-incompatible
+     * way in subsequent minor releases. */
+    newSharedPollSubscription(channel: string, options?: SharedPollSubscriptionOptions): SharedPollSubscription;
     /** getSubscription returns Subscription if it's registered in the internal
      * registry or null. */
     getSubscription(channel: string): Subscription | null;
+    /** Get a map subscription by channel. */
+    getMapSubscription(channel: string): MapSubscription | null;
+    /** Get a shared poll subscription by channel. */
+    getSharedPollSubscription(channel: string): SharedPollSubscription | null;
     /** removeSubscription allows removing Subcription from the internal registry. */
     removeSubscription(sub: Subscription | null): void;
+    /** Remove a map subscription. */
+    removeMapSubscription(sub: MapSubscription | null): void;
+    /** Remove a shared poll subscription. */
+    removeSharedPollSubscription(sub: SharedPollSubscription | null): void;
     /** Get a map with all current client-side subscriptions. */
     subscriptions(): Record<string, Subscription>;
+    /** Get all map subscriptions. */
+    mapSubscriptions(): Record<string, MapSubscription>;
+    /** Get all shared poll subscriptions. */
+    sharedPollSubscriptions(): Record<string, SharedPollSubscription>;
     /** ready returns a Promise which resolves upon client goes to Connected
      * state and rejects in case of client goes to Disconnected or Failed state.
      * Users can provide optional timeout in milliseconds. */
@@ -86,6 +144,17 @@ export declare class Centrifuge extends Centrifuge_base {
     rpc(method: string, data: any): Promise<RpcResult>;
     /** publish data to a channel. */
     publish(channel: string, data: any): Promise<PublishResult>;
+    /** Publish data to a key in a map channel without holding a MapSubscription.
+     * Use this when you need to write to a map channel from outside a subscription
+     * context (e.g. a standalone publisher). When you already hold a MapSubscription,
+     * prefer `sub.publish(key, data)` instead — it enforces the method-call guard and
+     * applies debounce configuration. */
+    mapPublish(channel: string, key: string, data: any): Promise<PublishResult>;
+    /** Remove a key from a map channel without holding a MapSubscription.
+     * Use this when you need to remove a key from outside a subscription context.
+     * When you already hold a MapSubscription, prefer `sub.remove(key)` instead —
+     * it enforces the method-call guard and cancels any pending debounced publish. */
+    mapRemove(channel: string, key: string): Promise<PublishResult>;
     /** history for a channel. By default it does not return publications (only current
      *  StreamPosition data) – provide an explicit limit > 0 to load publications.*/
     history(channel: string, options?: HistoryOptions): Promise<HistoryResult>;
@@ -135,7 +204,7 @@ export declare class Centrifuge extends Centrifuge_base {
     private _getRefreshRetryDelay;
     private _refreshResponse;
     private _removeSubscription;
-    protected _unsubscribe(sub: Subscription): Promise<void>;
+    protected _unsubscribe(sub: _BaseSubscription): Promise<void>;
     private _getSub;
     private _isServerSub;
     private _sendSubscribeCommands;

package/build/codes.d.ts

@@ -10,7 +10,9 @@ export declare enum errorCodes {
     subscriptionRefreshToken = 9,
     transportWriteError = 10,
     connectionClosed = 11,
-    badConfiguration = 12
+    badConfiguration = 12,
+    subscriptionGetState = 13,
+    sharedPollGetSignature = 14
 }
 export declare enum connectingCodes {
     connectCalled = 0,
@@ -35,5 +37,6 @@ export declare enum unsubscribedCodes {
     clientClosed = 2
 }
 export declare enum subscriptionFlags {
-    channelCompaction = 1
+    channelCompaction = 1,
+    rejectUnrecovered = 2
 }

package/build/index.d.ts

@@ -1,5 +1,6 @@
 import { Centrifuge, UnauthorizedError } from './centrifuge';
 import { Subscription } from './subscription';
+export type { BaseSubscription, MapSubscription, SharedPollSubscription } from './centrifuge';
 export * from "./types";
 export * from "./codes";
-export { Centrifuge, UnauthorizedError, Subscription };
+export { Centrifuge, UnauthorizedError, Subscription, };