Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fortuneHTTP
✓ const fortuneHTTP = require('fortune-http')
✗ import fortuneHTTP from 'fortune-http'
The library is primarily designed for CommonJS environments and uses `require()` for its main export, which is a function. ESM `import` is not officially supported or documented.
listener
✓ const listener = fortuneHTTP(fortuneInstance, options)
✗ const listener = new fortuneHTTP(fortuneInstance, options)
The `fortuneHTTP` export is a function that returns another listener function, not a constructor.
requestHandler
✓ server.on('request', (request, response) => listener(request, response).catch(console.error))
✗ server.on('request', listener)
The listener returns a Promise and requires explicit error handling via `.catch()`.
Demonstrates setting up a basic Node.js HTTP server using `fortune-http` with a mock `Fortune.js` instance, showcasing how to handle requests and catch potential errors.
const http = require('http');
const fortuneHTTP = require('fortune-http');
// A mock Fortune.js instance for demonstration purposes.
// In a real application, you would initialize Fortune.js.
const mockFortuneInstance = {
request: async (type, payload) => {
console.log(`Fortune.js request: ${type}`, payload);
// Simulate database operations
if (type === 'create') return { records: [{ id: Math.random().toString(36).substring(7), ...payload.records[0] }] };
if (type === 'find') return { records: [{ id: 'abc', message: 'Hello from Fortune!' }] };
return { records: [] };
}
};
// Pass in a Fortune instance and an optional options object.
const listener = fortuneHTTP(mockFortuneInstance, {
// Example customization for HTML serializer (default prefix is empty string)
prefix: '/api'
});
const server = http.createServer((request, response) =>
listener(request, response)
.catch(error => {
console.error('Fortune HTTP Error:', error.stack);
if (!response.headersSent) {
response.writeHead(500, { 'Content-Type': 'application/json' });
response.end(JSON.stringify({ error: error.message }));
}
})
);
const PORT = process.env.PORT || 3000;
server.listen(PORT, () => {
console.log(`Fortune HTTP server listening on http://localhost:${PORT}`);
console.log(`Try: curl http://localhost:${PORT}/api/find/posts`);
console.log(`Try: curl -X POST -H "Content-Type: application/json" -d '{"records": [{"message": "New post!"}]}' http://localhost:${PORT}/api/create/posts`);
});
Debug
Known issues
gotchaThe `fortuneHTTP` function returns a Promise. All calls to the listener must explicitly handle promise rejections (e.g., with `.catch()`) to prevent unhandled promise errors from crashing the Node.js process.fixEnsure all calls to the listener function are followed by a `.catch(error => { /* handle error */ })` block. affects: >=1.0.0
gotchaWhen used with middleware frameworks like Express, the `fortune-http` listener should typically be the last middleware in the stack for a given route, as it ends the response by default. Placing other middleware after it may lead to 'Headers already sent' errors.fixPosition `app.use(listener)` or similar at the end of your middleware chain for routes handled by Fortune HTTP.
affects: >=1.0.0
gotchaForm serializers in `fortune-http` require all payloads to include cookie values prefixed with `CSRF_` for Cross-Site Request Forgery (CSRF) protection. Omitting these will result in failed form submissions.fixEnsure that form submissions include appropriate CSRF cookie values prefixed with `CSRF_`.
affects: >=1.0.0
gotchaThe special field `__method__` can be used within form payloads to override the HTTP method. This is a specific mechanism for scenarios where standard HTTP methods cannot be used directly.fixIf HTTP method overriding is required for form submissions, include `__method__` field in the payload with the desired Fortune.js-accepted method.
affects: >=1.0.0
deprecatedPrevious versions of Fortune.js (before 5.0.0) had HTTP capabilities directly within the core `fortune.net.http` namespace. `fortune-http` was extracted as a separate module in Fortune.js v5.0.0. Older applications may need to update their import paths.fixFor Fortune.js v5.0.0 and later, use `require('fortune-http')` directly instead of `fortune.net.http`. affects: <5.0.0 (Fortune.js)
Errors
Common errors & fixes
TypeError: fortuneHTTP is not a function
Attempting to import `fortune-http` using an ESM `import` statement or incorrectly assuming it's a class, or if CommonJS `require` yields an unexpected value.
fixUse CommonJS `const fortuneHTTP = require('fortune-http')` as the primary method of importing. UnhandledPromiseRejectionWarning: Unhandled promise rejection.
The `listener` function returned by `fortuneHTTP` is asynchronous and returns a Promise. If this Promise rejects and the rejection is not caught, Node.js will log this warning or crash the process in newer versions.
fixAlways append a `.catch()` block to the `listener` call, e.g., `listener(request, response).catch(console.error)`.
Error: Headers already sent
When using `fortune-http` within an Express.js or similar middleware stack, another middleware might be attempting to send a response after `fortune-http` has already done so, or vice-versa, due to incorrect ordering.
fixEnsure that the `fortune-http` listener is positioned as the last middleware in the chain for the routes it is intended to handle, as it typically ends the response by default.
Fortune HTTP Error: A Fortune instance is required.
The `fortuneHTTP` function was called without providing a valid Fortune.js instance as its first argument.
fixPass an initialized instance of `Fortune.js` to `fortuneHTTP`, like `fortuneHTTP(myFortuneInstance, options)`.
CSRF token mismatch
A request, particularly a form submission, was made to `fortune-http`'s form serializers without the required `CSRF_` prefixed cookie values.
fixInclude a cookie value prefixed with `CSRF_` in your form submissions as required by the `fortune-http` form serializers for CSRF protection.
Audit
Dependencies
fortunerequiredThis module provides the HTTP interface for a Fortune.js instance, making it a peer dependency.
@node-rs/crc32requiredRuntime dependency for CRC32 calculations, introduced in version 1.2.28.