@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

``bash
pnpm add @common-sense/error-iq
`

Core usage

`ts
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

$3

`ts
// 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"');
`

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

`ts
// 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

`ts
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

`ts
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

`ts
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

`ts
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