@fluojs/socket.io 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './adapter.js';
+export * from './module.js';
+export { SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER } from './tokens.js';
+export * from './types.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":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrE,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './adapter.js';
+export * from './module.js';
+export { SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER } from './tokens.js';
+export * from './types.js';

package/dist/module.d.ts

@@ -0,0 +1,26 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { SocketIoModuleOptions } from './types.js';
+/**
+ * Root module entry point for registering the Socket.IO gateway adapter.
+ */
+export declare class SocketIoModule {
+    /**
+     * Creates a global module that exposes the raw Socket.IO server and room service tokens.
+     *
+     * @param options Socket.IO adapter options applied to the lifecycle service for this module instance.
+     * @returns A runtime module definition that can be imported into an application module.
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import { SocketIoModule } from '@fluojs/socket.io';
+     *
+     * @Module({
+     *   imports: [SocketIoModule.forRoot()],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(options?: SocketIoModuleOptions): ModuleType;
+}
+//# 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,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAwBxD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAShE"}

package/dist/module.js

@@ -0,0 +1,51 @@
+import { defineModule } from '@fluojs/runtime';
+import { SOCKETIO_OPTIONS_INTERNAL } from './options-token.internal.js';
+import { SocketIoLifecycleService } from './adapter.js';
+import { SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER } from './tokens.js';
+function createSocketIoProviderSet(options = {}) {
+  return [{
+    provide: SOCKETIO_OPTIONS_INTERNAL,
+    useValue: options
+  }, {
+    provide: SocketIoLifecycleService,
+    useClass: SocketIoLifecycleService
+  }, {
+    provide: SOCKETIO_SERVER,
+    useFactory: service => service.getServer(),
+    inject: [SocketIoLifecycleService]
+  }, {
+    provide: SOCKETIO_ROOM_SERVICE,
+    useExisting: SocketIoLifecycleService
+  }];
+}
+
+/**
+ * Root module entry point for registering the Socket.IO gateway adapter.
+ */
+export class SocketIoModule {
+  /**
+   * Creates a global module that exposes the raw Socket.IO server and room service tokens.
+   *
+   * @param options Socket.IO adapter options applied to the lifecycle service for this module instance.
+   * @returns A runtime module definition that can be imported into an application module.
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import { SocketIoModule } from '@fluojs/socket.io';
+   *
+   * @Module({
+   *   imports: [SocketIoModule.forRoot()],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(options = {}) {
+    class SocketIoRuntimeModule extends SocketIoModule {}
+    return defineModule(SocketIoRuntimeModule, {
+      exports: [SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER],
+      global: true,
+      providers: createSocketIoProviderSet(options)
+    });
+  }
+}

package/dist/options-token.internal.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from '@fluojs/core';
+import type { SocketIoModuleOptions } from './types.js';
+/**
+ * Internal injection token for the Socket.IO module options.
+ */
+export declare const SOCKETIO_OPTIONS_INTERNAL: Token<SocketIoModuleOptions>;
+//# sourceMappingURL=options-token.internal.d.ts.map

package/dist/options-token.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options-token.internal.d.ts","sourceRoot":"","sources":["../src/options-token.internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,KAAK,CAAC,qBAAqB,CAAuC,CAAC"}

package/dist/options-token.internal.js

@@ -0,0 +1,4 @@
+/**
+ * Internal injection token for the Socket.IO module options.
+ */
+export const SOCKETIO_OPTIONS_INTERNAL = Symbol.for('fluo.socketio.options');

package/dist/tokens.d.ts

@@ -0,0 +1,12 @@
+import type { Token } from '@fluojs/core';
+import type { Server } from 'socket.io';
+import type { SocketIoRoomService } from './types.js';
+/**
+ * Injection token for the raw Socket.IO `Server` instance managed by {@link SocketIoModule}.
+ */
+export declare const SOCKETIO_SERVER: Token<Server>;
+/**
+ * Injection token for the high-level room management service exposed by {@link SocketIoModule}.
+ */
+export declare const SOCKETIO_ROOM_SERVICE: Token<SocketIoRoomService>;
+//# 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,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,MAAM,CAAsC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,mBAAmB,CAA4C,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,9 @@
+/**
+ * Injection token for the raw Socket.IO `Server` instance managed by {@link SocketIoModule}.
+ */
+export const SOCKETIO_SERVER = Symbol.for('fluo.socketio.server');
+
+/**
+ * Injection token for the high-level room management service exposed by {@link SocketIoModule}.
+ */
+export const SOCKETIO_ROOM_SERVICE = Symbol.for('fluo.socketio.room-service');

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import type { IncomingMessage } from 'node:http';
+import type { ServerOptions, Socket } from 'socket.io';
+import type { WebSocketRoomService } from '@fluojs/websockets';
+/**
+ * Room management contract exposed by `@fluojs/socket.io` gateways.
+ *
+ * Extends the generic WebSocket room API with Socket.IO event emission semantics.
+ */
+export interface SocketIoRoomService extends WebSocketRoomService {
+    /**
+     * Emits an event with payload data to every socket in one room.
+     *
+     * @param room Room identifier that should receive the event.
+     * @param event Socket.IO event name emitted to room members.
+     * @param data Payload delivered with the event.
+     * @param namespacePath Optional namespace path when broadcasting outside the default namespace.
+     */
+    broadcastToRoom(room: string, event: string, data: unknown, namespacePath?: string): void;
+    /**
+     * Adds one socket to a room.
+     *
+     * @param socketId Socket identifier to move into the room.
+     * @param room Room identifier to join.
+     * @param namespacePath Optional namespace path when targeting a non-default namespace.
+     */
+    joinRoom(socketId: string, room: string, namespacePath?: string): void;
+    /**
+     * Removes one socket from a room.
+     *
+     * @param socketId Socket identifier to remove from the room.
+     * @param room Room identifier to leave.
+     * @param namespacePath Optional namespace path when targeting a non-default namespace.
+     */
+    leaveRoom(socketId: string, room: string, namespacePath?: string): void;
+}
+/**
+ * Rejection details returned by Socket.IO auth guards when a connection or message should be blocked.
+ */
+export interface SocketIoGuardRejection {
+    /** Optional structured payload forwarded to `connect_error` or acknowledgement callbacks. */
+    data?: unknown;
+    /** When `true`, rejected message events disconnect the current socket after the rejection is reported. */
+    disconnect?: boolean;
+    /** Caller-visible reason reported for the rejected operation. */
+    message?: string;
+}
+/**
+ * Runtime context passed to Socket.IO connection guards before gateway connect handlers execute.
+ */
+export interface SocketIoConnectionGuardContext {
+    /** Count of active Socket.IO connections already accepted by this lifecycle service. */
+    activeConnectionCount: number;
+    /** Namespace path currently being connected, normalized to the Socket.IO gateway path contract. */
+    namespacePath: string;
+    /** Raw HTTP handshake request exposed by the selected Socket.IO runtime. */
+    request: IncomingMessage;
+    /** Socket.IO socket instance under evaluation. */
+    socket: Socket;
+}
+/**
+ * Guard function that can reject one Socket.IO namespace connection before gateway lifecycle hooks run.
+ */
+export type SocketIoConnectionGuard = (context: SocketIoConnectionGuardContext) => Promise<boolean | SocketIoGuardRejection | void> | boolean | SocketIoGuardRejection | void;
+/**
+ * Runtime context passed to Socket.IO message guards before matched gateway message handlers execute.
+ */
+export interface SocketIoMessageGuardContext {
+    /** Number of active Socket.IO connections already accepted by this lifecycle service. */
+    activeConnectionCount: number;
+    /** Socket.IO event name currently being dispatched. */
+    event: string;
+    /** Namespace path that received the event. */
+    namespacePath: string;
+    /** Event payload extracted from the Socket.IO argument list. */
+    payload: unknown;
+    /** Raw HTTP handshake request associated with the current socket. */
+    request: IncomingMessage;
+    /** Socket.IO socket instance emitting the event. */
+    socket: Socket;
+}
+/**
+ * Guard function that can reject one inbound Socket.IO event before gateway message handlers execute.
+ */
+export type SocketIoMessageGuard = (context: SocketIoMessageGuardContext) => Promise<boolean | SocketIoGuardRejection | void> | boolean | SocketIoGuardRejection | void;
+/**
+ * Options accepted by {@link SocketIoModule.forRoot}.
+ */
+export interface SocketIoModuleOptions {
+    /**
+     * Optional auth guards evaluated before namespace connections and inbound message handlers proceed.
+     */
+    auth?: {
+        /** Rejects namespace connections before `@OnConnect()` handlers execute. */
+        connection?: SocketIoConnectionGuard;
+        /** Rejects inbound events before matching `@OnMessage(...)` handlers execute. */
+        message?: SocketIoMessageGuard;
+    };
+    /**
+     * In-memory outbound buffering controls applied before the server flushes messages to sockets.
+     */
+    buffer?: {
+        /** Maximum number of queued outbound messages allowed per socket before overflow handling applies. */
+        maxPendingMessagesPerSocket?: number;
+        /** Strategy used when one socket exceeds the configured pending message cap. */
+        overflowPolicy?: 'close' | 'drop-newest' | 'drop-oldest';
+    };
+    /** Cross-origin configuration forwarded to the underlying Socket.IO server. */
+    cors?: ServerOptions['cors'];
+    /**
+     * Engine-level bounds forwarded to Socket.IO's underlying Engine.IO server.
+     */
+    engine?: {
+        /** Maximum accepted inbound payload size in bytes before Engine.IO rejects the request or frame. */
+        maxHttpBufferSize?: number;
+    };
+    /** Graceful shutdown controls for draining Socket.IO resources during application close. */
+    shutdown?: {
+        /** Maximum time to wait for shutdown cleanup before forceful termination. */
+        timeoutMs?: number;
+    };
+    /** Enabled Socket.IO transports such as `websocket` or `polling`. */
+    transports?: ServerOptions['transports'];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@fluojs/socket.io",
+  "description": "Socket.IO v4 gateway adapter for Fluo applications, built on the shared runtime and websocket decorators.",
+  "keywords": [
+    "fluo",
+    "socket.io",
+    "websocket",
+    "gateway",
+    "realtime",
+    "platform"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/socket.io"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@socket.io/bun-engine": "^0.1.0",
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1",
+    "@fluojs/websockets": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "socket.io": "^4.0.0"
+  },
+  "devDependencies": {
+    "socket.io": "^4.8.1",
+    "socket.io-client": "^4.8.1",
+    "vitest": "^3.2.4",
+    "@fluojs/platform-express": "^1.0.0-beta.1",
+    "@fluojs/platform-fastify": "^1.0.0-beta.1",
+    "@fluojs/platform-nodejs": "^1.0.0-beta.1"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}