@dudousxd/nestjs-notifications-sse 0.2.0 → 0.3.0

package/dist/backplane.d.ts

@@ -0,0 +1,27 @@
+/** A serializable SSE message routed through an {@link SseBackplane}. */
+export interface SseBackplaneMessage {
+    data: unknown;
+    /** SSE event `type`. */
+    event?: string;
+}
+/**
+ * Cross-process fan-out for {@link import('./sse.hub').SseHub}.
+ *
+ * The default hub is **in-process** — a Subject per stream key — so a publish only reaches
+ * subscribers connected to the SAME node. In a multi-pod deployment, the code that publishes a
+ * notification and the node holding the user's SSE connection are often different processes (e.g. a
+ * worker writes, an API pod streams). Supply a backplane (e.g. {@link RedisSseBackplane}) and a
+ * publish on any node is broadcast to the SSE connections on every node.
+ */
+export interface SseBackplane {
+    /** Broadcast `message` for `key` to all nodes (including this one). */
+    publish(key: string, message: SseBackplaneMessage): void | Promise<void>;
+    /**
+     * Register the handler the hub uses to deliver inbound (cross-node) messages to its local
+     * subscribers. Called once when the hub initializes.
+     */
+    subscribe(handler: (key: string, message: SseBackplaneMessage) => void): void | Promise<void>;
+    /** Tear down any connections/subscriptions. Called on module destroy. */
+    close?(): void | Promise<void>;
+}
+//# sourceMappingURL=backplane.d.ts.map

package/dist/backplane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backplane.d.ts","sourceRoot":"","sources":["../src/backplane.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F,yEAAyE;IACzE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/backplane.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=backplane.js.map

package/dist/backplane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backplane.js","sourceRoot":"","sources":["../src/backplane.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { Sse, SseChannel, type SseChannelOptions, type SseNotification, } from './sse.channel';
 export { SseHub } from './sse.hub';
 export { SseChannelModule, type SseChannelModuleOptions } from './sse.module';
-export { SSE_OPTIONS } from './tokens';
+export { SSE_OPTIONS, SSE_BACKPLANE } from './tokens';
 export { sseKey } from './sse-key';
+export type { SseBackplane, SseBackplaneMessage } from './backplane';
+export { RedisSseBackplane, type RedisSseBackplaneOptions, type RedisPubSubClient, } from './redis.backplane';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EACH,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EACH,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sseKey = exports.SSE_OPTIONS = exports.SseChannelModule = exports.SseHub = exports.SseChannel = exports.Sse = void 0;
+exports.RedisSseBackplane = exports.sseKey = exports.SSE_BACKPLANE = exports.SSE_OPTIONS = exports.SseChannelModule = exports.SseHub = exports.SseChannel = exports.Sse = void 0;
 var sse_channel_1 = require("./sse.channel");
 Object.defineProperty(exports, "Sse", { enumerable: true, get: function () { return sse_channel_1.Sse; } });
 Object.defineProperty(exports, "SseChannel", { enumerable: true, get: function () { return sse_channel_1.SseChannel; } });
@@ -10,6 +10,9 @@ var sse_module_1 = require("./sse.module");
 Object.defineProperty(exports, "SseChannelModule", { enumerable: true, get: function () { return sse_module_1.SseChannelModule; } });
 var tokens_1 = require("./tokens");
 Object.defineProperty(exports, "SSE_OPTIONS", { enumerable: true, get: function () { return tokens_1.SSE_OPTIONS; } });
+Object.defineProperty(exports, "SSE_BACKPLANE", { enumerable: true, get: function () { return tokens_1.SSE_BACKPLANE; } });
 var sse_key_1 = require("./sse-key");
 Object.defineProperty(exports, "sseKey", { enumerable: true, get: function () { return sse_key_1.sseKey; } });
