@ndiinginc/router 4.8.0 → 4.9.0

package/README.md

@@ -11,7 +11,7 @@ Router HTTP kecil, cepat, dan **zero-dependency** untuk Node.js. Dibangun langsu
 - Nested router dengan `use(path, router)`
 - Middleware global dan per-path, mendukung `async`
 - Error handler dengan signature `(err, req, res)`
-- Timeout per request yang menghasilkan `504`, dengan `req.signal` untuk pembatalan kooperatif
+- Timeout per request, dengan `req.controller` (`AbortController`) untuk pembatalan kooperatif
 - `req.path`, `req.query`, `req.params`, `req.body`
 - Helper `res.status()`, `res.send()`, dan `res.json()`
 - Middleware bawaan: `json()` (dengan limit dan proteksi prototype pollution) dan `cors()`
@@ -93,15 +93,21 @@ app.get("/posts/:postId/comments/:commentId", (req, res) => {
 
 Satu segmen adalah satu parameter utuh; nama parameter tidak bisa digabung dengan teks lain dalam segmen yang sama (`:id.json` akan dianggap parameter bernama `id.json`).
 
-> Di setiap level hanya ada satu parameter. Jika `/users/:id` dan `/users/:userId/posts` didaftarkan bersamaan, keduanya memakai nama yang pertama didaftarkan (`id`). Pakai nama yang sama untuk level yang sama.
+Beberapa parameter dengan nama berbeda boleh ada di level yang sama. Router mencoba semuanya sesuai urutan pendaftaran, dan memakai yang cocok sampai akhir path:
+
+```js
+app.get("/users/:id", handler);
+app.get("/users/:userId/posts", handler);
+// GET /users/5/posts -> req.params.userId === "5"
+```
 
 ### Wildcard
 
-Segmen `*` menangkap **seluruh sisa path** (termasuk `/`) dan nilainya tersedia di `req.params[0]`.
+Segmen `*` menangkap **seluruh sisa path** (termasuk `/`) dan nilainya tersedia di `req.params.wildcard`.
 
 ```js
 app.get("/files/*", (req, res) => {
-    res.json({ file: req.params[0] });
+    res.json({ file: req.params.wildcard });
 });
 
 // GET /files/images/logo.png -> { file: "images/logo.png" }
@@ -111,8 +117,8 @@ Wildcard butuh minimal satu segmen tersisa, jadi `/files/*` tidak cocok dengan `
 
 ### Aturan matching
 
-- Di setiap level, router mencoba **static dulu, lalu parameter, lalu wildcard**. Jadi `/users/me` menang atas `/users/:id` bila keduanya terdaftar.
-- Jika cabang static gagal di tengah jalan, router mundur (backtrack) dan mencoba parameter, lalu wildcard.
+- Di setiap level, router mencoba **static dulu, lalu parameter (sesuai urutan pendaftaran), lalu wildcard**. Jadi `/users/me` menang atas `/users/:id` bila keduanya terdaftar.
+- Jika sebuah cabang gagal di tengah jalan, router mundur (backtrack) dan mencoba cabang berikutnya.
 - Trailing slash dan slash ganda diabaikan: `/users`, `/users/`, dan `//users` dianggap sama.
 
 ## Middleware
@@ -135,7 +141,7 @@ app.use("/admin", async (req, res) => {
 
 Chain berhenti otomatis begitu response selesai dikirim (`res.writableEnded`), jadi handler berikutnya tidak dipanggil.
 
-> Jika path tidak cocok dengan route mana pun, hanya middleware global (tanpa path) yang dijalankan sebelum respons 404 dikirim.
+> Jika tidak ada route yang cocok sepenuhnya, middleware pada bagian path yang cocok paling dalam tetap dijalankan sebelum respons 404. Contohnya, middleware `/admin` tetap jalan untuk `/admin/tidak-ada`, begitu juga middleware global.
 
 ## Nested Router
 
@@ -164,32 +170,32 @@ app.use("/admin", admin);
 
 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", () => {
-    throw new Error("Something broke");
-});
+> Deteksi error handler memakai `handler.length === 3`. Jangan memakai default parameter atau rest parameter di signature handler, karena mengubah `length`.
 
-app.use((err, req, res) => {
-    res.status(err.statusCode || 500).json({ error: { message: err.message } });
+### Menentukan status code
+
+Status code diambil dari `res.statusCode`. Set sebelum melempar error:
+
+```js
+app.get("/admin", (req, res) => {
+    res.status(403);
+    throw new Error("Forbidden");
 });
 ```
 
-> Deteksi error handler memakai `handler.length === 3`. Jangan memakai default parameter atau rest parameter di signature handler, karena mengubah `length`.
+Jika `res.statusCode` masih di bawah 400 saat error ditangani, hasilnya `500`. Properti `statusCode` pada objek error tidak dipakai.
 
-### Menentukan status code
+### Error handler sendiri
 
-Status code diambil dari properti `statusCode` pada error. Tanpa properti itu, hasilnya `500`.
+Di error handler, `res.statusCode` masih bernilai awal (`200`) bila error dilempar tanpa mengatur status, jadi atur sendiri:
 
 ```js
-app.get("/admin", () => {
-    const err = new Error("Forbidden");
-    err.statusCode = 403;
-    throw err;
+app.use((err, req, res) => {
+    const status = res.statusCode >= 400 ? res.statusCode : 500;
+    res.status(status).json({ error: { message: err.message } });
 });
 ```
 
-> `res.statusCode` atau `res.status()` yang diset **sebelum** error dilempar tidak dipakai oleh respons default. Gunakan `err.statusCode`, atau tangani sendiri di error handler.
-
 ### Respons default
 
 Jika tidak ada handler yang mengirim response, router mengirim JSON otomatis:
@@ -199,44 +205,44 @@ Jika tidak ada handler yang mengirim response, router mengirim JSON otomatis:
 ```
 
 - Tidak ada route cocok: `404 Not Found`
-- Error dengan `statusCode`: status tersebut dipakai
-- Error tanpa `statusCode`: `500`
+- `res.statusCode` sudah `>= 400`: dipakai apa adanya
+- `res.statusCode` masih `< 400`: diganti `500`
 - Jika error handler sendiri melempar error, error baru dibuat dengan `cause` menunjuk error asli
 - Field `stack` hanya disertakan saat `NODE_ENV=development`
 
 ## Timeout
 
-Aktifkan lewat opsi `requestTimeout` (milidetik) pada `App`. Jika seluruh chain handler melebihi waktu tersebut, error `504 Gateway Timeout` dilempar dan diteruskan ke error handler.
+Aktifkan lewat opsi `requestTimeout` (milidetik) pada `App`. Jika seluruh chain handler melebihi waktu tersebut, `res.statusCode` diset `502` dan error `Bad Gateway` dilempar ke error handler.
 
 ```js
 const app = new App({ requestTimeout: 5000 });
 ```
 
 - Tanpa opsi `requestTimeout` (atau bernilai `0`), tidak ada batas waktu
-- Handler yang sudah berjalan tidak dihentikan paksa. Tetapi setelah response dikirim, `res.json()` dan `res.send()` mengabaikan penulisan berikutnya, dan handler selanjutnya di chain tidak dipanggil
+- Handler yang sudah berjalan tidak dihentikan paksa. Setelah response dikirim, handler berikutnya di chain tidak dipanggil, dan error yang dilempar handler setelah timeout hanya dicatat lewat `console.error`
 
-### `req.signal`
+### `req.controller`
 
-Saat `requestTimeout` aktif, `req.signal` adalah `AbortSignal` yang di-abort ketika timeout terjadi (reason-nya error 504) atau ketika salah satu handler melempar error (reason-nya error tersebut). Teruskan ke operasi yang mendukungnya agar pekerjaan ikut dibatalkan:
+`req.controller` adalah `AbortController` milik request (dibuat saat pertama kali diakses). Saat `requestTimeout` aktif, `req.controller.signal` di-abort ketika timeout terjadi atau ketika salah satu handler melempar error; reason-nya adalah error terkait. Teruskan signal ke operasi yang mendukungnya agar pekerjaan ikut dibatalkan:
 
 ```js
 app.get("/proxy", async (req, res) => {
-    const upstream = await fetch("https://example.com/api", { signal: req.signal });
+    const upstream = await fetch("https://example.com/api", {
+        signal: req.controller.signal,
+    });
     res.json(await upstream.json());
 });
 ```
 
-`req.signal` bernilai `undefined` jika `requestTimeout` tidak diaktifkan.
-
 ## Request
 
 | Properti | Keterangan |
 | --- | --- |
 | `req.path` | Pathname tanpa query string |
 | `req.query` | Object query string, di-parse secara lazy. Key yang berulang menjadi array, dan `+` di-decode menjadi spasi |
-| `req.params` | Parameter dari route dinamis (sudah di-decode). Wildcard `*` ada di `req.params[0]` |
+| `req.params` | Parameter dari route dinamis (sudah di-decode). Wildcard `*` ada di `req.params.wildcard` |
 | `req.body` | Hasil parse body (butuh middleware `json()`) |
-| `req.signal` | `AbortSignal` yang di-abort saat timeout atau error handler (hanya jika `requestTimeout` aktif) |
+| `req.controller` | `AbortController` untuk request ini. Di-abort saat timeout atau error handler (jika `requestTimeout` aktif) |
 
 ```js
 // GET /search?tag=a&tag=b&page=2
@@ -245,7 +251,7 @@ app.get("/search", (req, res) => {
 });
 ```
 
-`req.query` dan `req.params` yang sampai ke handler memakai object tanpa prototype, jadi gunakan `Object.hasOwn(req.query, "key")` atau `"key" in req.query`, bukan `req.query.hasOwnProperty(...)`.
+`req.query` dan `req.params` memakai object tanpa prototype, jadi gunakan `Object.hasOwn(req.query, "key")` atau `"key" in req.query`, bukan `req.query.hasOwnProperty(...)`.
 
 `Request` adalah turunan `http.IncomingMessage`, jadi `req.headers`, `req.method`, dan lainnya tetap tersedia.
 
@@ -255,13 +261,13 @@ app.get("/search", (req, res) => {
 | --- | --- |
 | `res.status(code)` | Set status code, mengembalikan `res` sehingga bisa di-chain |
 | `res.send(chunk)` | Kirim response dan akhiri |
-| `res.json(value)` | Set `Content-Type: application/json`, serialize, lalu kirim |
+| `res.json(value)` | Set `Content-Type: application/json; charset=utf-8`, serialize, lalu kirim |
 
 ```js
 res.status(201).json({ created: true });
 ```
 
-`Response` adalah turunan `http.ServerResponse`, jadi `res.statusCode`, `res.setHeader()`, dan lainnya tetap tersedia.
+`res.send()` dan `res.json()` tidak melakukan apa-apa jika response sudah selesai dikirim. `Response` adalah turunan `http.ServerResponse`, jadi `res.statusCode`, `res.setHeader()`, dan lainnya tetap tersedia.
 
 ## Middleware Bawaan
 
@@ -278,8 +284,8 @@ app.use(App.json({ limit: 100 * 1024 })); // default 100 KB
 Perilaku:
 
 - 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 melebihi `limit` menghasilkan `413` (dicek lewat `Content-Length` dan saat streaming)
+- JSON tidak valid menghasilkan `400`, dengan error asli di `cause`
 - Body kosong menghasilkan `req.body = null`
 - Key `__proto__`, `constructor`, dan `prototype` dibuang untuk mencegah prototype pollution
 
@@ -299,7 +305,7 @@ app.use(
 
 | Opsi | Default | Keterangan |
 | --- | --- | --- |
-| `origin` | `"*"` | `"*"`, satu origin, array origin, atau `null` |
+| `origin` | `"*"` | `"*"`, satu origin, atau array origin. `null` tidak mengirim header `Access-Control-Allow-Origin` sama sekali |
 | `credentials` | `false` | Mengirim `Access-Control-Allow-Credentials: true` |
 | `headers` | - | `"*"` atau array nama header (tidak membedakan huruf besar/kecil) |
 | `methods` | - | `"*"` atau array nama method (tidak membedakan huruf besar/kecil) |
@@ -307,11 +313,13 @@ app.use(
 
 Perilaku:
 
-- Request `OPTIONS` dijawab langsung dengan `204` dan chain berhenti
-- Origin dicocokkan **persis sama** (case-sensitive) dengan header `Origin` dari request. Jika cocok, origin tersebut dipantulkan, dan header `Vary: Origin` ditambahkan pada request non-preflight
-- `Access-Control-Allow-Headers` dan `Access-Control-Allow-Methods` hanya dikirim pada preflight, dan hanya jika **semua** header atau method yang diminta ada di daftar
-- 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`
+- **Preflight** adalah request `OPTIONS` dengan header `Access-Control-Request-Method`. Preflight dijawab langsung dengan `204` dan chain berhenti. `OPTIONS` biasa diteruskan ke handler berikutnya
+- Origin dicocokkan **persis sama** (case-sensitive) dengan header `Origin` dari request. Jika cocok, origin tersebut dipantulkan dan header `Vary: Origin` ditambahkan
+- `Access-Control-Allow-Headers`: jika `headers` berupa array, header hanya dikirim bila **semua** header yang diminta ada di daftar
+- `Access-Control-Allow-Methods`: jika `methods` berupa array, header hanya dikirim bila method yang diminta ada di daftar
+- Jika `headers` atau `methods` tidak diisi, nilai yang diminta di preflight dipantulkan apa adanya
+- `"*"` untuk `headers` dan `methods` hanya dikirim sebagai `*` bila `credentials: false`. Dengan `credentials: true`, nilainya diperlakukan seperti tidak diisi (dipantulkan)
+- Pada request non-preflight, `headers` (jika array atau `"*"`) dikirim sebagai `Access-Control-Expose-Headers`
 
 > `origin: "*"` bersama `credentials: true` memantulkan **semua** origin dengan credentials. Pakai hanya untuk development; di production sebutkan origin secara eksplisit.
 
@@ -323,7 +331,7 @@ const app = new App({ cacheSize: 1000, requestTimeout: 5000 });
 
 | Opsi | Default | Keterangan |
 | --- | --- | --- |
-| `cacheSize` | `1000` | Jumlah maksimum entri LRU cache untuk hasil lookup `METHOD path`. Cache dikosongkan setiap ada route baru didaftarkan |
+| `cacheSize` | `1000` | Jumlah maksimum entri LRU cache untuk hasil lookup `METHOD path`. `0` menonaktifkan cache. Cache dikosongkan setiap ada route baru didaftarkan |
 | `requestTimeout` | `0` | Batas waktu handler dalam ms (khusus `App`). Lihat bagian [Timeout](#timeout) |
 
 `Router` hanya menerima `cacheSize`.
@@ -344,10 +352,10 @@ Mendaftarkan handler untuk method tertentu. `path` opsional; jika dihilangkan, h
 
 ### `router.find(method, path)`
 
-Mencari route tanpa menjalankannya. Hasilnya di-cache. Berguna untuk testing.
+Mencari route tanpa menjalankannya. Hasilnya di-cache dan `params`-nya di-freeze. Berguna untuk testing.
 
 ```js
-const { params, handlers, errorHandlers } = app.find("GET", "/users/1");
+const { matched, params, paramsLength, handlers, errorHandlers } = app.find("GET", "/users/1");
 ```
 
 ### `app.listen(...args)`
@@ -359,6 +367,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.8.0",
+  "version": "4.9.0",
   "description": "",
   "main": "./src/index.js",
   "scripts": {

package/src/app.js

@@ -1,8 +1,8 @@
-const http = require("node:http");
-const { Router } = require("./router.js");
-const { Request } = require("./request.js");
-const { Response } = require("./response.js");
-const { ErrorResponse } = require("./error.js");
+const http = require("http");
+const { EMPTY_PARAMS } = require("./util");
+const { Router } = require("./router");
+const { Request } = require("./request");
+const { Response } = require("./response");
 
 /**@type {import('http').ServerOptions}*/
 const SERVER_OPTIONS = {
@@ -11,41 +11,59 @@ const SERVER_OPTIONS = {
 };
 
 class App extends Router {
-    async withTimeout(req, handlerPromise) {
-        const controller = new AbortController();
-        const { signal } = controller;
-
-        req.signal = signal;
-
-        const timeout = setTimeout(() => {
-            controller.abort(ErrorResponse.status(504));
-        }, this.requestTimeout);
-
+    async withTimeout(req, res, handlerPromise) {
         let handleAbort;
         const timeoutPromise = new Promise((_, reject) => {
-            handleAbort = () => reject(signal.reason);
-            signal.addEventListener("abort", handleAbort, { once: true });
+            handleAbort = () => reject(req.controller.signal.reason);
+            req.controller.signal.addEventListener("abort", handleAbort, { once: true });
         });
 
+        const timeout = setTimeout(() => {
+            res.statusCode = 504;
+            req.controller.abort(new Error(http.STATUS_CODES[res.statusCode]));
+        }, this.requestTimeout);
+
         const promise = handlerPromise().catch((error) => {
-            if (!signal.aborted) {
-                controller.abort(error);
+            if (!req.controller.signal.aborted) {
+                req.controller.abort(error);
+            } else {
+                console.error(error); // swallow error?
             }
         });
 
-        await Promise.race([promise, timeoutPromise]).finally(() => {
-            signal.removeEventListener("abort", handleAbort);
+        try {
+            await Promise.race([promise, timeoutPromise]);
+        } finally {
             clearTimeout(timeout);
-        });
+            req.controller.signal.removeEventListener("abort", handleAbort);
+        }
+    }
+
+    fallback(res, err) {
+        if (!res.writableEnded) {
+            if (!err) {
+                res.statusCode = 404;
+                err = new Error(http.STATUS_CODES[res.statusCode]);
+            }
+            if (res.statusCode < 400) {
+                res.statusCode = 500;
+            }
+            const error = { message: err.message };
+            if (process.env.NODE_ENV === "development") {
+                error.stack = err.stack;
+            }
+            res.json({ error });
+        }
     }
 
     /**
-     * @param {import('http').IncomingMessage} req
-     * @param {import('http').ServerResponse} res
+     * @param {import('http').IncomingMessage & import('./request').Request} req
+     * @param {import('http').ServerResponse & import('./response').Response} res
      */
     async handle(req, res) {
-        const { params, handlers, errorHandlers } = this.find(req.method, req.path);
-        req.params = Object.assign(Object.create(null), params);
+        const { params, paramsLength, handlers, errorHandlers } = this.find(req.method, req.path);
+        req.params = paramsLength ? Object.assign(Object.create(null), params) : EMPTY_PARAMS;
+
         let err;
         try {
             const handlerPromise = async () => {
@@ -54,8 +72,11 @@ class App extends Router {
                     await handler(req, res);
                 }
             };
-            if (this.requestTimeout) await this.withTimeout(req, handlerPromise);
-            else await handlerPromise();
+            if (this.requestTimeout) {
+                await this.withTimeout(req, res, handlerPromise);
+            } else {
+                await handlerPromise();
+            }
         } catch (error) {
             err = error;
             try {
@@ -67,30 +88,18 @@ class App extends Router {
                 err = new Error(error.message, { cause: err });
             }
         }
-        err = this.fallback(res, err);
-    }
 
-    fallback(res, err) {
-        if (!res.writableEnded) {
-            if (!err) err = ErrorResponse.status(404);
-            res.statusCode = err.statusCode || 500;
-            const error = { message: err.message };
-            if (process.env.NODE_ENV === "development") {
-                error.stack = err.stack;
-            }
-            res.json({ error });
-        }
-        return err;
+        this.fallback(res, err);
     }
 
-    listen(...params) {
+    listen(...args) {
         const requestListener = (req, res) => this.handle(req, res);
         const server = http.createServer(SERVER_OPTIONS, requestListener);
-        server.listen(...params);
+        server.listen(...args);
         return server;
     }
 }
 
-App.SERVER_OPTIONS = SERVER_OPTIONS;
+App.SERVER_OPTIONS=SERVER_OPTIONS
 
 exports.App = App;

package/src/cache.js

@@ -13,6 +13,7 @@ class Cache {
     }
 
     set(key, value) {
+        if (this.size <= 0) return; // disabled
         if (this.map.has(key)) this.map.delete(key);
         else if (this.map.size >= this.size) {
             this.map.delete(this.map.keys().next().value);
@@ -24,5 +25,4 @@ class Cache {
         this.map.clear();
     }
 }
-
 exports.Cache = Cache;

package/src/index.js

@@ -1,8 +1,8 @@
-require("./polyfill.js");
-const { json } = require("./middleware/json.js");
-const { cors } = require("./middleware/cors.js");
-const { App } = require("./app.js");
-const { Router } = require("./router.js");
+require("./polyfill");
+const { App } = require("./app");
+const { Router } = require("./router");
+const { json } = require("./middleware/json");
+const { cors } = require("./middleware/cors");
 
 App.Router = Router;
 App.json = json;

package/src/middleware/cors.js

@@ -1,89 +1,83 @@
 /**
  * @typedef CORSOptions
- * @property {String} [origin="*"]
+ * @property {String|Array|Null} [origin="*"]
  * @property {Boolean} [credentials=false]
- * @property {String|Array} headers
+ * @property {String|Array} [headers]
  * @property {Number} [maxAge=0]
- * @property {String|Array} methods
+ * @property {String|Array} [methods]
  */
 
 /**
  * @param {CORSOptions} options
  */
 function cors({ origin = "*", credentials = false, headers, maxAge = 0, methods } = {}) {
-    if (headers && Array.isArray(headers)) {
-        headers = headers.map((header) => header.toLowerCase());
+    if (Array.isArray(headers)) {
+        headers = headers.map((h) => h.toLowerCase());
     }
-    if (methods && Array.isArray(methods)) {
-        methods = methods.map((method) => method.toUpperCase());
+    if (Array.isArray(methods)) {
+        methods = methods.map((m) => m.toUpperCase());
     }
 
-    /**
-     * @param {import('http').ServerResponse} res
-     */
     function setAllowCredentials(res) {
         if (credentials) {
             res.setHeader("Access-Control-Allow-Credentials", "true");
         }
     }
 
-    /**
-     * @param {import('http').IncomingMessage} req
-     * @param {import('http').ServerResponse} res
-     */
+    function setAllowOrigin(req, res) {
+        const reqOrigin = req.headers["origin"];
+        let value;
+        let explicit = false;
+
+        if (origin === "*" && !credentials) {
+            value = "*";
+        } else if (origin === "*" || origin === reqOrigin || (Array.isArray(origin) && origin.includes(reqOrigin))) {
+            value = reqOrigin;
+            explicit = true;
+        }
+        // origin === null -> skip (jangan set "null", celah keamanan)
+
+        if (value) res.setHeader("Access-Control-Allow-Origin", value);
+        if (explicit) res.appendHeader("Vary", "Origin");
+    }
+
     function setAllowHeaders(req, res) {
-        let reqHeaders = req.headers["access-control-request-headers"];
+        const reqHeaders = req.headers["access-control-request-headers"];
         if (!reqHeaders) return;
-        reqHeaders = reqHeaders.split(",").map((header) => header.trim().toLowerCase());
+
+        const requested = reqHeaders.split(",").map((h) => h.trim().toLowerCase());
+
         let value;
         if (headers === "*" && !credentials) {
             value = "*";
-        } else if (Array.isArray(headers) && reqHeaders.every((reqHeader) => headers.some((header) => header === reqHeader))) {
-            value = headers;
+        } else if (Array.isArray(headers)) {
+            const allowed = requested.filter((h) => headers.includes(h));
+            if (allowed.length === requested.length) value = headers;
+        } else {
+            // headers undefined -> echo request headers (wajib per spec)
+            value = requested;
         }
         if (value) res.setHeader("Access-Control-Allow-Headers", value);
     }
 
-    /**
-     * @param {import('http').IncomingMessage} req
-     * @param {import('http').ServerResponse} res
-     */
     function setAllowMethods(req, res) {
         const reqMethod = req.headers["access-control-request-method"];
         if (!reqMethod) return;
-        let value;
-        if (methods === "*" && !credentials) {
-            value = "*";
-        } else if (Array.isArray(methods) && methods.some((method) => method === reqMethod.toUpperCase())) {
-            value = methods;
-        }
-        if (value) res.setHeader("Access-Control-Allow-Methods", value);
-    }
 
-    /**
-     * @param {import('http').IncomingMessage} req
-     * @param {import('http').ServerResponse} res
-     */
-    function setAllowOrigin(req, res, preflight = true) {
-        const reqOrigin = req.headers["origin"];
+        const method = reqMethod.toUpperCase();
 
         let value;
-        let explicit;
-        if (origin === "*" && !credentials) {
+        if (methods === "*" && !credentials) {
             value = "*";
-        } else if (origin === null) {
-            value = "null";
-        } else if (origin === "*" || origin === reqOrigin || (Array.isArray(origin) && origin.some((origin) => origin === reqOrigin))) {
-            value = reqOrigin;
-            explicit = true;
+        } else if (Array.isArray(methods)) {
+            if (methods.includes(method)) value = methods;
+        } else {
+            // methods undefined -> echo request method
+            value = [method];
         }
-        if (value) res.setHeader("Access-Control-Allow-Origin", value);
-        if (!preflight && explicit) res.appendHeader("Vary", "Origin");
+        if (value) res.setHeader("Access-Control-Allow-Methods", value);
     }
 
-    /**
-     * @param {import('http').ServerResponse} res
-     */
     function setExposeHeaders(res) {
         let value;
         if (headers === "*" && !credentials) {
@@ -94,22 +88,17 @@ function cors({ origin = "*", credentials = false, headers, maxAge = 0, methods
         if (value) res.setHeader("Access-Control-Expose-Headers", value);
     }
 
-    /**
-     * @param {import('http').ServerResponse} res
-     */
     function setMaxAge(res) {
         if (maxAge > 0) {
             res.setHeader("Access-Control-Max-Age", maxAge);
         }
     }
 
-    /**
-     * @param {import('http').IncomingMessage} req
-     * @param {import('http').ServerResponse} res
-     */
     return (req, res) => {
         setAllowCredentials(res);
-        if (req.method === "OPTIONS") {
+
+        if (req.method === "OPTIONS" && req.headers["access-control-request-method"]) {
+            // preflight
             setAllowOrigin(req, res);
             setAllowHeaders(req, res);
             setAllowMethods(req, res);
@@ -118,9 +107,11 @@ function cors({ origin = "*", credentials = false, headers, maxAge = 0, methods
             res.setHeader("Content-Length", "0");
             res.end();
         } else {
-            setAllowOrigin(req, res, false);
+            // normal response (termasuk OPTIONS non-preflight)
+            setAllowOrigin(req, res);
             setExposeHeaders(res);
         }
     };
 }
+
 exports.cors = cors;

package/src/middleware/json.js

@@ -1,5 +1,4 @@
-const http = require("node:http");
-const { ErrorResponse } = require("../error.js");
+const http = require("http");
 
 function json({ limit = 100 * 1024 } = {}) {
     const reviver = (key, value) => {
@@ -18,14 +17,16 @@ function json({ limit = 100 * 1024 } = {}) {
         }
         const contentLength = parseInt(req.headers["content-length"], 10);
         if (contentLength && contentLength > limit) {
-            throw ErrorResponse.status(413);
+            res.statusCode = 413;
+            throw new Error(http.STATUS_CODES[res.statusCode]);
         }
         let chunkLength = 0;
         const chunks = [];
         for await (const chunk of req) {
             chunkLength += chunk.length;
             if (chunkLength > limit) {
-                throw ErrorResponse.status(413);
+                res.statusCode = 413;
+                throw new Error(http.STATUS_CODES[res.statusCode]);
             }
             chunks.push(chunk);
         }
@@ -36,9 +37,9 @@ function json({ limit = 100 * 1024 } = {}) {
         try {
             req.body = JSON.parse(Buffer.concat(chunks), reviver);
         } catch (error) {
-            throw new ErrorResponse({ statusCode: 400, message: "Invalid JSON body" }, { cause: error });
+            res.statusCode = 400;
+            throw new Error(http.STATUS_CODES[res.statusCode], { cause: error });
         }
     };
 }
-
 exports.json = json;

package/src/node.js

@@ -1,41 +1,32 @@
 class Node {
     constructor(segment = "") {
         this.segment = segment;
-        /**@type {Map<string, Node>}*/
-        this.staticChildren = new Map();
-        this.paramChild = null;
-        this.paramName = null;
-        this.wildcardChild = null;
-        /**@type {Map<string, Function[]>}*/
+        /** @type {Map<string, Node>} static children */
+        this.children = new Map();
+        /** @type {Map<string, Node>} param children, key = ':name' */
+        this.params = new Map();
+        /** @type {Node | null} wildcard child */
+        this.wildcard = null;
         this.handlers = new Map();
     }
-    /**
-     * @param {String} segment
-     * @returns {Node}
-     */
+
     add(segment) {
+        if (segment === "*") {
+            if (!this.wildcard) this.wildcard = new Node("*");
+            return this.wildcard;
+        }
+
         if (segment.startsWith(":")) {
-            if (this.paramChild) return this.paramChild;
-            this.paramChild = new Node(segment);
-            this.paramChild.paramName = segment.slice(1);
-            this.paramChild.type = "param";
-            return this.paramChild;
-        } else if (segment.startsWith("*")) {
-            if (this.wildcardChild) return this.wildcardChild;
-            this.wildcardChild = new Node(segment);
-            this.wildcardChild.type = "wildcard";
-            return this.wildcardChild;
-        } else {
-            return this.staticChildren.getOrInsertComputed(segment, (segment) => {
-                const node = new Node(segment);
-                node.type = "wildcard";
-                return node;
+            return this.params.getOrInsertComputed(segment, (segment) => {
+                return new Node(segment);
             });
         }
+
+        return this.children.getOrInsertComputed(segment, (segment) => {
+            return new Node(segment);
+        });
     }
-    /**
-     * @param {Node} node
-     */
+
     merge(node, offset) {
         for (const [method, entries] of node.handlers) {
             for (const entry of entries) {
@@ -46,37 +37,41 @@ class Node {
             }
         }
 
-        if (node.paramChild) {
-            this.add(node.paramChild.segment).merge(node.paramChild, offset);
+        if (node.wildcard) {
+            this.add("*").merge(node.wildcard, offset);
         }
-        if (node.wildcardChild) {
-            this.add(node.wildcardChild.segment).merge(node.wildcardChild, offset);
+
+        for (const [segment, child] of node.params) {
+            this.add(segment).merge(child, offset);
         }
-        for (const [segment, child] of node.staticChildren) {
+
+        for (const [segment, child] of node.children) {
             this.add(segment).merge(child, offset);
         }
     }
 
     getMaxSeq() {
         let max = -1;
-        for (const [method, entries] of this.handlers) {
+
+        for (const [, entries] of this.handlers) {
             for (const entry of entries) {
                 max = Math.max(max, entry.seq);
             }
         }
 
-        if (this.paramChild) {
-            max = Math.max(max, this.paramChild.getMaxSeq());
+        if (this.wildcard) {
+            max = Math.max(max, this.wildcard.getMaxSeq());
         }
-        if (this.wildcardChild) {
-            max = Math.max(max, this.wildcardChild.getMaxSeq());
+
+        for (const [, child] of this.params) {
+            max = Math.max(max, child.getMaxSeq());
         }
-        for (const [path, child] of this.staticChildren) {
+
+        for (const [, child] of this.children) {
             max = Math.max(max, child.getMaxSeq());
         }
 
         return max;
     }
 }
-
 exports.Node = Node;

package/src/request.js

@@ -1,32 +1,37 @@
-const http = require("node:http");
-const { parseUrl, parseQueryString } = require("./util.js");
+const http = require("http");
+const { parseUrl, parseQueryString } = require("./util");
 
 class Request extends http.IncomingMessage {
     _path;
-    _parsed;
+    _queryString;
     _query;
-    params = {};
-    signal;
+    _controller;
+
     get path() {
-        if (this._path) return this._path;
-        if (!/[?#]/.test(this.url)) {
-            this._path = this.url;
-            return this._path;
+        if (!this._path) {
+            const { path, queryString } = parseUrl(this.url);
+            this._path = path;
+            this._queryString = queryString;
         }
-        this._parsed = parseUrl(this.url);
-        this._path = this._parsed.path;
+
         return this._path;
     }
 
     get query() {
-        if (this._query) return this._query;
-        if (!this._parsed) {
-            this._query = Object.create(null);
-            return this._query;
+        if (!this._query) {
+            this._query = parseQueryString(this._queryString);
         }
-        this._query = parseQueryString(this._parsed.queryString);
         return this._query;
     }
-}
 
+    /**
+     * @returns {AbortController}
+     */
+    get controller() {
+        if (!this._controller) {
+            this._controller = new AbortController();
+        }
+        return this._controller;
+    }
+}
 exports.Request = Request;

package/src/response.js

@@ -1,22 +1,19 @@
-const http = require("node:http");
+const http = require("http");
 
 class Response extends http.ServerResponse {
-    status(statusCode) {
-        this.statusCode = statusCode;
+    status(code) {
+        this.statusCode = code;
         return this;
     }
     send(chunk) {
         if (this.writableEnded) return;
-        this.end(chunk, null, null); //avoid ArgumentsAdaptorTrampoline from V8
+        this.end(chunk, null, null);
     }
     json(value) {
-        if (this.writableEnded) return;
-        if (this.headersSent) {
-            this.end();
-            return;
+        if (!this.headersSent) {
+            this.setHeader("Content-Type", "application/json; charset=utf-8");
         }
-        this.setHeader("Content-Type", "application/json");
-        this.end(JSON.stringify(value), null, null); //avoid ArgumentsAdaptorTrampoline from V8
+        this.send(JSON.stringify(value));
     }
 }
 exports.Response = Response;

package/src/router.js

@@ -1,6 +1,6 @@
-const { Node } = require("./node.js");
-const { Cache } = require("./cache.js");
-const { decodePathParam } = require("./util.js");
+const { decodeParam } = require("./util");
+const { Node } = require("./node");
+const { Cache } = require("./cache");
 
 class Router {
     constructor(options = {}) {
@@ -22,10 +22,12 @@ class Router {
             handlers = [path, ...handlers];
             path = null;
         }
+
         let node = this.root;
+
         if (path) {
-            for (const part of this.split(path)) {
-                node = node.add(part);
+            for (const segment of this.split(path)) {
+                node = node.add(segment);
             }
         }
 
@@ -34,8 +36,8 @@ class Router {
                 node.merge(handler.root, this.seq);
                 this.seq += handler.root.getMaxSeq() + 1;
             } else {
-                const newMethod = handler.length === 3 ? "CATCH" : method;
-                node.handlers.getOrInsert(newMethod, []).push({
+                const key = handler.length === 3 ? "CATCH" : method;
+                node.handlers.getOrInsert(key, []).push({
                     handler,
                     seq: this.seq++,
                 });
@@ -98,96 +100,127 @@ class Router {
         return this;
     }
 
-    collectMiddleware(node, handlers, errorHandlers) {
-        if (node.handlers.has("ALL")) {
-            for (const entry of node.handlers.get("ALL")) {
-                handlers[entry.seq] = entry.handler;
-            }
-        }
-        if (node.handlers.has("CATCH")) {
-            for (const entry of node.handlers.get("CATCH")) {
-                errorHandlers[entry.seq] = entry.handler;
-            }
-        }
-    }
-
-    collectHandler(node, method, handlers) {
-        if (node && node.handlers.has(method)) {
-            for (const entry of node.handlers.get(method)) {
-                handlers[entry.seq] = entry.handler;
-            }
-        }
-    }
-
     /**
      * @param {Node} node
-     * @param {*} parts
-     * @param {*} i
-     * @param {*} params
-     * @param {*} path
-     * @returns
+     * @param {string[]} segments
+     * @param {number} index
+     * @param {Node[]} path
+     * @param {Record<string, string>} params
+     * @param {{ best: { nodes: Node[], params: Record<string, string> } }} state
+     * @returns {{ nodes: Node[], params: Record<string, string>, matched: boolean }}
      */
-    search(node, parts, i, params, path) {
-        if (!node) return null;
+    search(node, segments, index, path, params, state) {
         path.push(node);
-        if (i === parts.length) return path;
 
-        const part = parts[i];
+        // habis segmen -> full match
+        if (index === segments.length) {
+            return { nodes: path.slice(), params: { ...params }, matched: true };
+        }
+
+        const segment = segments[index];
+
+        // 1. static (prioritas tertinggi)
+        const staticChild = node.children.get(segment);
+        if (staticChild) {
+            const res = this.search(staticChild, segments, index + 1, path, params, state);
+            if (res.matched) return res;
+        }
 
-        if (node.staticChildren.has(part)) {
-            const r = this.search(node.staticChildren.get(part), parts, i + 1, params, path);
-            if (r) return r;
+        // 2. semua param child (bisa lebih dari satu)
+        for (const [key, child] of node.params) {
+            const name = key.slice(1); // buang ':'
+            const prev = params[name];
+            params[name] = decodeParam(segment);
+            const res = this.search(child, segments, index + 1, path, params, state);
+            if (res.matched) return res;
+            // backtrack param value
+            if (prev === undefined) delete params[name];
+            else params[name] = prev;
         }
 
-        if (node.paramChild) {
-            const saved = params[node.paramChild.paramName];
-            params[node.paramChild.paramName] = decodePathParam(part);
-            const r = this.search(node.paramChild, parts, i + 1, params, path);
-            if (r) return r;
-            if (saved === undefined) delete params[node.paramChild.paramName];
-            else params[node.paramChild.paramName] = saved;
+        // 3. wildcard (prioritas terendah, menyerap sisa segmen)
+        if (node.wildcard) {
+            const rest = segments.slice(index).join("/");
+            params["wildcard"] = decodeParam(rest);
+            path.push(node.wildcard);
+            return { nodes: path.slice(), params: { ...params }, matched: true };
         }
 
-        if (node.wildcardChild) {
-            params[0] = decodePathParam(parts.slice(i).join("/"));
-            path.push(node.wildcardChild);
-            return path;
+        // tidak match di sini -> update partial terpanjang
+        // path.length > state.best.nodes.length artinya kita sudah lebih dalam
+        if (path.length > state.best.nodes.length) {
+            state.best = { nodes: path.slice(), params: { ...params } };
         }
 
         path.pop();
-        return null;
+        return { matched: false };
+    }
+
+    collectHandler(r, method, handlers) {
+        if (r.handlers.has(method)) {
+            for (const entry of r.handlers.get(method)) {
+                handlers[entry.seq] = entry.handler;
+            }
+        }
+    }
+
+    collectErrorHandler(r, errorHandlers) {
+        if (r.handlers.has("CATCH")) {
+            for (const entry of r.handlers.get("CATCH")) {
+                errorHandlers[entry.seq] = entry.handler;
+            }
+        }
+    }
+
+    collectMiddleware(r, handlers, errorHandlers) {
+        this.collectHandler(r, "ALL", handlers);
+        this.collectErrorHandler(r, errorHandlers);
     }
 
     find(method, path) {
         const key = `${method} ${path}`;
+
         const cached = this.cache.get(key);
         if (cached) return cached;
 
-        const parts = this.split(path);
-        const params = {};
-        const nodePath = [];
-        const result = this.search(this.root, parts, 0, params, nodePath);
+        const segments = this.split(path);
 
+        const params = {};
         const handlers = {};
         const errorHandlers = {};
 
-        if (result) {
-            for (const n of result) {
-                this.collectMiddleware(n, handlers, errorHandlers);
-            }
-            this.collectHandler(result[result.length - 1], method, handlers);
-        } else {
-            this.collectMiddleware(this.root, handlers, errorHandlers);
+        /** @type {{ best: { nodes: Node[], params: Record<string, string> } }} */
+        const state = { best: { nodes: [], params: {} } };
+
+        const res = this.search(this.root, segments, 0, [], params, state);
+
+        const matchedNodes = res.matched ? res.nodes : state.best.nodes;
+        const finalParams = res.matched ? res.params : state.best.params;
+
+        // middleware dari semua node di jalur (partial atau full)
+        for (const r of matchedNodes) {
+            this.collectMiddleware(r, handlers, errorHandlers);
+        }
+
+        // method handler HANYA kalau full match
+        if (res.matched) {
+            const leaf = matchedNodes[matchedNodes.length - 1];
+            this.collectHandler(leaf, method, handlers);
         }
 
-        const value = {
-            params,
+        Object.freeze(finalParams);
+
+        const result = {
+            matched: res.matched,
+            params: finalParams,
+            paramsLength: Object.keys(finalParams).length,
             handlers: Object.values(handlers),
             errorHandlers: Object.values(errorHandlers),
         };
-        this.cache.set(key, value);
 
-        return value;
+        this.cache.set(key, result);
+
+        return result;
     }
 }
 exports.Router = Router;

package/src/util.js

@@ -1,46 +1,48 @@
-function decodeQueryParam(encoded) {
-    const normalize = encoded.replace(/\+/g, " ");
+const EMPTY_PARAMS = Object.freeze(Object.create(null));
+exports.EMPTY_PARAMS = EMPTY_PARAMS;
+
+function decodeParam(raw) {
     try {
-        return decodeURIComponent(normalize);
+        return decodeURIComponent(raw);
     } catch (error) {
-        return normalize;
+        return raw;
     }
 }
-exports.decodeQueryParam = decodeQueryParam;
+exports.decodeParam = decodeParam;
 
-function decodePathParam(encoded) {
+function decodeQuery(raw) {
+    const normalized = raw.replace(/\+/g, " ");
     try {
-        return decodeURIComponent(encoded);
-    } catch {
-        return encoded;
+        return decodeURIComponent(normalized);
+    } catch (error) {
+        return normalized;
     }
 }
 
-exports.decodePathParam = decodePathParam;
-
 function parseQueryString(queryString) {
-    const query = Object.create(null);
-    if (!queryString) return query;
-    const regex = /([^=&]*)?=([^&]*)?/g;
+    if (queryString === "") return Object.create(null);
+    const regex = /([^=&]*)=([^&]*)/g;
     let match;
+    const result = Object.create(null);
     while ((match = regex.exec(queryString))) {
-        const [, rawName = "", rawValue = ""] = match;
-        const name = decodeQueryParam(rawName);
-        const value = decodeQueryParam(rawValue);
-        if (Object.hasOwn(query, name)) {
-            if (Array.isArray(query[name])) query[name].push(value);
-            else query[name] = [query[name], value];
-        } else {
-            query[name] = value;
-        }
+        const [, rawName, rawValue] = match;
+        const name = decodeQuery(rawName);
+        const value = decodeQuery(rawValue);
+        if (Object.hasOwn(result, name)) {
+            if (Array.isArray(result[name])) result[name].push(value);
+            else result[name] = [result[name], value];
+        } else result[name] = value;
     }
-    return query;
+    return result;
 }
 exports.parseQueryString = parseQueryString;
 
 function parseUrl(url) {
+    if (!(url.includes("?") || url.includes("#"))) {
+        return { path: url, queryString: "" };
+    }
     const regex = /^([^?#]*)(\?([^#]*))?(#.*)?$/;
     const [, path = "/", , queryString = ""] = regex.exec(url);
-    return { path: path || "/", queryString };
+    return { path, queryString };
 }
 exports.parseUrl = parseUrl;

package/src/error.js

@@ -1,26 +0,0 @@
-const http = require("node:http");
-
-// Client error responses (400 – 499)
-// Server error responses (500 – 599)
-class ErrorResponse extends Error {
-    constructor({ statusCode, message } = {}, options) {
-        super(message, options);
-        this.name = this.constructor.name;
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, this.constructor);
-        }
-        this.statusCode = statusCode;
-    }
-
-    static status(statusCode, options) {
-        return new ErrorResponse(
-            {
-                statusCode,
-                message: http.STATUS_CODES[statusCode],
-            },
-            options,
-        );
-    }
-}
-
-exports.ErrorResponse = ErrorResponse;