HTTP Hash Router

2.0.1 verified Thu Apr 23 auth: no javascript maintenance

http-hash-router is a lightweight server-side routing utility for Node.js's native `http` module, built upon the `http-hash` package for pattern matching. It is currently at version 2.0.1 and appears to be a stable, mature package primarily designed for CommonJS environments, indicated by its `require` syntax in examples. While specific release cadence isn't published, its current version and historical usage patterns suggest a focus on stability rather than frequent feature updates. It provides a simple API to define routes using patterns (including parameters and splats) and associate them with request handlers. A key differentiator is its callback-based error handling, specifically designed to integrate directly into Node.js's HTTP server callback without introducing a complex middleware stack. It explicitly manages `404 Not Found` errors and provides a structured way to access URL parameters within handlers, making it suitable for minimalistic HTTP service implementations.

Common errors

error http-hash-router.expected.callback (runtime exception) ↓

cause The main `router` function was invoked without a fourth argument, which must be a callback function for error handling.

fix

Always provide a callback as the fourth argument to the router function, e.g., router(req, res, {}, onError);. This callback will receive any errors, including NotFoundError (for 404s), or will be passed to your route handler if no error occurred.

error TypeError: HttpHashRouter is not a function (when using import) ↓

cause The package is primarily CommonJS (CJS) and its default export might not be directly compatible with ESM `import` syntax without specific Node.js or bundler configuration.

fix

Use the CommonJS require() syntax: const HttpHashRouter = require('http-hash-router'); instead of import HttpHashRouter from 'http-hash-router';.

Warnings

gotcha The `router` function (`router(req, res, opts, cb)`) explicitly *requires* a callback function as its fourth argument. Failing to provide one will immediately throw an `http-hash-router.expected.callback` exception. ↓

fix Always pass a callback function as the fourth argument to `router(req, res, opts, onError)` to handle potential errors, including 404 Not Found errors.

gotcha This package is designed for CommonJS (CJS) environments and primarily uses `require()`. While it might be usable in an ESM project via compatibility layers, direct `import` statements are not officially supported or demonstrated. Users should anticipate potential interop issues if integrating into modern ESM-only Node.js projects. ↓

fix For ESM projects, consider using a CommonJS compatibility layer or bundler to consume this package. Alternatively, explore modern routing libraries built with native ESM support.

gotcha Error handling is entirely callback-based, meaning errors (including 404 Not Found) are passed to the provided callback function, not thrown or handled by Promises. This contrasts with modern `async/await` patterns. ↓

fix Ensure your application explicitly handles errors within the callback passed to the router. Convert callback-based handlers to Promises if integrating with an `async/await` codebase.

Install

npm install http-hash-router

yarn add http-hash-router

pnpm add http-hash-router

Imports

HttpHashRouter
wrong
```
import HttpHashRouter from 'http-hash-router';
```
correct
```
const HttpHashRouter = require('http-hash-router');
```
Package is primarily CommonJS (CJS). Direct ESM `import` statements are not officially supported and may require interop configuration.
router.set
wrong
```
router.add('/path', handlerFunc);
```
correct
```
router.set('/path', handlerFunc);
```
Routes are defined using the `.set()` method on the router instance, not `.add()` or other common router methods.

Quickstart

Demonstrates setting up a basic HTTP server with `http-hash-router`, defining two routes (one static, one with a parameter), and handling errors including 404s via a callback.

const http = require('http');
const HttpHashRouter = require('http-hash-router');

const router = HttpHashRouter();

router.set('/health', function health(req, res) {
    res.setHeader('Content-Type', 'text/plain');
    res.end('OK');
});

router.set('/greet/:name', function greet(req, res, opts, cb) {
    res.setHeader('Content-Type', 'text/plain');
    res.end(`Hello, ${opts.params.name}!`);
});

const server = http.createServer(function handler(req, res) {
    router(req, res, {}, onError);

    function onError(err) {
        if (err) {
            // Custom error serialization and response
            res.statusCode = err.statusCode || 500;
            res.setHeader('Content-Type', 'application/json');
            if (err.type === 'http-hash-router.not-found') {
                res.end(JSON.stringify({ error: 'Not Found', path: req.url }));
            } else {
                res.end(JSON.stringify({ error: err.message || 'Internal Server Error' }));
            }
        }
    }
});

server.listen(3000, () => {
    console.log('Server listening on http://localhost:3000');
    console.log('Try visiting http://localhost:3000/health and http://localhost:3000/greet/world');
});