@ndiinginc/router 4.4.0 → 4.4.1

package/README.md

@@ -1,18 +1,20 @@
 # @ndiinginc/router
 
-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.
+Router HTTP kecil, cepat, dan **zero-dependency** untuk Node.js. Dibangun langsung di atas `node:http`, dengan routing berbasis tree, LRU cache untuk lookup route, nested router, middleware async, error handler, timeout per request, serta middleware `json` dan `cors` bawaan.
 
 ## Fitur
 
 - Zero dependency, murni `node:http`
-- Routing berbasis tree per segment (static match diprioritaskan, lalu dynamic)
+- Routing berbasis tree per segmen (static match diprioritaskan, lalu dynamic)
 - Parameter dinamis `:id` dan wildcard `*`
+- LRU cache untuk hasil lookup route
 - Nested router dengan `use(path, router)`
 - Middleware global dan per-path, mendukung `async`
 - Error handler dengan signature `(err, req, res)`
+- Timeout per request (`req.timeout`) yang menghasilkan `504`
 - `req.path`, `req.query`, `req.params`, `req.body`
 - Helper `res.send()` dan `res.json()`
-- JSON body parser dengan limit ukuran dan proteksi prototype pollution
+- Middleware bawaan: `json()` (dengan limit dan proteksi prototype pollution) dan `cors()`
 - Semua HTTP method, termasuk `QUERY`
 
 ## Instalasi
@@ -21,14 +23,16 @@ Router HTTP kecil, cepat, dan **zero-dependency** untuk Node.js. Dibangun langsu
 npm install @ndiinginc/router
 ```
 
-Butuh **Node.js 22.1+** (memakai `URL.parse`).
+Butuh Node.js 18.3 atau lebih baru.
 
 ## Quick Start
 
 ```js
-const Router = require("@ndiinginc/router");
+const App = require("@ndiinginc/router");
 
