@yeliex/problem-details

Framework-agnostic RFC 9457 Problem Details core.

Install

pnpm add @yeliex/problem-details

API

ProblemDetail

class ProblemDetail extends Error {
  constructor(status: number, options?: ProblemDetailInit)
  constructor(status: number, detail?: string, options?: ProblemDetailInit)
}

• status: HTTP status code.
• detail: optional human-readable detail.
• options supports standard fields and custom extensions:
  • type (default: about:blank)
  • title (default: HTTP status phrase)
  • instance
  • cause
  • any custom extension members (for example traceId, code, foo)
  • supports Symbol extension members for internal-only metadata
  • extension members with undefined value are ignored in instance assignment

Usage

import { ProblemDetail } from '@yeliex/problem-details';

const problem = new ProblemDetail(404, 'User not found', {
  type: 'https://example.com/problems/user-not-found',
  instance: '/users/42',
  traceId: 'req-123',
});

console.log(problem.toJSON());

Debug Output

ProblemDetail provides custom toString() and Node.js inspect output, which is useful in logs and debugging.

HTTP Error Constructors

http-error is provided as a subpath export (not from root entry):

import { createError, createHttpError, httpErrors } from '@yeliex/problem-details/http-error';

throw new httpErrors.NotFound('User not found');
throw new httpErrors[404]('User not found');
throw new httpErrors['404']('User not found');

const ValidationError = createError(400, 'ValidationError', {
  title: 'Validation Failed',
  type: 'https://example.com/problems/validation-error',
  code: 'VALIDATION_ERROR',
});

const ConflictError = createHttpError(409, 'Conflict detected', {
  title: 'Business Conflict',
  code: 'BUSINESS_CONFLICT',
});

createError overloads:

createError(status: number, name: string)
createError(status: number, name: string, defaultOptions?: ProblemDetailInit)
createError(status: number, name: string, defaultDetail?: string, defaultOptions?: ProblemDetailInit)

createHttpError uses the same default argument model without the explicit name parameter.

Default options are applied first, and instance-time arguments override them:

const ValidationError = createError(400, 'ValidationError', {
  title: 'Validation Failed',
  type: 'https://example.com/problems/validation-error',
  code: 'VALIDATION_ERROR',
});

new ValidationError({ field: 'email' });
new ValidationError('Email is invalid', { field: 'email' });
new ValidationError(undefined, { title: 'Invalid Request' });

JSON Output

problem.toJSON() returns RFC 9457 base fields plus extensions:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid input",
  "instance": "/users",
  "traceId": "req-123"
}

License

MIT