@ndiinginc/router 4.11.1 → 4.12.0

package/package.json

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

package/src/app.js

@@ -1,5 +1,4 @@
 const http = require("http");
-const { EMPTY_PARAMS } = require("./util");
 const { Router } = require("./router");
 const { Request } = require("./request");
 const { Response } = require("./response");
@@ -11,6 +10,11 @@ const SERVER_OPTIONS = {
 };
 
 class App extends Router {
+    /**
+     * @param {Request} req
+     * @param {Response} res
+     * @param {Promise} handlerPromise
+     */
     async withTimeout(req, res, handlerPromise) {
         let handleAbort;
         const timeoutPromise = new Promise((_, reject) => {
@@ -35,6 +39,10 @@ class App extends Router {
         }
     }
 
+    /**
+     * @param {Response} res
+     * @param {Error} err
+     */
     fallback(res, err) {
         if (!res.writableEnded) {
             if (!err) {
@@ -53,12 +61,12 @@ class App extends Router {
     }
 
     /**
-     * @param {import('http').IncomingMessage & import('./request').Request} req
-     * @param {import('http').ServerResponse & import('./response').Response} res
+     * @param {Request} req
+     * @param {Response} res
      */
     async handle(req, res) {
         const { params, paramsLength, handlers, errorHandlers } = this.find(req.method, req.path);
-        req.params = paramsLength ? Object.assign(Object.create(null), params) : EMPTY_PARAMS;
+        req.params = paramsLength ? Object.assign(Object.create(null), params) : Object.create(null);
         let err;
         try {
             const handlerPromise = async () => {
@@ -86,6 +94,10 @@ class App extends Router {
         this.fallback(res, err);
     }
 
+    /**
+     * @param  {import('net').ListenOptions} args
+     * @returns {import('http').Server}
+     */
     listen(...args) {
         const requestListener = (req, res) => this.handle(req, res);
         const server = http.createServer(SERVER_OPTIONS, requestListener);

package/src/middleware/cors.js

@@ -1,14 +1,21 @@
 /**
- * @typedef CORSOptions
- * @property {String|Array|Null} [origin="*"]
- * @property {Boolean} [credentials=false]
- * @property {String|Array} [headers]
- * @property {Number} [maxAge=0]
- * @property {String|Array} [methods]
+ * @typedef {Object} Options
+ * @property {string|array} origin
+ * @property {boolean} credentials
+ * @property {string|array} headers
+ * @property {Number} maxAge
+ * @property {string|array} methods
  */
 
 /**
- * @param {CORSOptions} options
+ * @callback Callback
+ * @param {import('../request')} req
+ * @param {import('../response')} res
+ */
+
+/**
+ * @param {Options} Options
+ * @returns {Callback}
  */
 function cors({ origin = "*", credentials = false, headers, maxAge = 0, methods } = {}) {
     if (Array.isArray(headers)) {

package/src/middleware/json.js

@@ -1,6 +1,20 @@
 const http = require("http");
+/**
+ * @typedef {Object} Options
+ * @property {Number} [limit=1.024e+5]
+ */
 
-function json({ limit = 100 * 1024 } = {}) {
+/**
+ * @callback Callback
+ * @param {import('../request')} req
+ * @param {import('../response')} res
+ */
+
+/**
+ * @param {Options} Options
+ * @returns {Callback}
+ */
+function json({ limit = 1.024e5 } = {}) {
     const reviver = (key, value) => {
         if (key === "__proto__" || key === "constructor" || key === "prototype") {
             return undefined;

package/src/node.js

@@ -1,18 +1,30 @@
 class Node {
+    /**
+     * @param {String} segment
+     */
     constructor(segment = "") {
         this.segment = segment;
         if (segment.startsWith(":")) {
+            /**@type {String}*/
             this.name = segment.slice(1);
         }
-        /** @type {Map<string, Node>} static children */
+
+        /**@type {Map<string,Node>}*/
         this.children = new Map();
-        /** @type {Map<string, Node>} param children, key = ':name' */
+
+        /**@type {Map<string,Node>}*/
         this.params = new Map();
-        /** @type {Node | null} wildcard child */
+
+        /**@type {Node}*/
         this.wildcard = null;
+        /**@type {Map<string,Function[]>}*/
         this.handlers = new Map();
     }
 
+    /**
+     * @param {String} segment
+     * @returns {Node}
+     */
     add(segment) {
         if (segment === "*") {
             if (!this.wildcard) this.wildcard = new Node("*");
@@ -28,6 +40,10 @@ class Node {
         });
     }
 
+    /**
+     * @param {Node} node
+     * @param {Number} offset
+     */
     merge(node, offset) {
         for (const [method, entries] of node.handlers) {
             for (const entry of entries) {
@@ -48,6 +64,9 @@ class Node {
         }
     }
 
+    /**
+     * @returns {Number}
+     */
     getMaxSeq() {
         let max = -1;
         for (const [, entries] of this.handlers) {

package/src/request.js

@@ -23,9 +23,6 @@ class Request extends http.IncomingMessage {
         return this._query;
     }
 
-    /**
-     * @returns {AbortController}
-     */
     get controller() {
         if (!this._controller) {
             this._controller = new AbortController();

package/src/response.js

@@ -1,16 +1,26 @@
 const http = require("http");
 
 class Response extends http.ServerResponse {
+    /**
+     * @param {Number} code
+     * @returns {Response}
+     */
     status(code) {
         this.statusCode = code;
         return this;
     }
 
+    /**
+     * @param {String} chunk
+     */
     send(chunk) {
         if (this.writableEnded) return;
         this.end(chunk, null, null);
     }
 
+    /**
+     * @param {Object} value
+     */
     json(value) {
         if (!this.headersSent) {
             this.setHeader("Content-Type", "application/json; charset=utf-8");

package/src/router.js

@@ -1,17 +1,34 @@
 const { decodeParam } = require("./util");
 const { Node } = require("./node");
 
+/**
+ * @typedef {Object} Options
+ * @property {Number} requestTimeout
+ */
+
 class Router {
+    /**
+     * @param {Options} options
+     */
     constructor(options = {}) {
         this.requestTimeout = options.requestTimeout ?? 0;
         this.root = new Node();
         this.seq = 0;
     }
 
+    /**
+     * @param {String} path
+     * @returns {String[]}
+     */
     split(path) {
         return path.split("/").filter(Boolean);
     }
 
+    /**
+     * @param {String} method
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     */
     add(method, path, ...handlers) {
         if (typeof path === "function") {
             handlers = [path, ...handlers];
@@ -37,69 +54,125 @@ class Router {
         }
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     use(path, ...handlers) {
         this.add("ALL", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     get(path, ...handlers) {
         this.add("GET", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     query(path, ...handlers) {
         this.add("QUERY", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     head(path, ...handlers) {
         this.add("HEAD", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     options(path, ...handlers) {
         this.add("OPTIONS", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     trace(path, ...handlers) {
         this.add("TRACE", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     put(path, ...handlers) {
         this.add("PUT", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     delete(path, ...handlers) {
         this.add("DELETE", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     post(path, ...handlers) {
         this.add("POST", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     patch(path, ...handlers) {
         this.add("PATCH", path, ...handlers);
         return this;
     }
 
+    /**
+     * @param {String|Function} path
+     * @param  {Function[]} handlers
+     * @returns {this}
+     */
     connect(path, ...handlers) {
         this.add("CONNECT", path, ...handlers);
         return this;
     }
 
     /**
+     * @param {String} method
+     * @param {String[]} segments
      * @param {Node} node
-     * @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 }}
+     * @param {Array} path
+     * @param {Object} params
+     * @param {Object} state
+     * @param {Number} index
+     * @returns {{path:Array,params:Object,matched:Boolean}}
      */
     search(method, segments, node, path = [], params = {}, state = { path: [], params: {} }, index = 0) {
         path.push(node);
@@ -163,6 +236,11 @@ class Router {
         return { path: state.path, params: state.params, matched: false };
     }
 
+    /**
+     * @param {Node} r
+     * @param {String} method
+     * @param {Object} handlers
+     */
     collectHandler(r, method, handlers) {
         if (r.handlers.has(method)) {
             for (const entry of r.handlers.get(method)) {
@@ -171,11 +249,21 @@ class Router {
         }
     }
 
+    /**
+     * @param {Node} r
+     * @param {Object} handlers
+     * @param {Object} errorHandlers
+     */
     collectMiddleware(r, handlers, errorHandlers) {
         this.collectHandler(r, "ALL", handlers);
         this.collectHandler(r, "CATCH", errorHandlers);
     }
 
+    /**
+     * @param {String} method
+     * @param {String} path
+     * @returns {{matched: boolean;params: Object;paramsLength: number;handlers: any[];errorHandlers: any[];}}
+     */
     find(method, path) {
         const res = this.search(
             //

package/src/util.js

@@ -1,6 +1,7 @@
-const EMPTY_PARAMS = Object.create(null);
-exports.EMPTY_PARAMS = EMPTY_PARAMS;
-
+/**
+ * @param {String} raw
+ * @returns {String}
+ */
 function decodeParam(raw) {
     try {
         return decodeURIComponent(raw);
@@ -10,40 +11,44 @@ function decodeParam(raw) {
 }
 exports.decodeParam = decodeParam;
 
-function decodeQuery(raw) {
-    const normalized = raw.replace(/\+/g, " ");
-    try {
-        return decodeURIComponent(normalized);
-    } catch (error) {
-        return normalized;
-    }
-}
-
+/**
+ * @param {String} queryString
+ * @returns {Object}
+ */
 function parseQueryString(queryString) {
-    if (queryString === "") return Object.create(null);
-    const regex = /([^=&]*)=([^&]*)/g;
-    const result = Object.create(null);
-    let match;
-    while ((match = regex.exec(queryString))) {
-        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;
+    const query = Object.create(null);
+    if (queryString) {
+        for (const [name, value] of new URLSearchParams(queryString)) {
+            if (Object.hasOwn(query, name)) {
+                if (Array.isArray(query[name])) query[name].push(value);
+                else query[name] = [query[name], value];
+            } else query[name] = value;
+        }
     }
-
-    return result;
+    return query;
 }
 exports.parseQueryString = parseQueryString;
 
+/**
+ * @param {String} url
+ * @returns {{path: any;queryString: any;}}
+ */
 function parseUrl(url) {
-    if (!(url.includes("?") || url.includes("#"))) {
-        return { path: url, queryString: "" };
+    let path = url;
+    let queryString = "";
+    let hash = "";
+    if (url.includes("?") || url.includes("#")) {
+        const hashIdx = url.indexOf("#");
+        if (hashIdx !== -1) {
+            hash = url.slice(hashIdx + 1);
+            path = url.slice(0, hashIdx);
+        }
+        const queryIdx = path.indexOf("?");
+        if (queryIdx !== -1) {
+            queryString = path.slice(queryIdx + 1);
+            path = path.slice(0, queryIdx);
+        }
     }
-    const regex = /^([^?#]*)(\?([^#]*))?(#.*)?$/;
-    const [, path = "/", , queryString = ""] = regex.exec(url);
-    return { path, queryString };
+    return { path, queryString, hash };
 }
 exports.parseUrl = parseUrl;