@iskra-bun/socket-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @iskra-bun/socket-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release.

package/README.md

@@ -0,0 +1,31 @@
+# @iskra-bun/socket-kit
+
+WebSocket nativo de Bun para Iskra, con router de mensajes y broadcast por topics.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/socket-kit @iskra-bun/core
+```
+
+## Uso rapido
+
+```typescript
+import { App } from '@iskra-bun/core'
+import { SocketDriver } from '@iskra-bun/socket-kit'
+
+const app = new App({ name: 'mi-app' })
+app.register(new SocketDriver({ port: 3001 }))
+
+await app.start()
+```
+
+Define rutas de mensajes con el `SocketRouter` y emite a topics con broadcast; ver la guia para el protocolo.
+
+## Documentacion
+
+Guia completa: [docs/socket-kit.md](../../docs/socket-kit.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { Context, Driver, App, IskraError } from '@iskra-bun/core';
+import { ServerWebSocket } from 'bun';
+
+interface SocketContext<T = any> extends Context<T> {
+    socket: ServerWebSocket<any>;
+    broadcast(event: string, payload: any): void;
+}
+type SocketHandler = (ctx: SocketContext) => Promise<void> | void;
+declare class SocketRouter {
+    private handlers;
+    on(event: string, handler: SocketHandler): this;
+    getHandler(event: string): SocketHandler | undefined;
+}
+
+declare class SocketDriver implements Driver {
+    name: string;
+    private app;
+    private router;
+    private port;
+    private runningServer;
+    constructor(options?: {
+        port?: number;
+        router?: SocketRouter;
+    });
+    init(app: App): void;
+    start(): void;
+    broadcast(event: string, payload: any): void;
+    stop(): void;
+    private handleMessage;
+}
+
+declare class SocketConnectionError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+declare class SocketMessageError extends IskraError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+
+export { SocketConnectionError, type SocketContext, SocketDriver, SocketMessageError, SocketRouter };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/router.ts
+var SocketRouter = class {
+  handlers = /* @__PURE__ */ new Map();
+  on(event, handler) {
+    this.handlers.set(event, handler);
+    return this;
+  }
+  getHandler(event) {
+    return this.handlers.get(event);
+  }
+};
+
+// src/errors.ts
+import { IskraError, ErrorCodes } from "@iskra-bun/core";
+var SocketConnectionError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.SOCKET_CONNECTION_ERROR, ...options });
+    this.name = "SocketConnectionError";
+  }
+};
+var SocketMessageError = class extends IskraError {
+  constructor(message, options) {
+    super(message, { code: ErrorCodes.SOCKET_MESSAGE_ERROR, ...options });
+    this.name = "SocketMessageError";
+  }
+};
+
+// src/driver.ts
+var SocketDriver = class {
+  name = "SocketDriver";
+  app = null;
+  router;
+  port;
+  runningServer;
+  constructor(options = {}) {
+    this.port = options.port || 3001;
+    this.router = options.router || new SocketRouter();
+  }
+  init(app) {
+    this.app = app;
+  }
+  start() {
+    this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);
+    this.runningServer = Bun.serve({
+      port: this.port,
+      fetch(req, server) {
+        if (server.upgrade(req)) {
+          return;
+        }
+        return new Response("Upgrade failed", { status: 500 });
+      },
+      websocket: {
+        open: (ws) => {
+          this.app?.logger.debug("Socket connected");
+          ws.subscribe("global");
+          this.app?.emit("socket:connected", { id: ws.remoteAddress });
+        },
+        message: async (ws, message) => {
+          await this.handleMessage(ws, message);
+        },
+        close: (ws) => {
+          ws.unsubscribe("global");
+          this.app?.logger.debug("Socket disconnected");
+        }
+      }
+    });
+  }
+  broadcast(event, payload) {
+    if (this.runningServer) {
+      this.runningServer.publish("global", JSON.stringify({ event, payload }));
+    }
+  }
+  stop() {
+    if (this.runningServer) {
+      this.runningServer.stop();
+    }
+    this.app?.logger.info("SocketDriver stopped");
+  }
+  async handleMessage(ws, message) {
+    try {
+      const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+      const eventData = JSON.parse(text);
+      const { event, payload } = eventData;
+      if (!event) return;
+      const handler = this.router.getHandler(event);
+      if (handler && this.app) {
+        await handler({
+          app: this.app,
+          logger: this.app.logger.child({ source: "socket", event }),
+          payload: payload || {},
+          socket: ws,
+          reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),
+          broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data))
+          // Publish to topic/channel logic needed? Or just broadcast
+        });
+      } else {
+        this.app?.emit(`socket:${event}`, { socket: ws, payload });
+      }
+    } catch (err) {
+      const socketErr = new SocketMessageError("Failed to handle socket message", {
+        cause: err instanceof Error ? err : new Error(String(err))
+      });
+      this.app?.logger.error({ err: socketErr }, socketErr.message);
+    }
+  }
+};
+export {
+  SocketConnectionError,
+  SocketDriver,
+  SocketMessageError,
+  SocketRouter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/router.ts","../src/errors.ts","../src/driver.ts"],"sourcesContent":["import type { App, Context } from '@iskra-bun/core';\nimport type { ServerWebSocket } from 'bun';\n\nexport interface SocketContext<T = any> extends Context<T> {\n    socket: ServerWebSocket<any>;\n    broadcast(event: string, payload: any): void;\n}\n\nexport type SocketHandler = (ctx: SocketContext) => Promise<void> | void;\n\nexport class SocketRouter {\n    private handlers: Map<string, SocketHandler> = new Map();\n\n    on(event: string, handler: SocketHandler) {\n        this.handlers.set(event, handler);\n        return this;\n    }\n\n    getHandler(event: string): SocketHandler | undefined {\n        return this.handlers.get(event);\n    }\n}\n","import { IskraError, ErrorCodes } from '@iskra-bun/core';\n\n// ─── Socket Connection Error ─────────────────────────────────────────────────\n\nexport class SocketConnectionError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_CONNECTION_ERROR, ...options });\n        this.name = 'SocketConnectionError';\n    }\n}\n\n// ─── Socket Message Error ────────────────────────────────────────────────────\n\nexport class SocketMessageError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_MESSAGE_ERROR, ...options });\n        this.name = 'SocketMessageError';\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport { SocketRouter } from './router';\nimport type { ServerWebSocket } from 'bun';\nimport { SocketMessageError } from './errors';\n\nexport class SocketDriver implements Driver {\n    name = 'SocketDriver';\n    private app: App | null = null;\n    private router: SocketRouter;\n    private port: number;\n    private runningServer: any;\n\n    constructor(options: { port?: number; router?: SocketRouter } = {}) {\n        this.port = options.port || 3001;\n        this.router = options.router || new SocketRouter();\n    }\n\n    init(app: App) {\n        this.app = app;\n    }\n\n    start() {\n        this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);\n\n        this.runningServer = Bun.serve({\n            port: this.port,\n            fetch(req, server) {\n                // Upgrade logic\n                if (server.upgrade(req)) {\n                    return; // Bun handles the rest\n                }\n                return new Response(\"Upgrade failed\", { status: 500 });\n            },\n            websocket: {\n                open: (ws) => {\n                    this.app?.logger.debug('Socket connected');\n                    ws.subscribe('global');\n                    this.app?.emit('socket:connected', { id: ws.remoteAddress });\n                },\n                message: async (ws, message) => {\n                    await this.handleMessage(ws, message);\n                },\n                close: (ws) => {\n                    ws.unsubscribe('global');\n                    this.app?.logger.debug('Socket disconnected');\n                }\n            }\n        });\n    }\n\n    public broadcast(event: string, payload: any) {\n        if (this.runningServer) {\n            this.runningServer.publish('global', JSON.stringify({ event, payload }));\n        }\n    }\n\n    stop() {\n        if (this.runningServer) {\n            this.runningServer.stop();\n        }\n        this.app?.logger.info('SocketDriver stopped');\n    }\n\n    private async handleMessage(ws: ServerWebSocket<any>, message: string | Buffer) {\n        try {\n            const text = typeof message === 'string' ? message : new TextDecoder().decode(message);\n            const eventData = JSON.parse(text);\n            const { event, payload } = eventData;\n\n            if (!event) return;\n\n            // 1. Try Router\n            const handler = this.router.getHandler(event);\n            if (handler && this.app) {\n                await handler({\n                    app: this.app,\n                    logger: this.app.logger.child({ source: 'socket', event }),\n                    payload: payload || {},\n                    socket: ws,\n                    reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),\n                    broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data)) // Publish to topic/channel logic needed? Or just broadcast\n                });\n            } else {\n                // 2. Fallback to Global App Event\n                this.app?.emit(`socket:${event}`, { socket: ws, payload });\n            }\n\n        } catch (err) {\n            const socketErr = new SocketMessageError('Failed to handle socket message', {\n                cause: err instanceof Error ? err : new Error(String(err)),\n            });\n            this.app?.logger.error({ err: socketErr }, socketErr.message);\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@iskra-bun/socket-kit",
+    "version": "0.1.0",
+    "description": "WebSocket nativo de Bun para Iskra, con router y broadcast.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "typescript",
+        "websocket",
+        "realtime",
+        "broadcast"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/socket-kit"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/socket-kit#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "@iskra-bun/core": "0.1.0"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.5",
+        "@types/node": "^22.10.2"
+    }
+}

package/src/driver.ts

@@ -0,0 +1,95 @@
+import type { App, Driver } from '@iskra-bun/core';
+import { SocketRouter } from './router';
+import type { ServerWebSocket } from 'bun';
+import { SocketMessageError } from './errors';
+
+export class SocketDriver implements Driver {
+    name = 'SocketDriver';
+    private app: App | null = null;
+    private router: SocketRouter;
+    private port: number;
+    private runningServer: any;
+
+    constructor(options: { port?: number; router?: SocketRouter } = {}) {
+        this.port = options.port || 3001;
+        this.router = options.router || new SocketRouter();
+    }
+
+    init(app: App) {
+        this.app = app;
+    }
+
+    start() {
+        this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);
+
+        this.runningServer = Bun.serve({
+            port: this.port,
+            fetch(req, server) {
+                // Upgrade logic
+                if (server.upgrade(req)) {
+                    return; // Bun handles the rest
+                }
+                return new Response("Upgrade failed", { status: 500 });
+            },
+            websocket: {
+                open: (ws) => {
+                    this.app?.logger.debug('Socket connected');
+                    ws.subscribe('global');
+                    this.app?.emit('socket:connected', { id: ws.remoteAddress });
+                },
+                message: async (ws, message) => {
+                    await this.handleMessage(ws, message);
+                },
+                close: (ws) => {
+                    ws.unsubscribe('global');
+                    this.app?.logger.debug('Socket disconnected');
+                }
+            }
+        });
+    }
+
+    public broadcast(event: string, payload: any) {
+        if (this.runningServer) {
+            this.runningServer.publish('global', JSON.stringify({ event, payload }));
+        }
+    }
+
+    stop() {
+        if (this.runningServer) {
+            this.runningServer.stop();
+        }
+        this.app?.logger.info('SocketDriver stopped');
+    }
+
+    private async handleMessage(ws: ServerWebSocket<any>, message: string | Buffer) {
+        try {
+            const text = typeof message === 'string' ? message : new TextDecoder().decode(message);
+            const eventData = JSON.parse(text);
+            const { event, payload } = eventData;
+
+            if (!event) return;
+
+            // 1. Try Router
+            const handler = this.router.getHandler(event);
+            if (handler && this.app) {
+                await handler({
+                    app: this.app,
+                    logger: this.app.logger.child({ source: 'socket', event }),
+                    payload: payload || {},
+                    socket: ws,
+                    reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),
+                    broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data)) // Publish to topic/channel logic needed? Or just broadcast
+                });
+            } else {
+                // 2. Fallback to Global App Event
+                this.app?.emit(`socket:${event}`, { socket: ws, payload });
+            }
+
+        } catch (err) {
+            const socketErr = new SocketMessageError('Failed to handle socket message', {
+                cause: err instanceof Error ? err : new Error(String(err)),
+            });
+            this.app?.logger.error({ err: socketErr }, socketErr.message);
+        }
+    }
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+import { IskraError, ErrorCodes } from '@iskra-bun/core';
+
+// ─── Socket Connection Error ─────────────────────────────────────────────────
+
+export class SocketConnectionError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.SOCKET_CONNECTION_ERROR, ...options });
+        this.name = 'SocketConnectionError';
+    }
+}
+
+// ─── Socket Message Error ────────────────────────────────────────────────────
+
+export class SocketMessageError extends IskraError {
+    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {
+        super(message, { code: ErrorCodes.SOCKET_MESSAGE_ERROR, ...options });
+        this.name = 'SocketMessageError';
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { SocketDriver } from './driver';
+export { SocketRouter, type SocketContext } from './router';
+export * from './errors';

package/src/router.ts

@@ -0,0 +1,22 @@
+import type { App, Context } from '@iskra-bun/core';
+import type { ServerWebSocket } from 'bun';
+
+export interface SocketContext<T = any> extends Context<T> {
+    socket: ServerWebSocket<any>;
+    broadcast(event: string, payload: any): void;
+}
+
+export type SocketHandler = (ctx: SocketContext) => Promise<void> | void;
+
+export class SocketRouter {
+    private handlers: Map<string, SocketHandler> = new Map();
+
+    on(event: string, handler: SocketHandler) {
+        this.handlers.set(event, handler);
+        return this;
+    }
+
+    getHandler(event: string): SocketHandler | undefined {
+        return this.handlers.get(event);
+    }
+}