peepal-router 0.1.0

package/README.md

@@ -0,0 +1,209 @@
+![Trie Structure](assets/peepar.jpeg)
+# Peepar
+
+A fast and minimal Trie based HTTP router.
+
+Peepar name is inspired by the **Peepal (Sacred fig) tree**, known for its deep roots and branching structure. Just like the tree, Peepar organizes routes using a Trie data structure, enabling fast and predictable path matching with very low overhead.
+
+---
+
+## Features
+
+* Trie based routing for fast lookups
+* Zero dependencies
+* Very small footprint
+* Middleware chaining support
+* Dynamic route parameters
+* Wildcard route matching
+* Works in Node.js and Bun
+* TypeScript types included
+* Inbuilt params parser
+* Inbuilt query string parser
+
+---
+
+## Installation
+
+```bash
+npm install peepar
+```
+
+---
+
+## Basic Usage
+
+```js
+import { TrieRouter } from "peepar";
+
+const router = new TrieRouter();
+
+// Global Middleware
+router.pushMiddleware('/', function GlobalMiddleware1() => 'global middleware')
+router.pushMiddleware('/', function Middleware2() => 'global middleware 2')
+
+
+router.add("GET", "/", function handler () => "home");
+
+const matchedhandler = router.search("GET", "/");
+
+Output:
+  {
+    params: {},
+    handler: [GlobalMiddleware1,GlobalMiddleware2,handler]
+  }
+
+// Route specific middleware
+router.pushMiddleware("/users", function userMiddleware(ctx) => {
+  console.log("/users middleware");
+});
+router.add("GET", "/users/:id", function userHandler() => "user profile");
+
+const result = router.find("GET", "/users/42");
+// /users/42 is incoming path from the server
+const params = router.parseParams('/users/42',result.params); 
+// you will have to manually parse params until we support inbuilt params parse inside our router seach method.
+
+```
+
+Output:
+
+```js
+{
+  params: { id: 1 }, // id : 1 is'nt real params , it's just index of ":id" in path
+  handler: [GlobalMiddleware1,GlobalMiddleware2,userMiddleware,userHandler]
+}
+
+// params
+{ id: 42 }
+
+```
+
+---
+
+## Middleware
+ - peepar supports global and route specific middleware
+
+Global middleware:
+
+```js
+router.pushMiddleware("/", (ctx) => {
+  console.log("global middleware");
+});
+```
+
+Route specific middleware:
+
+```js
+router.pushMiddleware("/users", (ctx) => {
+  console.log("/users middleware");
+});
+```
+
+---
+
+## Wildcard Routes
+
+```js
+router.add("GET", "/static/*", () => "HTML page");
+```
+
+Matches:
+
+* /static/app.js
+* /static/css/style.css
+* /static/images/logo.png
+
+---
+
+## Performance
+
+Peepar is designed for speed and low allocation during hot path. we try to minimise allocation and make our fast as much as possible.
+
+Key design goals:
+
+* Try to Avoid unnecessary allocations in hot path
+* Minimal overhead during lookup
+* Fast static and dynamic route matching
+* Lightweight and cache friendly structure
+
+---
+
+## API
+
+### router.add(method, path, handler)
+### router.insert(method, path, handler)
+
+
+Register a route.
+
+### router.pushMiddleware(path, middleware)
+
+Register middleware for a path or globally.
+
+### router.search(method, path)
+### router.find(method, path)
+
+Find matching route and collect handlers.
+
+Returns:
+
+```ts
+{
+  params: Record<string, number>;
+  handler: Function[];
+}
+```
+
+---
+
+## Example
+
+```js
+import { TrieRouter } from "peepar";
+
+const router = new TrieRouter();
+
+router.pushMiddleware("/", () => console.log("global"));
+router.pushMiddleware("/api/*", () => console.log("api middleware"));
+
+router.add("GET", "/api/users/:id", () => console.log("user handler"));
+
+const res = router.find("GET", "/api/users/100");
+
+for (const fn of res.handler) {
+  fn();
+}
+```
+
+---
+
+## Roadmap
+
+* Route priority improvements
+* Param parsing inbuilt in search method
+* Optional parameter support
+* Regex based params
+* Zero allocation path parser
+* Extended benchmarking
+
+---
+
+## Contributing
+
+Contributions, ideas, and performance improvements are welcome.
+
+If you find a bug or want to improve performance, open an issue or submit a pull request.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+Pradeep Kumar
+
+GitHub: [https://github.com/pradeepbgs/peepar-router](https://github.com/pradeepbgs/peepar-router)

package/dist/router.d.ts

@@ -0,0 +1,26 @@
+declare class TrieNodes {
+    children: Record<string, TrieNodes>;
+    isEndOfWord: boolean;
+    handlers: Record<string, Function>;
+    middlewares: Function[];
+    params: Record<string, number>;
+    constructor();
+}
+export declare class TrieRouter {
+    root: TrieNodes;
+    globalMiddlewares: Function[];
+    constructor();
+    pushMiddleware(path: string, handlers: Function | Function[]): void;
+    insert(method: string, path: string, handler: Function): void;
+    add(method: string, path: string, handler: Function): void;
+    search(method: string, path: string): {
+        params: Record<string, number>;
+        handler: Function[];
+    };
+    find(method: string, path: string): {
+        params: Record<string, number>;
+        handler: Function[];
+    };
+    parseParams(inComingpath: string | null, param: Record<string, number> | null): Record<string, any>;
+}
+export {};

package/dist/router.js

@@ -0,0 +1,124 @@
+class TrieNodes {
+    constructor() {
+        this.children = {};
+        this.handlers = {};
+        this.isEndOfWord = false;
+        this.middlewares = [];
+        this.params = {};
+    }
+}
+//
+export class TrieRouter {
+    constructor() {
+        this.root = new TrieNodes();
+        this.globalMiddlewares = [];
+    }
+    pushMiddleware(path, handlers) {
+        if (!Array.isArray(handlers))
+            handlers = [handlers];
+        if (path === "/") {
+            this.globalMiddlewares.push(...handlers);
+            return;
+        }
+        let node = this.root;
+        const pathSegments = path.split("/").filter(Boolean);
+        for (const element of pathSegments) {
+            let key = element;
+            if (element.startsWith(":")) {
+                key = ":";
+            }
+            else if (element.startsWith("*")) {
+                node.middlewares.push(...handlers);
+            }
+            if (!node.children[key])
+                node.children[key] = new TrieNodes();
+            node = node.children[key];
+        }
+        node.middlewares.push(...handlers);
+        // node.isEndOfWord = true
+    }
+    insert(method, path, handler) {
+        let node = this.root;
+        const pathSegments = path.split("/").filter(Boolean);
+        // handle if path is /
+        if (path === "/") {
+            node.isEndOfWord = true;
+            node.handlers[method] = handler;
+            return;
+        }
+        let routeparams = {};
+        for (let i = 0; i < pathSegments.length; i++) {
+            const element = pathSegments[i];
+            let key = element;
+            let cleanParam = '';
+            if (element.startsWith(":")) {
+                key = ":";
+                cleanParam = element.slice(1);
+            }
+            if (!node.children[key])
+                node.children[key] = new TrieNodes();
+            node = node.children[key];
+            if (cleanParam) {
+                routeparams[cleanParam] = i;
+            }
+        }
+        node.params = routeparams;
+        node.handlers[method] = handler;
+        node.isEndOfWord = true;
+    }
+    add(method, path, handler) {
+        return this.insert(method, path, handler);
+    }
+    search(method, path) {
+        let node = this.root;
+        const pathSegments = path.split("/");
+        let collected = this.globalMiddlewares.slice();
+        for (let i = 0; i < pathSegments.length; i++) {
+            const element = pathSegments[i];
+            if (element.length === 0) {
+                continue;
+            }
+            if (node.children[element]) {
+                node = node.children[element];
+            }
+            else if (node.children[":"]) {
+                node = node.children[":"];
+            }
+            else if (node.children["*"]) {
+                node = node.children["*"];
+                break;
+            }
+            else {
+                return { params: node.params, handler: collected };
+            }
+            if (node.middlewares.length > 0) {
+                const mw = node.middlewares;
+                for (let j = 0; j < mw.length; j++) {
+                    collected.push(mw[j]);
+                }
+            }
+        }
+        const methodHandler = node.handlers[method];
+        if (methodHandler)
+            collected.push(methodHandler);
+        return {
+            params: node.params,
+            handler: collected,
+        };
+    }
+    find(method, path) {
+        return this.search(method, path);
+    }
+    // param parser
+    parseParams(inComingpath, param) {
+        const paramObject = {};
+        const pathWithoutQuery = inComingpath?.split('?')[0];
+        // URL = /user/id/register?name=pradeep
+        // [ "/user/id/register", "name=pradeep" ]
+        const paths = pathWithoutQuery?.split('/').filter(Boolean);
+        for (const key in param) {
+            paramObject[key] = paths?.[param[key]];
+        }
+        return paramObject;
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "peepal-router",
+  "version": "0.1.0",
+  "description": "a fast and minimal trie based http router",
+  "keywords": [
+    "http-router",
+    "trie-router",
+    "hono",
+    "diesel",
+    "express-router",
+    "radix-tree",
+    "tree"
+  ],
+  "homepage": "https://github.com/pradeepbgs/peepar-router#readme",
+  "bugs": {
+    "url": "https://github.com/pradeepbgs/peepar-router/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pradeepbgs/peepar-router.git"
+  },
+  "license": "MIT",
+  "author": "pradeepkumar",
+  "type": "module",
+  "main": "dist/router.js",
+  "types": "dist/router.d.ts",
+  "files": ["dist"],
+  "scripts": {
+      "build": "tsc",
+      "prepublishOnly": "npm run build"
+    },
+  "private": false,
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}