@devbro/neko-router 0.1.17 → 0.1.18

package/README.md

@@ -1,47 +1,718 @@
 # @devbro/neko-router
 
-cool routing solution for choosing the code that runs for a given URI.
+A powerful, flexible routing solution for Node.js and TypeScript applications. Build RESTful APIs and web applications with an intuitive, Express-like API.
 
-## supported features
+## Installation
 
-- support controller and function as main executor
-- middleware support both as class and function
-- singleton middleware and new instance per request middleware
-- support route variables
+```bash
+npm install @devbro/neko-router
+```
+
+## Features
+
+- 🎯 **Flexible Routing** - Support for functions and controllers
+- 🛣️ **Path Parameters** - Dynamic route segments with type safety
+- 🔒 **Middleware Support** - Function and class-based middleware
+- 🔄 **Singleton & Per-Request** - Choose middleware lifecycle
+- 📝 **Multiple HTTP Methods** - GET, POST, PUT, DELETE, PATCH, etc.
+- 🎨 **Fluent API** - Chainable, intuitive interface
+- 🛡️ **Type-Safe** - Full TypeScript support
+- ⚡ **High Performance** - Fast route matching and resolution
+
+## Quick Start
+
+```ts
+import { Router, Request, Response } from '@devbro/neko-router';
+
+// Create router instance
+const router = new Router();
+
+// Add a simple route
+router.addRoute(['GET'], '/api/users', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { users: ['Alice', 'Bob', 'Charlie'] };
+});
+
+// Resolve and execute
+const req = { url: '/api/users', method: 'GET' } as Request;
+const res = {} as Response;
+
+const compiledRoute = router.getCompiledRoute(req, res);
+const result = await compiledRoute.run();
+
+console.log(result); // { users: ['Alice', 'Bob', 'Charlie'] }
+```
+
+## Core Concepts
+
+### Basic Routing
+
+Define routes for different HTTP methods:
+
+```ts
+import { Router, Request, Response } from '@devbro/neko-router';
+
+const router = new Router();
+
+// GET request
+router.addRoute(['GET'], '/api/posts', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { posts: [] };
+});
+
+// POST request
+router.addRoute(['POST'], '/api/posts', async (req: Request, res: Response) => {
+  res.statusCode = 201;
+  return { message: 'Post created' };
+});
+
+// PUT request
+router.addRoute(['PUT'], '/api/posts/:id', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { message: `Post ${req.params.id} updated` };
+});
+
+// DELETE request
+router.addRoute(['DELETE'], '/api/posts/:id', async (req: Request, res: Response) => {
+  res.statusCode = 204;
+  return null;
+});
+```
+
+### Multiple HTTP Methods
+
+Handle multiple methods on the same route:
+
+```ts
+// Support both GET and HEAD
+router.addRoute(['GET', 'HEAD'], '/api/health', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { status: 'healthy' };
+});
+
+// Common pattern for resources
+router.addRoute(['GET', 'POST'], '/api/comments', async (req: Request, res: Response) => {
+  if (req.method === 'GET') {
+    return { comments: [] };
+  } else {
+    return { message: 'Comment created' };
+  }
+});
+```
+
+### Path Parameters
+
+Capture dynamic segments from the URL:
+
+```ts
+// Single parameter
+router.addRoute(['GET'], '/api/users/:userId', async (req: Request, res: Response) => {
+  const userId = req.params.userId;
+  res.statusCode = 200;
+  return { userId, name: 'John Doe' };
+});
+
+// Multiple parameters
+router.addRoute(
+  ['GET'],
+  '/api/posts/:postId/comments/:commentId',
+  async (req: Request, res: Response) => {
+    const { postId, commentId } = req.params;
+    res.statusCode = 200;
+    return { postId, commentId };
+  }
+);
+
+// Optional parameters with query strings
+router.addRoute(['GET'], '/api/search/:category', async (req: Request, res: Response) => {
+  const category = req.params.category;
+  const query = req.query?.q || '';
+  res.statusCode = 200;
+  return { category, query };
+});
+```
+
+## Middleware
+
+### Function Middleware
+
+Use simple functions as middleware:
+
+```ts
+// Logging middleware
+const loggerMiddleware = async (req: Request, res: Response, next: Function) => {
+  console.log(`[${req.method}] ${req.url}`);
+  await next();
+  console.log(`Response: ${res.statusCode}`);
+};
+
+// Authentication middleware
+const authMiddleware = async (req: Request, res: Response, next: Function) => {
+  const token = req.headers?.authorization;
+
+  if (!token) {
+    res.statusCode = 401;
+    return { error: 'Unauthorized' };
+  }
+
+  // Verify token...
+  req.user = { id: 1, name: 'User' };
+  await next();
+};
+
+// Apply middleware to route
+router
+  .addRoute(['GET'], '/api/protected', async (req: Request, res: Response) => {
+    return { user: req.user };
+  })
+  .addMiddleware([loggerMiddleware, authMiddleware]);
+```
+
+### Multiple Middleware
 
