extreme-router 1.0.0

package/docs/examples/server.deno.md

@@ -0,0 +1,71 @@
+```typescript
+// server.deno.ts
+// @deno-types="npm:extreme-router/dist/index.d.ts"
+import Extreme, { param, wildcard } from 'npm:extreme-router';
+
+// Define the type for your route store, mapping methods to handlers
+type MethodHandler = (req: Request, params?: Record<string, string>) => Response | Promise<Response>;
+type RouteStore = {
+  [method: string]: MethodHandler; // e.g., GET, POST
+};
+
+// Initialize the router
+const router = new Extreme<RouteStore>();
+
+// Register plugins (chaining supported)
+router.use(param).use(wildcard);
+
+// --- Define Handlers ---
+const homeHandler: MethodHandler = () => new Response('Welcome Home! (GET)');
+const createUserHandler: MethodHandler = async (req) => {
+  const body = await req.text();
+  return new Response(`Creating user... (POST) Data: ${body}`, { status: 201 });
+};
+const userHandler: MethodHandler = (req, params) => new Response(`User ID: ${params?.userId} (GET)`);
+const updateUserHandler: MethodHandler = async (req, params) => {
+  const body = await req.text();
+  return new Response(`Updating user ${params?.userId}... (PUT) Data: ${body}`);
+};
+const fileHandler: MethodHandler = (req, params) => new Response(`File path: ${params?.['*']} (GET)`);
+const notFoundHandler: MethodHandler = () => new Response('Not Found', { status: 404 });
+const methodNotAllowedHandler: MethodHandler = () => new Response('Method Not Allowed', { status: 405 });
+
+// --- Register Routes and Methods ---
+router.register('/').GET = homeHandler;
+
+const userRoute = router.register('/users/:userId');
+userRoute.GET = userHandler;
+userRoute.PUT = updateUserHandler;
+
+router.register('/users').POST = createUserHandler;
+
+router.register('/files/*').GET = fileHandler;
+
+// Create Deno server
+Deno.serve({ port: 3000 }, (req) => {
+  const url = new URL(req.url);
+  const match = router.match(url.pathname);
+
+  if (match) {
+    // Check if a handler exists for the request method
+    const handler = match[req.method as keyof RouteStore];
+    if (handler) {
+      if ('params' in match && match.params) {
+        // Dynamic route match
+        return handler(req, match.params);
+      } else {
+        // Static route match
+        return handler(req);
+      }
+    } else {
+      // Path matched, but method not allowed
+      return methodNotAllowedHandler(req);
+    }
+  }
+
+  // No path match found
+  return notFoundHandler(req);
+});
+
+console.log('Deno server listening on http://localhost:3000');
+```

package/docs/examples/server.node.md

