From 1a31149eb5eb3a114fe97b03f192e560953a84a2 Mon Sep 17 00:00:00 2001 From: generaltony007 <191973953+hakarrr@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:02:40 +0530 Subject: [PATCH 1/5] feat: add createRFC9457Error factory for RFC 9457 problem details Adds a new createRFC9457Error factory alongside createError. The created error instances expose toProblemDetails(), which serializes the error to an RFC 9457 problem details object (RFC 9457 obsoletes RFC 7807). The title defaults to the HTTP status reason phrase, as recommended by the RFC for about:blank problem types. Co-authored-by: generaltony007 <144252170+GeneralTony007@users.noreply.github.com> Signed-off-by: generaltony007 <191973953+hakarrr@users.noreply.github.com> --- index.js | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/index.js b/index.js index 4d8da8e..649f111 100644 --- a/index.js +++ b/index.js @@ -1,5 +1,6 @@ 'use strict' +const { STATUS_CODES } = require('node:http') const { format } = require('node:util') function toString () { @@ -90,6 +91,38 @@ function createError (code, message, statusCode = 500, Base = Error, captureStac return FastifyError } +function createRFC9457Error ( + code, + message, + statusCode = 500, + opts = {}, + Base = Error, + captureStackTrace = createError.captureStackTrace +) { + const RFC9457Error = createError(code, message, statusCode, Base, captureStackTrace) + + const type = opts.type || 'about:blank' + const title = opts.title + + RFC9457Error.prototype.toProblemDetails = function (instance = '', details = {}) { + const status = this.statusCode ?? statusCode + + return { + type, + // RFC 9457 recommends the HTTP status reason phrase as the title + // when no dedicated title is available + title: title || STATUS_CODES[status] || 'Unknown Error', + status, + detail: this.message, + instance, + code: this.code, + details + } + } + + return RFC9457Error +} + createError.captureStackTrace = true const FastifyErrorConstructor = createError(FastifyGenericErrorSymbol, 'Fastify Error', 500, Error) @@ -98,3 +131,4 @@ module.exports = createError module.exports.FastifyError = FastifyErrorConstructor module.exports.default = createError module.exports.createError = createError +module.exports.createRFC9457Error = createRFC9457Error From 0f3a9385ef2d45f68b62c223f415e3df1dd8d29e Mon Sep 17 00:00:00 2001 From: generaltony007 <191973953+hakarrr@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:03:13 +0530 Subject: [PATCH 2/5] docs: document createRFC9457Error Co-authored-by: generaltony007 <144252170+GeneralTony007@users.noreply.github.com> Signed-off-by: generaltony007 <191973953+hakarrr@users.noreply.github.com> --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 94814fe..357a35e 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,45 @@ console.log(new CustomError('world', {cause: new Error('cause')})) // error.cause => Error('cause') ``` +#### RFC 9457 problem details + +The module also exports `createRFC9457Error`, which creates error objects that can be serialized as [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem details objects (RFC 9457 obsoletes RFC 7807): + +```js +createRFC9457Error(code, message [, statusCode [, opts [, Base [, captureStackTrace]]]]) +``` + +It accepts the same parameters as `createError`, plus an optional `opts` object: + +- `type` (`string`, optional) - A URI reference that identifies the problem type. Defaults to `'about:blank'`. +- `title` (`string`, optional) - A short, human-readable summary of the problem type. Defaults to the HTTP status reason phrase for the error's status code (e.g. `'Not Found'` for `404`). + +The created error instances expose a `toProblemDetails(instance [, details])` method that returns the problem details object: + +```js +const { createRFC9457Error } = require('@fastify/error') + +const QuotaExceeded = createRFC9457Error( + 'QUOTA_EXCEEDED', + 'Quota exceeded by %d requests', + 429, + { type: 'https://example.net/probs/quota', title: 'Quota Exceeded' } +) + +console.log(new QuotaExceeded(7).toProblemDetails('/api/limits', { retryAfter: 60 })) +// { +// type: 'https://example.net/probs/quota', +// title: 'Quota Exceeded', +// status: 429, +// detail: 'Quota exceeded by 7 requests', +// instance: '/api/limits', +// code: 'QUOTA_EXCEEDED', +// details: { retryAfter: 60 } +// } +``` + +`instance` is a URI reference that identifies the specific occurrence of the problem (e.g. the request path), and `details` carries additional extension members. `code` and `details` are [extension members](https://www.rfc-editor.org/rfc/rfc9457.html#name-extension-members) and are not defined by RFC 9457 itself. + ### TypeScript It is possible to limit your error constructor with a generic type using TypeScript: From bd5b088f88cc3018e34896f6b96d0f2114799418 Mon Sep 17 00:00:00 2001 From: generaltony007 <191973953+hakarrr@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:03:38 +0530 Subject: [PATCH 3/5] types: add createRFC9457Error types Co-authored-by: generaltony007 <144252170+GeneralTony007@users.noreply.github.com> Signed-off-by: generaltony007 <191973953+hakarrr@users.noreply.github.com> --- types/index.d.ts | 55 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/types/index.d.ts b/types/index.d.ts index 2e59d9f..27af6a4 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -40,8 +40,63 @@ declare namespace createError { readonly prototype: FastifyError & E } + export interface RFC9457ErrorOptions { + type?: string + title?: string + } + + export interface RFC9457ProblemDetails { + type: string + title: string + status: number + detail: string + instance: string + code: string + details: Record + } + + export interface RFC9457Error extends FastifyError { + toProblemDetails(instance?: string, details?: Record): RFC9457ProblemDetails + } + + export interface RFC9457ErrorConstructor< + E extends { code: string, statusCode?: number } = { code: string, statusCode?: number }, + T extends unknown[] = [any?, any?, any?] + > { + new(...arg: T): RFC9457Error & E + (...arg: T): RFC9457Error & E + readonly prototype: RFC9457Error & E + } + export const FastifyError: FastifyErrorConstructor + export function createRFC9457Error ( + code: C, + message: string, + statusCode: SC, + opts?: RFC9457ErrorOptions, + Base?: ErrorConstructor, + captureStackTrace?: boolean + ): RFC9457ErrorConstructor<{ code: C, statusCode: SC }, Arg> + + export function createRFC9457Error ( + code: C, + message: string, + statusCode?: number, + opts?: RFC9457ErrorOptions, + Base?: ErrorConstructor, + captureStackTrace?: boolean + ): RFC9457ErrorConstructor<{ code: C }, Arg> + + export function createRFC9457Error ( + code: string, + message: string, + statusCode?: number, + opts?: RFC9457ErrorOptions, + Base?: ErrorConstructor, + captureStackTrace?: boolean + ): RFC9457ErrorConstructor<{ code: string }, Arg> + export const createError: CreateError export { createError as default } } From 1b3f7420ed8504bc406bb9838851901cc12cc4c0 Mon Sep 17 00:00:00 2001 From: generaltony007 <191973953+hakarrr@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:04:04 +0530 Subject: [PATCH 4/5] types: add tstyche tests for createRFC9457Error Co-authored-by: generaltony007 <144252170+GeneralTony007@users.noreply.github.com> Signed-off-by: generaltony007 <191973953+hakarrr@users.noreply.github.com> --- types/index.tst.ts | 48 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/types/index.tst.ts b/types/index.tst.ts index 8c15e83..fa81d9b 100644 --- a/types/index.tst.ts +++ b/types/index.tst.ts @@ -1,5 +1,5 @@ import { expect } from 'tstyche' -import createError, { FastifyError, FastifyErrorConstructor } from '..' +import createError, { FastifyError, FastifyErrorConstructor, RFC9457Error, RFC9457ErrorConstructor, RFC9457ProblemDetails, createRFC9457Error } from '..' const CustomError = createError('ERROR_CODE', 'message') expect(CustomError).type.toBe< @@ -151,3 +151,49 @@ if (error instanceof FastifyError) { expect(error.message).type.toBe() expect(error.statusCode).type.toBe() } + +const RFC9457CustomError = createRFC9457Error('ERROR_CODE', 'message') +expect(RFC9457CustomError).type.toBe< + RFC9457ErrorConstructor<{ code: 'ERROR_CODE' }> +>() +const rfc9457Err = new RFC9457CustomError() +expect(rfc9457Err).type.toBe() +expect(rfc9457Err.code).type.toBe<'ERROR_CODE'>() +expect(rfc9457Err.message).type.toBe() +expect(rfc9457Err.statusCode).type.toBe() + +const problemDetails = rfc9457Err.toProblemDetails('/path', { extra: 1 }) +expect(problemDetails).type.toBe() +expect(problemDetails.type).type.toBe() +expect(problemDetails.title).type.toBe() +expect(problemDetails.status).type.toBe() +expect(problemDetails.detail).type.toBe() +expect(problemDetails.instance).type.toBe() +expect(problemDetails.code).type.toBe() +expect(problemDetails.details).type.toBe>() + +const RFC9457TypedError = createRFC9457Error( + 'OTHER_CODE', + 'message', + 400, + { type: 'https://example.net/probs/other', title: 'Other' } +) +expect(RFC9457TypedError).type.toBe< + RFC9457ErrorConstructor<{ code: 'OTHER_CODE'; statusCode: 400 }> +>() +const rfc9457Typed = new RFC9457TypedError() +expect(rfc9457Typed).type.toBe< + RFC9457Error & { code: 'OTHER_CODE'; statusCode: 400 } +>() +expect(rfc9457Typed.statusCode).type.toBe<400>() + +const RFC9457TypedArgError = createRFC9457Error<[string]>( + 'ARG_CODE', + 'expect %s message', + 400 +) +RFC9457TypedArgError('a') +expect(RFC9457TypedArgError).type.not.toBeCallableWith('a', 'b') +expect(RFC9457TypedArgError).type.not.toBeConstructableWith('a', 'b') +expect(RFC9457TypedArgError).type.not.toBeCallableWith(1) +expect(RFC9457TypedArgError).type.not.toBeConstructableWith(1) From 53fc5cba7de0e4dadc3eec8c2eb8827b038eebca Mon Sep 17 00:00:00 2001 From: generaltony007 <191973953+hakarrr@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:04:32 +0530 Subject: [PATCH 5/5] test: cover createRFC9457Error Co-authored-by: generaltony007 <144252170+GeneralTony007@users.noreply.github.com> Signed-off-by: generaltony007 <191973953+hakarrr@users.noreply.github.com> --- test/rfc9457.test.js | 109 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 test/rfc9457.test.js diff --git a/test/rfc9457.test.js b/test/rfc9457.test.js new file mode 100644 index 0000000..3702809 --- /dev/null +++ b/test/rfc9457.test.js @@ -0,0 +1,109 @@ +'use strict' + +const test = require('node:test') +const { createRFC9457Error } = require('..') + +test('toProblemDetails() with defaults', (t) => { + t.plan(1) + + const E = createRFC9457Error('CODE', 'oops') + const e = new E() + const pd = e.toProblemDetails() + + t.assert.deepStrictEqual(pd, { + type: 'about:blank', + title: 'Internal Server Error', + status: 500, + detail: 'oops', + instance: '', + code: 'CODE', + details: {} + }) +}) + +test('title defaults to the HTTP reason phrase for the status', (t) => { + t.plan(1) + + const NotFound = createRFC9457Error('NOT_FOUND', 'user %s does not exist', 404) + const pd = new NotFound('alice').toProblemDetails('/users/alice') + + t.assert.deepStrictEqual(pd, { + type: 'about:blank', + title: 'Not Found', + status: 404, + detail: 'user alice does not exist', + instance: '/users/alice', + code: 'NOT_FOUND', + details: {} + }) +}) + +test('toProblemDetails() with custom type, title and extension details', (t) => { + t.plan(1) + + const Warning = createRFC9457Error( + 'WARN', + 'Threshold exceeded by %d', + 429, + { type: 'https://example.net/probs/warn', title: 'Warning' } + ) + const w = new Warning(7) + + const pd = w.toProblemDetails('/limit', { retryAfter: 60, exceeded: true }) + + t.assert.deepStrictEqual(pd, { + type: 'https://example.net/probs/warn', + title: 'Warning', + status: 429, + detail: 'Threshold exceeded by 7', + instance: '/limit', + code: 'WARN', + details: { retryAfter: 60, exceeded: true } + }) +}) + +test('title falls back to a generic label for unknown status codes', (t) => { + t.plan(2) + + const E = createRFC9457Error('WEIRD', 'unusual status', 599) + const pd = new E().toProblemDetails() + + t.assert.equal(pd.title, 'Unknown Error') + t.assert.equal(pd.status, 599) +}) + +test('toProblemDetails() falls back to the factory statusCode when the instance has none', (t) => { + t.plan(2) + + // createError drops a falsy statusCode from the instance + const E = createRFC9457Error('CODE', 'oops', 0) + const pd = new E().toProblemDetails() + + t.assert.equal(pd.status, 0) + t.assert.equal(pd.title, 'Unknown Error') +}) + +test('toProblemDetails() honors an overridden instance statusCode', (t) => { + t.plan(2) + + const E = createRFC9457Error('CODE', 'oops', 500) + const e = new E() + e.statusCode = 502 + const pd = e.toProblemDetails() + + t.assert.equal(pd.status, 502) + t.assert.equal(pd.title, 'Bad Gateway') +}) + +test('created errors behave like regular fastify errors', (t) => { + t.plan(5) + + const E = createRFC9457Error('CODE', 'hey %s', 400) + const err = new E('alice') + + t.assert.ok(err instanceof Error) + t.assert.equal(err.name, 'FastifyError') + t.assert.equal(err.code, 'CODE') + t.assert.equal(err.message, 'hey alice') + t.assert.equal(err.toString(), 'FastifyError [CODE]: hey alice') +})