npm-express

1
# Router System
2

3
Modular route handlers for organizing and grouping related routes with middleware support, enabling clean separation of concerns in large applications.
4

5
## Capabilities
6

7
### Router Creation
8

9
Create router instances for modular route organization and middleware mounting.
10

11
```javascript { .api }
12
/**
13
 * Create router instance for modular route handlers
14
 * @param {RouterOptions} [options] - Router configuration options
15
 * @returns {Router} Router instance with routing capabilities
16
 */
17
function Router(options?: RouterOptions): Router;
18

19
/**
20
 * Router configuration options
21
 */
22
interface RouterOptions {
23
  /** Enable case-sensitive routing (default: false) */
24
  caseSensitive?: boolean;
25
  /** Merge parameters from parent router (default: false) */
26
  mergeParams?: boolean;
27
  /** Enable strict routing (trailing slash matters) (default: false) */
28
  strict?: boolean;
29
}
30

31
/**
32
 * Access Router constructor via express.Router
33
 */
34
declare const express: {
35
  Router(options?: RouterOptions): Router;
36
};
37
```
38

39
**Usage Examples:**
40

41
```javascript
42
const express = require('express');
43

44
// Basic router creation
45
const userRouter = express.Router();
46

47
// Router with options
48
const apiRouter = express.Router({
49
  caseSensitive: true,
50
  strict: true
51
});
52

53
// Router with merged params (access parent route params)
54
const postRouter = express.Router({ mergeParams: true });
55

56
// Mount routers on main app
57
const app = express();
58
app.use('/users', userRouter);
59
app.use('/api/v1', apiRouter);
60
app.use('/users/:userId/posts', postRouter);
61
```
62

63
### Router Middleware
64

65
Mount middleware functions on router instances for request processing.
66

67
```javascript { .api }
68
/**
69
 * Router instance with middleware and routing capabilities
70
 */
71
interface Router {
72
  /**
73
   * Mount middleware function(s) at optional path
74
   * @param {string} [path] - Optional path to mount middleware (default: '/')
75
   * @param {...RequestHandler} handlers - Middleware function(s) to mount
76
   * @returns {Router} Router instance for chaining
77
   */
78
  use(path?: string, ...handlers: RequestHandler[]): Router;
79
  
80
  /**
81
   * Add parameter middleware for route parameters
82
   * @param {string} name - Parameter name to trigger on
83
   * @param {ParamHandler} handler - Parameter handler function
84
   * @returns {Router} Router instance for chaining
85
   */
86
  param(name: string, handler: ParamHandler): Router;
87
}
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const userRouter = express.Router();
94

95
// Router-level middleware (applies to all routes in this router)
96
userRouter.use((req, res, next) => {
97
  console.log('User router middleware');
98
  req.startTime = Date.now();
99
  next();
100
});
101

102
// Path-specific middleware within router
103
userRouter.use('/profile', authenticateUser, (req, res, next) => {
104
  req.isProfileRoute = true;
105
  next();
106
});
107

108
// Parameter middleware for router
109
userRouter.param('id', (req, res, next, id) => {
110
  // Load user and attach to request
111
  User.findById(id, (err, user) => {
112
    if (err) return next(err);
113
    if (!user) return next(new Error('User not found'));
114
    req.user = user;
115
    next();
116
  });
117
});
118

119
// Multiple middleware functions
120
userRouter.use(
121
  authenticateUser,
122
  authorizeUser,
123
  logUserAccess
124
);
125

126
function authenticateUser(req, res, next) {
127
  // Authentication logic
128
  next();
129
}
130

131
function authorizeUser(req, res, next) {
132
  // Authorization logic
133
  next();
134
}
135

136
function logUserAccess(req, res, next) {
137
  console.log(`User ${req.user.id} accessed ${req.path}`);
138
  next();
139
}
140
```
141

142
### Router HTTP Methods
143

144
Handle HTTP methods within router instances for organized route definition.
145