@@ -0,0 +1,102 @@
+```javascript
+// server.node.mjs
+import http from 'node:http';
+import Extreme, { param, wildcard } from 'extreme-router';
+
+// Define the type for your route store, mapping methods to handlers
+type MethodHandler = (req: http.IncomingMessage, res: http.ServerResponse, params?: Record<string, string>) => void;
+type RouteStore = {
+  [method: string]: MethodHandler; // e.g., GET, POST
+};
+
+// Initialize the router
+const router = new Extreme<RouteStore>();
+
+// Register plugins (chaining supported)
+router.use(param)
+.use(wildcard);
+
+// --- Define Handlers ---
+const homeHandler: MethodHandler = (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'text/plain' });
+  res.end('Welcome Home! (GET)');
+};
+const createUserHandler: MethodHandler = (req, res) => {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', () => {
+    res.writeHead(201, { 'Content-Type': 'text/plain' });
+    res.end(`Creating user... (POST) Data: ${body}`);
+  });
+};
+const userHandler: MethodHandler = (req, res, params) => {
+  res.writeHead(200, { 'Content-Type': 'text/plain' });
+  res.end(`User ID: ${params?.userId} (GET)`);
+};
+const updateUserHandler: MethodHandler = (req, res, params) => {
+  let body = '';
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+  req.on('end', () => {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end(`Updating user ${params?.userId}... (PUT) Data: ${body}`);
+  });
+};
+const fileHandler: MethodHandler = (req, res, params) => {
+  res.writeHead(200, { 'Content-Type': 'text/plain' });
+  res.end(`File path: ${params?.['*']} (GET)`);
+};
+const notFoundHandler: MethodHandler = (req, res) => {
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('Not Found');
+};
+const methodNotAllowedHandler: MethodHandler = (req, res) => {
+  res.writeHead(405, { 'Content-Type': 'text/plain' });
+  res.end('Method Not Allowed');
+};
+
+// --- Register Routes and Methods ---
+router.register('/').GET = homeHandler;
+
+const userRoute = router.register('/users/:userId');
+userRoute.GET = userHandler;
+userRoute.PUT = updateUserHandler;
+
+router.register('/users').POST = createUserHandler;
+
+router.register('/files/*').GET = fileHandler;
+
+// Create Node.js server
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+  const match = router.match(url.pathname);
+  const method = req.method ?? 'GET'; // Default to GET if method is undefined
+
+  if (match) {
+    // Check if a handler exists for the request method
+    const handler = match[method as keyof RouteStore];
+    if (handler) {
+      if ('params' in match && match.params) {
+        // Dynamic route match
+        handler(req, res, match.params);
+      } else {
+        // Static route match
+        handler(req, res);
+      }
+    } else {
+      // Path matched, but method not allowed
+      methodNotAllowedHandler(req, res);
+    }
+  } else {
+    // No path match found
+    notFoundHandler(req, res);
+  }
+});
+
+server.listen(3000, () => {
+  console.log('Node.js server listening on http://localhost:3000');
+});
+```

package/docs/optional-parameters-priority.md