-## example
+Chain multiple middleware functions:
 
 ```ts
-import {Router, Request, Response} from '@devbro/neko-router';
-const router: Router = new Router();
+const middleware1 = async (req: Request, res: Response, next: Function) => {
+  console.log('Middleware 1 - Before');
+  await next();
+  console.log('Middleware 1 - After');
+};
 
-router.addRoute(['GET', 'HEAD'], '/api/v1/countries', async (req: Request, res: Response) => {
-    return 'GET countries';
+const middleware2 = async (req: Request, res: Response, next: Function) => {
+  console.log('Middleware 2 - Before');
+  await next();
+  console.log('Middleware 2 - After');
+};
+
+router
+  .addRoute(['POST'], '/api/data', async (req: Request, res: Response) => {
+    return { message: 'Data processed' };
+  })
+  .addMiddleware([middleware1, middleware2]);
+
+// Execution order:
+// Middleware 1 - Before
+// Middleware 2 - Before
+// Route handler
+// Middleware 2 - After
+// Middleware 1 - After
+```
+
+### Inline Middleware
+
+Add middleware directly in the chain:
+
+```ts
+router
+  .addRoute(['GET'], '/api/users/:id', async (req: Request, res: Response) => {
+    return { userId: req.params.id };
+  })
+  .addMiddleware(async (req, res, next) => {
+    console.log('Accessing user:', req.params.id);
+    await next();
+    console.log('Request completed with status:', res.statusCode);
+  });
+```
+
+### Class-Based Middleware
+
+Use classes for more complex middleware:
+
+```ts
+class AuthenticationMiddleware {
+  async handle(req: Request, res: Response, next: Function) {
+    // Authentication logic
+    const token = req.headers?.authorization;
+
+    if (!token) {
+      res.statusCode = 401;
+      throw new Error('No token provided');
+    }
+
+    // Verify and attach user
+    req.user = await this.verifyToken(token);
+    await next();
+  }
+
+  private async verifyToken(token: string) {
+    // Token verification logic
+    return { id: 1, email: 'user@example.com' };
+  }
+}
+
+// Use the class middleware
+const authMiddleware = new AuthenticationMiddleware();
+
+router
+  .addRoute(['GET'], '/api/profile', async (req: Request, res: Response) => {
+    return { profile: req.user };
+  })
+  .addMiddleware(authMiddleware.handle.bind(authMiddleware));
+```
+
+### Singleton vs Per-Request Middleware
+
+```ts
+// Singleton middleware - shared instance across requests
+class CacheMiddleware {
+  private cache = new Map();
+
+  async handle(req: Request, res: Response, next: Function) {
+    const key = req.url;
+
+    if (this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+
+    await next();
+    this.cache.set(key, res.body);
+  }
+}
+
+const cacheMiddleware = new CacheMiddleware(); // Single instance
+
+// Per-request middleware - new instance for each request
+router
+  .addRoute(['GET'], '/api/data', async (req: Request, res: Response) => {
+    return { data: 'expensive computation' };
+  })
+  .addMiddleware(cacheMiddleware.handle.bind(cacheMiddleware));
+```
+
+## Route Resolution
+
+### Resolving Routes
+
+```ts
+const router = new Router();
+
+router.addRoute(['GET'], '/api/users', async (req: Request, res: Response) => {
+  return { users: [] };
 });
 
+// Create request object
+const req = {
+  url: '/api/users',
+  method: 'GET',
+  headers: {},
+  query: {},
+} as Request;
+
+const res = {} as Response;
+
+// Resolve the route
+const resolved = router.resolve(req);
+console.log(resolved); // Route information
+
+// Get compiled route and execute
+const compiledRoute = router.getCompiledRoute(req, res);
+const result = await compiledRoute.run();
+
+console.log(res.statusCode); // 200
+console.log(result); // { users: [] }
+```
+
+### Handling 404
+
+```ts
+const req = { url: '/api/nonexistent', method: 'GET' } as Request;
+const res = {} as Response;
+
+try {
+  const compiledRoute = router.getCompiledRoute(req, res);
+  await compiledRoute.run();
+} catch (error) {
+  // Handle route not found
+  res.statusCode = 404;
+  return { error: 'Route not found' };
+}
+```
+
+## Real-World Examples
+
+### RESTful API
+
+```ts
+import { Router, Request, Response } from '@devbro/neko-router';
+
+const router = new Router();
+
+// Logging middleware
+const logger = async (req: Request, res: Response, next: Function) => {
+  const start = Date.now();
+  await next();
+  const duration = Date.now() - start;
+  console.log(`[${req.method}] ${req.url} - ${res.statusCode} (${duration}ms)`);
+};
+
+// List all posts
+router
+  .addRoute(['GET'], '/api/posts', async (req: Request, res: Response) => {
+    const posts = await database.getPosts();
+    res.statusCode = 200;
+    return { posts };
+  })
+  .addMiddleware(logger);
+
+// Get single post
+router
+  .addRoute(['GET'], '/api/posts/:id', async (req: Request, res: Response) => {
+    const post = await database.getPost(req.params.id);
+    res.statusCode = 200;
+    return { post };
+  })
+  .addMiddleware(logger);
+
+// Create post
 router
-    .addRoute(['POST'], '/api/v1/countries', async (req: Request, res: Response) => {
-    return 'POST countries';
-    })
-    .addMiddleware([m1, m2]);
+  .addRoute(['POST'], '/api/posts', async (req: Request, res: Response) => {
+    const newPost = await database.createPost(req.body);
+    res.statusCode = 201;
+    return { post: newPost };
+  })
+  .addMiddleware([logger, authMiddleware]);
 
-    router.addRoute(
-      ['GET'],
-      '/api/v1/countries/:countryId',
-      async (req: Request, res: Response) => {
-        return 'GET PARAM countries ' + req.params?.countryId;
-      }
-    ).addMiddleware((req,res,next) => {
-        console.log('request.params:', req.params);
-        await next();
-        console.log('final result:', res.statusCode);
-    });
+// Update post
+router
+  .addRoute(['PUT'], '/api/posts/:id', async (req: Request, res: Response) => {
+    const updated = await database.updatePost(req.params.id, req.body);
+    res.statusCode = 200;
+    return { post: updated };
+  })
+  .addMiddleware([logger, authMiddleware]);
+
+// Delete post
+router
+  .addRoute(['DELETE'], '/api/posts/:id', async (req: Request, res: Response) => {
+    await database.deletePost(req.params.id);
+    res.statusCode = 204;
+    return null;
+  })
+  .addMiddleware([logger, authMiddleware]);
+```
+
+### Error Handling Middleware
+
+```ts
+const errorHandler = async (req: Request, res: Response, next: Function) => {
+  try {
+    await next();
+  } catch (error) {
+    console.error('Error:', error);
+    res.statusCode = 500;
+    return {
+      error: 'Internal Server Error',
+      message: error.message,
+    };
+  }
+};
+
+router
+  .addRoute(['GET'], '/api/risky', async (req: Request, res: Response) => {
+    throw new Error('Something went wrong!');
+  })
+  .addMiddleware(errorHandler);
+```
+
+### Request Validation
+
+```ts
+const validateCreateUser = async (req: Request, res: Response, next: Function) => {
+  const { email, name } = req.body;
+
+  if (!email || !name) {
+    res.statusCode = 400;
+    return { error: 'Email and name are required' };
+  }
+
+  if (!email.includes('@')) {
+    res.statusCode = 400;
+    return { error: 'Invalid email format' };
+  }
+
+  await next();
+};
+
+router
+  .addRoute(['POST'], '/api/users', async (req: Request, res: Response) => {
+    const user = await createUser(req.body);
+    res.statusCode = 201;
+    return { user };
+  })
+  .addMiddleware(validateCreateUser);
+```
+
+### CORS Middleware
+
+```ts
+const corsMiddleware = async (req: Request, res: Response, next: Function) => {
+  res.headers = {
+    ...res.headers,
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+  };
+
+  if (req.method === 'OPTIONS') {
+    res.statusCode = 204;
+    return null;
+  }
+
+  await next();
+};
+
+// Apply to all routes
+router
+  .addRoute(
+    ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    '/api/*',
+    async (req: Request, res: Response) => {
+      // Route handler
+    }
+  )
+  .addMiddleware(corsMiddleware);
+```
+
+### Rate Limiting
+
+```ts
+class RateLimiter {
+  private requests = new Map<string, number[]>();
+  private limit = 100;
+  private window = 60000; // 1 minute
+
+  async handle(req: Request, res: Response, next: Function) {
+    const ip = req.headers['x-forwarded-for'] || req.connection?.remoteAddress;
+    const now = Date.now();
+
+    if (!this.requests.has(ip)) {
+      this.requests.set(ip, []);
+    }
+
+    const userRequests = this.requests.get(ip)!;
+    const recentRequests = userRequests.filter((time) => now - time < this.window);
+
+    if (recentRequests.length >= this.limit) {
+      res.statusCode = 429;
+      return { error: 'Too many requests' };
+    }
+
+    recentRequests.push(now);
+    this.requests.set(ip, recentRequests);
+
+    await next();
+  }
+}
+
+const rateLimiter = new RateLimiter();
+
+router
+  .addRoute(['GET'], '/api/data', async (req: Request, res: Response) => {
+    return { data: 'sensitive information' };
+  })
+  .addMiddleware(rateLimiter.handle.bind(rateLimiter));
+```
+
+## Integration with HTTP Servers
+
+### With Node.js HTTP
+
+```ts
+import http from 'http';
+import { Router, Request, Response } from '@devbro/neko-router';
+
+const router = new Router();
+
+// Define routes
+router.addRoute(['GET'], '/api/hello', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { message: 'Hello World' };
+});
+
+// Create HTTP server
+const server = http.createServer(async (req, res) => {
+  try {
+    const request = req as Request;
+    const response = res as Response;
+
+    const compiledRoute = router.getCompiledRoute(request, response);
+    const result = await compiledRoute.run();
+
+    res.writeHead(response.statusCode || 200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(result));
+  } catch (error) {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not Found' }));
+  }
+});
+
+server.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### With Express
+
+```ts
+import express from 'express';
+import { Router as NekoRouter, Request, Response } from '@devbro/neko-router';
 