146
```javascript { .api }
147
/**
148
 * Router HTTP method handlers
149
 */
150
interface Router {
151
  /** Handle GET requests */
152
  get(path: string, ...handlers: RequestHandler[]): Router;
153
  /** Handle POST requests */
154
  post(path: string, ...handlers: RequestHandler[]): Router;
155
  /** Handle PUT requests */
156
  put(path: string, ...handlers: RequestHandler[]): Router;
157
  /** Handle DELETE requests */
158
  delete(path: string, ...handlers: RequestHandler[]): Router;
159
  /** Handle PATCH requests */
160
  patch(path: string, ...handlers: RequestHandler[]): Router;
161
  /** Handle HEAD requests */
162
  head(path: string, ...handlers: RequestHandler[]): Router;
163
  /** Handle OPTIONS requests */
164
  options(path: string, ...handlers: RequestHandler[]): Router;
165
  /** Handle all HTTP methods */
166
  all(path: string, ...handlers: RequestHandler[]): Router;
167
}
168
```
169

170
**Usage Examples:**
171

172
```javascript
173
const userRouter = express.Router();
174

175
// GET routes
176
userRouter.get('/', (req, res) => {
177
  res.json({ message: 'Get all users' });
178
});
179

180
userRouter.get('/:id', (req, res) => {
181
  // req.user is available from param middleware
182
  res.json(req.user);
183
});
184

185
// POST routes
186
userRouter.post('/', validateUserData, (req, res) => {
187
  const user = createUser(req.body);
188
  res.status(201).json(user);
189
});
190

191
// PUT routes
192
userRouter.put('/:id', validateUserData, (req, res) => {
193
  const updatedUser = updateUser(req.user.id, req.body);
194
  res.json(updatedUser);
195
});
196

197
// DELETE routes
198
userRouter.delete('/:id', (req, res) => {
199
  deleteUser(req.user.id);
200
  res.sendStatus(204);
201
});
202

203
// PATCH routes
204
userRouter.patch('/:id', (req, res) => {
205
  const patchedUser = patchUser(req.user.id, req.body);
206
  res.json(patchedUser);
207
});
208

209
// Handle all methods for specific path
210
userRouter.all('/:id/reset', (req, res) => {
211
  resetUser(req.user.id);
212
  res.json({ message: 'User reset' });
213
});
214

215
function validateUserData(req, res, next) {
216
  if (!req.body.name) {
217
    return res.status(400).json({ error: 'Name is required' });
218
  }
219
  next();
220
}
221
```
222

223
### Router Route Creation
224

225
Create route instances within routers for method chaining and organization.
226

227
```javascript { .api }
228
/**
229
 * Create route instance for path with chainable method handlers
230
 * @param {string} path - Route path pattern within router
231
 * @returns {Route} Route instance for chaining HTTP methods
232
 */
233
router.route(path: string): Route;
234

235
/**
236
 * Route instance with chainable HTTP method handlers
237
 */
238
interface Route {
239
  /** Route path pattern */
240
  path: string;
241
  /** HTTP methods handled by this route */
242
  methods: { [method: string]: boolean };
243
  
244
  /** Handle all HTTP methods */
245
  all(...handlers: RequestHandler[]): Route;
246
  /** Handle GET requests */
247
  get(...handlers: RequestHandler[]): Route;
248
  /** Handle POST requests */
249
  post(...handlers: RequestHandler[]): Route;
250
  /** Handle PUT requests */
251
  put(...handlers: RequestHandler[]): Route;
252
  /** Handle DELETE requests */
253
  delete(...handlers: RequestHandler[]): Route;
254
  /** Handle PATCH requests */
255
  patch(...handlers: RequestHandler[]): Route;
256
}
257
```
258

259
**Usage Examples:**
260

