@modern-admin/realtime 0.1.0

package/dist/gateway.d.ts

@@ -0,0 +1,50 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { type OnGatewayInit } from '@nestjs/websockets';
+import type { IRealtimeBus, RealtimeEvent } from '@modern-admin/core';
+/**
+ * Minimal duck-typed surface of a socket.io-style server we rely on. Kept
+ * structural so we don't import socket.io directly and so consumers that
+ * use a different platform adapter (ws, uWebSockets) can still wire this
+ * gateway as long as `emit` and `to(room).emit` exist.
+ */
+interface RealtimeServerLike {
+    emit(event: string, ...args: unknown[]): unknown;
+    to?(room: string): {
+        emit(event: string, ...args: unknown[]): unknown;
+    };
+}
+interface RealtimeSocketLike {
+    id: string;
+    join?(room: string): unknown;
+    leave?(room: string): unknown;
+    emit(event: string, ...args: unknown[]): unknown;
+}
+/**
+ * NestJS WebSocket gateway. On bootstrap subscribes to the realtime bus and
+ * fans events out to socket.io clients. Clients can opt into per-resource
+ * rooms via the `subscribe` / `unsubscribe` messages to reduce noise.
+ */
+export declare class RealtimeGateway implements OnGatewayInit, OnModuleInit {
+    private readonly bus;
+    server: RealtimeServerLike;
+    private unsubscribe;
+    constructor(bus: IRealtimeBus);
+    onModuleInit(): Promise<void>;
+    afterInit(): void;
+    /** Broadcast an event to subscribers of the resource room and the global room. */
+    broadcast(event: RealtimeEvent): void;
+    handleSubscribe(body: {
+        resourceId?: string;
+        all?: boolean;
+    }, client: RealtimeSocketLike): {
+        ok: true;
+    };
+    handleUnsubscribe(body: {
+        resourceId?: string;
+        all?: boolean;
+    }, client: RealtimeSocketLike): {
+        ok: true;
+    };
+}
+export {};
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC1D,OAAO,EAGL,KAAK,aAAa,EAInB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGrE;;;;;GAKG;AACH,UAAU,kBAAkB;IAC1B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAChD,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;KAAE,CAAA;CACxE;AAED,UAAU,kBAAkB;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC5B,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;CACjD;AAKD;;;;GAIG;AACH,qBAIa,eAAgB,YAAW,aAAa,EAAE,YAAY;IAM/B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJ/C,MAAM,EAAG,kBAAkB,CAAA;IAElC,OAAO,CAAC,WAAW,CAA4B;gBAEI,GAAG,EAAE,YAAY;IAE9D,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC,SAAS,IAAI,IAAI;IAIjB,kFAAkF;IAClF,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAYrC,eAAe,CACE,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,EACxC,MAAM,EAAE,kBAAkB,GAC5C;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE;IAWf,iBAAiB,CACA,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,EACxC,MAAM,EAAE,kBAAkB,GAC5C;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE;CAShB"}

package/dist/gateway.js

