express-auto-router

[!TAG] 1.0.0

A dynamic route composition system for Express.js applications that automatically discovers and mount routes and middleware based on your file system structure. Inspired by Next.js routing conventions.

Features
Installation
How it Works
- 1. Directory Structure as Routes
- 2. Key Design Decisions
Opinions in the Code
Potential Issues and Considerations
- 1. Trailing Slash Handling
- 2. Middleware Control
Best Practices When Using This System
Future Considerations
- 3. Priority-Based Routing
API
Usage
CommonJS (CJS) Usage
ES Modules (ESM) Usage
Contributing
Rules
Commit Message
Testing
- Running Tests
License
Acknowledgments
- Dependencies
- Development Dependencies

Features

📁 File-System Based Routing - Automatically generates Express.js routes from your directory structure, similar to Next.js ( Convention over Configuration )
🔄 Dynamic Route Parameters - Supports dynamic route parameters using [paramName] syntax that converts to Express.js :paramName format
🔗 Hierarchical Middleware - Middleware cascades down from parent to child routes automatically
🎯 Convention over Configuration - Follows clear conventions with _middleware.js and index.js files
🔒 Strict URL Handling - Enforces consistent URL patterns with trailing slashes for better route organization
🎨 Clean API Design - Simple and intuitive API that requires minimal setup
🛠️ Flexible Middleware Management:
- Global middleware at root level
- Route-specific middleware at any level
- Support for multiple middleware functions per route
- Priority-based middleware ordering with optional { fn, priority } objects
- Backward compatible - Plain function returns continue to work unchanged
- Mixed format support - Use priority objects and plain functions together
- Cross-hierarchy middleware control and deterministic execution order
📦 Zero External Dependencies - Only requires Express.js as a peer dependency
🔍 Type-Safe Path Parameters - Directory names define your route parameters, ensuring consistency
🎮 Full HTTP Method Support - Works with all Express HTTP methods (GET, POST, PUT, PATCH, DELETE)
⚡ Performance Optimized - Routes are compiled at startup, not on each request
🧪 Testing Friendly - Easy to test with clear route structure and middleware organization
🎯 Priority-Based Routing - Optional numeric prefix convention ({priority}-{name}) for deterministic route and middleware ordering
🔧 Route Conflict Resolution - Eliminates route shadowing issues with explicit priority control
📊 Deterministic Behavior - Routes always register in the same order across all environments

Installation

NPM

npm install @psenger/express-auto-router --save

YARN

yarn add @psenger/express-auto-router

How it Works

Express Auto Router is an elegant solution that transforms your directory structure into a fully functional Express.js routing system. It follows the philosophy of "convention over configuration" similar to Next.js and Nuxt.js, but for Express.js backend applications.

1. Directory Structure as Routes

The system uses your file system structure to automatically generate Express routes. For example:

routes/
  ├── _middleware.js         # Global middleware
  ├── users/
  │   ├── _middleware.js     # Users-specific middleware
  │   ├── index.js           # /users/ endpoint
  │   └── [id]/              # Dynamic parameter
  │       ├── _middleware.js # User-specific middleware
  │       └── index.js       # /users/:id/ endpoint

2. Key Design Decisions

Dynamic Routes

Uses a bracket notation [paramName] for dynamic route parameters
Automatically converts these to Express.js style parameters (:paramName)
Example: /users/[userId]/posts/[postId]/ becomes /users/:userId/posts/:postId/

Hierarchical Middleware

One of the most powerful features is the hierarchical middleware system:

Middleware cascades down from parent to child routes
Each directory can have its own _middleware.js file
Middleware is applied in order from most general to most specific
Example: A request to /api/users/123/ will execute middleware in this order:
1. /api/_middleware.js
2. /api/users/_middleware.js
3. /api/users/[id]/_middleware.js

Strict Route Endings

An opinionated decision in the code is the use of trailing slashes (/). The router is configured with { strict: true }, which means:

All routes must end with a trailing slash
/users and /users/ are treated as different routes
This is enforced throughout the system for consistency

Opinions in the Code

Strict Mode

const routerOptions = options.routerOptions || { strict: true }

The code enforces strict mode by default, treating trailing slashes as significant.

Middleware File Naming

export function isMiddlewareFile(entry) {
  return entry.isFile() && entry.name === '_middleware.js'
}

The system expects middleware files to be named exactly _middleware.js.

Hierarchical Middleware Organization The dictionaryKeyStartsWithPath function enforces a hierarchical middleware structure, sorting by path length to ensure proper execution order. Please note this is an opinion of how middleware should work and is baked into this system. If you want to control this it would have to be done inside the middleware.
Parameter calls

Global parameters/options can be passed to the controllers and middleware like this

const middlewareOptions = { logLevel: debug }
const controllerOptions = { env: 'test' }
composeRoutes(express, routeMappings, { middlewareOptions, controllerOptions } )

You should write your Controllers like this.

module.exports = ( router, controllerOptions ) => {
  ...
  return router
}

You should write your Middleware like this.

module.exports = ( middlewareOptions ) => {
  return [
    ...
  ]
}

Potential Issues and Considerations

1. Trailing Slash Handling

The biggest potential issue is the strict trailing slash requirement:

Pros:

Consistent URL structure
Clear distinction between directories and files
Prevents double-slash issues

Cons:

Many load balancers and Nginx configurations may strip trailing slashes
Can cause issues with some CDNs
May require additional configuration in reverse proxies

Mitigation Strategies:

Configure Nginx to preserve trailing slashes:

location / {
    proxy_pass http://backend;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-NginX-Proxy true;
    proxy_redirect off;
}

Use URL rewriting rules to add trailing slashes if missing

2. Middleware Control

While the hierarchical middleware system is powerful, it can lead to unexpected behavior if not carefully managed. The code allows for fine-grained control through:

Selective middleware application
Middleware can check the route and choose to skip processing
Order of middleware is predictable based on path depth

Best Practices When Using This System

Consistent Route Structure
- Always use trailing slashes in your routes
- Keep route parameters in brackets: [paramName]
- Use descriptive parameter names
Middleware Organization
- Place shared middleware at the highest appropriate level
- Use middleware selectively - don't add unnecessary layers
- Consider performance implications of deeply nested routes
- RECOMMENDED: Use priority-based middleware for deterministic execution order
Priority-Based Middleware Best Practice
- Use { fn: middleware, priority: number } objects for critical middleware ordering
- Assign priorities based on dependency requirements:
  - CORS: priority 5-10 (must execute first)
  - Authentication: priority 15-25 (after CORS)
  - Validation: priority 30-40 (after auth)
  - Business logic: priority 50-70 (default range)
  - Logging/cleanup: priority 80-90 (execute last)

