@common-sense/error-iq

TypeScript-first RFC 9457 Problem Details built around explicit HttpError classes, with plug-and-play Express, Fastify, Koa, and Nest integrations. Defaults are standard-compliant and ready out-of-the-box.

Install

pnpm add @common-sense/error-iq

Core usage

import { BadRequest, UnprocessableContent, ServiceUnavailable, contentTypeProblemJson } from '@common-sense/error-iq';

throw new BadRequest('Invalid input');
throw new UnprocessableContent('Bad data');
throw new ServiceUnavailable('Try later');

• contentTypeProblemJson = application/problem+json

More examples

// 401 Unauthorized with WWW-Authenticate
import { Unauthorized } from '@common-sense/error-iq';
throw new Unauthorized('Invalid token', /* instance */ null, /* extensions */ null, /* WWW-Authenticate */ 'Bearer realm="api", error="invalid_token"');

// 409 Conflict with Retry-After (seconds)
import { Conflict } from '@common-sense/error-iq';
throw new Conflict('Resource conflict', /* instance */ null, /* extensions */ null, /* retryAfter */ 60);

// 500 Internal Server Error with detail, instance, and extensions
import { InternalServerError } from '@common-sense/error-iq';
throw new InternalServerError(
  'Unexpected failure while processing order 123',
  '/orders/123',
  { traceId: '7f5c1a2b', component: 'payments', severity: 'critical' },
);

Express

import express from 'express';
import { express as erriq, UnprocessableContent } from '@common-sense/error-iq';

const app = express();

app.get('/demo', (_req, _res) => {
  throw new UnprocessableContent('Bad data');
});

// 404 then error
app.use(erriq.notFoundHandler());
app.use(erriq.errorHandler());

app.listen(3000);

Fastify

import Fastify from 'fastify';
import { registerFastifyHandler } from '@common-sense/error-iq/fastify';
import { Conflict } from '@common-sense/error-iq';

const app = Fastify();
registerFastifyHandler(app);

app.get('/demo', async () => {
  throw new Conflict('Conflict');
});

app.listen({ port: 3000 });

Koa

import Koa from 'koa';
import { errorMiddleware } from '@common-sense/error-iq/koa';
import { NotFound } from '@common-sense/error-iq';

const app = new Koa();
app.use(errorMiddleware());

app.use(() => {
  throw new NotFound('Nope');
});

app.listen(3000);

Nest

import { NestFactory } from '@nestjs/core';
import { ProblemFilter } from '@common-sense/error-iq/nest';
import { Forbidden } from '@common-sense/error-iq';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new ProblemFilter());
  await app.listen(3000);
}

// In controllers/services
throw new Forbidden('Not allowed');

The middlewares automatically serialize thrown errors as RFC 9457 Problem Details with the correct Content-Type and relevant headers (e.g., WWW-Authenticate, Retry-After, Allow) when provided by the error class.

RFC 9457 fields (Problem Details)

• type: URI identifying the problem type (use about:blank if none)
• title: Short, human-readable summary of the problem type
• status: HTTP status code for this occurrence
• detail: Human-readable explanation specific to this occurrence
• instance: URI reference identifying the specific occurrence
• extensions: Additional application-specific members are allowed

Why RFC 9457 and why this library?

• Interoperability: Standard, predictable error responses across services and clients
• Better DX: Strongly-typed error classes per status code; no ad-hoc shapes
• Framework parity: Drop-in middleware/filters for Express, Fastify, Koa, and Nest
• Headers propagation: Properly forwards standard headers (WWW-Authenticate, Retry-After, Allow)
• Sensible defaults: application/problem+json out of the box

API (surface)

• Client error classes: BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, NotAcceptable, ProxyAuthenticationRequired, RequestTimeout, Conflict, Gone, LengthRequired, PreconditionFailed, PayloadTooLarge, URITooLong, UnsupportedMediaType, RangeNotSatisfiable, ExpectationFailed, IAmATeapot, UnprocessableContent, TooEarly, UpgradeRequired, PreconditionRequired, TooManyRequests, RequestHeaderFieldsTooLarge, UnavailableForLegalReasons
• Server error classes: InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, GatewayTimeout, HTTPVersionNotSupported, InsufficientStorage, LoopDetected, NotExtended, NetworkAuthenticationRequired
• contentTypeProblemJson – application/problem+json
• Framework adapters: @common-sense/error-iq/express, @common-sense/error-iq/fastify, @common-sense/error-iq/koa, @common-sense/error-iq/nest

License

MIT