@@ -0,0 +1,98 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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); }
+};
+import { Inject } from '@nestjs/common';
+import { ConnectedSocket, MessageBody, SubscribeMessage, WebSocketGateway, WebSocketServer, } from '@nestjs/websockets';
+import { REALTIME_BUS, REALTIME_EVENT } from './tokens.js';
+const ALL_ROOM = 'modern-admin:all';
+const resourceRoom = (resourceId) => `modern-admin:resource:${resourceId}`;
+/**
+ * NestJS WebSocket gateway. On bootstrap subscribes to the realtime bus and
+ * fans events out to socket.io clients. Clients can opt into per-resource
+ * rooms via the `subscribe` / `unsubscribe` messages to reduce noise.
+ */
+let RealtimeGateway = class RealtimeGateway {
+    constructor(bus) {
+        this.bus = bus;
+        this.unsubscribe = null;
+    }
+    async onModuleInit() {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = await this.bus.subscribe((event) => {
+            this.broadcast(event);
+        });
+    }
+    afterInit() {
+        // Hook reserved for socket.io middleware injection by consumers.
+    }
+    /** Broadcast an event to subscribers of the resource room and the global room. */
+    broadcast(event) {
+        const server = this.server;
+        if (!server)
+            return;
+        if (typeof server.to === 'function') {
+            server.to(resourceRoom(event.resourceId)).emit(REALTIME_EVENT, event);
+            server.to(ALL_ROOM).emit(REALTIME_EVENT, event);
+            return;
+        }
+        server.emit(REALTIME_EVENT, event);
+    }
+    handleSubscribe(body, client) {
+        if (body?.all && typeof client.join === 'function') {
+            client.join(ALL_ROOM);
+        }
+        if (body?.resourceId && typeof client.join === 'function') {
+            client.join(resourceRoom(body.resourceId));
+        }
+        return { ok: true };
+    }
+    handleUnsubscribe(body, client) {
+        if (body?.all && typeof client.leave === 'function') {
+            client.leave(ALL_ROOM);
+        }
+        if (body?.resourceId && typeof client.leave === 'function') {
+            client.leave(resourceRoom(body.resourceId));
+        }
+        return { ok: true };
+    }
+};
+__decorate([
+    WebSocketServer(),
+    __metadata("design:type", Object)
+], RealtimeGateway.prototype, "server", void 0);
+__decorate([
+    SubscribeMessage('subscribe'),
+    __param(0, MessageBody()),
+    __param(1, ConnectedSocket()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Object)
+], RealtimeGateway.prototype, "handleSubscribe", null);
+__decorate([
+    SubscribeMessage('unsubscribe'),
+    __param(0, MessageBody()),
+    __param(1, ConnectedSocket()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Object)
+], RealtimeGateway.prototype, "handleUnsubscribe", null);
+RealtimeGateway = __decorate([
+    WebSocketGateway({
+        namespace: 'admin/realtime',
+        cors: { origin: true, credentials: true },
+    }),
+    __param(0, Inject(REALTIME_BUS)),
+    __metadata("design:paramtypes", [Object])
+], RealtimeGateway);
+export { RealtimeGateway };
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ModernAdminRealtimeModule, type ModernAdminRealtimeModuleOptions } from './module.js';
+export { RealtimeGateway } from './gateway.js';
+export { RedisRealtimeBus, type RealtimeRedisLike, type RedisRealtimeBusOptions } from './redis-bus.js';
+export { REALTIME_BUS, REALTIME_EVENT } from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,yBAAyB,EAAE,KAAK,gCAAgC,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AACvG,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @modern-admin/realtime — WebSocket gateway and pub/sub buses for live
+// resource events. Pair `ModernAdminRealtimeModule.forRoot({ bus })` with
+// `ModernAdminModule.forRoot({ realtime: bus })` to broadcast every
+// create/update/delete to connected clients.
+export { ModernAdminRealtimeModule } from './module.js';
+export { RealtimeGateway } from './gateway.js';
+export { RedisRealtimeBus } from './redis-bus.js';
+export { REALTIME_BUS, REALTIME_EVENT } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0EAA0E;AAC1E,oEAAoE;AACpE,6CAA6C;AAE7C,OAAO,EAAE,yBAAyB,EAAyC,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,gBAAgB,EAAwD,MAAM,gBAAgB,CAAA;AACvG,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/module.d.ts