261
```javascript
262
const userRouter = express.Router();
263

264
// Method chaining with router route
265
userRouter.route('/:id')
266
  .all((req, res, next) => {
267
    // Middleware for all methods on this route
268
    console.log(`Accessing user ${req.params.id}`);
269
    next();
270
  })
271
  .get((req, res) => {
272
    res.json(req.user);
273
  })
274
  .put((req, res) => {
275
    const updatedUser = updateUser(req.params.id, req.body);
276
    res.json(updatedUser);
277
  })
278
  .delete((req, res) => {
279
    deleteUser(req.params.id);
280
    res.sendStatus(204);
281
  });
282

283
// Multiple route chains
284
userRouter.route('/profile')
285
  .get(getProfile)
286
  .post(createProfile)
287
  .put(updateProfile);
288

289
userRouter.route('/settings')
290
  .get(getSettings)
291
  .patch(updateSettings);
292

293
function getProfile(req, res) {
294
  res.json(req.user.profile);
295
}
296

297
function createProfile(req, res) {
298
  const profile = createUserProfile(req.user.id, req.body);
299
  res.status(201).json(profile);
300
}
301

302
function updateProfile(req, res) {
303
  const profile = updateUserProfile(req.user.id, req.body);
304
  res.json(profile);
305
}
306
```
307

308
### Router Mounting and Nesting
309

310
Mount routers on applications and nest routers within other routers for hierarchical organization.
311

312
```javascript { .api }
313
/**
314
 * Mount router on application or another router
315
 */
316
app.use(path: string, router: Router): Application;
317
router.use(path: string, childRouter: Router): Router;
318
```
319

320
**Usage Examples:**
321

322
```javascript
323
const express = require('express');
324
const app = express();
325

326
// Create routers for different modules
327
const userRouter = express.Router();
328
const postRouter = express.Router();
329
const commentRouter = express.Router();
330

331
// User routes
332
userRouter.get('/', getAllUsers);
333
userRouter.get('/:id', getUser);
334
userRouter.post('/', createUser);
335

336
// Post routes (nested under users)
337
postRouter.get('/', getUserPosts);
338
postRouter.post('/', createUserPost);
339
postRouter.get('/:postId', getUserPost);
340

341
// Comment routes (nested under posts)
342
commentRouter.get('/', getPostComments);
343
commentRouter.post('/', createPostComment);
344

345
// Nest routers
346
postRouter.use('/:postId/comments', commentRouter);
347
userRouter.use('/:userId/posts', postRouter);
348

349
// Mount main router on app
350
app.use('/api/users', userRouter);
351

352
// Resulting URL structure:
353
// GET /api/users                           -> getAllUsers
354
// GET /api/users/123                       -> getUser
355
// GET /api/users/123/posts                 -> getUserPosts
356
// GET /api/users/123/posts/456             -> getUserPost
357
// GET /api/users/123/posts/456/comments    -> getPostComments
358
// POST /api/users/123/posts/456/comments   -> createPostComment
359

360
// API versioning with routers
361
const v1Router = express.Router();
362
const v2Router = express.Router();
363

364
v1Router.use('/users', userRouter);
365
v1Router.get('/status', (req, res) => res.json({ version: 'v1' }));
366

367
v2Router.use('/users', userRouter);
368
v2Router.get('/status', (req, res) => res.json({ version: 'v2' }));
369

370
app.use('/api/v1', v1Router);
371
app.use('/api/v2', v2Router);
372
```
373

374
### Router Error Handling
375

376
Handle errors within router instances with error middleware.
377

378
```javascript { .api }
379
/**
380
 * Error handling middleware signature for routers
381
 * @param {Error} err - Error object
382
 * @param {Request} req - Express request object
383
 * @param {Response} res - Express response object
384
 * @param {NextFunction} next - Next middleware function
385
 */
386
type RouterErrorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => void;
387
```
388

389
**Usage Examples:**
390