Mixed Format Example

// routes/api/_middleware.js
module.exports = (options) => {
  return [
    { fn: corsMiddleware, priority: 5 },     // Priority 5 - executes FIRST
    authMiddleware,                          // Plain function → priority 50 (default)
    { fn: rateLimitMiddleware, priority: 15 }, // Priority 15 - executes SECOND
    validationMiddleware,                    // Plain function → priority 50 (default)  
    { fn: loggingMiddleware, priority: 90 }  // Priority 90 - executes LAST
  ]
}

Execution Order:

corsMiddleware (priority 5)
rateLimitMiddleware (priority 15)
authMiddleware (priority 50 - plain function gets default)
validationMiddleware (priority 50 - plain function gets default)
loggingMiddleware (priority 90)

Key Point: Plain functions without priority objects automatically get priority 50 (default). When multiple functions have the same priority, they execute in alphabetical order by function name.

Error Handling
- Implement error handling middleware at the appropriate levels
- Use the hierarchical structure to catch errors at the right scope
- Place error handlers with priority 95-99 to ensure they execute last
ESM Module Format Best Practices
- Controller Files: When using ESM (export default), ensure proper export format:
```
// ✅ Correct ESM controller format
export default (router, controllerOptions) => {
  router.get((req, res) => res.json({}))
  return router
}
```
- Middleware Files: When using ESM (export default), ensure proper export format:
```
// ✅ Correct ESM middleware format  
export default (middlewareOptions) => {
  function middleware(req, res, next) {
    // middleware logic
    next()
  }
  return middleware
}
```
- Mixed Environments: The library automatically handles both CommonJS and ESM modules
- Error Prevention: Always use export default for the main function, not named exports
- Compatibility: ESM modules work seamlessly with the library's universal module loader
Testing
- Test routes with and without trailing slashes
- Verify middleware execution order using priority system
- Test dynamic parameter handling
- Test mixed priority/non-priority middleware scenarios

Future Considerations

Optional Strict Mode
- Consider making the strict trailing slash behavior configurable
- Add options for automatic slash handling
Middleware Enhancement
- Implement middleware bypass options
- Add middleware execution tracking for debugging
Performance Optimization
- Cache route compilation results
- Implement lazy loading for large route trees
- Add route validation at startup

This system provides a powerful and elegant solution for Express.js routing, but users should be aware of its opinions and potential infrastructure considerations, particularly regarding the trailing slash requirement.

3. Priority-Based Routing

Express Auto Router supports an optional priority-based routing system that solves route conflicts and provides deterministic ordering. This feature is completely backward compatible - existing projects continue to work unchanged.

The Problem: Route Registration Order

Without priority control, routes register in filesystem alphabetical order, which can cause conflicts:

routes/
├── users/
│   ├── [id]/index.js           # Registers FIRST (alphabetically) → /users/:id/
│   └── admin/index.js          # Registers SECOND → /users/admin/

Problem: /users/:id/ captures ALL requests, including /users/admin/ because :id matches "admin".

Traditional Routing (Backward Compatible)

The traditional approach works exactly as before - no changes needed:

routes/
├── api/
│   ├── users/
│   │   ├── index.js            # /api/users/ → Priority 50 (default)
│   │   ├── profile/
│   │   │   └── index.js        # /api/users/profile/ → Priority 50 (default)
│   │   └── [id]/
│   │       └── index.js        # /api/users/:id/ → Priority 50 (default)
│   └── posts/
│       └── index.js            # /api/posts/ → Priority 50 (default)

Registration Order (alphabetical): /api/posts/ → /api/users/ → /api/users/:id/ → /api/users/profile/

Priority-Based Routing (Optional Enhancement)

Use numeric prefixes to control registration order when needed:

Format: {priority}-{name} where priority is 00-99 (lower numbers = higher priority = register first)

routes/
├── users/
│   ├── 10-all/index.js          # Priority 10 → /users/all/
│   ├── 15-[id]/index.js         # Priority 15 → /users/:id/  
│   ├── 20-admin/index.js        # Priority 20 → /users/admin/
│   ├── profile/index.js         # Priority 50 (default) → /users/profile/
│   ├── [sessionId]/index.js     # Priority 50 (default) → /users/:sessionId/
│   └── 90-settings/index.js     # Priority 90 → /users/settings/

Registration Order: /users/all/ → /users/:id/ → /users/admin/ → /users/profile/ → /users/:sessionId/ → /users/settings/

Dynamic Routes with Priorities

Priority prefixes work with dynamic routes (placeholders) too:

routes/
├── api/
│   └── users/
│       ├── 05-[userId]/         # Priority 5 → /api/users/:userId/
│       ├── 10-all/              # Priority 10 → /api/users/all/
│       ├── 15-[id]/             # Priority 15 → /api/users/:id/
│       ├── 20-admin/            # Priority 20 → /api/users/admin/
│       ├── profile/             # Priority 50 (default) → /api/users/profile/
│       └── [sessionId]/         # Priority 50 (default) → /api/users/:sessionId/

Why this works:

/api/users/:userId/ (priority 5) registers first - catches specific user ID patterns
/api/users/all/ (priority 10) registers second - catches "all" requests
/api/users/:id/ (priority 15) registers third - catches other ID patterns
Static routes like profile and remaining dynamic routes follow

Mixed Priority/Non-Priority Behavior

You can mix prefixed and non-prefixed directories in the same project:

routes/
├── 05-critical/
│   └── index.js                 # Priority 5 → /critical/
├── api/
│   ├── users/
│   │   ├── 10-all/index.js      # Priority 10 → /api/users/all/
│   │   ├── profile/index.js     # Priority 50 (default) → /api/users/profile/
│   │   └── [id]/index.js        # Priority 50 (default) → /api/users/:id/
│   └── posts/index.js           # Priority 50 (default) → /api/posts/
└── public/
    └── index.js                 # Priority 50 (default) → /public/

Three-Level Sorting Logic:

Priority Level (00-99, default 50 for non-prefixed)
Route Type (static routes before dynamic routes at same priority)
Alphabetical (for same priority and type)

Final Registration Order:

/critical/ (priority 5)
/api/users/all/ (priority 10)
/api/posts/ (priority 50, alphabetically before public)
/api/users/profile/ (priority 50, static)
/public/ (priority 50, alphabetically after posts)
/api/users/:id/ (priority 50, dynamic - comes after static at same priority)

