@ndiinginc/router 0.0.0-stage → 4.0.0

package/.gitattributes

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ridho Prasetya
+
+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.

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+# @ndiinginc/router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Router HTTP kecil, cepat, dan **zero-dependency** untuk Node.js. Dibangun langsung di atas `node:http`, dengan routing berbasis tree, nested router, middleware async, error handler, dan JSON body parser bawaan.
+
+## Fitur
+
+- Zero dependency, murni `node:http`
+- Routing berbasis tree per segment (static match diprioritaskan, lalu dynamic)
+- Parameter dinamis `:id` dan wildcard `*`
+- Nested router dengan `use(path, router)`
+- Middleware global dan per-path, mendukung `async`
+- Error handler dengan signature `(err, req, res)`
+- `req.path`, `req.query`, `req.params`, `req.body`
+- Helper `res.send()` dan `res.json()`
+- JSON body parser dengan limit ukuran dan proteksi prototype pollution
+- Semua HTTP method, termasuk `QUERY`
+
+## Instalasi
+
+```bash
+npm install @ndiinginc/router
+```
+
+Butuh **Node.js 22.1+** (memakai `URL.parse`).
+
+## Quick Start
+
+```js
+const Router = require("@ndiinginc/router");
+
+const app = new Router();
+
+app.get("/", (req, res) => {
+    res.json({ hello: "world" });
+});
+
+app.get("/users/:id", (req, res) => {
+    res.json({ id: req.params.id });
+});
+
+app.listen(3000);
+```
+
+## Routing
+
+Semua method mengembalikan `this`, jadi bisa di-chain.
+
+```js
+app.get("/users", handler)
+   .post("/users", handler)
+   .put("/users/:id", handler)
+   .patch("/users/:id", handler)
+   .delete("/users/:id", handler);
+```
+
+Method yang tersedia: `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `trace`, `connect`, `query`, dan `use` (semua method).
+
+### Parameter dinamis
+
+```js
+app.get("/posts/:postId/comments/:commentId", (req, res) => {
+    const { postId, commentId } = req.params;
+    res.json({ postId, commentId });
+});
+```
+
+### Wildcard
+
+`*` cocok dengan karakter apa pun di dalam satu segmen.
+
+```js
+app.get("/files/report-*", (req, res) => {
+    res.json({ path: req.path });
+});
+```
+
+### Prioritas match
+
+Untuk setiap segmen, router mencoba **static match dulu**, baru pattern dinamis. Jadi `/users/me` menang atas `/users/:id` bila keduanya terdaftar.
+
+## Middleware
+
+Middleware didaftarkan dengan `use()` dan dijalankan **berurutan sesuai urutan pendaftaran**.
+
+```js
+// Global
+app.use((req, res) => {
+    console.log(req.method, req.path);
+});
+
+// Scoped: jalan untuk /admin dan semua sub-path-nya
+app.use("/admin", async (req, res) => {
+    if (req.headers.authorization !== "secret") {
+        res.statusCode = 401;
+        res.json({ error: "Unauthorized" });
+    }
+});
+```
+
+Chain berhenti otomatis begitu response dikirim (`res.send()` / `res.json()` menandai `res.done = true`), jadi handler berikutnya tidak dipanggil.
+
+> Middleware global tetap dijalankan walaupun tidak ada route yang cocok (sebelum 404 dikirim).
+
+## Nested Router
+
+Pecah aplikasi jadi beberapa router lalu pasang dengan `use(path, router)`. Nesting bisa berlapis.
+
+```js
+const users = new Router();
+users.get("/", (req, res) => res.json({ list: [] }));
+users.get("/:id", (req, res) => res.json({ id: req.params.id }));
+
+const admin = new Router();
+admin.use("/users", users);
+
+const app = new Router();
+app.use("/admin", admin);
+
+// GET /admin/users      -> list
+// GET /admin/users/42   -> { id: "42" }
+```
+
+## Error Handling
+
+Handler dengan **tiga argumen** `(err, req, res)` dikenali sebagai error handler. Error handler dipanggil saat handler atau middleware melempar error (sync maupun async).
+
+```js
+app.get("/boom", () => {
+    throw new Error("Something broke");
+});
+
+app.use((err, req, res) => {
+    res.statusCode = err.statusCode || 500;
+    res.json({ error: err.message });
+});
+```
+
+### Respons default
+
+Jika tidak ada handler yang mengirim response, router mengirim JSON otomatis:
+
+```json
+{ "error": { "code": undefined, "message": "Not Found" } }
+```
+
+- Tidak ada route cocok: status `404`
+- Error dengan status 2xx: dinaikkan menjadi `500`
+- Saat `NODE_ENV=development`, field `stack` ikut disertakan
+
+## Request
+
+| Properti | Keterangan |
+| --- | --- |
+| `req.path` | Pathname tanpa query string |
+| `req.query` | Object query string. Key yang berulang menjadi array |
+| `req.params` | Parameter dari route dinamis |
+| `req.body` | Hasil parse body (butuh middleware `json()`) |
+
+```js
+// GET /search?tag=a&tag=b&page=2
+app.get("/search", (req, res) => {
+    res.json(req.query); // { tag: ["a", "b"], page: "2" }
+});
+```
+
+## Response
+
+| Method | Keterangan |
+| --- | --- |
+| `res.send(string)` | Kirim response dan akhiri chain |
+| `res.json(object)` | Set `content-type: application/json`, serialize, lalu kirim |
+
+Keduanya juga turunan dari `http.ServerResponse`, jadi `res.statusCode`, `res.setHeader()`, dan lainnya tetap tersedia.
+
+## JSON Body Parser
+
+```js
+const Router = require("@ndiinginc/router");
+const { json } = require("@ndiinginc/router/middleware");
+
+const app = new Router();
+
+app.use(json({ limit: 100 * 1024 })); // default 100 KB
+
+app.post("/users", (req, res) => {
+    res.json({ received: req.body });
+});
+```
+
+Perilaku:
+
+- Hanya memproses method `POST`, `PUT`, `PATCH`, dan `QUERY` dengan `content-type: application/json`
+- Body melebihi `limit` memicu error `413 Payload Too Large` (dicek lewat `content-length` dan saat streaming)
+- JSON tidak valid memicu error `400 Invalid JSON body`
+- Body kosong menghasilkan `req.body = null`
+- Key `__proto__`, `constructor`, dan `prototype` dibuang untuk mencegah prototype pollution
+
+## API
+
+### `new Router()`
+
+Membuat instance router baru.
+
+### `router.use([path], handler | router)`
+
+Mendaftarkan middleware, error handler, atau nested router untuk semua method.
+
+### `router.<method>([path], handler)`
+
+Mendaftarkan handler untuk method tertentu. `path` opsional; jika dihilangkan, handler dipasang di root router.
+
+### `router.find(method, path)`
+
+Mencari route tanpa menjalankannya. Berguna untuk testing.
+
+```js
+const { params, handlers, errorHandlers } = app.find("GET", "/users/1");
+```
+
+### `router.listen(...args)`
+
+Membuat `http.Server` dengan `Request` dan `Response` milik router, lalu memanggil `server.listen(...args)`. Mengembalikan instance `http.Server`.
+
+```js
+const server = app.listen(0); // port acak
+console.log(server.address().port);
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Lisensi
+
+MIT

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@ndiinginc/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "4.0.0",
+  "description": "",
+  "main": "./src/router.js",
+  "scripts": {
+    "test": "nodemon --exec \"node -e \\\"require('@ndiinginc/test')(require('path').resolve('tests'),{verbose:true})\\\"\"",
+    "dev": "nodemon src/router.js",
+    "prettier": "npx prettier . --write",
+    "commit": "node -e \"require('@ndiinginc/commit')()\"",
+    "npm:dry-run": "npm publish --dry-run",
+    "npm:login": "npm login",
+    "npm:publish": "npm publish --access public",
+    "tsc": "npx tsc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@ndiinginc/commit": "^1.0.1",
+    "@ndiinginc/test": "^1.5.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.6.4"
+  }
 }

