@steijnveer/fbr-plugin-io 0.0.1

package/README.md

@@ -0,0 +1,216 @@
+# @steijnveer/fbr-plugin-io
+
+Socket.io integration plugin for [@steijnveer/file-based-router](https://github.com/steijnveer/file-based-router)
+
+## Overview
+
+This plugin adds Socket.io support to your file-based-router application with automatic event handler discovery and registration. Define your Socket.io event handlers in files, and the plugin will automatically load and register them.
+
+## Installation
+
+```bash
+npm install @steijnveer/fbr-plugin-io
+```
+
+## Quick Start
+
+### 1. Configure the plugin
+
+```typescript
+// '/fbr.config.ts'
+import ioPlugin from '@steijnveer/fbr-plugin-io';
+import defineConfig from '@steijnveer/file-based-router/defineConfig';
+
+export default defineConfig({
+  plugins: [
+    ioPlugin({
+      eventsDir: 'src\\events',  // Directory containing event handlers
+      extensions: ['.ts', '.js'] // File extensions to load
+    })
+  ]
+});
+```
+
+### 2. Create event handlers
+
+Create event handler files in your events directory (default: `src/events`):
+
+**src/events/message.ts**
+```typescript
+import type { Socket } from '@steijnveer/fbr-plugin-io';
+
+// Export named functions - function name becomes the event name
+export function message(socket: Socket, data: { text: string }) {
+  log('Received message:', data.text);
+  socket.emit('message:response', { echo: data.text });
+}
+```
+
+**src/events/chat.ts**
+```typescript
+import type { Socket } from '@steijnveer/fbr-plugin-io';
+
+export function join(socket: Socket, data: { room: string }) {
+  socket.join(data.room);
+  socket.to(data.room).emit('user:joined', { id: socket.id });
+}
+
+export function leave(socket: Socket, data: { room: string }) {
+  socket.leave(data.room);
+  socket.to(data.room).emit('user:left', { id: socket.id });
+}
+```
+
+**src/events/index.ts** (for connection handlers)
+```typescript
+import type { Socket } from '@steijnveer/fbr-plugin-io';
+
+// Special 'connection' event handlers
+export function connection(socket: Socket) {
+  log('User connected: ' + socket.id);
+  socket.emit('welcome', { message: 'Welcome to the server!' });
+}
+```
+
+### 3. Access Socket.io server instance
+
+The Socket.io server instance is available on your server object:
+
+```typescript
+import type { Io } from '@steijnveer/fbr-plugin-io';
+
+// Emit to all connected clients
+server._io.emit('broadcast', { message: 'Hello everyone!' });
+
+// Access specific rooms
+server._io.to('room-name').emit('room:message', { text: 'Hello room!' });
+```
+
+## Configuration
+
+### Plugin Options
+
+```typescript
+interface IoPluginConfig {
+  eventsDir?: string;    // Directory containing event handlers (default: 'src\\events')
+  extensions?: string[]; // File extensions to load (default: ['.ts', '.js'])
+}
+```
+
+## Event Handler Conventions
+
+### Event Naming
+
+- **File name becomes event prefix**: `message.ts` → `message` event
+- **Named exports**: Use function name as event name
+  - `export function join()` in `chat.ts` → `chat:join` event
+- **Default exports**: Use file name as event name
+  - `export default function()` in `message.ts` → `message` event
+- **index.ts**: Exports use direct function names
+  - `export function connection()` in `index.ts` → `connection` event
+
+### Event Handler Signature
+
+```typescript
+type EventHandler = (socket: Socket, data: any) => void;
+```
+
+- **socket**: The Socket.io socket instance for the connected client
+- **data**: The data sent from the client (null if no data provided)
+
+### Special Events
+
+- **connection**: Handlers named `connection` are executed when a client connects
+- These handlers run after other event listeners are attached to the socket
+
+## Examples
+
+### Broadcasting to all clients
+
+**src/events/admin.ts**
+```typescript
+import type { Socket } from '@steijnveer/fbr-plugin-io';
+
+export function announce(socket: Socket, data: { message: string }) {
+  // Broadcast to all clients including sender
+  socket.server.emit('announcement', { message: data.message });
+}
+```
+
+### Room-based chat
+
+**src/events/room.ts**
+```typescript
+import type { Socket } from '@steijnveer/fbr-plugin-io';
+
+export function join(socket: Socket, data: { roomId: string }) {
+  socket.join(data.roomId);
+  socket.to(data.roomId).emit('room:userJoined', { 
+    userId: socket.id,
+    roomId: data.roomId 
+  });
+}
+
+export function message(socket: Socket, data: { roomId: string, text: string }) {
+  socket.to(data.roomId).emit('room:message', {
+    userId: socket.id,
+    text: data.text,
+    timestamp: Date.now()
+  });
+}
+```
+
+## TypeScript Support
+
+The plugin includes full TypeScript support with type definitions:
+
+```typescript
+import type { 
+  Socket,      // Socket.io socket instance with type safety
+  Io,          // Socket.io server instance
+  EventsMap,   // Event name to handler mapping
+  IoPluginConfig // Plugin configuration options
+} from '@steijnveer/fbr-plugin-io';
+```
+
+## Client-Side Usage
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="/socket.io/socket.io.js"></script>
+</head>
+<body>
+  <script>
+    const socket = io();
+    
+    // Listen for events
+    socket.on('welcome', (data) => {
+      console.log(data.message);
+    });
+    
+    // Emit events (matches your handler in message.ts)
+    socket.emit('message', { text: 'Hello server!' });
+    
+    // Listen for responses
+    socket.on('message:response', (data) => {
+      console.log('Echo:', data.echo);
+    });
+  </script>
+</body>
+</html>
+```
+
+## Debug Logging
+
+The plugin includes built-in debug logging for:
+- User connections/disconnections
+- All incoming events with data
+- All outgoing events with data
+
+Logs include the socket ID for easy debugging.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { Server } from '@steijnveer/file-based-router';
+import '@steijnveer/file-based-router/utils';
+import type { IoPluginConfig } from './types';
+declare function ioPlugin({ eventsDir, extensions }?: IoPluginConfig): (server: Server) => Promise<void>;
+export default ioPlugin;
+export type * from './types';
+export { ioPlugin };
+//# 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,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,qCAAqC,CAAC;AAK7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAqB9C,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,GAAE,cAAmB,IAEhD,QAAQ,MAAM,mBAyB7B;AAGD,eAAe,QAAQ,CAAC;AACxB,mBAAmB,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,54 @@
+import '@steijnveer/file-based-router/utils';
+import { readdirSync } from 'fs';
+import { extname, join, resolve } from 'path';
+import { Server as Io } from 'socket.io';
+import { pathToFileURL } from 'url';
+async function importEvents(eventsDir, extensions) {
+    const eventsDirPath = resolve(eventsDir);
+    const files = readdirSync(eventsDirPath, { withFileTypes: true })
+        .filter(entry => entry.isFile() && extensions.includes(extname(entry.name)));
+    const events = await Promise.all(files.map(async (file) => {
+        const fileName = file.name.replace(extname(file.name), '');
+        const module = await import(pathToFileURL(join(eventsDirPath, fileName)).href);
+        const eventHandlers = Object.entries(module)
+            .filter(([_, handler]) => typeof handler === 'function');
+        return fileName === 'index'
+            ? eventHandlers
+            : eventHandlers.map(([exportName, handler]) => [
+                exportName === 'default'
+                    ? fileName
+                    : `${fileName}:${exportName}`, handler
+            ]);
+    }));
+    return events.flat();
+}
+function ioPlugin({ eventsDir, extensions } = {}) {
+    const eventsPromise = importEvents(eventsDir ?? 'src\\events', extensions ?? ['.ts', '.js']);
+    return async (server) => {
+        server._io = new Io(server._httpServer);
+        const allEvents = await eventsPromise;
+        const events = allEvents
+            .filter(([eventName]) => eventName !== 'connection');
+        const connectionhandlers = allEvents
+            .filter(([eventName]) => eventName === 'connection')
+            .map(([_, handler]) => handler);
+        server._io.on('connection', (socket) => {
+            log(`a user connected: ${socket.id}`);
+            socket.on('disconnect', () => {
+                log(`(${socket.id}) user disconnected`);
+            });
+            socket.onAny((event, data) => {
+                log(`(${socket.id}) Received event: ${event} with args: ${JSON.stringify(data)}`);
+            });
+            socket.onAnyOutgoing((event, data) => {
+                log(`(${socket.id}) Emitting event: ${event} with args: ${JSON.stringify(data)}`);
+            });
+            for (const [eventName, handler] of events)
+                socket.on(eventName, (data) => handler(socket, data ?? null));
+            for (const handler of connectionhandlers)
+                handler(socket, null);
+        });
+    };
+}
+export default ioPlugin;
+export { ioPlugin };

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+import '@steijnveer/file-based-router/utils';
+import type { Server as IoServer, Socket as IoSocket } from 'socket.io';
+type IoPluginConfig = {
+    eventsDir?: string;
+    extensions?: string[];
+};
+type EventsMap = Record<string, (data?: any) => void>;
+type Io<SocketData = any> = IoServer<EventsMap, EventsMap, never, SocketData>;
+type Socket<SocketData = any> = IoSocket<EventsMap, EventsMap, never, SocketData>;
+declare module '@steijnveer/file-based-router' {
+    interface Server {
+        _io: Io;
+    }
+}
+export type { EventsMap, Io, IoPluginConfig, Socket };
+//# 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":"AAAA,OAAO,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAExE,KAAK,cAAc,GAAG;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC,CAAC;AAEtD,KAAK,EAAE,CAAC,UAAU,GAAG,GAAG,IAAI,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AAE9E,KAAK,MAAM,CAAC,UAAU,GAAG,GAAG,IAAI,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AAElF,OAAO,QAAQ,+BAA+B,CAAC;IAC7C,UAAU,MAAM;QACd,GAAG,EAAE,EAAE,CAAC;KACT;CACF;AAGD,YAAY,EAAE,SAAS,EAAE,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+import '@steijnveer/file-based-router/utils';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "author": "Steijn Veer",
+  "dependencies": {
+    "@steijnveer/file-based-router": "^0.0.9",
+    "socket.io": "^4.8.3"
+  },
+  "description": "fbr plugin: Socket.io integration",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.10.1",
+    "@types/socket.io": "^3.0.1",
+    "typescript": "~5.9.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "fbr",
+    "io",
+    "socket.io",
+    "file-based",
+    "plugin",
+    "typescript",
+    "websocket"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "name": "@steijnveer/fbr-plugin-io",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.0.1"
+}