@hackthedev/socket-tools 1.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,69 @@
+# Socket Toolbox
+
+This small and awesome library was made to simplify a basic socket.io setup by using an existing express server. In this example the express server will be setup with the [express-starter](#) library. The library will scan a directory for files that include socket.io handlers to keep everything modular without pain. Files inside the scanned directory that do not have the required socket handler block will fail to load and cause an error.
+
+```js
+import ExpressStarter from "@hackthedev/express-starter"
+import SocketTools from "@hackthedev/socket-tools"
+
+// express setup
+let starter = new ExpressStarter()
+starter.registerErrorHandlers();
+starter.registerTemplateMiddleware();
+starter.app.use(starter.express.static(starter.dirname + "/public"));
+starter.startHttpServer(5000);
+
+// Socket.io Setup
+let socketTools = new SocketTools({expressHttpServer: starter.server});
+socketTools.listen();
+```
+
+------
+
+## Setting up socket events
+
+On default the socket library will recursively scan for `.mjs` files inside the `./modules/sockets` folder relative from what `process.cwd()` returns. These files at a very minimum are required to have this structure:
+
+```js
+export default (io) => (socket) => {
+    socket.on('hello', function (data, response) {
+        response({ error: null, message: "Hi " + data.name })
+    });
+}
+```
+
+You can define multiple socket events and even functions inside or outside of the required `export default (io) => (socket) => {}`  block. You can do literally anything as long as the required block is present, because otherwise it will abort loading that file and logging it as error.
+
+```js
+function getLeftMessage(){
+    return ", have a great time!";
+}
+
+export default (io) => (socket) => {
+    socket.on('hello', function (data, response) {
+        response({ error: null, message: "Hi " + data.name })
+    });
+    
+    socket.on('bye', function (data, response) {
+        response({ error: null, message: "Bye " + data.name + getLeftMessage() })
+    });
+}
+```
+
+------
+
+## Custom sockets directory
+
+You can also specify a custom directory path to scan that for files instead. The default will always be `path.join(process.cwd(), "modules/sockets")`
+
+```js
+let socketTools = new SocketTools({expressHttpServer: starter.server, modulesDir: path.join(process.cwd(), "sockets")});
+```
+
+------
+
+## Non-socket files in scan directory
+
+If you have files inside the "scan directory" aka `modulesDir` then you can add the following line to the file to avoid the socket toolbox from reporting errors: `export default (io) => (socket) => {}`
+
+By leaving it empty it wont have any real effect and avoids errors and possible crashes.

package/bun.lock

@@ -0,0 +1,57 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "dependencies": {
+        "@hackthedev/terminal-logger": "^1.0.0",
+        "socket.io": "^4.8.3",
+      },
+    },
+  },
+  "packages": {
+    "@hackthedev/terminal-logger": ["@hackthedev/terminal-logger@1.0.0", "", {}, "sha512-n2SiSpJXCCbFJwgyzR94aDkgelTsK0CG7Ruh6W0n05D5oAm8wZz8F1+0SCJISf2L0/lhTD39zeNxGRVYse8EKA=="],
+
+    "@socket.io/component-emitter": ["@socket.io/component-emitter@3.1.2", "", {}, "sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA=="],
+
+    "@types/cors": ["@types/cors@2.8.19", "", { "dependencies": { "@types/node": "*" } }, "sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg=="],
+
+    "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
+
+    "accepts": ["accepts@1.3.8", "", { "dependencies": { "mime-types": "~2.1.34", "negotiator": "0.6.3" } }, "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw=="],
+
+    "base64id": ["base64id@2.0.0", "", {}, "sha512-lGe34o6EHj9y3Kts9R4ZYs/Gr+6N7MCaMlIFA3F1R2O5/m7K06AxfSeO5530PEERE6/WyEg3lsuyw4GHlPZHog=="],
+
+    "cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
+    "cors": ["cors@2.8.5", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "engine.io": ["engine.io@6.6.5", "", { "dependencies": { "@types/cors": "^2.8.12", "@types/node": ">=10.0.0", "accepts": "~1.3.4", "base64id": "2.0.0", "cookie": "~0.7.2", "cors": "~2.8.5", "debug": "~4.4.1", "engine.io-parser": "~5.2.1", "ws": "~8.18.3" } }, "sha512-2RZdgEbXmp5+dVbRm0P7HQUImZpICccJy7rN7Tv+SFa55pH+lxnuw6/K1ZxxBfHoYpSkHLAO92oa8O4SwFXA2A=="],
+
+    "engine.io-parser": ["engine.io-parser@5.2.3", "", {}, "sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q=="],
+
+    "mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
+
+    "mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "negotiator": ["negotiator@0.6.3", "", {}, "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg=="],
+
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "socket.io": ["socket.io@4.8.3", "", { "dependencies": { "accepts": "~1.3.4", "base64id": "~2.0.0", "cors": "~2.8.5", "debug": "~4.4.1", "engine.io": "~6.6.0", "socket.io-adapter": "~2.5.2", "socket.io-parser": "~4.2.4" } }, "sha512-2Dd78bqzzjE6KPkD5fHZmDAKRNe3J15q+YHDrIsy9WEkqttc7GY+kT9OBLSMaPbQaEd0x1BjcmtMtXkfpc+T5A=="],
+
+    "socket.io-adapter": ["socket.io-adapter@2.5.6", "", { "dependencies": { "debug": "~4.4.1", "ws": "~8.18.3" } }, "sha512-DkkO/dz7MGln0dHn5bmN3pPy+JmywNICWrJqVWiVOyvXjWQFIv9c2h24JrQLLFJ2aQVQf/Cvl1vblnd4r2apLQ=="],
+
+    "socket.io-parser": ["socket.io-parser@4.2.5", "", { "dependencies": { "@socket.io/component-emitter": "~3.1.0", "debug": "~4.4.1" } }, "sha512-bPMmpy/5WWKHea5Y/jYAP6k74A+hvmRCQaJuJB6I/ML5JZq/KfNieUVo/3Mh7SAqn7TyFdIo6wqYHInG1MU1bQ=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
+    "ws": ["ws@8.18.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg=="],
+  }
+}

package/index.mjs

@@ -0,0 +1,109 @@
+import {Server} from "socket.io";
+import {pathToFileURL} from "url";
+import Logger from "@hackthedev/terminal-logger";
+import path from "path";
+import fs from "fs";
+
+export default class SocketTools {
+    constructor({
+                    expressHttpServer,
+                    maxHttpBufferSize,
+                    pingInterval,
+                    pingTimeout,
+                    modulesDir,
+                    cors = {}
+                } = {}) {
+
+        if (!expressHttpServer) throw new Error("SocketTools: expressHttpServer is required");
+        if (!maxHttpBufferSize) maxHttpBufferSize = 1e8;
+        if (!pingInterval) pingInterval = 25000;
+        if (!pingTimeout) pingTimeout = 60000;
+        if (!modulesDir) modulesDir = path.join(process.cwd(), "modules/sockets");
+
+        if (!cors?.origin) cors.origin = "*";
+        if (!cors?.methods) cors.methods = ["GET", "POST"];
+        if (!cors?.credentials) cors.credentials = false;
+
+        this.socketHandlers = [];
+        this.activeSockets = new Map();
+
+        this.io = new Server(expressHttpServer, {
+            maxHttpBufferSize,
+            secure: true,
+            pingInterval,
+            pingTimeout,
+            cors
+        });
+
+        this.loadSocketHandlers(this.modulesDir);
+    }
+
+    listen({
+               onDisconnect = null,
+               onConnection = null
+           } = {}) {
+
+        this.io.on("connection", async (socket) => {
+
+            this.registerSocketEvents(socket);
+            socket.on("disconnect", () => {
+
+            })
+        })
+    }
+
+    async loadSocketHandlers(mainHandlersDir) {
+        const fileList = [];
+
+        const scanDir = (dir) => {
+            const files = fs.readdirSync(dir, {withFileTypes: true});
+            for (const file of files) {
+                const filePath = path.join(dir, file.name);
+                if (file.isDirectory()) {
+                    scanDir(filePath);
+                }
+                else if (file.name.endsWith(".mjs")) {
+                    fileList.push(filePath);
+                }
+            }
+        };
+
+        scanDir(mainHandlersDir);
+
+        for (const filePath of fileList) {
+            const fileUrl = pathToFileURL(filePath).href;
+            try {
+                const {default: handlerFactory} = await import(fileUrl);
+                const handler = handlerFactory(this.io);
+
+                if (typeof handler === "function") {
+                    this.socketHandlers.push(handler);
+                    Logger.debug(`Preloaded socket handler: ${filePath}`);
+                }
+                else {
+                    Logger.warn(`Ignored invalid socket handler in ${filePath}`);
+                }
+            } catch (err) {
+                Logger.error(`Error importing socket handler: ${fileUrl}`);
+                Logger.error(err);
+            }
+        }
+    }
+
+    registerSocketEvents(socket) {
+        try {
+            const attachedHandlers = [];
+
+            for (const handler of this.socketHandlers) {
+                const cleanup = handler(socket);
+                if (typeof cleanup === "function") {
+                    attachedHandlers.push(cleanup);
+                }
+            }
+
+            this.activeSockets.set(socket.id, attachedHandlers);
+        } catch (err) {
+            console.error("Error registering socket events:", err);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hackthedev/socket-tools",
+  "version": "1.0.1",
+  "description": "This small and awesome library was made to simplify a basic socket.io setup by using an existing express server. In this example the express server will be setup with the [express-starter](#) library. The library will scan a directory for files that include socket.io handlers to keep everything modular without pain. Files inside the scanned directory that do not have the required socket handler block will fail to load and cause an error.",
+  "license": "ISC",
+  "author": "",
+  "main": "index.mjs",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@hackthedev/terminal-logger": "^1.0.0",
+    "socket.io": "^4.8.3"
+  }
+}