@nestjs-redis/socket.io-adapter 0.0.21

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saba Pochkhua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/CSenshi/nestjs-redis/main/docs/images/logo.png" alt="NestJS Redis Toolkit Logo" width="200" height="200">
+
+# @nestjs-redis/socket.io-adapter
+
+Redis-powered Socket.IO adapter for NestJS enabling scalable WebSocket connections across multiple instances.
+
+[![npm version](https://badge.fury.io/js/%40nestjs-redis%2Fsocket.io-adapter.svg)](https://www.npmjs.com/package/@nestjs-redis/socket.io-adapter)
+[![npm downloads](https://img.shields.io/npm/dm/@nestjs-redis/socket.io-adapter.svg)](https://www.npmjs.com/package/@nestjs-redis/socket.io-adapter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![NestJS](https://img.shields.io/badge/NestJS-9%2B-red.svg)](https://nestjs.com/) [![Redis](https://img.shields.io/badge/Redis-5+-red.svg)](https://redis.io/)
+
+</div>
+
+---
+
+## Features
+
+- **Horizontal scaling**: Connect clients to any server instance
+- **Redis pub/sub**: Automatic event distribution across instances
+- **Lifecycle management**: Redis connections are managed automatically
+- **Works with existing connections**: Integrates seamlessly with `@nestjs-redis/client`
+- **Type-safe**: Full TypeScript support
+- **Production-ready**: Built on the official Socket.IO Redis adapter
+
+## Installation
+
+```bash
+npm install @nestjs-redis/socket.io-adapter
+# or
+yarn add @nestjs-redis/socket.io-adapter
+# or
+pnpm add @nestjs-redis/socket.io-adapter
+```
+
+## Quick Start
+
+### Setup with existing Redis connection (Recommended)
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { RedisModule } from '@nestjs-redis/client';
+
+@Module({
+  imports: [
+    RedisModule.forRoot({
+      options: { url: 'redis://localhost:6379' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { setupRedisAdapter } from '@nestjs-redis/socket.io-adapter';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Setup Redis adapter for Socket.IO
+  await setupRedisAdapter(app);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+### Multiple Redis connections
+
+If you have multiple Redis connections, specify which one to use:
+
+```typescript
+// app.module.ts
+@Module({
+  imports: [
+    RedisModule.forRoot({
+      options: { url: 'redis://localhost:6379' },
+    }),
+    RedisModule.forRoot({
+      connectionName: 'websockets',
+      options: { url: 'redis://websockets:6379' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+// main.ts
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Use the 'websockets' Redis connection
+  await setupRedisAdapter(app, 'websockets');
+
+  await app.listen(3000);
+}
+```
+
+## The Problem
+
+When scaling your NestJS application horizontally with multiple instances, WebSocket connections become a challenge. By default, Socket.IO connections are tied to a single server instance, which means:
+
+- Events sent from one server instance won't reach clients connected to other instances
+- Real-time features break when users connect to different servers
+- Load balancing becomes complex as you need sticky sessions
+
+## The Solution
+
+This package provides a Redis-backed Socket.IO adapter that uses Redis pub/sub to synchronize events across all server instances. When a server emits an event, it's published to Redis and distributed to all other server instances, ensuring all clients receive the event regardless of which server they're connected to.
+
+## How It Works
+
+1. **Redis Pub/Sub**: The adapter creates two Redis connections - one for publishing and one for subscribing
+2. **Event Distribution**: When a server emits an event, it's published to a Redis channel
+3. **Cross-Instance Delivery**: All server instances subscribe to the same channels and forward events to their connected clients
+4. **Automatic Management**: Connection lifecycle is handled automatically by the adapter
+
+## API
+
+### `setupRedisAdapter(app, redisToken?)`
+
+Sets up the Redis adapter for the NestJS application.
+
+- `app`: NestJS application instance
+- `redisToken` (optional): Redis connection name (defaults to the default connection)
+
+### `RedisIoAdapter`
+
+The underlying Socket.IO adapter class that handles Redis connections.
+
+## Architecture
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Server 1  │    │   Server 2  │    │   Server 3  │
+│  ┌───────┐  │    │  ┌───────┐  │    │  ┌───────┐  │
+│  │Client │  │    │  │Client │  │    │  │Client │  │
+│  └───────┘  │    │  └───────┘  │    │  └───────┘  │
+└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
+       │                  │                  │
+       └──────────────────┼──────────────────┘
+                          │
+                    ┌─────▼─────┐
+                    │   Redis   │
+                    │  Pub/Sub  │
+                    └───────────┘
+```
+
+## Learn More
+
+- [NestJS WebSocket Adapter Documentation](https://docs.nestjs.com/websockets/adapter)
+- [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/)
+- [Redis Pub/Sub](https://redis.io/docs/manual/pubsub/)
+
+## Links
+
+- Root repo: [CSenshi/nestjs-redis](https://github.com/CSenshi/nestjs-redis)
+- Issues: [GitHub Issues](https://github.com/CSenshi/nestjs-redis/issues)
+- Discussions: [GitHub Discussions](https://github.com/CSenshi/nestjs-redis/discussions)
+
+## Contributing
+
+Please see the [root contributing guidelines](https://github.com/CSenshi/nestjs-redis#contributing).
+
+## License
+
+MIT © [CSenshi](https://github.com/CSenshi)

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@nestjs-redis/socket.io-adapter",
+  "version": "0.0.21",
+  "license": "MIT",
+  "author": "Saba Pochkhua <saba.pochkhua@gmail.com> (https://github.com/CSenshi)",
+  "description": "Redis-powered Socket.IO adapter for NestJS enabling scalable WebSocket connections",
+  "keywords": [
+    "nestjs",
+    "redis",
+    "socket.io",
+    "websockets",
+    "adapter",
+    "scalable",
+    "typescript",
+    "node-redis"
+  ],
+  "homepage": "https://github.com/CSenshi/nestjs-redis/tree/main/packages/socket.io-adapter",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "!**/*.tsbuildinfo"
+  ],
+  "nx": {
+    "name": "socket.io-adapter",
+    "targets": {
+      "build": {
+        "executor": "@nx/js:tsc",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "dist/packages/socket.io-adapter",
+          "tsConfig": "packages/socket.io-adapter/tsconfig.lib.json",
+          "packageJson": "packages/socket.io-adapter/package.json",
+          "main": "packages/socket.io-adapter/src/index.ts",
+          "assets": [
+            "packages/socket.io-adapter/*.md",
+            "LICENSE"
+          ]
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "@nestjs/platform-socket.io": "^11.1.6",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "tslib": "^2.8.0"
+  },
+  "devDependencies": {
+    "@nestjs-redis/client": "0.10.1",
+    "@nestjs/testing": "^11.0.0",
+    "@nestjs/websockets": "^11.1.6",
+    "redis": "^5.0.0",
+    "socket.io-client": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0 || ^11.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CSenshi/nestjs-redis",
+    "directory": "packages/socket.io-adapter"
+  },
+  "type": "commonjs"
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib/exceptions';
+export * from './lib/redis-io.adapter';
+export * from './lib/setup-redis-adapter';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/socket.io-adapter/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC"}

package/src/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/exceptions"), exports);
+tslib_1.__exportStar(require("./lib/redis-io.adapter"), exports);
+tslib_1.__exportStar(require("./lib/setup-redis-adapter"), exports);

package/src/lib/exceptions.d.ts

@@ -0,0 +1,7 @@
+export declare class RedisClientNotFoundException extends Error {
+    constructor(redisToken?: string);
+}
+export declare class RedisAdapterAlreadySetUpException extends Error {
+    constructor();
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/src/lib/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../../../../packages/socket.io-adapter/src/lib/exceptions.ts"],"names":[],"mappings":"AAAA,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,UAAU,CAAC,EAAE,MAAM;CA6BhC;AAED,qBAAa,iCAAkC,SAAQ,KAAK;;CAK3D"}

package/src/lib/exceptions.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisAdapterAlreadySetUpException = exports.RedisClientNotFoundException = void 0;
+class RedisClientNotFoundException extends Error {
+    constructor(redisToken) {
+        const baseMessage = `Redis client not found. Please ensure that the Redis client is properly configured and provided in the application context.
+
+Most common solution:
+Import and configure RedisModule in your app.module.ts:`;
+        const configExample = redisToken
+            ? `  RedisModule.forRoot({
+    connectionName: '${redisToken}', // <-- connection name 
+    options: { url: process.env['REDIS_URL'] },
+  }),`
+            : `  RedisModule.forRoot({
+    options: { url: process.env['REDIS_URL'] },
+  }),`;
+        const troubleshooting = `
+
+Make sure you have:
+1. RedisModule imported in your module`;
+        super(baseMessage + '\n\n' + configExample + troubleshooting);
+        this.name = 'RedisClientNotFoundException';
+        if (redisToken) {
+            this.message += `\n\nRequired connection name: ${redisToken}`;
+        }
+        this.message += `\n`;
+    }
+}
+exports.RedisClientNotFoundException = RedisClientNotFoundException;
+class RedisAdapterAlreadySetUpException extends Error {
+    constructor() {
+        super('Redis adapter is already set up for this application instance.');
+        this.name = 'RedisAdapterAlreadySetUpException';
+    }
+}
+exports.RedisAdapterAlreadySetUpException = RedisAdapterAlreadySetUpException;

package/src/lib/redis-io.adapter.d.ts

@@ -0,0 +1,11 @@
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import type { RedisClientType } from 'redis';
+export declare class RedisIoAdapter extends IoAdapter {
+    private pubClient;
+    private subClient;
+    private adapterConstructor;
+    connectToRedis(redisClient: RedisClientType): Promise<void>;
+    createIOServer(port: number, options?: Parameters<IoAdapter['createIOServer']>[1]): ReturnType<IoAdapter['createIOServer']>;
+    close(server: Parameters<IoAdapter['close']>[0]): Promise<void>;
+}
+//# sourceMappingURL=redis-io.adapter.d.ts.map

package/src/lib/redis-io.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-io.adapter.d.ts","sourceRoot":"","sources":["../../../../../packages/socket.io-adapter/src/lib/redis-io.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAE7C,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,SAAS,CAA8B;IAE/C,OAAO,CAAC,kBAAkB,CAA+C;IAEnE,cAAc,CAAC,WAAW,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IASxD,cAAc,CACrB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAM3B,KAAK,CAClB,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC;CAOjB"}

package/src/lib/redis-io.adapter.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisIoAdapter = void 0;
+const platform_socket_io_1 = require("@nestjs/platform-socket.io");
+const redis_adapter_1 = require("@socket.io/redis-adapter");
+class RedisIoAdapter extends platform_socket_io_1.IoAdapter {
+    async connectToRedis(redisClient) {
+        this.pubClient = redisClient;
+        this.subClient = this.pubClient.duplicate();
+        await this.subClient.connect();
+        this.adapterConstructor = (0, redis_adapter_1.createAdapter)(this.pubClient, this.subClient);
+    }
+    createIOServer(port, options) {
+        const server = super.createIOServer(port, options);
+        server.adapter(this.adapterConstructor);
+        return server;
+    }
+    async close(server) {
+        super.close(server);
+        if (this.subClient) {
+            await this.subClient.quit();
+        }
+    }
+}
+exports.RedisIoAdapter = RedisIoAdapter;

package/src/lib/setup-redis-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { INestApplication } from '@nestjs/common';
+/**
+ * Sets up the Redis adapter for a NestJS application.
+ *
+ * @param app - The NestJS application instance
+ * @param redisToken - Optional Redis client token for named connections
+ * @returns A promise that resolves when the adapter is set up
+ * @throws RedisClientNotFoundException if the Redis client is not found
+ */
+export declare function setupRedisAdapter(app: INestApplication, redisToken?: string): Promise<void>;
+//# sourceMappingURL=setup-redis-adapter.d.ts.map

package/src/lib/setup-redis-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-redis-adapter.d.ts","sourceRoot":"","sources":["../../../../../packages/socket.io-adapter/src/lib/setup-redis-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAWvD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,gBAAgB,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/src/lib/setup-redis-adapter.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupRedisAdapter = setupRedisAdapter;
+const core_1 = require("@nestjs/core");
+const exceptions_1 = require("@nestjs/core/errors/exceptions");
+const exceptions_2 = require("./exceptions");
+const redis_io_adapter_1 = require("./redis-io.adapter");
+const appSet = new Set();
+/**
+ * Sets up the Redis adapter for a NestJS application.
+ *
+ * @param app - The NestJS application instance
+ * @param redisToken - Optional Redis client token for named connections
+ * @returns A promise that resolves when the adapter is set up
+ * @throws RedisClientNotFoundException if the Redis client is not found
+ */
+async function setupRedisAdapter(app, redisToken) {
+    if (appSet.has(app)) {
+        throw new exceptions_2.RedisAdapterAlreadySetUpException();
+    }
+    appSet.add(app);
+    const redisIoAdapter = new redis_io_adapter_1.RedisIoAdapter(app);
+    try {
+        const moduleRef = app.get(core_1.ModuleRef);
+        const redisClient = moduleRef.get(RedisToken(redisToken), {
+            strict: false,
+        });
+        await redisIoAdapter.connectToRedis(redisClient);
+        app.useWebSocketAdapter(redisIoAdapter);
+    }
+    catch (error) {
+        if (error instanceof exceptions_1.UnknownElementException) {
+            throw new exceptions_2.RedisClientNotFoundException(redisToken);
+        }
+        throw error;
+    }
+}
+/**
+ * Creates a Redis client injection token.
+ *
+ * @param connectionName - Optional connection name
+ * @returns Injection token for the Redis client
+ * @publicApi
+ */
+function RedisToken(connectionName) {
+    if (connectionName) {
+        return `REDIS_CLIENT_${connectionName.toUpperCase()}`;
+    }
+    return 'REDIS_CLIENT';
+}