@@ -0,0 +1,64 @@
+### Note on Optional Parameters and Priority
+
+The interaction between optional parameters (`:name?`) and subsequent segments is governed by plugin priorities during the matching process. Consider a route like `/prefix/:optional?/nextSegment` and a URL like `/prefix/value`.
+
+When the router encounters the `value` segment after `/prefix`, it looks at the potential nodes registered at that point:
+
+1.  A node representing the optional segment (`:optional?`), handled by the `optionalParam` plugin (priority 600).
+2.  A node representing the path _without_ the optional segment (leading directly to `nextSegment`). If `nextSegment` is static, it has the highest priority. If it's dynamic (e.g., `:nextSegment`), it's handled by its corresponding plugin (e.g., `param` with priority 700).
+
+The router compares the priorities of the plugins handling these potential next steps:
+
+- **Case 1: `nextSegment` has higher priority (lower number) than `:optional?`**
+
+  - The router first attempts to match `value` against `nextSegment`.
+  - If it matches, the path taken is `/prefix/nextSegment`, effectively skipping the optional parameter logic for this segment.
+  - If it _doesn't_ match, the router then attempts to match `value` using the `optionalParam` plugin.
+
+- **Case 2: `:optional?` has higher priority (lower number) than `nextSegment`** (This is the case with built-in `optionalParam` (600) vs `param` (700) or `wildcard` (800)).
+  - The router first attempts to match `value` using the higher-priority `optionalParam` plugin.
+  - Crucially, the built-in `optionalParam` plugin's matching logic is designed to **always succeed** for the segment it checks. It consumes `value` and assigns it to the `:optional` parameter.
+  - The router then proceeds _down the path that includes the optional segment_.
+  - It then attempts to match the _next_ segment in the URL against the node _following_ the optional one (i.e., the `nextSegment` node that is a child of the `:optional?` node).
+  - If the rest of the URL matches the structure defined _after_ the optional segment, the match succeeds.
+  - If the rest of the URL _doesn't_ match (e.g., the URL ends after `value` but the route expected `nextSegment`), the match fails.
+
+**Key Takeaway:** Because the built-in `optionalParam` (priority 600) has a higher priority than `param` (700) and `wildcard` (800), and its matching function always consumes the segment, it will generally "win" the priority check against a subsequent standard parameter or wildcard. The match then _must_ follow the path structure _including_ the optional parameter.
+
+**Revisiting the Example:**
+
+Let's re-analyze the example `/products/:category?/:productId` with this understanding:
+
+```typescript
+// ... (import and setup) ...
+
+// Register plugins (lower priority number = higher precedence)
+// Order of registration does not matter for the built-in plugins, but it's good practice to register them in a logical order.
+router.use(optionalParam); // Priority 600
+.use(param); // Priority 700
+
+// Route: /products/:category?/:productId
+router.register('/products/:category?/:productId').name = 'GetProduct';
+
+// Matching /products/books/987:
+// - After /products, encounter 'books'.
+// - Potential next nodes: ':category?' (optionalParam, 600) and ':productId' (param, 700 - representing the path without the optional).
+// - optionalParam (600) has higher priority.
+// - optionalParam matches and consumes 'books' for :category.
+// - Router proceeds down the optional path. Expects ':productId' next.
+// - Encounters '987'. Matches ':productId' (using param plugin).
+// - End of URL, end of path. Success.
+console.log(router.match('/products/books/987'));
+// { name: 'GetProduct', params: { category: 'books', productId: '987' } } // Correct based on priority logic.
+
+// Matching /products/654:
+// - After /products, encounter '654'.
+// - Potential next nodes: ':category?' (optionalParam, 600) and ':productId' (param, 700).
+// - optionalParam (600) has higher priority.
+// - optionalParam matches and consumes '654' for :category.
+// - Router proceeds down the optional path. Expects ':productId' next.
+// - No more segments in the URL.
+// - Match fails because the path requires ':productId' after ':category'.
+console.log(router.match('/products/654'));
+// null // Corrected: optionalParam (higher priority) consumes '654' for :category, then fails as :productId is missing.
+```

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "extreme-router",
+  "version": "1.0.0",
+  "description": "A high-performance, tree-based router for JavaScript and TypeScript, featuring a powerful plugin system for extreme extensibility",
+  "author": "lior cohen",
+  "homepage": "https://github.com/liorcodev/extreme-router#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liorcodev/extreme-router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/liorcodev/extreme-router/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "router",
+    "routing",
+    "javascript",
+    "typescript",
+    "node",
+    "modular",
+    "bun",
+    "browser",
+    "performance",
+    "extensible",
+    "plugin",
+    "url",
+    "path",
+    "matching",
+    "tree",
+    "radix",
+    "trie",
+    "dynamic",
+    "static",
+    "regex",
+    "wildcard",
+    "optional",
+    "parameters"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.26.0",
+    "@types/benchmark": "^2.1.5",
+    "@types/bun": "latest",
+    "@vitest/coverage-v8": "3.1.2",
+    "benchmark": "^2.1.4",
+    "chalk": "^5.4.1",
+    "eslint": "^9.26.0",
+    "globals": "^16.1.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "minimist": "^1.2.8",
+    "prettier": "^3.5.3",
+    "tsup": "^8.4.0",
+    "typescript-eslint": "^8.32.0",
+    "vitest": "^3.1.3"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "lint": "bun eslint",
+    "lint:fix": "bun eslint --fix",
+    "lint-staged": "lint-staged",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "build": "tsup",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"benchmark/**/*.js\" \"scripts/**/*.js\"",
+    "benchmark": "bun run benchmark/match.benchmark.js --type mixed",
+    "benchmark:dynamic": "bun run benchmark/match.benchmark.js --type dynamic",
+    "benchmark:static": "bun run benchmark/match.benchmark.js --type static",
+    "benchmark:stress": "bun run benchmark/match.stress.js",
+    "benchmark:memory": "bun run benchmark/match.memory.js",
+    "size": "bun run scripts/bundle-size.js",
+    "prepublishOnly": "bun run format && bun run test:coverage && bun run lint:fix && bun run build && bun run size"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  }
+}