package/rest/router.http

@@ -0,0 +1,18 @@
+###
+GET http://localhost:3000
+###
+POST http://localhost:3000
+Content-Type: application/json; charset=utf-8; asdfadsf
+
+{
+    "user":"name",
+    "pass":"word"
+}
+###
+GET http://localhost:4000
+###
+GET http://localhost:5000
+
+autocannon -c 100 -d 10 -p 10 localhost:3000
+autocannon -c 100 -d 10 -p 10 localhost:4000
+autocannon -c 100 -d 10 -p 10 localhost:5000

package/src/middleware.js

@@ -0,0 +1,52 @@
+const http = require("node:http");
+
+function json({ limit = 100 * 1024 } = {}) {
+    const reviver = (key, value) => {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            return undefined;
+        }
+        return value;
+    };
+
+    return async (req, res) => {
+        if (!["POST", "PUT", "PATCH", "QUERY"].includes(req.method)) {
+            return;
+        }
+
+        const contentType = req.headers["content-type"];
+        if (!contentType || !contentType.includes("application/json")) {
+            return;
+        }
+
+        const contentLength = parseInt(req.headers["content-length"], 10);
+        if (contentLength && contentLength > limit) {
+            res.statusCode = 413;
+            throw new Error(http.STATUS_CODES[res.statusCode]);
+        }
+
+        let bodySize = 0;
+        const chunks = [];
+        for await (const chunk of req) {
+            bodySize += chunk.length;
+            if (bodySize > limit) {
+                res.statusCode = 413;
+                throw new Error(http.STATUS_CODES[res.statusCode]);
+            }
+            chunks.push(chunk);
+        }
+
+        if (chunks.length === 0) {
+            req.body = null;
+            return;
+        }
+
+        const rawBody = Buffer.concat(chunks).toString("utf8");
+        try {
+            req.body = JSON.parse(rawBody, reviver);
+        } catch (error) {
+            res.statusCode = 400;
+            throw new Error("Invalid JSON body");
+        }
+    };
+}
+module.exports.json = json;

