Express HTTP Problem Details

0.2.1 verified Sat Apr 25 auth: no javascript

Express middleware for RFC 7807 HTTP Problem Details content negotiation. Current stable version 0.2.1. It integrates with http-problem-details-mapper to map custom Node.js errors to standard Problem Documents. Key differentiators: automatic content negotiation based on Accept header, ships TypeScript types, and builds on the PDMLab ecosystem of problem-details libraries. Release cadence is low, with the last release in 2020.

Common errors

error TypeError: Cannot destructure property 'strategy' of 'undefined' or 'null' ↓

cause HttpProblemResponse called without arguments.

fix

server.use(HttpProblemResponse({ strategy }))

error TypeError: strategy.mapError is not a function ↓

cause The 'strategy' object does not implement the MappingStrategy interface.

fix

Use an instance of DefaultMappingStrategy from http-problem-details-mapper.

error TypeError: (intermediate value) is not iterable ↓

cause MapperRegistry.registerMapper() expects a single mapper, not an array.

fix

Call registerMapper multiple times, or pass mappers individually.

Warnings

gotcha Middleware must be placed after all other error-handling middleware that sends responses, otherwise Problem Document may not be generated. ↓

fix Ensure HttpProblemResponse is the last error-handling middleware.

deprecated ExpressMappingStrategy was deprecated in v0.2.0 in favor of DefaultMappingStrategy from http-problem-details-mapper. ↓

fix Use DefaultMappingStrategy from http-problem-details-mapper instead.

gotcha The package does not include express as a dependency; it must be installed separately. ↓

fix Install express separately: npm install express.

gotcha HttpProblemResponse expects a 'strategy' option; omitting it will cause a runtime error. ↓

fix Always pass an object with a 'strategy' property that implements MappingStrategy.

breaking In v0.1.0, the middleware was named 'httpProblemResponse' (lowercase); renamed to 'HttpProblemResponse' in v0.2.0. ↓

fix Import { HttpProblemResponse } from 'express-http-problem-details' (capital H).

Install

npm install express-http-problem-details

yarn add express-http-problem-details

pnpm add express-http-problem-details

Imports

HttpProblemResponse

wrong

const { HttpProblemResponse } = require('express-http-problem-details')

correct

import { HttpProblemResponse } from 'express-http-problem-details'

ESM import; commonjs require works but is discouraged.

ExpressMappingStrategy

wrong

import ExpressMappingStrategy from 'express-http-problem-details'

correct

import { ExpressMappingStrategy } from 'express-http-problem-details'

Named export, not default. Available since v0.1.0.

default

wrong

const HttpProblemResponse = require('express-http-problem-details')

correct

const HttpProblemResponse = require('express-http-problem-details').HttpProblemResponse

No default export; must destructure in CJS.

Quickstart

Express app using HttpProblemResponse middleware to map NotFoundError to RFC 7807 Problem Document.

import express from 'express';
import { HttpProblemResponse } from 'express-http-problem-details';
import { ProblemDocument } from 'http-problem-details';
import { DefaultMappingStrategy, MapperRegistry, ErrorMapper } from 'http-problem-details-mapper';

class NotFoundError extends Error {
  constructor({ type, id }) {
    super();
    this.message = `${type} with id ${id} could not be found.`;
  }
}

class NotFoundErrorMapper extends ErrorMapper {
  constructor() { super(NotFoundError); }
  mapError(error) {
    return new ProblemDocument({ status: 404, title: error.message, type: 'http://tempuri.org/NotFoundError' });
  }
}

const strategy = new DefaultMappingStrategy(
  new MapperRegistry().registerMapper(new NotFoundErrorMapper())
);

const server = express();
server.get('/', (req, res) => { throw new NotFoundError({ type: 'customer', id: '123' }); });
server.use((err, req, res, next) => { console.error(err.stack); next(err); });
server.use(HttpProblemResponse({ strategy }));
server.listen(3000);