Route Priority Rules

Priority range: 00-99 (two digits required for sorting)
Lower numbers = higher priority = register first
Default priority: 50 for directories without numeric prefixes
URL path: Priority prefix is stripped from the final URL (10-users becomes /users/)
Backward compatible: Non-prefixed directories continue to work exactly as before
Deterministic: Same registration order across all environments and filesystems

Common Use Cases

Route Conflict Resolution:

routes/
├── users/
│   ├── 05-all/index.js          # /users/all/ - registers before dynamic routes
│   ├── 10-admin/index.js        # /users/admin/ - specific route  
│   ├── 20-[id]/index.js         # /users/:id/ - general ID route
│   └── 90-[catchAll]/index.js   # /users/:catchAll/ - catch remaining patterns

API Versioning:

routes/
├── 10-v2/
│   └── users/index.js           # /v2/users/ - newer API version first
└── 50-v1/
    └── users/index.js           # /v1/users/ - legacy version

Feature Flags:

routes/
├── 01-beta/
│   └── features/index.js        # /beta/features/ - beta features first
└── features/index.js            # /features/ - stable features

Middleware Priority Support

Express Auto Router supports an optional priority-based middleware system that provides deterministic execution order across the directory hierarchy. This feature is completely backward compatible - existing projects continue to work unchanged.

Traditional Middleware (Backward Compatible)

The traditional approach continues to work exactly as before:

// routes/_middleware.js
module.exports = (options) => {
  return authMiddleware  // Single function
}

// or return multiple functions
module.exports = (options) => {
  return [corsMiddleware, authMiddleware, loggingMiddleware]
}

Priority-Based Middleware (Optional Enhancement)

For precise control over execution order, use the priority object format:

// routes/_middleware.js (parent directory)
module.exports = (options) => {
  return [
    { fn: corsMiddleware, priority: 5 },        // Execute FIRST
    { fn: authMiddleware, priority: 20 },       // After CORS
    { fn: loggingMiddleware, priority: 90 }     // Execute LAST
  ]
}

// routes/users/_middleware.js (child directory)
module.exports = (options) => {
  return [
    { fn: userValidationMiddleware, priority: 15 }, // After CORS, before auth
    { fn: userContextMiddleware, priority: 50 }     // Default priority
  ]
}

Mixed Format Support

You can mix both approaches in the same file:

// routes/api/_middleware.js
module.exports = (options) => {
  return [
    corsMiddleware,                           // Plain function → priority 50 (default)
    { fn: authMiddleware, priority: 10 },     // Priority object → priority 10  
    rateLimitMiddleware,                      // Plain function → priority 50 (default)
    { fn: loggingMiddleware, priority: 90 }   // Priority object → priority 90
  ]
}

Cross-Hierarchy Execution Order

When a request hits /users/profile/, middleware from ALL directory levels is collected and sorted by priority:

Directory Structure:

routes/
├── _middleware.js          # CORS (priority 5), Auth (priority 20)
└── users/
    ├── _middleware.js      # User validation (priority 15), User context (priority 50)
    └── profile/
        └── index.js        # Route handler

Final execution order for /users/profile/:

CORS middleware (priority 5) - from /
User validation (priority 15) - from /users/
Auth middleware (priority 20) - from /
User context (priority 50) - from /users/

Priority Rules

Priority range: 0-99 (lower numbers = higher priority = execute first)
Default priority: 50 for plain functions without priority specified
Cross-hierarchy: Functions from any directory level can control their execution order
Deterministic: Same execution order every time, across all environments

Key Benefits:

Backward Compatible: Existing projects work unchanged
Optional: Only use priorities where needed
Mixed Format Support: Use priority objects and plain functions together
Deterministic: Same behavior across all environments
Conflict Resolution: Prevents middleware execution order issues

API

Functions

Global	Description
loadModule(modulePath) ⇒ `Promise.<any>` \| `any`	Universal module loader that handles both CommonJS and ESM modules Tries CommonJS first, falls back to dynamic import for ESM
isMiddlewareFile(entry) ⇒ `boolean`	Checks if a directory entry is a middleware file
autoBox(ary) ⇒ `Array`	Ensures a value is always an array by wrapping non-array values
replaceUrlPlaceholders(urlPath) ⇒ `string`	Converts URL placeholder syntax [param] to Express parameter syntax :param
isPlaceholder(urlPath) ⇒ `boolean`	Checks if a URL path contains a placeholder
validatePath(path)	Validates if a path is a non-empty string
joinUrlPaths(base, segment) ⇒ `string`	Safely joins URL paths without creating double slashes Removes trailing slash from base and ensures segment starts with slash
parseDirectoryPriority(dirName) ⇒ `Object`	Parses directory name for priority prefix, extracts route name, and detects route type
normalizeMiddlewarePriority(middleware, sourceIndex, sourcePath) ⇒ `Array`	Normalizes middleware to priority objects with consistent structure
sortMiddlewareFunctions(middlewareArray) ⇒ `Array`	Sorts and flattens middleware functions by four-level priority system
dictionaryKeyStartsWithPath(dictionary, path) ⇒ `Array.<function()>`	Retrieves and sorts middleware functions that match a given path Finds all entries in the dictionary where the given path starts with the dictionary key, sorts them by key length (shortest first), and returns the flattened array of middleware functions Supports both legacy middleware format (plain functions) and priority object format ({ fn, priority }) with backward compatibility. Priority objects are sorted using the four-level priority system.
curryObjectMethods(router, urlPath, ...initialMiddleWareFunctions) ⇒ `Object`	Creates a curried router object with pre-configured URL path and middleware Returns a proxy to the original router that applies the given URL path and middleware functions to all HTTP method calls (get, post, put, etc.) automatically
buildMiddlewareDictionary(basePath, baseURL, [options]) ⇒ `Object.<string, Array.<function()>>`	Builds a dictionary of middleware functions from a directory structure Recursively scans the given directory for '_middleware.js' files and builds a dictionary mapping URL paths to their corresponding middleware functions
buildRoutes(basePath, baseURL) ⇒ `Array.<Array.<string>>`	Builds an array of route mappings from a directory structure Recursively scans the given directory for 'index.js' files and builds an array of URL paths and their corresponding file paths, converting directory placeholders to Express params
composeRoutes(express, routeMappings, [options]) ⇒ `Object`	Composes Express routes from a directory structure with middleware support. This is the main function that processes route mappings, builds middleware dictionaries, and configures an Express router with all discovered routes and middleware.

loadModule(modulePath) ⇒ `Promise.<any>` | `any`