package/src/node.js

@@ -0,0 +1,70 @@
+const { Pattern } = require("./pattern.js");
+
+class Node {
+    constructor(segment) {
+        this.segment = segment;
+        this.pattern = new Pattern(segment);
+        /**@type {Map<string, Node>}*/
+        this.children = new Map();
+        /**@type {Map<string, Function[]>}*/
+        this.handlers = new Map();
+    }
+
+    add(segment) {
+        if (!this.children.has(segment)) {
+            this.children.set(segment, new Node(segment));
+        }
+        return this.children.get(segment);
+    }
+
+    /**
+     * @param {Node} node
+     * @param {Number} offset
+     */
+    merge(node, offset) {
+        for (const [method, handlers] of node.handlers) {
+            for (const handler of handlers) {
+                handler.seq += offset;
+                this.handlers.getOrInsert(method, []).push(handler);
+            }
+        }
+
+        for (const [segment, child] of node.children) {
+            if (!this.children.has(segment)) {
+                child.setSeqOffset(offset);
+                this.children.set(segment, child);
+            } else {
+                this.children.get(segment).merge(child, offset);
+            }
+        }
+    }
+
+    setSeqOffset(offset) {
+        for (const [, handlers] of this.handlers) {
+            for (const handler of handlers) {
+                handler.seq += offset;
+            }
+        }
+
+        for (const [, child] of this.children) {
+            child.setSeqOffset(offset);
+        }
+    }
+
+    getMaxSeq() {
+        let max = -1;
+
+        for (const [, handlers] of this.handlers) {
+            for (const handler of handlers) {
+                max = Math.max(max, handler.seq);
+            }
+        }
+
+        for (const [, child] of this.children) {
+            max = Math.max(max, child.getMaxSeq());
+        }
+
+        return max;
+    }
+}
+exports.Node = Node;

