@fastify/error 4.2.1 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,6 +19,6 @@ jobs:
19
19
  permissions:
20
20
  id-token: write # required for npm provenance via OIDC
21
21
  contents: write # required to push the release commit and the tag
22
- uses: fastify/workflows/.github/workflows/reusable-release.yml@b1a11bce713bc857e52b2231fec3c89071ad3135
22
+ uses: fastify/workflows/.github/workflows/reusable-release.yml@731d0cca9a6a5b9586dad6b0326d49001ab9216f
23
23
  with:
24
24
  semver: ${{ inputs.semver }}
package/README.md CHANGED
@@ -47,6 +47,45 @@ console.log(new CustomError('world', {cause: new Error('cause')}))
47
47
  // error.cause => Error('cause')
48
48
  ```
49
49
 
50
+ #### RFC 9457 problem details
51
+
52
+ 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):
53
+
54
+ ```js
55
+ createRFC9457Error(code, message [, statusCode [, opts [, Base [, captureStackTrace]]]])
56
+ ```
57
+
58
+ It accepts the same parameters as `createError`, plus an optional `opts` object:
59
+
60
+ - `type` (`string`, optional) - A URI reference that identifies the problem type. Defaults to `'about:blank'`.
61
+ - `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`).
62
+
63
+ The created error instances expose a `toProblemDetails(instance [, details])` method that returns the problem details object:
64
+
65
+ ```js
66
+ const { createRFC9457Error } = require('@fastify/error')
67
+
68
+ const QuotaExceeded = createRFC9457Error(
69
+ 'QUOTA_EXCEEDED',
70
+ 'Quota exceeded by %d requests',
71
+ 429,
72
+ { type: 'https://example.net/probs/quota', title: 'Quota Exceeded' }
73
+ )
74
+
75
+ console.log(new QuotaExceeded(7).toProblemDetails('/api/limits', { retryAfter: 60 }))
76
+ // {
77
+ // type: 'https://example.net/probs/quota',
78
+ // title: 'Quota Exceeded',
79
+ // status: 429,
80
+ // detail: 'Quota exceeded by 7 requests',
81
+ // instance: '/api/limits',
82
+ // code: 'QUOTA_EXCEEDED',
83
+ // details: { retryAfter: 60 }
84
+ // }
85
+ ```
86
+
87
+ `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.
88
+
50
89
  ### TypeScript
51
90
 
52
91
  It is possible to limit your error constructor with a generic type using TypeScript:
package/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  'use strict'
2
2
 
3
+ const { STATUS_CODES } = require('node:http')
3
4
  const { format } = require('node:util')
4
5
 