Universal module loader that handles both CommonJS and ESM modules Tries CommonJS first, falls back to dynamic import for ESM

Kind: global function
Returns: Promise.<any> | any - - The loaded module

Param	Type	Description
modulePath	`string`	Path to the module to load

isMiddlewareFile(entry) ⇒ `boolean`

Checks if a directory entry is a middleware file

Kind: global function
Returns: boolean - - True if the entry is a file named '_middleware.js'

Param	Type	Description
entry	`Object`	The directory entry to check (fs.Dirent object)

Example

// With a file entry for '_middleware.js'
const middlewareEntry = { isFile: () => true, name: '_middleware.js' };
isMiddlewareFile(middlewareEntry); // Returns: true

Example

// With a directory entry
const dirEntry = { isFile: () => false, name: '_middleware.js' };
isMiddlewareFile(dirEntry); // Returns: false

Example

// With a different file
const otherFileEntry = { isFile: () => true, name: 'index.js' };
isMiddlewareFile(otherFileEntry); // Returns: false

autoBox(ary) ⇒ `Array`

Ensures a value is always an array by wrapping non-array values

Kind: global function
Returns: Array - - Wraps the value in an array, or if the input was an array already it will return it as is.

Param	Type	Description
ary	`*`	The value to convert to an array

Example

// With a non-array value
autoBox(5); // Returns: [5]

Example

// With an array value
autoBox([1, 2, 3]); // Returns: [1, 2, 3]

Example

// With null or undefined
autoBox(null); // Returns: [null]
autoBox(undefined); // Returns: [undefined]

Example

// With an object
autoBox({ key: 'value' }); // Returns: [{ key: 'value' }]

replaceUrlPlaceholders(urlPath) ⇒ `string`

Converts URL placeholder syntax [param] to Express parameter syntax :param

Kind: global function
Returns: string - - The URL path with Express-style parameters

Param	Type	Description
urlPath	`string`	The URL path containing placeholders

Example

// With single placeholder
replaceUrlPlaceholders('/users/[id]'); // Returns: '/users/:id'

Example

// With multiple placeholders
replaceUrlPlaceholders('/users/[id]/posts/[postId]'); // Returns: '/users/:id/posts/:postId'

Example

// With no placeholders
replaceUrlPlaceholders('/users/list'); // Returns: '/users/list'

Example

// With nested/complex placeholders
replaceUrlPlaceholders('/products/[category]/[id]/reviews/[reviewId]');
// Returns: '/products/:category/:id/reviews/:reviewId'

isPlaceholder(urlPath) ⇒ `boolean`

Checks if a URL path contains a placeholder

Kind: global function
Returns: boolean - - True if the path contains a placeholder

Param	Type	Description
urlPath	`string`	The URL path to check

Example

// With placeholder
isPlaceholder('/users/[id]'); // Returns: true

Example

// With multiple placeholders
isPlaceholder('/users/[id]/posts/[postId]'); // Returns: true

Example

// Without placeholder
isPlaceholder('/users/list'); // Returns: false

Example

// With square brackets in a different context (not a placeholder)
isPlaceholder('/users/list[all]'); // Returns: true (matches the regex pattern)

validatePath(path)

Validates if a path is a non-empty string

Kind: global function
Throws:

Error If path is not a string or is empty

Param	Type	Description
path	`string`	The path to validate

Example

// With valid path
validatePath('/api/users'); // No error thrown

Example

// With empty string
try {
  validatePath('');
} catch (error) {
  console.error(error.message); // Outputs: 'Invalid path provided'
}

Example

// With null value
try {
  validatePath(null);
} catch (error) {
  console.error(error.message); // Outputs: 'Invalid path provided'
}

Example

// With non-string value
try {
  validatePath(123);
} catch (error) {
  console.error(error.message); // Outputs: 'Invalid path provided'
}

joinUrlPaths(base, segment) ⇒ `string`

Safely joins URL paths without creating double slashes Removes trailing slash from base and ensures segment starts with slash

Kind: global function
Returns: string - - The joined path without double slashes

Param	Type	Description
base	`string`	The base URL path
segment	`string`	The path segment to append

Example

// With base having trailing slash
joinUrlPaths('/api/', 'users')
// Returns: '/api/users'

Example

// With base not having trailing slash
joinUrlPaths('/api', 'users')
// Returns: '/api/users'

Example

// With segment having leading slash
joinUrlPaths('/api', '/users')
// Returns: '/api/users'

Example

// Preventing double slashes
joinUrlPaths('/api/', '/users')
// Returns: '/api/users'

Example

// With empty base (edge case)
joinUrlPaths('', 'users')
// Returns: '/users'

Example

// With empty segment (edge case)
joinUrlPaths('/api', '')
// Returns: '/api/'

Example

// With both empty (edge case)
joinUrlPaths('', '')
// Returns: '/'

parseDirectoryPriority(dirName) ⇒ `Object`

Parses directory name for priority prefix, extracts route name, and detects route type

Kind: global function
Returns: Object - - { priority: number, name: string, hasPrefix: boolean, isDynamic: boolean }
Note: Logs warning message to console.info when invalid priority prefix is detected (out of 00-99 range)
Note: Valid priority range is 00-99; invalid ranges default to priority 50 with hasPrefix: false

Param	Type	Description
dirName	`string`	Directory name (e.g., "10-users", "users", "05-[id]", "[sessionId]")

Example

// With priority prefix and static route
parseDirectoryPriority("10-users")
// Returns: { priority: 10, name: "users", hasPrefix: true, isDynamic: false }

Example

// With priority prefix and dynamic route
parseDirectoryPriority("05-[userId]")
// Returns: { priority: 5, name: "[userId]", hasPrefix: true, isDynamic: true }

Example

// Without priority prefix (static route)
parseDirectoryPriority("users")
// Returns: { priority: 50, name: "users", hasPrefix: false, isDynamic: false }

Example

// Without priority prefix (dynamic route)
parseDirectoryPriority("[sessionId]")
// Returns: { priority: 50, name: "[sessionId]", hasPrefix: false, isDynamic: true }

Example

// Invalid priority range (falls back to default)
parseDirectoryPriority("150-invalid")
// Logs: "Invalid priority prefix detected in directory "150-invalid", using default priority 50"
// Returns: { priority: 50, name: "150-invalid", hasPrefix: false, isDynamic: false }

Example

// Invalid priority format (falls back to default)
parseDirectoryPriority("x5-invalid")
// Returns: { priority: 50, name: "x5-invalid", hasPrefix: false, isDynamic: false }