package/src/pattern.js

@@ -0,0 +1,24 @@
+class Pattern {
+    static baseURL = "http://localhost";
+
+    constructor(input) {
+        const regexStr = input
+            .replace(/[.+*?^${}()|[\]\\]/g, "\\$&")
+            .replace(/:(\w+)/g, "(?<$1>[^/]+)")
+            .replace(/\\\*/g, ".*");
+        this.regex = new RegExp(`^${regexStr}$`);
+    }
+
+    exec(input) {
+        const match = this.regex.exec(input);
+        if (!match) return null;
+        return {
+            pathname: { groups: match.groups || {} },
+        };
+    }
+
+    test(input) {
+        return this.regex.test(input);
+    }
+}
+exports.Pattern = Pattern;

package/src/polyfill.js

@@ -0,0 +1,9 @@
+// Polyfill for Map.prototype.getOrInsert
+if (!Map.prototype.getOrInsert) {
+    Map.prototype.getOrInsert = function (key, defaultValue) {
+        if (!this.has(key)) {
+            this.set(key, defaultValue);
+        }
+        return this.get(key);
+    };
+}

package/src/request.js

@@ -0,0 +1,29 @@
+const { IncomingMessage } = require("node:http");
+
+class Request extends IncomingMessage {
+    get path() {
+        if (this.url.indexOf("?") !== -1) {
+            this.parsed = URL.parse(this.url, "http://localhost");
+            return this.parsed.pathname;
+        }
+        return this.url;
+    }
+
+    get query() {
+        const query = {};
+        if (!this.parsed) return query;
+        for (const [name, value] of this.parsed.searchParams) {
+            if (query[name]) {
+                if (Array.isArray(query[name])) {
+                    query[name].push(value);
+                } else {
+                    query[name] = [query[name], value];
+                }
+            } else {
+                query[name] = value;
+            }
+        }
+        return query;
+    }
+}
+exports.Request = Request;

package/src/response.js

@@ -0,0 +1,14 @@
+const { ServerResponse } = require("node:http");
+
+class Response extends ServerResponse {
+    send(string) {
+        this.done = true;
+        this.end(string);
+    }
+
+    json(object) {
+        this.setHeader("content-type", "application/json");
+        this.send(JSON.stringify(object));
+    }
+}
+exports.Response = Response;

package/src/router.js