@@ -0,0 +1,18 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type IRealtimeBus } from '@modern-admin/core';
+export interface ModernAdminRealtimeModuleOptions {
+    /** Custom bus implementation (e.g. RedisRealtimeBus). Defaults to in-memory. */
+    bus?: IRealtimeBus;
+    /** Make the module global so other features can reuse the bus token. */
+    global?: boolean;
+}
+/**
+ * NestJS dynamic module wrapping the realtime bus and the WebSocket gateway.
+ *
+ * Pair with `ModernAdminModule.forRoot({ realtime: <same bus> })` so the
+ * core invoke pipeline publishes onto the same bus the gateway listens to.
+ */
+export declare class ModernAdminRealtimeModule {
+    static forRoot(options?: ModernAdminRealtimeModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI3E,MAAM,WAAW,gCAAgC;IAC/C,gFAAgF;IAChF,GAAG,CAAC,EAAE,YAAY,CAAA;IAClB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;GAKG;AACH,qBACa,yBAAyB;IACpC,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,gCAAqC,GAAG,aAAa;CAY9E"}

package/dist/module.js

@@ -0,0 +1,36 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 ModernAdminRealtimeModule_1;
+import { Module } from '@nestjs/common';
+import { InMemoryRealtimeBus } from '@modern-admin/core';
+import { RealtimeGateway } from './gateway.js';
+import { REALTIME_BUS } from './tokens.js';
+/**
+ * NestJS dynamic module wrapping the realtime bus and the WebSocket gateway.
+ *
+ * Pair with `ModernAdminModule.forRoot({ realtime: <same bus> })` so the
+ * core invoke pipeline publishes onto the same bus the gateway listens to.
+ */
+let ModernAdminRealtimeModule = ModernAdminRealtimeModule_1 = class ModernAdminRealtimeModule {
+    static forRoot(options = {}) {
+        const bus = options.bus ?? new InMemoryRealtimeBus();
+        return {
+            module: ModernAdminRealtimeModule_1,
+            global: options.global ?? false,
+            providers: [
+                { provide: REALTIME_BUS, useValue: bus },
+                RealtimeGateway,
+            ],
+            exports: [REALTIME_BUS, RealtimeGateway],
+        };
+    }
+};
+ModernAdminRealtimeModule = ModernAdminRealtimeModule_1 = __decorate([
+    Module({})
+], ModernAdminRealtimeModule);
+export { ModernAdminRealtimeModule };
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAqB,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAS1C;;;;;GAKG;AAEI,IAAM,yBAAyB,iCAA/B,MAAM,yBAAyB;IACpC,MAAM,CAAC,OAAO,CAAC,UAA4C,EAAE;QAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,mBAAmB,EAAE,CAAA;QACpD,OAAO;YACL,MAAM,EAAE,2BAAyB;YACjC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;YAC/B,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,EAAE;gBACxC,eAAe;aAChB;YACD,OAAO,EAAE,CAAC,YAAY,EAAE,eAAe,CAAC;SACzC,CAAA;IACH,CAAC;CACF,CAAA;AAbY,yBAAyB;IADrC,MAAM,CAAC,EAAE,CAAC;GACE,yBAAyB,CAarC"}

package/dist/redis-bus.d.ts

@@ -0,0 +1,41 @@
+import type { IRealtimeBus, RealtimeEvent, RealtimeHandler } from '@modern-admin/core';
+/**
+ * Minimal duck-typed surface of an ioredis client. We never import the real
+ * type so consumers can swap implementations (mock, sentinel, cluster) as
+ * long as `publish`, `subscribe`, and `duplicate` are present.
+ */
+export interface RealtimeRedisLike {
+    publish(channel: string, message: string): Promise<unknown>;
+    subscribe(channel: string): Promise<unknown> | unknown;
+    unsubscribe(channel: string): Promise<unknown> | unknown;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    off(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    duplicate(): RealtimeRedisLike;
+    /** Optional teardown for tests/process exits. */
+    quit?(): Promise<unknown> | unknown;
+}
+export interface RedisRealtimeBusOptions {
+    client: RealtimeRedisLike;
+    channel?: string;
+}
+/**
+ * Realtime bus backed by Redis pub/sub for cross-instance fan-out. Uses a
+ * dedicated subscriber connection (`client.duplicate()`) so subscriptions do
+ * not block the publisher's command pipeline. Events are JSON-encoded; an
+ * unparseable payload is dropped silently to avoid bringing the listener
+ * down on a single bad publish.
+ */
+export declare class RedisRealtimeBus implements IRealtimeBus {
+    private readonly publisher;
+    private readonly channel;
+    private subscriber;
+    private subscriberStarted;
+    private readonly handlers;
+    constructor(options: RedisRealtimeBusOptions);
+    publish(event: RealtimeEvent): Promise<void>;
+    subscribe(handler: RealtimeHandler): Promise<() => void>;
+    /** Stop the subscriber connection. Useful in tests / graceful shutdown. */
+    close(): Promise<void>;
+    private ensureSubscriber;
+}
+//# sourceMappingURL=redis-bus.d.ts.map

package/dist/redis-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-bus.d.ts","sourceRoot":"","sources":["../src/redis-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEtF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3D,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IACtD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IACxD,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAA;IACnF,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAA;IACpF,SAAS,IAAI,iBAAiB,CAAA;IAC9B,iDAAiD;IACjD,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,iBAAiB,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;gBAE1C,OAAO,EAAE,uBAAuB;IAKtC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAQ9D,2EAA2E;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAqBd,gBAAgB;CAqB/B"}

package/dist/redis-bus.js

@@ -0,0 +1,75 @@
+const DEFAULT_CHANNEL = 'modern-admin:realtime';
+/**
+ * Realtime bus backed by Redis pub/sub for cross-instance fan-out. Uses a
+ * dedicated subscriber connection (`client.duplicate()`) so subscriptions do
+ * not block the publisher's command pipeline. Events are JSON-encoded; an
+ * unparseable payload is dropped silently to avoid bringing the listener
+ * down on a single bad publish.
+ */
+export class RedisRealtimeBus {
+    constructor(options) {
+        this.subscriber = null;
+        this.subscriberStarted = null;
+        this.handlers = new Set();
+        this.publisher = options.client;
+        this.channel = options.channel ?? DEFAULT_CHANNEL;
+    }
+    async publish(event) {
+        await this.publisher.publish(this.channel, JSON.stringify(event));
+    }
+    async subscribe(handler) {
+        this.handlers.add(handler);
+        await this.ensureSubscriber();
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /** Stop the subscriber connection. Useful in tests / graceful shutdown. */
+    async close() {
+        if (this.subscriber) {
+            const sub = this.subscriber;
+            this.subscriber = null;
+            this.subscriberStarted = null;
+            try {
+                await sub.unsubscribe(this.channel);
+            }
+            catch {
+                // ignore
+            }
+            if (typeof sub.quit === 'function') {
+                try {
+                    await sub.quit();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        this.handlers.clear();
+    }
+    async ensureSubscriber() {
+        if (this.subscriberStarted)
+            return this.subscriberStarted;
+        const sub = this.publisher.duplicate();
+        this.subscriber = sub;
+        this.subscriberStarted = (async () => {
+            sub.on('message', (channel, message) => {
+                if (channel !== this.channel)
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(message);
+                }
+                catch {
+                    return;
+                }
+                for (const handler of this.handlers) {
+                    void handler(event);
+                }
+            });
+            await sub.subscribe(this.channel);
+        })();
+        return this.subscriberStarted;
+    }
+}
+//# sourceMappingURL=redis-bus.js.map

package/dist/redis-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-bus.js","sourceRoot":"","sources":["../src/redis-bus.ts"],"names":[],"mappings":"AAuBA,MAAM,eAAe,GAAG,uBAAuB,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAO3B,YAAY,OAAgC;QAJpC,eAAU,GAA6B,IAAI,CAAA;QAC3C,sBAAiB,GAAyB,IAAI,CAAA;QACrC,aAAQ,GAAG,IAAI,GAAG,EAAmB,CAAA;QAGpD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAA;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAA;IACnD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAoB;QAChC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;IACnE,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAwB;QACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC1B,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAA;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAC/B,CAAC,CAAA;IACH,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAA;YAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;YACtB,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAA;YAC7B,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACrC,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;gBAClB,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS;gBACX,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IACvB,CAAC;IAEO,KAAK,CAAC,gBAAgB;QAC5B,IAAI,IAAI,CAAC,iBAAiB;YAAE,OAAO,IAAI,CAAC,iBAAiB,CAAA;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAA;QACtC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAA;QACrB,IAAI,CAAC,iBAAiB,GAAG,CAAC,KAAK,IAAI,EAAE;YACnC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;gBACrC,IAAI,OAAO,KAAK,IAAI,CAAC,OAAO;oBAAE,OAAM;gBACpC,IAAI,KAAoB,CAAA;gBACxB,IAAI,CAAC;oBACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAA;gBAC9C,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAM;gBACR,CAAC;gBACD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACpC,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;gBACrB,CAAC;YACH,CAAC,CAAC,CAAA;YACF,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnC,CAAC,CAAC,EAAE,CAAA;QACJ,OAAO,IAAI,CAAC,iBAAiB,CAAA;IAC/B,CAAC;CACF"}

package/dist/tokens.d.ts

@@ -0,0 +1,5 @@
+/** DI token for the IRealtimeBus instance shared across modules. */
+export declare const REALTIME_BUS: unique symbol;
+/** WebSocket event name used when broadcasting realtime events to clients. */
+export declare const REALTIME_EVENT = "modernAdmin:realtime";
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,eAAO,MAAM,YAAY,eAA2C,CAAA;AAEpE,8EAA8E;AAC9E,eAAO,MAAM,cAAc,yBAAyB,CAAA"}

package/dist/tokens.js

@@ -0,0 +1,5 @@
+/** DI token for the IRealtimeBus instance shared across modules. */
+export const REALTIME_BUS = Symbol.for('@modern-admin/realtime:Bus');
+/** WebSocket event name used when broadcasting realtime events to clients. */
+export const REALTIME_EVENT = 'modernAdmin:realtime';
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAA;AAEpE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,sBAAsB,CAAA"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@modern-admin/realtime",
+  "version": "0.1.0",
+  "description": "WebSocket gateway + realtime bus implementations for Modern Admin.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modern-admin/modern-admin.git",
+    "directory": "packages/realtime"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@modern-admin/core": "0.1.0",
+    "@modern-admin/nest": "0.1.0"
+  },
+  "devDependencies": {
+    "@modern-admin/tsconfig": "0.1.0",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/websockets": "^11.1.19",
+    "@types/bun": "^1.3.13",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/websockets": "^11.1.19",
+    "@nestjs/platform-socket.io": "^11.1.19"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/websockets": {
+      "optional": true
+    },
+    "@nestjs/platform-socket.io": {
+      "optional": true
+    }
+  }
+}

package/src/gateway.ts

@@ -0,0 +1,101 @@
+import { Inject, type OnModuleInit } from '@nestjs/common'
+import {
+  ConnectedSocket,
+  MessageBody,
+  type OnGatewayInit,
+  SubscribeMessage,
+  WebSocketGateway,
+  WebSocketServer,
+} from '@nestjs/websockets'
+import type { IRealtimeBus, RealtimeEvent } from '@modern-admin/core'
+import { REALTIME_BUS, REALTIME_EVENT } from './tokens.js'
+
+/**
+ * Minimal duck-typed surface of a socket.io-style server we rely on. Kept
+ * structural so we don't import socket.io directly and so consumers that
+ * use a different platform adapter (ws, uWebSockets) can still wire this
+ * gateway as long as `emit` and `to(room).emit` exist.
+ */
+interface RealtimeServerLike {
+  emit(event: string, ...args: unknown[]): unknown
+  to?(room: string): { emit(event: string, ...args: unknown[]): unknown }
+}
+
+interface RealtimeSocketLike {
+  id: string
+  join?(room: string): unknown
+  leave?(room: string): unknown
+  emit(event: string, ...args: unknown[]): unknown
+}
+
+const ALL_ROOM = 'modern-admin:all'
+const resourceRoom = (resourceId: string): string => `modern-admin:resource:${resourceId}`
+
+/**
+ * NestJS WebSocket gateway. On bootstrap subscribes to the realtime bus and
+ * fans events out to socket.io clients. Clients can opt into per-resource
+ * rooms via the `subscribe` / `unsubscribe` messages to reduce noise.
+ */
+@WebSocketGateway({
+  namespace: 'admin/realtime',
+  cors: { origin: true, credentials: true },
+})
+export class RealtimeGateway implements OnGatewayInit, OnModuleInit {
+  @WebSocketServer()
+  public server!: RealtimeServerLike
+
+  private unsubscribe: (() => void) | null = null
+
+  constructor(@Inject(REALTIME_BUS) private readonly bus: IRealtimeBus) {}
+
+  async onModuleInit(): Promise<void> {
+    if (this.unsubscribe) return
+    this.unsubscribe = await this.bus.subscribe((event) => {
+      this.broadcast(event)
+    })
+  }
+
+  afterInit(): void {
+    // Hook reserved for socket.io middleware injection by consumers.
+  }
+
+  /** Broadcast an event to subscribers of the resource room and the global room. */
+  broadcast(event: RealtimeEvent): void {
+    const server = this.server
+    if (!server) return
+    if (typeof server.to === 'function') {
+      server.to(resourceRoom(event.resourceId)).emit(REALTIME_EVENT, event)
+      server.to(ALL_ROOM).emit(REALTIME_EVENT, event)
+      return
+    }
+    server.emit(REALTIME_EVENT, event)
+  }
+
+  @SubscribeMessage('subscribe')
+  handleSubscribe(
+    @MessageBody() body: { resourceId?: string; all?: boolean },
+    @ConnectedSocket() client: RealtimeSocketLike,
+  ): { ok: true } {
+    if (body?.all && typeof client.join === 'function') {
+      client.join(ALL_ROOM)
+    }
+    if (body?.resourceId && typeof client.join === 'function') {
+      client.join(resourceRoom(body.resourceId))
+    }
+    return { ok: true }
+  }
+
+  @SubscribeMessage('unsubscribe')
+  handleUnsubscribe(
+    @MessageBody() body: { resourceId?: string; all?: boolean },
+    @ConnectedSocket() client: RealtimeSocketLike,
+  ): { ok: true } {
+    if (body?.all && typeof client.leave === 'function') {
+      client.leave(ALL_ROOM)
+    }
+    if (body?.resourceId && typeof client.leave === 'function') {
+      client.leave(resourceRoom(body.resourceId))
+    }
+    return { ok: true }
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// @modern-admin/realtime — WebSocket gateway and pub/sub buses for live
+// resource events. Pair `ModernAdminRealtimeModule.forRoot({ bus })` with
+// `ModernAdminModule.forRoot({ realtime: bus })` to broadcast every
+// create/update/delete to connected clients.
+
+export { ModernAdminRealtimeModule, type ModernAdminRealtimeModuleOptions } from './module.js'
+export { RealtimeGateway } from './gateway.js'
+export { RedisRealtimeBus, type RealtimeRedisLike, type RedisRealtimeBusOptions } from './redis-bus.js'
+export { REALTIME_BUS, REALTIME_EVENT } from './tokens.js'

package/src/module.ts

@@ -0,0 +1,33 @@
+import { type DynamicModule, Module } from '@nestjs/common'
+import { InMemoryRealtimeBus, type IRealtimeBus } from '@modern-admin/core'
+import { RealtimeGateway } from './gateway.js'
+import { REALTIME_BUS } from './tokens.js'
+
+export interface ModernAdminRealtimeModuleOptions {
+  /** Custom bus implementation (e.g. RedisRealtimeBus). Defaults to in-memory. */
+  bus?: IRealtimeBus
+  /** Make the module global so other features can reuse the bus token. */
+  global?: boolean
+}
+
+/**
+ * NestJS dynamic module wrapping the realtime bus and the WebSocket gateway.
+ *
+ * Pair with `ModernAdminModule.forRoot({ realtime: <same bus> })` so the
+ * core invoke pipeline publishes onto the same bus the gateway listens to.
+ */
+@Module({})
+export class ModernAdminRealtimeModule {
+  static forRoot(options: ModernAdminRealtimeModuleOptions = {}): DynamicModule {
+    const bus = options.bus ?? new InMemoryRealtimeBus()
+    return {
+      module: ModernAdminRealtimeModule,
+      global: options.global ?? false,
+      providers: [
+        { provide: REALTIME_BUS, useValue: bus },
+        RealtimeGateway,
+      ],
+      exports: [REALTIME_BUS, RealtimeGateway],
+    }
+  }
+}

package/src/redis-bus.ts

@@ -0,0 +1,100 @@
+import type { IRealtimeBus, RealtimeEvent, RealtimeHandler } from '@modern-admin/core'
+
+/**
+ * Minimal duck-typed surface of an ioredis client. We never import the real
+ * type so consumers can swap implementations (mock, sentinel, cluster) as
+ * long as `publish`, `subscribe`, and `duplicate` are present.
+ */
+export interface RealtimeRedisLike {
+  publish(channel: string, message: string): Promise<unknown>
+  subscribe(channel: string): Promise<unknown> | unknown
+  unsubscribe(channel: string): Promise<unknown> | unknown
+  on(event: 'message', listener: (channel: string, message: string) => void): unknown
+  off(event: 'message', listener: (channel: string, message: string) => void): unknown
+  duplicate(): RealtimeRedisLike
+  /** Optional teardown for tests/process exits. */
+  quit?(): Promise<unknown> | unknown
+}
+
+export interface RedisRealtimeBusOptions {
+  client: RealtimeRedisLike
+  channel?: string
+}
+
+const DEFAULT_CHANNEL = 'modern-admin:realtime'
+
+/**
+ * Realtime bus backed by Redis pub/sub for cross-instance fan-out. Uses a
+ * dedicated subscriber connection (`client.duplicate()`) so subscriptions do
+ * not block the publisher's command pipeline. Events are JSON-encoded; an
+ * unparseable payload is dropped silently to avoid bringing the listener
+ * down on a single bad publish.
+ */
+export class RedisRealtimeBus implements IRealtimeBus {
+  private readonly publisher: RealtimeRedisLike
+  private readonly channel: string
+  private subscriber: RealtimeRedisLike | null = null
+  private subscriberStarted: Promise<void> | null = null
+  private readonly handlers = new Set<RealtimeHandler>()
+
+  constructor(options: RedisRealtimeBusOptions) {
+    this.publisher = options.client
+    this.channel = options.channel ?? DEFAULT_CHANNEL
+  }
+
+  async publish(event: RealtimeEvent): Promise<void> {
+    await this.publisher.publish(this.channel, JSON.stringify(event))
+  }
+
+  async subscribe(handler: RealtimeHandler): Promise<() => void> {
+    this.handlers.add(handler)
+    await this.ensureSubscriber()
+    return () => {
+      this.handlers.delete(handler)
+    }
+  }
+
+  /** Stop the subscriber connection. Useful in tests / graceful shutdown. */
+  async close(): Promise<void> {
+    if (this.subscriber) {
+      const sub = this.subscriber
+      this.subscriber = null
+      this.subscriberStarted = null
+      try {
+        await sub.unsubscribe(this.channel)
+      } catch {
+        // ignore
+      }
+      if (typeof sub.quit === 'function') {
+        try {
+          await sub.quit()
+        } catch {
+          // ignore
+        }
+      }
+    }
+    this.handlers.clear()
+  }
+
+  private async ensureSubscriber(): Promise<void> {
+    if (this.subscriberStarted) return this.subscriberStarted
+    const sub = this.publisher.duplicate()
+    this.subscriber = sub
+    this.subscriberStarted = (async () => {
+      sub.on('message', (channel, message) => {
+        if (channel !== this.channel) return
+        let event: RealtimeEvent
+        try {
+          event = JSON.parse(message) as RealtimeEvent
+        } catch {
+          return
+        }
+        for (const handler of this.handlers) {
+          void handler(event)
+        }
+      })
+      await sub.subscribe(this.channel)
+    })()
+    return this.subscriberStarted
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,5 @@
+/** DI token for the IRealtimeBus instance shared across modules. */
+export const REALTIME_BUS = Symbol.for('@modern-admin/realtime:Bus')
+
+/** WebSocket event name used when broadcasting realtime events to clients. */
+export const REALTIME_EVENT = 'modernAdmin:realtime'