391
```javascript
392
const userRouter = express.Router();
393

394
// Regular routes
395
userRouter.get('/:id', async (req, res, next) => {
396
  try {
397
    const user = await User.findById(req.params.id);
398
    if (!user) {
399
      const error = new Error('User not found');
400
      error.status = 404;
401
      return next(error);
402
    }
403
    res.json(user);
404
  } catch (error) {
405
    next(error);
406
  }
407
});
408

409
userRouter.post('/', async (req, res, next) => {
410
  try {
411
    const user = await User.create(req.body);
412
    res.status(201).json(user);
413
  } catch (error) {
414
    next(error);
415
  }
416
});
417

418
// Router-specific error handler
419
userRouter.use((err, req, res, next) => {
420
  if (err.name === 'ValidationError') {
421
    return res.status(400).json({
422
      error: 'Validation Error',
423
      details: err.message
424
    });
425
  }
426
  
427
  if (err.status === 404) {
428
    return res.status(404).json({
429
      error: 'User not found'
430
    });
431
  }
432
  
433
  // Pass to application error handler
434
  next(err);
435
});
436

437
// Mount router
438
app.use('/api/users', userRouter);
439

440
// Application-level error handler
441
app.use((err, req, res, next) => {
442
  console.error(err.stack);
443
  res.status(500).json({
444
    error: 'Internal Server Error'
445
  });
446
});
447
```
448

449
### Router Organization Patterns
450

451
Common patterns for organizing routes and middleware in large applications.
452

453
**Usage Examples:**
454

455
```javascript
456
// File: routes/users.js
457
const express = require('express');
458
const router = express.Router();
459

460
// Middleware specific to user routes
461
router.use(authenticateUser);
462
router.use(validateUserAccess);
463

464
// User CRUD operations
465
router.get('/', getAllUsers);
466
router.get('/:id', getUser);
467
router.post('/', createUser);
468
router.put('/:id', updateUser);
469
router.delete('/:id', deleteUser);
470

471
module.exports = router;
472

473
// File: routes/posts.js
474
const express = require('express');
475
const router = express.Router({ mergeParams: true });
476

477
router.get('/', getUserPosts);
478
router.post('/', createUserPost);
479
router.get('/:postId', getUserPost);
480
router.put('/:postId', updateUserPost);
481
router.delete('/:postId', deleteUserPost);
482

483
module.exports = router;
484

485
// File: app.js
486
const express = require('express');
487
const userRoutes = require('./routes/users');
488
const postRoutes = require('./routes/posts');
489

490
const app = express();
491

492
// Mount routes
493
app.use('/api/users', userRoutes);
494
app.use('/api/users/:userId/posts', postRoutes);
495

496
// Admin routes with prefix
497
const adminRouter = express.Router();
498
adminRouter.use(requireAdmin);
499
adminRouter.get('/stats', getAdminStats);
500
adminRouter.get('/logs', getSystemLogs);
501
app.use('/admin', adminRouter);
502

503
// API versioning
504
const v1 = express.Router();
505
const v2 = express.Router();
506

507
v1.use('/users', userRoutes);
508
v2.use('/users', require('./routes/v2/users'));
509

510
app.use('/api/v1', v1);
511
app.use('/api/v2', v2);
512
```
513

514
## Router Properties and Methods
515

516
```javascript { .api }
517
/**
518
 * Additional router properties and internal methods
519
 */
520
interface Router {
521
  /** Handle request (internal routing mechanism) */
522
  handle(req: Request, res: Response, next: NextFunction): void;
523
  
524
  /** Router stack (internal middleware/route storage) */
525
  stack: any[];
526
}
527
```
528

529
**Usage Examples:**
530

531
```javascript
532
const router = express.Router();
533

534
// Custom router middleware to inspect routing
535
router.use((req, res, next) => {
536
  console.log(`Router handling: ${req.method} ${req.originalUrl}`);
537
  console.log(`Router stack size: ${router.stack.length}`);
538
  next();
539
});
540

541
// Mount on app
542
app.use('/api', router);
543
```