@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.
- package/.github/workflows/release.yml +1 -1
- package/README.md +39 -0
- package/index.js +34 -0
- package/package.json +1 -1
- package/test/rfc9457.test.js +109 -0
- package/types/index.d.ts +55 -0
- package/types/index.tst.ts +47 -1
|
@@ -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@
|
|
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
|
@@ -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
|
}
|
package/types/index.tst.ts
CHANGED
|
@@ -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)
|