@moducate/houston v1.0.0
Houston
⚠ RFC 7807 compliant errors for Node.js
- 📋 Fully compliant. Fully compliant with the RFC 7807 specification!
- ⚙ Configurable. Supports custom JSON stringify functions!
- 📃 Support for templating. Create template functions to generate errors from parameters!
- 🐁 Tiny. Total bundle size comes in at < 300B minified + gzipped!
- 💡 Lightweight. Tiny (see above), zero dependencies, and tree-shakeable!
- 💪 TypeScript. Fully typed and self-documenting!
- 🎉 Support for Node.js >=10.24!
🚀 Quick Start
Install
# npm
npm i @moducate/houston
# or yarn
yarn add @moducate/houston
Import
// ESM / TypeScript
import { withError } from "@moducate/houston";
// or CommonJS
const { withError } = require("@moducate/houston");
📄 Templates
You can create error templates using the exported withTemplate
function:
const { withTemplate } = require("@moducate/houston");
const app = require("express")();
const [withUserNotFound, rawUserNotFound] = withTemplate(({ userId }) => ({
type: "https://example.com/user-not-found",
status: 404,
instance: `/users/${userId}`,
}));
app.get("/not-found", (_, res) => {
return withUserNotFound(res, { userId: 1 });
});
const res = rawUserNotFound({ userId: 1 });
// => The second function returned by withTemplate transforms and returns an object (decoupled from http.ServerResponse)
console.log(JSON.stringify(res));
// => { "type": "https://example.com/user-not-found", "status": 404, "instance": "/users/1" }
If you are not needing to use both functions, you can use this handy shorthand to obtain one of them:
const { withTemplate } = require("@moducate/houston");
const [withNotFound] = withTemplate(() => ({ type: "https://example.com/not-found", status: 404 }));
// => Returns the function that transforms a http.ServerResponse
const [, withNotFound] = withTemplate(() => ({ type: "https://example.com/not-found", status: 404 }));
// => Returns the raw function for transforming an object
💪 TypeScript
withTemplate
supports TypeScript generics so you can have type definitions for your template's parameters:
const [withUserNotFound] = withTemplate<{ userId: number }>(({ userId }) => ({
type: "https://example.com/user-not-found",
status: 404,
instance: `/users/${userId}`,
}));
// => withUserNotFound's second parameter (`params`) now has the type `{ userId: number }`
🏷 MIME Type
The exported mime
constant can be used to obtain the media/MIME type for RFC 7807 JSON errors.
const { mime } = require("@moducate/houston");
console.log(mime);
// => 'application/problem+json'
This is what the Content-Type
header of the response supplied to withError
is set to.
⚙ Options
You can supply options as an additional parameter to withError
and withTemplate
(and the subsequent withError
function
returned by the template) to configure Houston's behaviour:
...
withError(
res,
{ type: "https://example.com/not-found", status: 404 },
{ /* options */ },
);
...
options.stringify
You can supply a custom function used to stringify the error response's JSON body.
By default,
JSON.stringify
is used.
💡 Examples
📁 Full source code for these examples can be found in the
examples
directory.
Express
const { withError } = require("@moducate/houston");
const app = require("express")();
app.get("/not-found", (_, res) => {
return withError(res, { type: "https://example.com/not-found", status: 404 });
});
Next.js API Routes
import { withError } from "@moducate/houston";
export default function handler(req, res) {
return withError(res, { type: "https://example.com/not-found", status: 404 });
}
Fastify
⚠ Fastify uses a custom
Reply
class, rather thanhttp.ServerResponse
.This means you need to supply
reply.raw
(instead ofreply
) towithError()
.
const { withError } = require("@moducate/houston");
const app = require("fastify")();
app.get("/not-found", (_, reply) => {
return withError(reply.raw, { type: "https://example.com/not-found", status: 404 });
});
fast-json-stringify
See the examples/fast-json-stringify
directory for an example project using Houston with Fastify and fast-json-stringify.
Templates
See the examples/templates
directory for an example project using Houston's templating functionality with Express.
⚖ License
Houston is licensed under the MIT License
.