+var redis_backplane_1 = require("./redis.backplane");
+Object.defineProperty(exports, "RedisSseBackplane", { enumerable: true, get: function () { return redis_backplane_1.RedisSseBackplane; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAKuB;AAJrB,kGAAA,GAAG,OAAA;AACH,yGAAA,UAAU,OAAA;AAIZ,qCAAmC;AAA1B,iGAAA,MAAM,OAAA;AACf,2CAA8E;AAArE,8GAAA,gBAAgB,OAAA;AACzB,mCAAuC;AAA9B,qGAAA,WAAW,OAAA;AACpB,qCAAmC;AAA1B,iGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAKuB;AAJrB,kGAAA,GAAG,OAAA;AACH,yGAAA,UAAU,OAAA;AAIZ,qCAAmC;AAA1B,iGAAA,MAAM,OAAA;AACf,2CAA8E;AAArE,8GAAA,gBAAgB,OAAA;AACzB,mCAAsD;AAA7C,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AACnC,qCAAmC;AAA1B,iGAAA,MAAM,OAAA;AAEf,qDAI2B;AAHzB,oHAAA,iBAAiB,OAAA"}

package/dist/redis.backplane.d.ts

@@ -0,0 +1,43 @@
+import type { SseBackplane, SseBackplaneMessage } from './backplane';
+/**
+ * The slice of an `ioredis`-style client this backplane uses. Pass real `ioredis` instances (or any
+ * compatible client) — the package doesn't depend on `ioredis` itself, so you control the version
+ * and connection. Use SEPARATE clients for publisher and subscriber: a subscriber connection enters
+ * subscribe mode and can't issue regular commands.
+ */
+export interface RedisPubSubClient {
+    publish(channel: string, message: string): unknown;
+    subscribe(channel: string, callback?: (err: Error | null, count: number) => void): unknown;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    quit?(): unknown;
+}
+export interface RedisSseBackplaneOptions {
+    /** Client used to publish (regular command mode). */
+    publisher: RedisPubSubClient;
+    /** Client used to subscribe (enters subscribe mode). Must be a different connection. */
+    subscriber: RedisPubSubClient;
+    /** Pub/sub channel. Default `nestjs-notifications:sse`. */
+    channel?: string;
+}
+/**
+ * A Redis pub/sub {@link SseBackplane}. Every publish fans out over one Redis channel to all nodes,
+ * so SSE connections on any pod receive notifications written on any other pod. Mirrors the common
+ * "writer pod / API pod" split.
+ *
+ * ```ts
+ * import Redis from 'ioredis';
+ * SseChannelModule.forRoot({
+ *   backplane: new RedisSseBackplane({ publisher: new Redis(url), subscriber: new Redis(url) }),
+ * });
+ * ```
+ */
+export declare class RedisSseBackplane implements SseBackplane {
+    private readonly publisher;
+    private readonly subscriber;
+    private readonly channel;
+    constructor(options: RedisSseBackplaneOptions);
+    publish(key: string, message: SseBackplaneMessage): void;
+    subscribe(handler: (key: string, message: SseBackplaneMessage) => void): void;
+    close(): void;
+}
+//# sourceMappingURL=redis.backplane.d.ts.map

package/dist/redis.backplane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.backplane.d.ts","sourceRoot":"","sources":["../src/redis.backplane.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IAC3F,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;IACpF,IAAI,CAAC,IAAI,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,SAAS,EAAE,iBAAiB,CAAC;IAC7B,wFAAwF;IACxF,UAAU,EAAE,iBAAiB,CAAC;IAC9B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,wBAAwB;IAM7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAIxD,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IAa7E,KAAK,IAAI,IAAI;CAId"}

package/dist/redis.backplane.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisSseBackplane = void 0;
+const DEFAULT_CHANNEL = 'nestjs-notifications:sse';
+/**
+ * A Redis pub/sub {@link SseBackplane}. Every publish fans out over one Redis channel to all nodes,
+ * so SSE connections on any pod receive notifications written on any other pod. Mirrors the common
+ * "writer pod / API pod" split.
+ *
+ * ```ts
+ * import Redis from 'ioredis';
+ * SseChannelModule.forRoot({
+ *   backplane: new RedisSseBackplane({ publisher: new Redis(url), subscriber: new Redis(url) }),
+ * });
+ * ```
+ */
+class RedisSseBackplane {
+    publisher;
+    subscriber;
+    channel;
+    constructor(options) {
+        this.publisher = options.publisher;
+        this.subscriber = options.subscriber;
+        this.channel = options.channel ?? DEFAULT_CHANNEL;
+    }
+    publish(key, message) {
+        this.publisher.publish(this.channel, JSON.stringify({ key, message }));
+    }
+    subscribe(handler) {
+        this.subscriber.subscribe(this.channel);
+        this.subscriber.on('message', (channel, raw) => {
+            if (channel !== this.channel)
+                return;
+            try {
+                const parsed = JSON.parse(raw);
+                handler(parsed.key, parsed.message);
+            }
+            catch {
+                // Ignore malformed payloads — never let a bad message tear down the subscription.
+            }
+        });
+    }
+    close() {
+        this.publisher.quit?.();
+        this.subscriber.quit?.();
+    }
+}
+exports.RedisSseBackplane = RedisSseBackplane;
+//# sourceMappingURL=redis.backplane.js.map

package/dist/redis.backplane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.backplane.js","sourceRoot":"","sources":["../src/redis.backplane.ts"],"names":[],"mappings":";;;AAwBA,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAa,iBAAiB;IACX,SAAS,CAAoB;IAC7B,UAAU,CAAoB;IAC9B,OAAO,CAAS;IAEjC,YAAY,OAAiC;QAC3C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC;IACpD,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,OAA4B;QAC/C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,SAAS,CAAC,OAA4D;QACpE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;YAC7C,IAAI,OAAO,KAAK,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAkD,CAAC;gBAChF,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,kFAAkF;YACpF,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;IAC3B,CAAC;CACF;AAhCD,8CAgCC"}

package/dist/sse.hub.d.ts

@@ -1,33 +1,40 @@
-import { type MessageEvent } from '@nestjs/common';
+import { type MessageEvent, type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
 import { type Observable } from 'rxjs';
+import type { SseBackplane } from './backplane';
 /**
- * In-memory fan-out for native NestJS Server-Sent Events. Keeps one
- * {@link Subject} per stream key; the channel pushes events into it via
- * {@link SseHub.publish} and a controller's `@Sse()` endpoint reads from it via
- * {@link SseHub.stream}.
+ * Fan-out for native NestJS Server-Sent Events. Keeps one {@link Subject} per stream key; the
+ * channel pushes events into it via {@link SseHub.publish} and a controller's `@Sse()` endpoint
+ * reads from it via {@link SseHub.stream}.
  *
- * Each key may have multiple concurrent subscribers (e.g. a user with several
- * open tabs). The Subject is created lazily on first subscribe and torn down
- * once the last subscriber unsubscribes.
+ * Each key may have multiple concurrent subscribers (e.g. a user with several open tabs). The
+ * Subject is created lazily on first subscribe and torn down once the last subscriber unsubscribes.
+ *
+ * By default delivery is **in-process**. Provide an {@link SseBackplane} (e.g. Redis pub/sub) to
+ * fan out across pods: a publish on any node then reaches the SSE connections on every node.
  */
-export declare class SseHub {
+export declare class SseHub implements OnModuleInit, OnModuleDestroy {
+    private readonly backplane?;
     private readonly subjects;
     private readonly refcounts;
+    constructor(backplane?: SseBackplane | undefined);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
     /**
-     * Return the live stream for `key` as an Observable. Subscribing creates the
-     * underlying Subject (if absent) and bumps its refcount; unsubscribing
-     * decrements it and removes the Subject once no subscribers remain. Return
-     * this directly from a controller's `@Sse()` method.
+     * Return the live stream for `key` as an Observable. Subscribing creates the underlying Subject
+     * (if absent) and bumps its refcount; unsubscribing decrements it and removes the Subject once no
+     * subscribers remain. Return this directly from a controller's `@Sse()` method.
      */
     stream(key: string): Observable<MessageEvent>;
     /**
-     * Push a `MessageEvent` to every subscriber of `key`. No-ops when nobody is
-     * listening (no Subject exists), since SSE is fire-and-forget. `options.event`
-     * sets the SSE event `type`.
+     * Push a message to every subscriber of `key`. With a backplane it's broadcast to all nodes
+     * (delivered back through the backplane subscription, including to this node); without one it's
+     * delivered to local subscribers directly. `options.event` sets the SSE event `type`.
      */
     publish(key: string, data: unknown, options?: {
         event?: string;
     }): void;
+    /** Deliver a message to this node's local subscribers of `key` (no-op when none). */
+    private deliverLocal;
     private subjectFor;
 }
 //# sourceMappingURL=sse.hub.d.ts.map

package/dist/sse.hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.hub.d.ts","sourceRoot":"","sources":["../src/sse.hub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,MAAM,CAAC;AAE1D;;;;;;;;;GASG;AACH,qBACa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC;IAkB7C;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWvE,OAAO,CAAC,UAAU;CAQnB"}
+{"version":3,"file":"sse.hub.d.ts","sourceRoot":"","sources":["../src/sse.hub.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,EAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,MAAM,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;GAUG;AACH,qBACa,MAAO,YAAW,YAAY,EAAE,eAAe;IAOxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAN7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;gBAKpC,SAAS,CAAC,EAAE,YAAY,YAAA;IAGrC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC;IAkB7C;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IASvE,qFAAqF;IACrF,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,UAAU;CAQnB"}

package/dist/sse.hub.js

@@ -5,28 +5,48 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SseHub = void 0;
 const common_1 = require("@nestjs/common");
 const rxjs_1 = require("rxjs");
+const tokens_1 = require("./tokens");
 /**
- * In-memory fan-out for native NestJS Server-Sent Events. Keeps one
- * {@link Subject} per stream key; the channel pushes events into it via
- * {@link SseHub.publish} and a controller's `@Sse()` endpoint reads from it via
- * {@link SseHub.stream}.
+ * Fan-out for native NestJS Server-Sent Events. Keeps one {@link Subject} per stream key; the
+ * channel pushes events into it via {@link SseHub.publish} and a controller's `@Sse()` endpoint
+ * reads from it via {@link SseHub.stream}.
+ *
+ * Each key may have multiple concurrent subscribers (e.g. a user with several open tabs). The
+ * Subject is created lazily on first subscribe and torn down once the last subscriber unsubscribes.
  *
- * Each key may have multiple concurrent subscribers (e.g. a user with several
- * open tabs). The Subject is created lazily on first subscribe and torn down
- * once the last subscriber unsubscribes.
+ * By default delivery is **in-process**. Provide an {@link SseBackplane} (e.g. Redis pub/sub) to
+ * fan out across pods: a publish on any node then reaches the SSE connections on every node.
  */
 let SseHub = class SseHub {
+    backplane;
     subjects = new Map();
     refcounts = new Map();
+    constructor(backplane) {
+        this.backplane = backplane;
+    }
+    async onModuleInit() {
+        // Inbound messages from other nodes are delivered to this node's local subscribers.
+        if (this.backplane) {
+            await this.backplane.subscribe((key, message) => this.deliverLocal(key, message));
+        }
+    }
+    async onModuleDestroy() {
+        await this.backplane?.close?.();
+    }
     /**
-     * Return the live stream for `key` as an Observable. Subscribing creates the
-     * underlying Subject (if absent) and bumps its refcount; unsubscribing
-     * decrements it and removes the Subject once no subscribers remain. Return
-     * this directly from a controller's `@Sse()` method.
+     * Return the live stream for `key` as an Observable. Subscribing creates the underlying Subject
+     * (if absent) and bumps its refcount; unsubscribing decrements it and removes the Subject once no
+     * subscribers remain. Return this directly from a controller's `@Sse()` method.
      */
     stream(key) {
         const subject = this.subjectFor(key);
@@ -44,19 +64,25 @@ let SseHub = class SseHub {
         }));
     }
     /**
-     * Push a `MessageEvent` to every subscriber of `key`. No-ops when nobody is
-     * listening (no Subject exists), since SSE is fire-and-forget. `options.event`
-     * sets the SSE event `type`.
+     * Push a message to every subscriber of `key`. With a backplane it's broadcast to all nodes
+     * (delivered back through the backplane subscription, including to this node); without one it's
+     * delivered to local subscribers directly. `options.event` sets the SSE event `type`.
      */
     publish(key, data, options) {
+        const message = { data, event: options?.event };
+        if (this.backplane) {
+            void this.backplane.publish(key, message);
+            return;
+        }
+        this.deliverLocal(key, message);
+    }
+    /** Deliver a message to this node's local subscribers of `key` (no-op when none). */
+    deliverLocal(key, message) {
         const subject = this.subjects.get(key);
         if (!subject)
             return;
-        const data_ = data;
-        const message = options?.event
-            ? { data: data_, type: options.event }
-            : { data: data_ };
-        subject.next(message);
+        const data = message.data;
+        subject.next(message.event ? { data, type: message.event } : { data });
     }
     subjectFor(key) {
         let subject = this.subjects.get(key);
@@ -69,6 +95,9 @@ let SseHub = class SseHub {
 };
 exports.SseHub = SseHub;
 exports.SseHub = SseHub = __decorate([
-    (0, common_1.Injectable)()
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(tokens_1.SSE_BACKPLANE)),
+    __metadata("design:paramtypes", [Object])
 ], SseHub);
 //# sourceMappingURL=sse.hub.js.map

package/dist/sse.hub.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.hub.js","sourceRoot":"","sources":["../src/sse.hub.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA+D;AAC/D,+BAA0D;AAE1D;;;;;;;;;GASG;AAEI,IAAM,MAAM,GAAZ,MAAM,MAAM;IACA,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;IACpD,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,GAAW;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAE5D,OAAO,OAAO,CAAC,YAAY,EAAE,CAAC,IAAI,CAChC,IAAA,eAAQ,EAAC,GAAG,EAAE;YACZ,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAChD,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACd,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC3B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,GAAW,EAAE,IAAa,EAAE,OAA4B;QAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,KAAK,GAAG,IAA4B,CAAC;QAC3C,MAAM,OAAO,GAAiB,OAAO,EAAE,KAAK;YAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;YACtC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAEO,UAAU,CAAC,GAAW;QAC5B,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,IAAI,cAAO,EAAgB,CAAC;YACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF,CAAA;AApDY,wBAAM;iBAAN,MAAM;IADlB,IAAA,mBAAU,GAAE;GACA,MAAM,CAoDlB"}
+{"version":3,"file":"sse.hub.js","sourceRoot":"","sources":["../src/sse.hub.ts"],"names":[],"mappings":"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"}

package/dist/sse.module.d.ts

@@ -1,7 +1,14 @@
 import { type DynamicModule } from '@nestjs/common';
+import type { SseBackplane } from './backplane';
 export interface SseChannelModuleOptions {
     /** SSE event name (`type`) emitted to clients. Defaults to `'notification'`. */
     event?: string;
+    /**
+     * Cross-pod fan-out backplane (e.g. {@link import('./redis.backplane').RedisSseBackplane}). Omit
+     * for in-process delivery (single node). Required when publishers and SSE connections live on
+     * different processes.
+     */
+    backplane?: SseBackplane;
     /** Register globally so the channel is discoverable app-wide. Default true. */
     global?: boolean;
 }

package/dist/sse.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.module.d.ts","sourceRoot":"","sources":["../src/sse.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AAK3E,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBACa,gBAAgB;IAC3B,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,uBAA4B,GAAG,aAAa;CAkBrE"}
+{"version":3,"file":"sse.module.d.ts","sourceRoot":"","sources":["../src/sse.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBACa,gBAAgB;IAC3B,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,uBAA4B,GAAG,aAAa;CAmBrE"}

package/dist/sse.module.js

@@ -31,6 +31,7 @@ let SseChannelModule = SseChannelModule_1 = class SseChannelModule {
         };
         const providers = [
             { provide: tokens_1.SSE_OPTIONS, useValue: channelOptions },
+            { provide: tokens_1.SSE_BACKPLANE, useValue: options.backplane ?? null },
             sse_hub_1.SseHub,
             sse_channel_1.SseChannel,
         ];

package/dist/sse.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.module.js","sourceRoot":"","sources":["../src/sse.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA2E;AAC3E,+CAAmE;AACnE,uCAAmC;AACnC,qCAAuC;AASvC;;;;;;;;;;;GAWG;AAEI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IAC3B,MAAM,CAAC,OAAO,CAAC,UAAmC,EAAE;QAClD,MAAM,cAAc,GAAsB;YACxC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,cAAc;SACvC,CAAC;QAEF,MAAM,SAAS,GAAe;YAC5B,EAAE,OAAO,EAAE,oBAAW,EAAE,QAAQ,EAAE,cAAc,EAAE;YAClD,gBAAM;YACN,wBAAU;SACX,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,kBAAgB;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,SAAS;YACT,OAAO,EAAE,CAAC,gBAAM,EAAE,wBAAU,CAAC;SAC9B,CAAC;IACJ,CAAC;CACF,CAAA;AAnBY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,gBAAgB,CAmB5B"}
+{"version":3,"file":"sse.module.js","sourceRoot":"","sources":["../src/sse.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA2E;AAE3E,+CAAmE;AACnE,uCAAmC;AACnC,qCAAsD;AAetD;;;;;;;;;;;GAWG;AAEI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IAC3B,MAAM,CAAC,OAAO,CAAC,UAAmC,EAAE;QAClD,MAAM,cAAc,GAAsB;YACxC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,cAAc;SACvC,CAAC;QAEF,MAAM,SAAS,GAAe;YAC5B,EAAE,OAAO,EAAE,oBAAW,EAAE,QAAQ,EAAE,cAAc,EAAE;YAClD,EAAE,OAAO,EAAE,sBAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,EAAE;YAC/D,gBAAM;YACN,wBAAU;SACX,CAAC;QAEF,OAAO;YACL,MAAM,EAAE,kBAAgB;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,SAAS;YACT,OAAO,EAAE,CAAC,gBAAM,EAAE,wBAAU,CAAC;SAC9B,CAAC;IACJ,CAAC;CACF,CAAA;AApBY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,gBAAgB,CAoB5B"}

package/dist/tokens.d.ts

@@ -1,3 +1,5 @@
 /** DI token for the resolved {@link SseChannelOptions} (event name, etc.). */
 export declare const SSE_OPTIONS: unique symbol;
+/** DI token for the optional {@link import('./backplane').SseBackplane} (cross-pod fan-out). */
+export declare const SSE_BACKPLANE: unique symbol;
 //# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,eAAO,MAAM,WAAW,eAAwB,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,eAAO,MAAM,WAAW,eAAwB,CAAC;AAEjD,gGAAgG;AAChG,eAAO,MAAM,aAAa,eAA0B,CAAC"}

package/dist/tokens.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SSE_OPTIONS = void 0;
+exports.SSE_BACKPLANE = exports.SSE_OPTIONS = void 0;
 /** DI token for the resolved {@link SseChannelOptions} (event name, etc.). */
 exports.SSE_OPTIONS = Symbol('SSE_OPTIONS');
+/** DI token for the optional {@link import('./backplane').SseBackplane} (cross-pod fan-out). */
+exports.SSE_BACKPLANE = Symbol('SSE_BACKPLANE');
 //# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AACjE,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AACjE,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAEjD,gGAAgG;AACnF,QAAA,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-notifications-sse",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Server-Sent Events channel for nestjs-notifications — push real-time notifications over native NestJS SSE",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -21,11 +21,11 @@
     "rxjs": "^7.0.0"
   },
   "devDependencies": {
-    "@nestjs/common": "^11.0.0",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.0.0",
-    "typescript": "^5.7.2",
-    "@dudousxd/nestjs-notifications-core": "^0.4.0"
+    "@nestjs/common": "11.1.26",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "@dudousxd/nestjs-notifications-core": "^0.5.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",