@@ -0,0 +1,212 @@
+require("./polyfill.js");
+const http = require("node:http");
+const { Response } = require("./response.js");
+const { Request } = require("./request.js");
+const { Node } = require("./node.js");
+
+class Router {
+    /**@type {Node}*/
+    root;
+
+    constructor() {
+        this.root = new Node("");
+        this.seq = 0;
+    }
+
+    split(path) {
+        return path.split("/").filter(Boolean);
+    }
+
+    add(method, path, handler) {
+        if (typeof path === "function") {
+            handler = path;
+            path = null;
+        }
+
+        let node = this.root;
+
+        if (path !== null) {
+            for (const segment of this.split(path)) {
+                node = node.add(segment);
+            }
+        }
+
+        if (handler.root) {
+            node.merge(handler.root, this.seq);
+            this.seq = node.getMaxSeq() + 1;
+        } else {
+            handler.seq = this.seq++;
+            node.handlers.getOrInsert(method, []).push(handler);
+        }
+    }
+
+    use(path, handler) {
+        this.add("ALL", path, handler);
+        return this;
+    }
+
+    get(path, handler) {
+        this.add("GET", path, handler);
+        return this;
+    }
+    query(path, handler) {
+        this.add("QUERY", path, handler);
+        return this;
+    }
+    head(path, handler) {
+        this.add("HEAD", path, handler);
+        return this;
+    }
+    options(path, handler) {
+        this.add("OPTIONS", path, handler);
+        return this;
+    }
+    trace(path, handler) {
+        this.add("TRACE", path, handler);
+        return this;
+    }
+    put(path, handler) {
+        this.add("PUT", path, handler);
+        return this;
+    }
+    delete(path, handler) {
+        this.add("DELETE", path, handler);
+        return this;
+    }
+    post(path, handler) {
+        this.add("POST", path, handler);
+        return this;
+    }
+    patch(path, handler) {
+        this.add("PATCH", path, handler);
+        return this;
+    }
+    connect(path, handler) {
+        this.add("CONNECT", path, handler);
+        return this;
+    }
+
+    find(method, path) {
+        let params = {};
+        let handlers = {};
+        let errorHandlers = {};
+
+        let node = this.root;
+
+        const inputs = this.split(path);
+        if (inputs.length) {
+            for (const input of inputs) {
+                let matched = node.children.get(input);
+
+                if (!matched) {
+                    for (const [, child] of node.children) {
+                        const match = child.pattern.exec(input);
+                        if (match) {
+                            matched = child;
+                            Object.assign(params, match.pathname.groups);
+                            break;
+                        }
+                    }
+                }
+
+                if (!matched) {
+                    node = null;
+                    params = {};
+                    break;
+                }
+
+                node = matched;
+
+                if (node.handlers.has("ALL")) {
+                    for (const handler of node.handlers.get("ALL")) {
+                        if (handler.length === 3) errorHandlers[handler.seq] = handler;
+                        else handlers[handler.seq] = handler;
+                    }
+                }
+            }
+        }
+
+        if (this.root.handlers.has("ALL")) {
+            for (const handler of this.root.handlers.get("ALL")) {
+                if (handler.length === 3) errorHandlers[handler.seq] = handler;
+                else handlers[handler.seq] = handler;
+            }
+        }
+
+        if (node && node.handlers.has(method)) {
+            for (const handler of node.handlers.get(method)) {
+                if (handler.length === 3) errorHandlers[handler.seq] = handler;
+                else handlers[handler.seq] = handler;
+            }
+        }
+
+        return {
+            params,
+            handlers: Object.values(handlers),
+            errorHandlers: Object.values(errorHandlers),
+        };
+    }
+
+    /**
+     * @param {import('http').RequestOptions} req
+     * @param {import('http').ServerResponse} res
+     */
+    async handleRequest(req, res) {
+        const result = this.find(req.method, req.path);
+        req.params = result.params;
+
+        try {
+            for (const handler of result.handlers) {
+                if (res.done) break;
+                await handler(req, res);
+            }
+        } catch (error) {
+            res.error = error;
+
+            try {
+                for (const handler of result.errorHandlers) {
+                    if (res.done) break;
+                    await handler(res.error, req, res);
+                }
+            } catch (error) {
+                res.error = error;
+            }
+        }
+
+        if (!res.done) {
+            if (!res.error) {
+                res.statusCode = 404;
+                res.error = new Error(http.STATUS_CODES[res.statusCode]);
+            }
+
+            res.statusCode = res.statusCode >= 200 && res.statusCode < 300 ? 500 : res.statusCode;
+
+            const error = {
+                code: res.error.code,
+                message: res.error.message,
+            };
+            if (process.env.NODE_ENV === "development") error.stack = res.error.stack;
+
+            res.json({ error });
+        }
+    }
+
+    /**
+     * @returns {import('http').Server}
+     */
+    listen(...params) {
+        const server = http.createServer(
+            {
+                IncomingMessage: Request,
+                ServerResponse: Response,
+            },
+            (req, res) => this.handleRequest(req, res),
+        );
+
+        server.listen(...params);
+
+        return server;
+    }
+}
+
+module.exports = Router;