normalizeMiddlewarePriority(middleware, sourceIndex, sourcePath) ⇒ `Array`

Normalizes middleware to priority objects with consistent structure

Kind: global function
Returns: Array - Array of {fn, priority, sourceIndex, sourcePath} objects

Param	Type	Default	Description
middleware	`function` \| `Object` \| `Array`		Middleware function(s) or priority objects
sourceIndex	`number`	`0`	Original array position for tracking
sourcePath	`string`		Source path for specificity tracking

Example

// With plain function
normalizeMiddlewarePriority(corsMiddleware, 0, '/api/')
// Returns: [{ fn: corsMiddleware, priority: 50, sourceIndex: 0, sourcePath: '/api/' }]

Example

// With priority object
normalizeMiddlewarePriority({ fn: authMiddleware, priority: 10 }, 1, '/api/')
// Returns: [{ fn: authMiddleware, priority: 10, sourceIndex: 1, sourcePath: '/api/' }]

Example

// With array of mixed types
normalizeMiddlewarePriority([corsMiddleware, { fn: authMiddleware, priority: 20 }], 0, '/api/')
// Returns: [
//   { fn: corsMiddleware, priority: 50, sourceIndex: 0, sourcePath: '/api/' },
//   { fn: authMiddleware, priority: 20, sourceIndex: 1, sourcePath: '/api/' }
// ]

sortMiddlewareFunctions(middlewareArray) ⇒ `Array`

Sorts and flattens middleware functions by four-level priority system

Kind: global function
Returns: Array - Array of middleware functions sorted by priority

Param	Type	Description
middlewareArray	`Array`	Array of {fn, priority, sourceIndex, sourcePath} objects

Example

// With mixed priority middleware
const middleware = [
  { fn: authMiddleware, priority: 20, sourceIndex: 0, sourcePath: '/api/' },
  { fn: corsMiddleware, priority: 5, sourceIndex: 1, sourcePath: '/api/' },
  { fn: loggingMiddleware, priority: 90, sourceIndex: 0, sourcePath: '/api/users/' }
]
sortMiddlewareFunctions(middleware)
// Returns: [corsMiddleware, authMiddleware, loggingMiddleware]

dictionaryKeyStartsWithPath(dictionary, path) ⇒ `Array.<function()>`

Retrieves and sorts middleware functions that match a given path Finds all entries in the dictionary where the given path starts with the dictionary key, sorts them by key length (shortest first), and returns the flattened array of middleware functions

Supports both legacy middleware format (plain functions) and priority object format ({ fn, priority }) with backward compatibility. Priority objects are sorted using the four-level priority system.

Kind: global function
Returns: Array.<function()> - - Array of middleware functions that apply to the path, ordered by priority and path specificity
Note: Automatically converts legacy middleware functions to priority objects with default priority 50
Note: Uses four-level sorting: priority → function name → source index → path specificity

Param	Type	Description
dictionary	`Object.<string, (function()\|Array.<function()>\|Array.<Object>)>`	Dictionary of paths to middleware functions or priority objects
path	`string`	The path to match

Example

// With matching paths (legacy format)
const dict = {
  '/api/': [authMiddleware],
  '/api/users/': [userMiddleware]
};
dictionaryKeyStartsWithPath(dict, '/api/users/profile');
// Returns: [authMiddleware, userMiddleware] (in order from least to most specific)

Example

// With priority objects (new format)
const dict = {
  '/api/': [
    { fn: corsMiddleware, priority: 5 },
    { fn: authMiddleware, priority: 20 }
  ],
  '/api/users/': [
    { fn: userValidationMiddleware, priority: 15 }
  ]
};
dictionaryKeyStartsWithPath(dict, '/api/users/profile');
// Returns: [corsMiddleware, userValidationMiddleware, authMiddleware] (sorted by priority)

Example

// With mixed legacy and priority format (backward compatible)
const dict = {
  '/api/': [legacyMiddleware, { fn: priorityMiddleware, priority: 10 }],
  '/api/users/': userMiddleware  // Single function
};
dictionaryKeyStartsWithPath(dict, '/api/users/');
// Returns: [priorityMiddleware, legacyMiddleware, userMiddleware] (priority objects sorted first)

Example

// With no matching paths
const dict = {
  '/api/': [authMiddleware],
  '/api/users/': [userMiddleware]
};
dictionaryKeyStartsWithPath(dict, '/admin/');
// Returns: []

Example

// With null or undefined values in the dictionary (they are filtered out)
const dict = {
  '/api/': [authMiddleware, null],
  '/api/users/': undefined
};
dictionaryKeyStartsWithPath(dict, '/api/users/');
// Returns: [authMiddleware]

curryObjectMethods(router, urlPath, ...initialMiddleWareFunctions) ⇒ `Object`

Creates a curried router object with pre-configured URL path and middleware Returns a proxy to the original router that applies the given URL path and middleware functions to all HTTP method calls (get, post, put, etc.) automatically

Kind: global function
Returns: Object - - Curried router proxy with pre-configured path and middleware

Param	Type	Description
router	`Object`	Express router instance
urlPath	`string`	The URL path to be curried
...initialMiddleWareFunctions	`function`	Initial middleware functions to be applied (rest parameter, accepts multiple functions)

Example

// Basic usage with a single middleware function
const router = express.Router();
const curriedRouter = curryObjectMethods(router, '/users', authMiddleware);
curriedRouter.get((req, res) => res.json({}));
// Equivalent to: router.get('/users', authMiddleware, (req, res) => res.json({}));

Example

// With multiple middleware functions
const curriedRouter = curryObjectMethods(router, '/posts', authMiddleware, logMiddleware);
curriedRouter.post((req, res) => res.status(201).json({}));
// Equivalent to: router.post('/posts', authMiddleware, logMiddleware, (req, res) => res.status(201).json({}));

Example

// With no middleware
const curriedRouter = curryObjectMethods(router, '/public');
curriedRouter.get((req, res) => res.send('Hello'));
// Equivalent to: router.get('/public', (req, res) => res.send('Hello'));

Example

// Accessing the original router object
const curriedRouter = curryObjectMethods(router, '/api');
const originalRouter = curriedRouter._getOriginalObject();
// originalRouter is the router instance passed in the first parameter

buildMiddlewareDictionary(basePath, baseURL, [options]) ⇒ `Object.<string, Array.<function()>>`

Builds a dictionary of middleware functions from a directory structure Recursively scans the given directory for '_middleware.js' files and builds a dictionary mapping URL paths to their corresponding middleware functions