5
6
  function toString () {
@@ -90,6 +91,38 @@ function createError (code, message, statusCode = 500, Base = Error, captureStac
90
91
  return FastifyError
91
92
  }
92
93
 
94
+ function createRFC9457Error (
95
+ code,
96
+ message,
97
+ statusCode = 500,
98
+ opts = {},
99
+ Base = Error,
100
+ captureStackTrace = createError.captureStackTrace
101
+ ) {
102
+ const RFC9457Error = createError(code, message, statusCode, Base, captureStackTrace)
103
+
104
+ const type = opts.type || 'about:blank'
105
+ const title = opts.title
106
+
107
+ RFC9457Error.prototype.toProblemDetails = function (instance = '', details = {}) {
108
+ const status = this.statusCode ?? statusCode
109
+
110
+ return {
111
+ type,
112
+ // RFC 9457 recommends the HTTP status reason phrase as the title
113
+ // when no dedicated title is available
114
+ title: title || STATUS_CODES[status] || 'Unknown Error',
115
+ status,
116
+ detail: this.message,
117
+ instance,
118
+ code: this.code,
119
+ details
120
+ }
121
+ }
122
+
123
+ return RFC9457Error
124
+ }
125
+
93
126
  createError.captureStackTrace = true
94
127
 
95
128
  const FastifyErrorConstructor = createError(FastifyGenericErrorSymbol, 'Fastify Error', 500, Error)
@@ -98,3 +131,4 @@ module.exports = createError
98
131
  module.exports.FastifyError = FastifyErrorConstructor
99
132
  module.exports.default = createError
100
133
  module.exports.createError = createError
134
+ module.exports.createRFC9457Error = createRFC9457Error
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fastify/error",
3
- "version": "4.2.1",
3
+ "version": "4.3.0",
4
4
  "description": "A small utility, used by Fastify itself, for generating consistent error objects across your codebase and plugins.",
5
5
  "main": "index.js",
6
6
  "type": "commonjs",
@@ -0,0 +1,109 @@
1
+ 'use strict'
2
+
3
+ const test = require('node:test')
4
+ const { createRFC9457Error } = require('..')
5
+
6
+ test('toProblemDetails() with defaults', (t) => {
7
+ t.plan(1)
8
+
9
+ const E = createRFC9457Error('CODE', 'oops')
10
+ const e = new E()
11
+ const pd = e.toProblemDetails()
12
+
13
+ t.assert.deepStrictEqual(pd, {
14
+ type: 'about:blank',
15
+ title: 'Internal Server Error',
16
+ status: 500,
17
+ detail: 'oops',
18
+ instance: '',
19
+ code: 'CODE',
20
+ details: {}
21
+ })
22
+ })
23
+
24
+ test('title defaults to the HTTP reason phrase for the status', (t) => {
25
+ t.plan(1)
26
+
27
+ const NotFound = createRFC9457Error('NOT_FOUND', 'user %s does not exist', 404)
28
+ const pd = new NotFound('alice').toProblemDetails('/users/alice')
29
+
30
+ t.assert.deepStrictEqual(pd, {
31
+ type: 'about:blank',
32
+ title: 'Not Found',
33
+ status: 404,
34
+ detail: 'user alice does not exist',
35
+ instance: '/users/alice',
36
+ code: 'NOT_FOUND',
37
+ details: {}
38
+ })
39
+ })
40
+
41
+ test('toProblemDetails() with custom type, title and extension details', (t) => {
42
+ t.plan(1)
43
+
44
+ const Warning = createRFC9457Error(
45
+ 'WARN',
46
+ 'Threshold exceeded by %d',
47
+ 429,
48
+ { type: 'https://example.net/probs/warn', title: 'Warning' }
49
+ )
50
+ const w = new Warning(7)
51
+
52
+ const pd = w.toProblemDetails('/limit', { retryAfter: 60, exceeded: true })
53
+
54
+ t.assert.deepStrictEqual(pd, {
55
+ type: 'https://example.net/probs/warn',
56
+ title: 'Warning',
57
+ status: 429,
58
+ detail: 'Threshold exceeded by 7',
59
+ instance: '/limit',
60
+ code: 'WARN',
61
+ details: { retryAfter: 60, exceeded: true }
62
+ })
63
+ })
64
+
65
+ test('title falls back to a generic label for unknown status codes', (t) => {
66
+ t.plan(2)
67
+
68
+ const E = createRFC9457Error('WEIRD', 'unusual status', 599)
69
+ const pd = new E().toProblemDetails()
70
+
71
+ t.assert.equal(pd.title, 'Unknown Error')
72
+ t.assert.equal(pd.status, 599)
73
+ })
74
+
75
+ test('toProblemDetails() falls back to the factory statusCode when the instance has none', (t) => {
76
+ t.plan(2)
77
+
78
+ // createError drops a falsy statusCode from the instance
79
+ const E = createRFC9457Error('CODE', 'oops', 0)
80
+ const pd = new E().toProblemDetails()
81
+
82
+ t.assert.equal(pd.status, 0)
83
+ t.assert.equal(pd.title, 'Unknown Error')
84
+ })
85
+
86
+ test('toProblemDetails() honors an overridden instance statusCode', (t) => {
87
+ t.plan(2)
88
+
89
+ const E = createRFC9457Error('CODE', 'oops', 500)
90
+ const e = new E()
91
+ e.statusCode = 502
92
+ const pd = e.toProblemDetails()
93
+
94
+ t.assert.equal(pd.status, 502)
95
+ t.assert.equal(pd.title, 'Bad Gateway')
96
+ })
97
+
98
+ test('created errors behave like regular fastify errors', (t) => {
99
+ t.plan(5)
100
+
101
+ const E = createRFC9457Error('CODE', 'hey %s', 400)
102
+ const err = new E('alice')
103
+
104
+ t.assert.ok(err instanceof Error)
105
+ t.assert.equal(err.name, 'FastifyError')
106
+ t.assert.equal(err.code, 'CODE')
107
+ t.assert.equal(err.message, 'hey alice')
108
+ t.assert.equal(err.toString(), 'FastifyError [CODE]: hey alice')
109
+ })
package/types/index.d.ts CHANGED
@@ -40,8 +40,63 @@ declare namespace createError {
40
40
  readonly prototype: FastifyError & E
41
41
  }
42
42
 
43
+ export interface RFC9457ErrorOptions {
44
+ type?: string
45
+ title?: string
46
+ }
47
+
48
+ export interface RFC9457ProblemDetails {
49
+ type: string
50
+ title: string
51
+ status: number
52
+ detail: string
53
+ instance: string
54
+ code: string
55
+ details: Record<string, unknown>
56
+ }
57
+
58
+ export interface RFC9457Error extends FastifyError {
59
+ toProblemDetails(instance?: string, details?: Record<string, unknown>): RFC9457ProblemDetails
60
+ }
61
+
62
+ export interface RFC9457ErrorConstructor<
63
+ E extends { code: string, statusCode?: number } = { code: string, statusCode?: number },
64
+ T extends unknown[] = [any?, any?, any?]
65
+ > {
66
+ new(...arg: T): RFC9457Error & E
67
+ (...arg: T): RFC9457Error & E
68
+ readonly prototype: RFC9457Error & E
69
+ }
70
+
43
71
  export const FastifyError: FastifyErrorConstructor
44
72
 
73
+ export function createRFC9457Error<C extends string, SC extends number, Arg extends unknown[] = [any?, any?, any?]> (
74
+ code: C,
75
+ message: string,
76
+ statusCode: SC,
77
+ opts?: RFC9457ErrorOptions,
78
+ Base?: ErrorConstructor,
79
+ captureStackTrace?: boolean
80
+ ): RFC9457ErrorConstructor<{ code: C, statusCode: SC }, Arg>
81
+
82
+ export function createRFC9457Error<C extends string, Arg extends unknown[] = [any?, any?, any?]> (
83
+ code: C,
84
+ message: string,
85
+ statusCode?: number,
86
+ opts?: RFC9457ErrorOptions,
87
+ Base?: ErrorConstructor,
88
+ captureStackTrace?: boolean
89
+ ): RFC9457ErrorConstructor<{ code: C }, Arg>
90
+
91
+ export function createRFC9457Error<Arg extends unknown[] = [any?, any?, any?]> (
92
+ code: string,
93
+ message: string,
94
+ statusCode?: number,
95
+ opts?: RFC9457ErrorOptions,
96
+ Base?: ErrorConstructor,
97
+ captureStackTrace?: boolean
98
+ ): RFC9457ErrorConstructor<{ code: string }, Arg>
99
+
45
100
  export const createError: CreateError
46
101
  export { createError as default }
47
102
  }
