Initial commit と༼ ◕_◕ と ༽

Author: koistya

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This library `bun-ws-router` is a WebSocket router for Bun implemented in TypeScript. It provides a simple and efficient way to handle WebSocket connections and route messages to different handlers based on the message type. It's intended to be used together with Zod-based validation for message types.

.gitignore

@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "always"
+  },
+  "editor.tabSize": 2
+}

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025-present Konstantin Tarkus, Kriasoft (hello@kriasoft.com)
+
+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.

README.md

@@ -0,0 +1,211 @@
+# Bun WebSocket Router
+
+A type-safe WebSocket router for Bun with Zod-based message validation. Route WebSocket messages to handlers based on message type with full TypeScript support.
+
+### Key Features
+
+- **Type-safe messaging**: Built-in validation using Zod schemas
+- **Simple API**: Intuitive routing system for WebSocket messages
+- **Performance**: Leverages Bun's native WebSocket implementation
+- **Flexible**: Works with any Bun server setup, including Hono
+- **Room support**: Easily group clients and broadcast messages
+- **Lightweight**: Minimal dependencies for fast startup
+
+Perfect for real-time applications like chat systems, live dashboards, multiplayer games, and notification services.
+
+## Installation
+
+```bash
+bun add bun-ws-router zod
+```
+
+## Getting Started
+
+The following example demonstrates how to set up a Bun server with both (RESTful) HTTP and WebSocket routers.
+
+```ts
+import { Hono } from "hono";
+import { WebSocketRouter } from "bun-ws-router";
+import { exampleRouter } from "./example";
+
+// HTTP router
+const app = new Hono();
+app.get("/", (c) => c.text("Welcome to Hono!"));
+
+// WebSocket router
+const ws = new WebSocketRouter();
+ws.addRoutes(exampleRouter); // Add routes from another file
+
+Bun.serve({
+  port: 3000,
+
+  fetch(req, server) {
+    const url = new URL(req.url);
+
+    // Handle WebSocket upgrade requests
+    if (url.pathname === "/ws") {
+      return ws.upgrade(req, {
+        server,
+      });
+    }
+
+    // Handle regular HTTP requests
+    return app.fetch(req, { server });
+  },
+
+  // Handle WebSocket connections
+  websocket: ws.websocket,
+});
+
+console.log(`WebSocket server listening on ws://localhost:3000/ws`);
+```
+
+## How to handle authentication
+
+You can handle authentication by checking the `Authorization` header for a JWT token or any other authentication method you prefer. The following example demonstrates how to verify a JWT token and pass the user information to the WebSocket router.
+
+```ts
+import { WebSocketRouter } from "bun-ws-router";
+import { DecodedIdToken } from "firebase-admin/auth";
+import { verifyIdToken } from "./auth"; // Your authentication logic
+
+type Meta = {
+  user?: DecodedIdToken | null;
+};
+
+// WebSocket router
+const ws = new WebSocketRouter<Meta>();
+
+Bun.serve({
+  port: 3000,
+
+  async fetch(req, server) {
+    const url = new URL(req.url);
+
+    // Check if the user is authenticated
+    const user = await verifyToken(req);
+
+    // Handle WebSocket upgrade requests
+    if (url.pathname === "/ws") {
+      return ws.upgrade(req, {
+        server,
+        data: { user },
+      });
+    }
+
+    // Handle regular HTTP requests
+    return await app.fetch(req, { server, user });
+  },
+
+  // Handle WebSocket connections
+  websocket: ws.websocket,
+});
+```
+
+The `verifyIdToken` function is a placeholder for your authentication logic which could use user ID token verification from `firebase-admin` or any other authentication library.
+
+## How to define message types
+
+You can define message types using the `messageSchema` function from `bun-ws-router`. This function takes a message type name such as `JOIN_ROOM`, `SEND_MESSAGE` etc. and a Zod schema for the message payload. The following example demonstrates how to define message types for a chat application.
+
+```ts
+import { messageSchema } from "bun-ws-router";
+import { z } from "zod";
+
+export const JoinRoom = messageSchema("JOIN_ROOM", {
+  roomId: z.string(),
+});
+
+export const UserJoined = messageSchema("USER_JOINED", {
+  roomId: z.string(),
+  userId: z.string(),
+});
+
+export const UserLeft = messageSchema("USER_LEFT", {
+  userId: z.string(),
+});
+
+export const SendMessage = messageSchema("SEND_MESSAGE", {
+  roomId: z.string(),
+  message: z.string(),
+});
+```
+
+## How to define routes
+
+You can define routes using the `WebSocketRouter` instance methods: `onOpen`, `onMessage`, and `onClose`.
+
+```ts
+import { WebSocketRouter } from "bun-ws-router";
+import { Meta, JoinRoom, UserJoined, SendMessage, UserLeft } from "./schema";
+
+const ws = new WebSocketRouter<Meta>();
+
+// Handle new connections
+ws.onOpen((c) => {
+  console.log(
+    `Client connected: ${c.ws.data.clientId}, User ID: ${c.ws.data.userId}`
+  );
+  // You could send a welcome message here
+});
+
+// Handle specific message types
+ws.onMessage(JoinRoom, (c) => {
+  const { roomId } = c.payload;
+  const userId = c.ws.data.userId || c.ws.data.clientId; // Use userId if available, else clientId
+  c.ws.data.roomId = roomId; // Store room in connection data
+  console.log(`User ${userId} joining room: ${roomId}`);
+
+  // Example: Send confirmation back or broadcast to room
+  // This requires implementing broadcast/room logic separately
+  // c.send(UserJoined, { roomId, userId });
+});
+
+ws.onMessage(SendMessage, (c) => {
+  const { message } = c.payload;
+  const userId = c.ws.data.userId || c.ws.data.clientId;
+  const roomId = c.ws.data.roomId;
+  console.log(`Message in room ${roomId} from ${userId}: ${message}`);
+  // Add logic to broadcast message to others in the room
+});
+
+// Handle disconnections
+ws.onClose((c) => {
+  const userId = c.ws.data.userId || c.ws.data.clientId;
+  console.log(`Client disconnected: ${userId}, code: ${c.code}`);
+  // Example: Notify others in the room the user left
+  // This requires implementing broadcast/room logic separately
+  // broadcast(c.ws.data.roomId, UserLeft, { userId });
+});
+```
+
+**Note:** The `c.send(...)` function sends a message back to the _current_ client.
+
+## How to compose routes
+
+You can compose routes from different files into a single router. This is useful for organizing your code and keeping related routes together.
+
+```ts
+import { WebSocketRouter } from "bun-ws-router";
+import { Meta } from "./schemas";
+import { chatRoutes } from "./chat";
+import { notificationRoutes } from "./notification";
+
+const ws = new WebSocketRouter<Meta>();
+ws.addRoutes(chatRoutes);
+ws.addRoutes(notificationRoutes);
+```
+
+Where `chatRoutes` and `notificationRoutes` are other router instances defined in separate files.
+
+## Support
+
+Feel free to discuss any issues or suggestions on our [Discord](https://discord.com/invite/bSsv7XM) channel. We welcome contributions and feedback from the community.
+
+## Backers
+
+<a href="https://reactstarter.com/b/1"><img src="https://reactstarter.com/b/1.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/2"><img src="https://reactstarter.com/b/2.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/3"><img src="https://reactstarter.com/b/3.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/4"><img src="https://reactstarter.com/b/4.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/5"><img src="https://reactstarter.com/b/5.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/6"><img src="https://reactstarter.com/b/6.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/7"><img src="https://reactstarter.com/b/7.png" height="60" /></a>&nbsp;&nbsp;<a href="https://reactstarter.com/b/8"><img src="https://reactstarter.com/b/8.png" height="60" /></a>
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

bun.lock

@@ -0,0 +1,38 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "bun-ws-router",
+      "dependencies": {
+        "uuid": "^11.1.0",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.2.10",
+        "hono": "^4.7.7",
+        "typescript": "^5.8.3",
+        "zod": "^3.24.3",
+      },
+      "peerDependencies": {
+        "@types/bun": ">=1.2.0",
+        "zod": ">=3.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.10", "", { "dependencies": { "bun-types": "1.2.10" } }, "sha512-eilv6WFM3M0c9ztJt7/g80BDusK98z/FrFwseZgT4bXCq2vPhXD4z8R3oddmAn+R/Nmz9vBn4kweJKmGTZj+lg=="],
+
+    "@types/node": ["@types/node@22.15.2", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-uKXqKN9beGoMdBfcaTY1ecwz6ctxuJAcUlwE55938g0ZJ8lRxwAZqRz2AJ4pzpt5dHdTPMB863UZ0ESiFUcP7A=="],
+
+    "bun-types": ["bun-types@1.2.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-b5ITZMnVdf3m1gMvJHG+gIfeJHiQPJak0f7925Hxu6ZN5VKA8AGy4GZ4lM+Xkn6jtWxg5S3ldWvfmXdvnkp3GQ=="],
+
+    "hono": ["hono@4.7.7", "", {}, "sha512-2PCpQRbN87Crty8/L/7akZN3UyZIAopSoRxCwRbJgUuV1+MHNFHzYFxZTg4v/03cXUm+jce/qa2VSBZpKBm3Qw=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+    "uuid": ["uuid@11.1.0", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A=="],
+
+    "zod": ["zod@3.24.3", "", {}, "sha512-HhY1oqzWCQWuUqvBFnsyrtZRhyPeR7SUGv+C4+MsisMuVfSPx8HpwWqH8tRahSlt6M3PiFAcoeFhZAqIXTxoSg=="],
+  }
+}

example/example.ts

@@ -0,0 +1,20 @@
+import { WebSocketRouter } from "../router";
+import { JoinRoomSchema, UserJoinedSchema } from "./schema";
+
+const ws = new WebSocketRouter();
+
+ws.onMessage(JoinRoomSchema, (c) => {
+  const { roomId } = c.payload;
+  console.log(`User joined room: ${roomId}`);
+
+  c.send(UserJoinedSchema, {
+    roomId,
+    userId: c.meta.clientId,
+  });
+});
+
+ws.onClose((c) => {
+  console.log(`Connection closed`);
+});
+
+export { ws as exampleRouter };

example/index.ts

@@ -0,0 +1,30 @@
+import { Hono } from "hono";
+import { WebSocketRouter } from "../index";
+import { exampleRouter } from "./example";
+
+// HTTP router
+const app = new Hono();
+app.get("/", (c) => c.text("Welcome to Hono!"));
+
+// WebSocket router
+const ws = new WebSocketRouter();
+ws.addRoutes(exampleRouter);
+
+Bun.serve({
+  port: 3000,
+
+  fetch(req, server) {
+    const url = new URL(req.url);
+
+    // Handle WebSocket upgrade requests
+    if (url.pathname === "/ws") {
+      return ws.upgrade(req, { server });
+    }
+
+    // Handle regular HTTP requests
+    return app.fetch(req, { server });
+  },
+
+  // Handle WebSocket connections
+  websocket: ws.websocket,
+});

example/schema.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { MessageSchema } from "../schema";
+
+export const JoinRoomSchema = MessageSchema.extend({
+  type: z.literal("JOIN_ROOM"),
+  payload: z.object({
+    roomId: z.string(),
+  }),
+});
+
+export const UserJoinedSchema = MessageSchema.extend({
+  type: z.literal("USER_JOINED"),
+  payload: z.object({
+    roomId: z.string(),
+    userId: z.string().optional(),
+  }),
+});

handlers.ts

@@ -0,0 +1,10 @@
+/* SPDX-FileCopyrightText: 2025-present Kriasoft */
+/* SPDX-License-Identifier: MIT */
+
+import type { CloseHandler, MessageHandlerEntry, OpenHandler } from "./types";
+
+export class WebSocketHandlers<T = any> {
+  public readonly open: OpenHandler<T>[] = [];
+  public readonly close: CloseHandler<T>[] = [];
+  public readonly message = new Map<string, MessageHandlerEntry>();
+}