-    let req = { url: '/api/v1/countries', method: 'GET' } as Request;
-    let res = { ??? } as Response;
-    let resolved = router.resolve(req);
+const app = express();
+const router = new NekoRouter();
 
-    let compiled_route = router.getCompiledRoute(req,res);
-    await compiled_route.run();
-    console.log(res.statusCode);
+// Define routes in neko-router
+router.addRoute(['GET'], '/api/users', async (req: Request, res: Response) => {
+  res.statusCode = 200;
+  return { users: [] };
+});
+
+// Use as Express middleware
+app.use(async (req, res, next) => {
+  try {
+    const request = req as Request;
+    const response = res as Response;
+
+    const compiledRoute = router.getCompiledRoute(request, response);
+    const result = await compiledRoute.run();
+
+    res.status(response.statusCode || 200).json(result);
+  } catch (error) {
+    next();
+  }
+});
+
+app.listen(3000);
 ```
+
+## Best Practices
+
+1. **Organize Routes** - Group related routes together
+2. **Use Middleware** - Extract common logic into reusable middleware
+3. **Error Handling** - Always wrap route handlers in error handling middleware
+4. **Validation** - Validate input data before processing
+5. **Type Safety** - Use TypeScript interfaces for request/response types
+6. **Status Codes** - Set appropriate HTTP status codes
+7. **Async/Await** - Use async/await for cleaner asynchronous code
+8. **Naming** - Use descriptive names for routes and middleware
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```ts
+import { Router, Request, Response, Middleware } from '@devbro/neko-router';
+
+// Extend Request type
+interface CustomRequest extends Request {
+  user?: {
+    id: number;
+    email: string;
+  };
+}
+
+// Type-safe route handler
+router.addRoute(['GET'], '/api/profile', async (req: CustomRequest, res: Response) => {
+  if (!req.user) {
+    res.statusCode = 401;
+    return { error: 'Unauthorized' };
+  }
+
+  return { profile: req.user };
+});
+
+// Type-safe middleware
+const authMiddleware: Middleware = async (req: CustomRequest, res: Response, next: Function) => {
+  // Authentication logic
+  await next();
+};
+```
+
+## API Reference
+
+### `Router`
+
+#### Methods
+
+##### `addRoute(methods: string[], path: string, handler: Function): Route`
+
+Add a new route to the router.
+
+```ts
+router.addRoute(['GET', 'POST'], '/api/users', handler);
+```
+
+##### `resolve(req: Request): RouteInfo | null`
+
+Resolve a request to route information.
+
+```ts
+const routeInfo = router.resolve(req);
+```
+
+##### `getCompiledRoute(req: Request, res: Response): CompiledRoute`
+
+Get a compiled route ready for execution.
+
+```ts
+const compiled = router.getCompiledRoute(req, res);
+await compiled.run();
+```
+
+### `Route`
+
+#### Methods
+
+##### `addMiddleware(middleware: Function | Function[]): Route`
+
+Add middleware to the route.
+
+```ts
+route.addMiddleware([middleware1, middleware2]);
+route.addMiddleware(singleMiddleware);
+```
+
+### Types
+
+```ts
+interface Request {
+  url: string;
+  method: string;
+  headers?: Record<string, string>;
+  params?: Record<string, string>;
+  query?: Record<string, any>;
+  body?: any;
+  [key: string]: any;
+}
+
+interface Response {
+  statusCode?: number;
+  headers?: Record<string, string>;
+  body?: any;
+  [key: string]: any;
+}
+
+type Middleware = (req: Request, res: Response, next: Function) => Promise<any>;
+```
+
+## Performance Tips
+
+1. **Route Order** - Place specific routes before generic ones
+2. **Middleware Order** - Put fast middleware before slow ones
+3. **Caching** - Cache route resolution results when possible
+4. **Async Operations** - Use async/await efficiently
+5. **Memory Management** - Clean up middleware state appropriately
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@devbro/neko-http](https://www.npmjs.com/package/@devbro/neko-http) - HTTP client utilities
+- [@devbro/neko-context](https://www.npmjs.com/package/@devbro/neko-context) - Context management
+- [@devbro/pashmak](https://www.npmjs.com/package/@devbro/pashmak) - Full-stack TypeScript framework

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devbro/neko-router",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "general purpose router for URI to controller selection",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -18,6 +18,7 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
+    "bench": "vitest bench",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage",
     "format": "eslint . --fix --ext ts,tsx --report-unused-disable-directives --max-warnings 0 ",