@@ -1,5 +1,5 @@
1
1
  import { expect } from 'tstyche'
2
- import createError, { FastifyError, FastifyErrorConstructor } from '..'
2
+ import createError, { FastifyError, FastifyErrorConstructor, RFC9457Error, RFC9457ErrorConstructor, RFC9457ProblemDetails, createRFC9457Error } from '..'
3
3
 
4
4
  const CustomError = createError('ERROR_CODE', 'message')
5
5
  expect(CustomError).type.toBe<
@@ -151,3 +151,49 @@ if (error instanceof FastifyError) {
151
151
  expect(error.message).type.toBe<string>()
152
152
  expect(error.statusCode).type.toBe<number | undefined>()
153
153
  }
154
+
155
+ const RFC9457CustomError = createRFC9457Error('ERROR_CODE', 'message')
156
+ expect(RFC9457CustomError).type.toBe<
157
+ RFC9457ErrorConstructor<{ code: 'ERROR_CODE' }>
158
+ >()
159
+ const rfc9457Err = new RFC9457CustomError()
160
+ expect(rfc9457Err).type.toBe<RFC9457Error & { code: 'ERROR_CODE' }>()
161
+ expect(rfc9457Err.code).type.toBe<'ERROR_CODE'>()
162
+ expect(rfc9457Err.message).type.toBe<string>()
163
+ expect(rfc9457Err.statusCode).type.toBe<number | undefined>()
164
+
165
+ const problemDetails = rfc9457Err.toProblemDetails('/path', { extra: 1 })
166
+ expect(problemDetails).type.toBe<RFC9457ProblemDetails>()
167
+ expect(problemDetails.type).type.toBe<string>()
168
+ expect(problemDetails.title).type.toBe<string>()
169
+ expect(problemDetails.status).type.toBe<number>()
170
+ expect(problemDetails.detail).type.toBe<string>()
171
+ expect(problemDetails.instance).type.toBe<string>()
172
+ expect(problemDetails.code).type.toBe<string>()
173
+ expect(problemDetails.details).type.toBe<Record<string, unknown>>()
174
+
175
+ const RFC9457TypedError = createRFC9457Error(
176
+ 'OTHER_CODE',
177
+ 'message',
178
+ 400,
179
+ { type: 'https://example.net/probs/other', title: 'Other' }
180
+ )
181
+ expect(RFC9457TypedError).type.toBe<
182
+ RFC9457ErrorConstructor<{ code: 'OTHER_CODE'; statusCode: 400 }>
183
+ >()
184
+ const rfc9457Typed = new RFC9457TypedError()
185
+ expect(rfc9457Typed).type.toBe<
186
+ RFC9457Error & { code: 'OTHER_CODE'; statusCode: 400 }
187
+ >()
188
+ expect(rfc9457Typed.statusCode).type.toBe<400>()
189
+
190
+ const RFC9457TypedArgError = createRFC9457Error<[string]>(
191
+ 'ARG_CODE',
192
+ 'expect %s message',
193
+ 400
194
+ )
195
+ RFC9457TypedArgError('a')
196
+ expect(RFC9457TypedArgError).type.not.toBeCallableWith('a', 'b')
197
+ expect(RFC9457TypedArgError).type.not.toBeConstructableWith('a', 'b')
198
+ expect(RFC9457TypedArgError).type.not.toBeCallableWith(1)
199
+ expect(RFC9457TypedArgError).type.not.toBeConstructableWith(1)