Kind: global function
Returns: Object.<string, Array.<function()>> - Dictionary where keys are URL paths and values are arrays of middleware functions

Param	Type	Description
basePath	`string`	Base filesystem path to start scanning
baseURL	`string`	Base URL path for the routes
[options]	`Object`	Options that can be passed to all controllers when they are executed.

Example

// Basic directory structure with middleware
// ./src/routes/_middleware.js         -> exports a global middleware
// ./src/routes/users/_middleware.js   -> exports a users-specific middleware
const middlewares = buildMiddlewareDictionary('./src/routes', '/api');
// Returns: {
//   '/api/': [globalMiddleware],
//   '/api/users/': [usersMiddleware]
// }

Example

// With dynamic route parameters
// ./src/routes/users/[id]/_middleware.js  -> exports a user-specific middleware
const middlewares = buildMiddlewareDictionary('./src/routes', '/api');
// Returns: {
//   '/api/': [globalMiddleware],
//   '/api/users/': [usersMiddleware],
//   '/api/users/:id/': [userSpecificMiddleware]
// }

Example

// With middleware exporting multiple functions
// ./src/routes/_middleware.js  -> exports [authMiddleware, logMiddleware]
const middlewares = buildMiddlewareDictionary('./src/routes', '/api');
// Returns: {
//   '/api/': [authMiddleware, logMiddleware]
// }

Example

// With middleware exporting a single function
// ./src/routes/_middleware.js  -> exports singleMiddleware (not in an array)
const middlewares = buildMiddlewareDictionary('./src/routes', '/api');
// Returns: {
//   '/api/': [singleMiddleware]
// }

buildRoutes(basePath, baseURL) ⇒ `Array.<Array.<string>>`

Builds an array of route mappings from a directory structure Recursively scans the given directory for 'index.js' files and builds an array of URL paths and their corresponding file paths, converting directory placeholders to Express params

Kind: global function
Returns: Array.<Array.<string>> - Array of tuples where first element is URL path and second is file path

Param	Type	Description
basePath	`string`	Base filesystem path to start scanning
baseURL	`string`	Base URL path for the routes

Example

// Basic directory structure
// ./src/routes/users/index.js
// ./src/routes/posts/index.js
const routes = buildRoutes('./src/routes', '/api');
// Returns: [
//   ['/api/users/', './src/routes/users/index.js'],
//   ['/api/posts/', './src/routes/posts/index.js']
// ]

Example

// With dynamic route parameters
// ./src/routes/users/[id]/index.js
const routes = buildRoutes('./src/routes', '/api');
// Returns: [
//   ['/api/users/:id/', './src/routes/users/[id]/index.js']
// ]

Example

// With nested dynamic routes
// ./src/routes/users/[userId]/posts/[postId]/index.js
const routes = buildRoutes('./src/routes', '/api');
// Returns: [
//   ['/api/users/:userId/posts/:postId/', './src/routes/users/[userId]/posts/[postId]/index.js']
// ]

Example

// With root route
// ./src/routes/index.js
const routes = buildRoutes('./src/routes', '/api');
// Returns: [
//   ['/api/', './src/routes/index.js']
// ]

composeRoutes(express, routeMappings, [options]) ⇒ `Object`

Composes Express routes from a directory structure with middleware support. This is the main function that processes route mappings, builds middleware dictionaries, and configures an Express router with all discovered routes and middleware.

Kind: global function
Returns: Object - Configured Express router with applied routes

Param	Type	Description
express	`Object`	The Express module instance
routeMappings	`Array.<Object>`	Array of route mapping configurations
routeMappings[].basePath	`string`	Base filesystem path to start scanning
routeMappings[].baseURL	`string`	Base URL path for the routes
[options]	`Object`	Configuration options
[options.routerOptions]	`Object`	Options for the Express router (default: `{ strict: true }` stay with this for best results but be advised it makes paths require to be terminated with `/` )
[options.middlewareOptions]	`Object`	Options passed to every middleware.
[options.controllerOptions]	`Object`	Options passed to every controller.

Example

// Basic usage with a single route mapping
const express = require('express');
const app = express();

const router = composeRoutes(express, [
  {
    basePath: './src/routes',
    baseURL: '/api'
  }
]);

app.use(router);
// This will set up all routes found in './src/routes' with their middleware

Example

// With multiple route mappings
const router = composeRoutes(express, [
  {
    basePath: './src/api/routes',
    baseURL: '/api'
  },
  {
    basePath: './src/admin/routes',
    baseURL: '/admin'
  }
]);

Example

// With custom router options
const router = composeRoutes(express, [
  {
    basePath: './src/routes',
    baseURL: '/api'
  }
], {
  routerOptions: {
    strict: true,
  }
});

Example

// With an existing router instance
const existingRouter = express.Router();
const router = composeRoutes(express, [
  {
    basePath: './src/routes',
    baseURL: '/api'
  }
], {
  router: existingRouter
});

Usage

Lets make some assumptions, and then walk through what will happen.

your Routes should look something like this.

src/routes
├── closed
│   └── organizations
│       └── [organizationId]
│           ├── clients
│           │   └── [clientId]
│           │       ├── contracts
│           │       │   └── index.js
│           │       └── projects
│           │           └── index.js
│           └── departments
│               └── [departmentId]
│                   ├── employees
│                   │   ├── [employeeId]
│                   │   │   ├── projects
│                   │   │   │   └── index.js
│                   │   │   └── tasks
│                   │   │       └── index.js
│                   │   └── index.js
│                   └── subdepartments
│                       └── [subDepartmentId]
│                           └── employees
│                               ├── [employeeId]
│                               │   ├── projects
│                               │   │   └── index.js
│                               │   └── tasks
│                               │       └── index.js
│                               └── index.js
└── open
    ├── _middleware.js
    ├── blog-posts
    │   ├── [blogPostId]
    │   │   └── index.js
    │   ├── _middleware.js
    │   └── index.js
    └── users
        ├── [userId]
        │   ├── blog-posts
        │   │   ├── _middleware.js
        │   │   └── index.js
        │   ├── friends
        │   │   ├── [friendId]
        │   │   │   └── blog-posts
        │   │   │       ├── _middleware.js
        │   │   │       └── index.js
        │   │   └── index.js
        │   └── index.js
        └── index.js

This program will scan a directory structure and build URLs and Path Parameters based on the following rules:

path parameters can only be a directory
path parameters are identified as a bracket ( [ ) followed by some text that can be a valid Express path parameter and then closed off by a closing bracket ]
there can only be two files in a single directory, an index.js or _middleware.js
both of these javascript files, must return a function to be executed
- _middleware.js accepts no parameters, however this is to allow you to perform Dependency Injection (DI) for the purpose of testing and isolation ( more on this later )
  - The middleware is hieratical by default, using Regular Expressions to do this, makes a system unnecessarily more complicated and impacts performance.
- index.js accepts a Express Router and is expected to return that router with controllers ( and local middleware ) attached to the router object.
  - while in the index.js you will not need to provide a path, the code will do that for you, it will even convert the path variables to Express Path variables.

An example index.js

A simple example without a local middleware

const standard_controllers = (req, res, _next) => res.status(200).send({
  route: `${req.baseUrl}${req.route.path}`,
  params: req.params
})

module.exports = (router) => {
  router.get(standard_controllers)
  router.post(standard_controllers)
  router.put(standard_controllers)
  router.patch(standard_controllers)
  router.delete(standard_controllers)
  return router
}

Another simple example with localized middleware ( it will only apply to requests made into this path )

const microMiddleware = (req, res, next) => {
  req.params = req.params || {};
  req.params.context = req.params.context || {};
  Object.assign(req.params.context, { microMiddleware: true })
  next()
}

const standard_controllers = (req, res, _next) => res.status(200).send({
  route: `${req.baseUrl}${req.route.path}`,
  params: req.params
})

module.exports = (router) => {
  router.get(microMiddleware, standard_controllers)
  router.post(microMiddleware, standard_controllers)
  router.put(microMiddleware, standard_controllers)
  router.patch(microMiddleware, standard_controllers)
  router.delete(microMiddleware, standard_controllers)
  return router
}

An example _middleware.js

A single middleware that will be applied to the current directory ( end point ) and all subsequent paths.

module.exports = () => {
  function standard_middleware(req, res, next) {
    req.params = req.params || {};
    req.params.context = req.params.context || {};
    // Merge the context object with req.params.context
    Object.assign(req.params.context, { blogPost: true })
    next()
  }

  return standard_middleware
}

Multiple middleware, with importance on the order of execution, applied to the current directory ( end point ) and all subsequent paths.

module.exports = () => {
  function standard_middleware_must_go_first(req, res, next) {
    req.params = req.params || {};
    req.params.context = req.params.context || {};
    // Merge the context object with req.params.context
    Object.assign(req.params.context, { first: true })
    next()
  }

  function standard_middleware_must_go_second(req, res, next) {
    req.params = req.params || {};
    req.params.context = req.params.context || {};
    if (req.params.context.first) {
      Object.assign(req.params.context, { second: true })
      return next()
    }
    next(new Error('Missing required first execution of the middleware'))
  }

  return [
    standard_middleware_must_go_first,
    standard_middleware_must_go_second
  ]
}

At this point, you are ready to use it...

CommonJS (CJS) Usage

Due to how Rollup exports the module, you need to access the default property when using CommonJS:

const express = require('express')
const { join } = require('path')
// Note: Access .default due to Rollup export structure
const { composeRoutes } = require('@psenger/express-auto-router').default
const app = express()
const routeMappings = [
  {
    basePath: join(process.cwd(), 'src', 'routes', 'open'),
    baseURL: '/open'
  },
  {
    basePath: join(process.cwd(), 'src', 'routes', 'closed'),
    baseURL: '/closed'
  }
]
app.use('/api', composeRoutes(express, routeMappings))
module.exports = app

ES Modules (ESM) Usage

For ES modules, you also need to access the default property:

import express from 'express'
import { join } from 'path'
// Note: Access .default due to Rollup export structure
import module from '@psenger/express-auto-router'
const composeRoutes = module.default

const app = express()
const routeMappings = [
  {
    basePath: join(process.cwd(), 'src', 'routes', 'open'),
    baseURL: '/open'
  },
  {
    basePath: join(process.cwd(), 'src', 'routes', 'closed'),
    baseURL: '/closed'
  }
]
app.use('/api', composeRoutes(express, routeMappings))
export default app

Contributing

Thanks for contributing! 😁 Here are some rules that will make your change to Express-auto-router fruitful.

Rules

Raise a ticket to the feature or bug can be discussed
Pull requests are welcome, but must be accompanied by a ticket approved by the repo owner
You are expected to add a unit test or two to cover the proposed changes.
Please run the tests and make sure tests are all passing before submitting your pull request
Do as the Romans do and stick with existing whitespace and formatting conventions (i.e., tabs instead of spaces, etc)
- we have provided the following: .editorconfig and .eslintrc
- Don't tamper with or change .editorconfig and .eslintrc
Please consider adding an example under examples/ that demonstrates any new functionality

Commit Message

This module uses release-please which needs commit messages to look like the following Conventional Commits

Basic Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type is typically fix, feat. When type ends with a ! or includes BREAKING CHANGE in the body/footer, it indicates this is a breaking change.

type should be followed by a short description,

optional body can have more detail

Commit Types and CHANGELOG Impact

The following commit types will be grouped in the CHANGELOG:

Type	Description	CHANGELOG Section	Example
`feat`	New feature	Features	`feat: add markdown table support`
`fix`	Bug fix	Bug Fixes	`fix: resolve parsing error for nested lists`
`perf`	Performance improvement	Performance Improvements	`perf: optimize regex for faster parsing`
`revert`	Revert a previous commit	Reverts	`revert: feat: add markdown table support`

The following types are valid but typically excluded from CHANGELOG:

docs: Documentation only changes
style: Code style changes (formatting, missing semicolons, etc)
refactor: Code changes that neither fix bugs nor add features
test: Adding or updating tests
build: Changes to build system or dependencies
ci: Changes to CI configuration files and scripts
chore: Other changes that don't modify src or test files

Commit Examples

Features

# Simple feature
git commit -m "feat: add support for custom fence renderers"

# Feature with scope (include ticket if applicable)
git commit -m "feat(parser): add HTML5 output option (TICKET-123)"

# Feature with detailed body
git commit -m "feat: add plugin system for custom syntaxes" -m "- Support for registering custom parsers
- Add hooks for pre/post processing
- Include TypeScript definitions"

Bug Fixes

# Simple fix
git commit -m "fix: correct fence detection for indented blocks"

# Fix with scope and ticket
git commit -m "fix(lexer): handle edge case in nested fences (TICKET-456)"

Breaking Changes (for major releases)

# Method 1: Using ! after type
git commit -m "feat!: change API to use async/await pattern"

# Method 2: Using BREAKING CHANGE in body
git commit -m "feat: redesign parser API" -m "BREAKING CHANGE: parse() now returns a Promise instead of synchronous result.
Update all calls to use await or .then()"