-const app = new Router();
+const app = new App();
+
+app.use(App.json());
 
 app.get("/", (req, res) => {
     res.json({ hello: "world" });
@@ -38,19 +42,44 @@ app.get("/users/:id", (req, res) => {
     res.json({ id: req.params.id });
 });
 
+app.post("/users", (req, res) => {
+    res.json({ received: req.body });
+});
+
 app.listen(3000);
 ```
 
+Yang diekspor adalah class `App`, dengan tiga properti tambahan:
+
+| Export | Keterangan |
+| --- | --- |
+| `App` | Router + HTTP server (`listen`) |
+| `App.Router` | Router tanpa server, untuk nested router |
+| `App.json` | Middleware JSON body parser |
+| `App.cors` | Middleware CORS |
+
 ## 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);
+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).
 
+Satu route boleh punya beberapa handler:
+
+```js
+app.get("/profile", authenticate, loadUser, (req, res) => {
+    res.json(req.user);
+});
+```
+
 ### Parameter dinamis
 
 ```js
@@ -62,7 +91,7 @@ app.get("/posts/:postId/comments/:commentId", (req, res) => {
 
 ### Wildcard
 
-`*` cocok dengan karakter apa pun di dalam satu segmen.
+`*` cocok dengan karakter apa pun **di dalam satu segmen**. Wildcard tidak melintasi `/`.
 
 ```js
 app.get("/files/report-*", (req, res) => {
@@ -70,13 +99,15 @@ app.get("/files/report-*", (req, res) => {
 });
 ```
 
-### Prioritas match
+### Aturan matching
 
-Untuk setiap segmen, router mencoba **static match dulu**, baru pattern dinamis. Jadi `/users/me` menang atas `/users/:id` bila keduanya terdaftar.
+- Untuk setiap segmen, router mencoba **static match dulu**, baru pattern dinamis. Jadi `/users/me` menang atas `/users/:id` bila keduanya terdaftar.
+- Jika ada beberapa pattern dinamis di level yang sama, yang **terdaftar lebih dulu** yang dipakai (tanpa backtracking).
+- Trailing slash dan slash ganda diabaikan: `/users`, `/users/`, dan `//users` dianggap sama.
 
 ## Middleware
 
-Middleware didaftarkan dengan `use()` dan dijalankan **berurutan sesuai urutan pendaftaran**.
+Middleware didaftarkan dengan `use()`. Semua handler (middleware dan route) dijalankan **berurutan sesuai urutan pendaftaran**.
 
 ```js
 // Global
@@ -93,15 +124,17 @@ app.use("/admin", async (req, res) => {
 });
 ```
 
-Chain berhenti otomatis begitu response dikirim (`res.send()` / `res.json()` menandai `res.done = true`), jadi handler berikutnya tidak dipanggil.
+Chain berhenti otomatis begitu response selesai dikirim (`res.writableEnded`), jadi handler berikutnya tidak dipanggil.
 
-> Middleware global tetap dijalankan walaupun tidak ada route yang cocok (sebelum 404 dikirim).
+> Middleware tetap dijalankan walaupun tidak ada route yang cocok, sebelum respons 404 dikirim.
 
 ## Nested Router
 
-Pecah aplikasi jadi beberapa router lalu pasang dengan `use(path, router)`. Nesting bisa berlapis.
+Pecah aplikasi menjadi beberapa router, lalu pasang dengan `use(path, router)`. Nesting bisa berlapis.
 
 ```js
+const { Router } = App;
+
 const users = new Router();
 users.get("/", (req, res) => res.json({ list: [] }));
 users.get("/:id", (req, res) => res.json({ id: req.params.id }));
@@ -109,16 +142,18 @@ users.get("/:id", (req, res) => res.json({ id: req.params.id }));
 const admin = new Router();
 admin.use("/users", users);
 
-const app = new Router();
+const app = new App();
 app.use("/admin", admin);
 
-// GET /admin/users      -> list
+// GET /admin/users      -> { list: [] }
 // GET /admin/users/42   -> { id: "42" }
 ```
 
+> Tree sub-router digabungkan saat `use()` dipanggil. Daftarkan semua route ke sub-router **sebelum** di-mount; route yang ditambahkan setelahnya tidak ikut. Satu instance sub-router sebaiknya hanya di-mount satu kali.
+
 ## 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).
+Handler dengan **tiga argumen** `(err, req, res)` dikenali sebagai error handler. Dipanggil saat handler atau middleware melempar error (sync maupun async).
 
 ```js
 app.get("/boom", () => {
@@ -127,7 +162,28 @@ app.get("/boom", () => {
 
 app.use((err, req, res) => {
     res.statusCode = err.statusCode || 500;
-    res.json({ error: err.message });
+    res.json({ error: { message: err.message } });
+});
+```
+
+> Deteksi error handler memakai `handler.length === 3`. Jangan memakai default parameter atau rest parameter di signature handler, karena mengubah `length`.
+
+### Menentukan status code
+
+Ada dua cara:
+
+```js
+// 1. Properti statusCode pada error
+app.get("/admin", () => {
+    const err = new Error("Forbidden");
+    err.statusCode = 403;
+    throw err;
+});
+
+// 2. Set res.statusCode sebelum throw
+app.get("/limit", (req, res) => {
+    res.statusCode = 429;
+    throw new Error("Too Many Requests");
 });
 ```
 
@@ -136,21 +192,39 @@ app.use((err, req, res) => {
 Jika tidak ada handler yang mengirim response, router mengirim JSON otomatis:
 
 ```json
-{ "error": { "code": undefined, "message": "Not Found" } }
+{ "error": { "message": "Not Found" } }
 ```
 
-- Tidak ada route cocok: status `404`
-- Error dengan status 2xx: dinaikkan menjadi `500`
-- Saat `NODE_ENV=development`, field `stack` ikut disertakan
+- Tidak ada route cocok: `404 Not Found`
+- Error tanpa status code: `500`
+- Jika `res.statusCode` sudah `>= 400`, nilainya dipertahankan
+- Jika error handler sendiri melempar error, error baru dibuat dengan `cause` menunjuk error asli
+
+- Field `stack` hanya disertakan saat `NODE_ENV=development`
+
+## Timeout
+
+Set `req.timeout` (milidetik) untuk membatasi waktu eksekusi handler. Jika terlampaui, error `504 Gateway Timeout` dilempar dan diteruskan ke error handler.
+
+```js
+app.use((req) => {
+    req.timeout = 5000;
+});
+```
+
+- Nilai default `0` (tanpa timeout)
+- Harus diset **secara sinkron di middleware pertama** pada chain, karena dibaca sesaat setelah chain mulai berjalan
+- Timeout tidak membatalkan handler yang sedang berjalan; hanya menghentikan penantian dan mengirim error
 
 ## 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()`)         |
+| Properti | Keterangan |
+| --- | --- |
+| `req.path` | Pathname tanpa query string |
+| `req.query` | Object query string, di-parse secara lazy. Key yang berulang menjadi array |
+| `req.params` | Parameter dari route dinamis (sudah di-decode dengan `decodeURIComponent`) |
+| `req.body` | Hasil parse body (butuh middleware `json()`) |
+| `req.timeout` | Batas waktu handler dalam ms (default `0`) |
 
 ```js
 // GET /search?tag=a&tag=b&page=2
@@ -159,61 +233,99 @@ app.get("/search", (req, res) => {
 });
 ```
 
+`Request` adalah turunan `http.IncomingMessage`, jadi `req.headers`, `req.method`, dan lainnya tetap tersedia.
+
 ## Response
 
-| Method             | Keterangan                                                  |
-| ------------------ | ----------------------------------------------------------- |
-| `res.send(string)` | Kirim response dan akhiri chain                             |
-| `res.json(object)` | Set `content-type: application/json`, serialize, lalu kirim |
+| Method | Keterangan |
+| --- | --- |
+| `res.send(chunk)` | Kirim response dan akhiri |
+| `res.json(value)` | Set `Content-Type: application/json`, serialize, lalu kirim |
 
-Keduanya juga turunan dari `http.ServerResponse`, jadi `res.statusCode`, `res.setHeader()`, dan lainnya tetap tersedia.
+`Response` adalah turunan `http.ServerResponse`, jadi `res.statusCode`, `res.setHeader()`, dan lainnya tetap tersedia.
 
-## JSON Body Parser
+## Middleware Bawaan
+
+### `json([options])`
 
 ```js
-const Router = require("@ndiinginc/router");
-const { json } = require("@ndiinginc/router/middleware");
+app.use(App.json({ limit: 100 * 1024 })); // default 100 KB
+```
+
+| Opsi | Default | Keterangan |
+| --- | --- | --- |
+| `limit` | `102400` | Ukuran body maksimum dalam byte |
 
-const app = new Router();
+Perilaku:
 
-app.use(json({ limit: 100 * 1024 })); // default 100 KB
+- Hanya memproses method `POST`, `PUT`, `PATCH`, dan `QUERY` dengan `Content-Type: application/json`
+- Body melebihi `limit` menghasilkan `413 Payload Too Large` (dicek lewat `Content-Length` dan saat streaming)
+- JSON tidak valid menghasilkan `400` dengan pesan `Invalid JSON body`
+- Body kosong menghasilkan `req.body = null`
+- Key `__proto__`, `constructor`, dan `prototype` dibuang untuk mencegah prototype pollution
 
-app.post("/users", (req, res) => {
-    res.json({ received: req.body });
-});
+### `cors([options])`
+
+```js
+app.use(
+    App.cors({
+        origin: "https://example.com",
+        credentials: true,
+        methods: ["GET", "POST", "PUT", "DELETE"],
+        headers: ["Content-Type", "Authorization"],
+        maxAge: 600,
+    }),
+);
 ```
 
+| Opsi | Default | Keterangan |
+| --- | --- | --- |
+| `origin` | `"*"` | `"*"`, string origin, atau `null` |
+| `credentials` | `false` | Mengirim `Access-Control-Allow-Credentials: true` |
+| `headers` | - | `"*"` atau array nama header |
+| `methods` | - | `"*"` atau array nama method |
+| `maxAge` | `0` | Lama cache preflight (detik). `0` berarti header tidak dikirim |
+
 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
+- Request `OPTIONS` dijawab langsung dengan `204` dan chain berhenti
+- Dengan `origin: "*"` dan `credentials: true`, origin dari request dipantulkan dan header `Vary: Origin` ditambahkan
+- Nilai `"*"` untuk `headers` dan `methods` diabaikan saat `credentials: true`, sesuai spesifikasi CORS
+- Pada request non-preflight, `headers` (jika array) dikirim sebagai `Access-Control-Expose-Headers`
+
+## Opsi Router
+
+```js
+const app = new App({ size: 1000 });
+```
+
+| Opsi | Default | Keterangan |
+| --- | --- | --- |
+| `size` | `1000` | Jumlah maksimum entri LRU cache untuk hasil lookup `METHOD path` |
 
 ## API
 
-### `new Router()`
+### `new App([options])` / `new Router([options])`
 
-Membuat instance router baru.
+Membuat instance baru. `App` adalah `Router` ditambah `listen()`.
 
-### `router.use([path], handler | router)`
+### `router.use([path], ...handlers | router)`
 
 Mendaftarkan middleware, error handler, atau nested router untuk semua method.
 
-### `router.<method>([path], handler)`
+### `router.<method>([path], ...handlers)`
 
-Mendaftarkan handler untuk method tertentu. `path` opsional; jika dihilangkan, handler dipasang di root router.
+Mendaftarkan handler untuk method tertentu. `path` opsional; jika dihilangkan, handler dipasang di root.
 
 ### `router.find(method, path)`
 
-Mencari route tanpa menjalankannya. Berguna untuk testing.
+Mencari route tanpa menjalankannya. Hasilnya di-cache. Berguna untuk testing.
 
 ```js
 const { params, handlers, errorHandlers } = app.find("GET", "/users/1");
 ```
 
-### `router.listen(...args)`
+### `app.listen(...args)`
 
 Membuat `http.Server` dengan `Request` dan `Response` milik router, lalu memanggil `server.listen(...args)`. Mengembalikan instance `http.Server`.
 
@@ -222,6 +334,18 @@ const server = app.listen(0); // port acak
 console.log(server.address().port);
 ```
 
+## Benchmark
+
+Hello world dengan satu route `GET /`, diuji memakai `autocannon -c 100 -d 40 -p 10` di mesin lokal.
+
+| | Req/sec (avg) | Latency (avg) |
+| --- | --- | --- |
+| Fastify | 31.475 | 31,27 ms |
+| **@ndiinginc/router** | 29.735 | 33,12 ms |
+| Express | 20.211 | 48,93 ms |
+
+Hasil bervariasi tergantung mesin, versi Node.js, dan jumlah route. Benchmark ini hanya menggambarkan overhead dasar, bukan performa aplikasi nyata.
+
 ## Testing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ndiinginc/router",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "description": "",
   "main": "./src/index.js",
   "scripts": {

package/src/app.js

@@ -59,7 +59,11 @@ class App extends Router {
                 res.statusCode = err.statusCode || 500;
             }
 
-            res.json({ error: { message: err.message, stack: err.stack } });
+            const error = { message: err.message };
+            if (process.env.NODE_ENV === "development") {
+                error.stack = err.stack;
+            }
+            res.json({ error });
         }
     }
 

package/src/router.js

@@ -107,7 +107,7 @@ class Router {
 
         let node = this.root;
 
-        let params = {};
+        let params = Object.create(null);
         const handlers = {};
         const errorHandlers = {};
 
@@ -120,7 +120,14 @@ class Router {
                     const match = child.pattern.exec(input);
                     if (match) {
                         matched = child;
-                        Object.assign(params, match.groups);
+                        for (const name in match.groups) {
+                            const raw = match.groups[name];
+                            try {
+                                params[name] = decodeURIComponent(raw);
+                            } catch {
+                                params[name] = raw;
+                            }
+                        }
                         break;
                     }
                 }
@@ -128,7 +135,7 @@ class Router {
 
             if (!matched) {
                 node = null;
-                params = {};
+                params = Object.create(null);
                 break;
             }
 

package/src/util.js

@@ -2,13 +2,25 @@ const URL_REGEX = /^([^?#]*)(\?([^#]*))?(#.*)?$/;
 const QUERY_STRING_REGEX = /([^=&]*)?=([^&]*)?/g;
 
 function parseQueryString(queryString) {
-    const result = {};
+    const result = Object.create(null);
 
     let match;
     while ((match = QUERY_STRING_REGEX.exec(queryString)) !== null) {
-        const [, name = "", raw = ""] = match;
+        const [, rawName = "", rawValue = ""] = match;
 
-        const value = decodeURIComponent(raw);
+        let name 
+        try {
+            name = decodeURIComponent(rawName)
+        } catch (error) {
+            name=rawName
+        }
+        
+        let value 
+        try {
+            value = decodeURIComponent(rawValue)
+        } catch (error) {
+            value=rawValue
+        }
 
         if (result[name]) {
             if (Array.isArray(result[name])) result[name].push(value);