# Method 3: Multi-line format
git commit -m "refactor: update configuration schema

BREAKING CHANGE: Config property 'enableLegacy' removed.
Use 'parserMode: \"legacy\"' instead.

Closes #789"

Other Types (won't appear in CHANGELOG)

# Documentation
git commit -m "docs: improve API documentation examples"

# Code style
git commit -m "style: apply eslint formatting rules"

# Tests
git commit -m "test: add edge cases for fence parsing"

# Build/Dependencies
git commit -m "build: update to webpack 5"
git commit -m "chore: bump dependencies"

# CI/CD
git commit -m "ci: add Node.js 20 to test matrix"

Commit Message Best Practices

First line should be no more than 72 characters
Use present tense ("add feature" not "added feature")
Use imperative mood ("fix bug" not "fixes bug")
Reference tickets when applicable: feat(TICKET-123): add feature or include in body
Be specific - "fix: resolve memory leak in parser" is better than "fix: fix bug"

What Makes a Good Commit Message

❌ Bad:

Added new feature
fix
Updated code
FEAT: ADD PARSER (wrong case)
feat - add parser (wrong separator)

✅ Good:

feat: add markdown table parsing support
fix: prevent infinite loop when parsing malformed fences
feat(parser): implement GFM-style strikethrough (TICKET-234)
fix!: correct fence regex to match spec

BREAKING CHANGE: Fences with spaces after opening backticks are no longer valid.
This aligns with CommonMark specification.

Testing

All tests are expected to work
Tests are based off of dist/index.js NOT your src code. Therefore, you should BUILD it first.
Coverage should not go down, and I acknowledge it is very difficult to get the tests to 100%

Running Tests

# Build first
npm run build

# Run all tests
npm run test

# Run with coverage
npm run test:coverage

# Run linting
npm run test:lint

# Run integration tests
cd test/integration-cjs && npm test
cd test/integration-esm && npm test

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgments

This project directly uses the following open-source packages:

Dependencies

None

Development Dependencies

@psenger/markdown-fences - MIT License
@rollup/plugin-commonjs - MIT License
@rollup/plugin-node-resolve - MIT License
eslint-config-prettier - MIT License
eslint-plugin-jest - MIT License
eslint-plugin-prettier - MIT License
eslint - MIT License
express - MIT License
jest-html-reporters - MIT License
jest - MIT License
jsdoc - Apache-2.0 License
license-checker - BSD-3-Clause License
markdown-toc - MIT License
prettier - MIT License
rimraf - ISC License
rollup - MIT License
standard-version - ISC License
supertest - MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github		.github
docs		docs
scripts		scripts
src		src
test		test
.README.md		.README.md
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT_STEPS.md		DEPLOYMENT_STEPS.md
HOWITWORKS.md		HOWITWORKS.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
USAGE.md		USAGE.md
eslint.config.mjs		eslint.config.mjs
jest.config.cjs		jest.config.cjs
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js

License

psenger/express-auto-router

Folders and files

Latest commit

History

Repository files navigation

express-auto-router

Table of Contents

Features

Installation

How it Works

1. Directory Structure as Routes

2. Key Design Decisions

Dynamic Routes

Hierarchical Middleware

Strict Route Endings

Opinions in the Code

Potential Issues and Considerations

1. Trailing Slash Handling

2. Middleware Control

Best Practices When Using This System

Future Considerations

3. Priority-Based Routing

The Problem: Route Registration Order

Traditional Routing (Backward Compatible)

Priority-Based Routing (Optional Enhancement)

Dynamic Routes with Priorities

Mixed Priority/Non-Priority Behavior

Route Priority Rules

Common Use Cases

Middleware Priority Support

Traditional Middleware (Backward Compatible)

Priority-Based Middleware (Optional Enhancement)

Mixed Format Support

Cross-Hierarchy Execution Order

Priority Rules

API

Functions

loadModule(modulePath) ⇒ Promise.<any> | any

isMiddlewareFile(entry) ⇒ boolean

autoBox(ary) ⇒ Array

replaceUrlPlaceholders(urlPath) ⇒ string

isPlaceholder(urlPath) ⇒ boolean

validatePath(path)

joinUrlPaths(base, segment) ⇒ string

parseDirectoryPriority(dirName) ⇒ Object

normalizeMiddlewarePriority(middleware, sourceIndex, sourcePath) ⇒ Array

sortMiddlewareFunctions(middlewareArray) ⇒ Array

dictionaryKeyStartsWithPath(dictionary, path) ⇒ Array.<function()>

curryObjectMethods(router, urlPath, ...initialMiddleWareFunctions) ⇒ Object

buildMiddlewareDictionary(basePath, baseURL, [options]) ⇒ Object.<string, Array.<function()>>

buildRoutes(basePath, baseURL) ⇒ Array.<Array.<string>>

composeRoutes(express, routeMappings, [options]) ⇒ Object

Usage

CommonJS (CJS) Usage

ES Modules (ESM) Usage

Contributing

Rules

Commit Message

Basic Format

Commit Types and CHANGELOG Impact

Commit Examples

Features

Bug Fixes

Breaking Changes (for major releases)

Other Types (won't appear in CHANGELOG)

Commit Message Best Practices

What Makes a Good Commit Message

Testing

Running Tests

License

Acknowledgments

Dependencies

Development Dependencies

About

Topics

Resources

License

Contributing

Uh oh!

loadModule(modulePath) ⇒ `Promise.<any>` | `any`

isMiddlewareFile(entry) ⇒ `boolean`

autoBox(ary) ⇒ `Array`

replaceUrlPlaceholders(urlPath) ⇒ `string`

isPlaceholder(urlPath) ⇒ `boolean`

joinUrlPaths(base, segment) ⇒ `string`

parseDirectoryPriority(dirName) ⇒ `Object`

normalizeMiddlewarePriority(middleware, sourceIndex, sourcePath) ⇒ `Array`

sortMiddlewareFunctions(middlewareArray) ⇒ `Array`

dictionaryKeyStartsWithPath(dictionary, path) ⇒ `Array.<function()>`

curryObjectMethods(router, urlPath, ...initialMiddleWareFunctions) ⇒ `Object`

buildMiddlewareDictionary(basePath, baseURL, [options]) ⇒ `Object.<string, Array.<function()>>`

buildRoutes(basePath, baseURL) ⇒ `Array.<Array.<string>>`

composeRoutes(express, routeMappings, [options]) ⇒ `Object`

Packages