@fastify/error 4.1.0 → 4.2.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.
@@ -14,6 +14,9 @@ on:
14
14
  - 'docs/**'
15
15
  - '*.md'
16
16
 
17
+ permissions:
18
+ contents: read
19
+
17
20
  jobs:
18
21
  test:
19
22
  permissions:
package/README.md CHANGED
@@ -15,7 +15,7 @@ npm i @fastify/error
15
15
 
16
16
  The module exports a function that you can use for consistent error objects, it takes 4 parameters:
17
17
 
18
- ```
18
+ ```js
19
19
  createError(code, message [, statusCode [, Base [, captureStackTrace]]])
20
20
  ```
21
21
 
@@ -58,6 +58,83 @@ new CustomError('world')
58
58
  new CustomError(1)
59
59
  ```
60
60
 
61
+ ### instanceof
62
+
63
+ All errors created with `createError` will be instances of the base error constructor you provided, or `Error` if none was provided.
64
+
65
+ ```js
66
+ const createError = require('@fastify/error')
67
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
68
+ const customError = new CustomError('world')
69
+
70
+ console.log(customError instanceof CustomError) // true
71
+ console.log(customError instanceof TypeError) // true
72
+ console.log(customError instanceof Error) // true
73
+ ```
74
+
75
+ All instantiated errors are instances of the `FastifyError` class, which can be required directly from the module.
76
+
77
+ ```js
78
+ const { createError, FastifyError } = require('@fastify/error')
79
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
80
+ const customError = new CustomError('world')
81
+
82
+ console.log(customError instanceof FastifyError) // true
83
+ ```
84
+
85
+ A `FastifyError` created by `createError` can extend another `FastifyError` while maintaining correct `instanceof` behavior.
86
+
87
+ ```js
88
+ const { createError, FastifyError } = require('@fastify/error')
89
+
90
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
91
+ const ChildCustomError = createError('CHILD_ERROR_CODE', 'Hello %s', 500, CustomError)
92
+
93
+ const customError = new ChildCustomError('world')
94
+
95
+ console.log(customError instanceof ChildCustomError) // true
96
+ console.log(customError instanceof CustomError) // true
97
+ console.log(customError instanceof FastifyError) // true
98
+ console.log(customError instanceof TypeError) // true
99
+ console.log(customError instanceof Error) // true
100
+ ```
101
+
102
+ If `fastify-error` is installed multiple times directly or as a transitive dependency, `instanceof` checks for errors created by `createError` will still work correctly across these installations, as long as their error codes (e.g., `FST_ERR_CUSTOM_ERROR`) are identical.
103
+
104
+ ```js
105
+ const { createError, FastifyError } = require('@fastify/error')
106
+
107
+ // CustomError from `@fastify/some-plugin` is created with `createError` and
108
+ // has its own `@fastify/error` installation as dependency. CustomError has
109
+ // FST_ERR_CUSTOM_ERROR as code.
110
+ const { CustomError: CustomErrorFromPlugin } = require('@fastify/some-plugin')
111
+
112
+ const CustomError = createError('FST_ERR_CUSTOM_ERROR', 'Hello %s', 500)
113
+
114
+ const customError = new CustomError('world')
115
+ const customErrorFromPlugin = new CustomErrorFromPlugin('world')
116
+
117
+ console.log(customError instanceof CustomError) // true
118
+ console.log(customError instanceof CustomErrorFromPlugin) // true
119
+ console.log(customErrorFromPlugin instanceof CustomError) // true
120
+ console.log(customErrorFromPlugin instanceof CustomErrorFromPlugin) // true
121
+ ```
122
+
123
+ Changing the code of an instantiated Error will not change the result of the `instanceof` operator.
124
+
125
+ ```js
126
+ const { createError, FastifyError } = require('@fastify/error')
127
+
128
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
129
+ const AnotherCustomError = createError('ANOTHER_ERROR_CODE', 'Hello %s', 500, CustomError)
130
+
131
+ const customError = new CustomError('world')
132
+ customError.code = 'ANOTHER_ERROR_CODE'
133
+
134
+ console.log(customError instanceof CustomError) // true
135
+ console.log(customError instanceof AnotherCustomError) // false
136
+ ```
137
+
61
138
  ## License
62
139
 
63
140
  Licensed under [MIT](./LICENSE).
package/index.js CHANGED
@@ -6,13 +6,23 @@ function toString () {
6
6
  return `${this.name} [${this.code}]: ${this.message}`
7
7
  }
8
8
 
9
+ const FastifyGenericErrorSymbol = Symbol.for('fastify-error-generic')
10
+
9
11
  function createError (code, message, statusCode = 500, Base = Error, captureStackTrace = createError.captureStackTrace) {
12
+ const shouldCreateFastifyGenericError = code === FastifyGenericErrorSymbol
13
+
14
+ if (shouldCreateFastifyGenericError) {
15
+ code = 'FST_ERR'
16
+ }
17
+
10
18
  if (!code) throw new Error('Fastify error code must not be empty')
11
19
  if (!message) throw new Error('Fastify error message must not be empty')
12
20
 
13
21
  code = code.toUpperCase()
14
22
  !statusCode && (statusCode = undefined)
15
23
 
24
+ const FastifySpecificErrorSymbol = Symbol.for(`fastify-error ${code}`)
25
+
16
26
  function FastifyError (...args) {
17
27
  if (!new.target) {
18
28
  return new FastifyError(...args)
@@ -38,9 +48,41 @@ function createError (code, message, statusCode = 500, Base = Error, captureStac
38
48
  enumerable: false,
39
49
  writable: true,
40
50
  configurable: true
51
+ },
52
+ [FastifyGenericErrorSymbol]: {
53
+ value: true,
54
+ enumerable: false,
55
+ writable: false,
56
+ configurable: false
57
+ },
58
+ [FastifySpecificErrorSymbol]: {
59
+ value: true,
60
+ enumerable: false,
61
+ writable: false,
62
+ configurable: false
41
63
  }
42
64
  })
43
65
 
66
+ if (shouldCreateFastifyGenericError) {
67
+ Object.defineProperty(FastifyError, Symbol.hasInstance, {
68
+ value (instance) {
69
+ return instance && instance[FastifyGenericErrorSymbol]
70
+ },
71
+ configurable: false,
72
+ writable: false,
73
+ enumerable: false
74
+ })
75
+ } else {
76
+ Object.defineProperty(FastifyError, Symbol.hasInstance, {
77
+ value (instance) {
78
+ return instance && instance[FastifySpecificErrorSymbol]
79
+ },
80
+ configurable: false,
81
+ writable: false,
82
+ enumerable: false
83
+ })
84
+ }
85
+
44
86
  FastifyError.prototype[Symbol.toStringTag] = 'Error'
45
87
 
46
88
  FastifyError.prototype.toString = toString
@@ -50,6 +92,9 @@ function createError (code, message, statusCode = 500, Base = Error, captureStac
50
92
 
51
93
  createError.captureStackTrace = true
52
94
 
95
+ const FastifyErrorConstructor = createError(FastifyGenericErrorSymbol, 'Fastify Error', 500, Error)
96
+
53
97
  module.exports = createError
98
+ module.exports.FastifyError = FastifyErrorConstructor
54
99
  module.exports.default = createError
55
100
  module.exports.createError = createError
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fastify/error",
3
- "version": "4.1.0",
3
+ "version": "4.2.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",
@@ -62,7 +62,7 @@
62
62
  "c8": "^10.1.2",
63
63
  "eslint": "^9.17.0",
64
64
  "neostandard": "^0.12.0",
65
- "tsd": "^0.31.0"
65
+ "tsd": "^0.32.0"
66
66
  },
67
67
  "tsd": {
68
68
  "compilerOptions": {
@@ -1,7 +1,7 @@
1
1
  'use strict'
2
2
 
3
3
  const test = require('node:test')
4
- const createError = require('..')
4
+ const { createError, FastifyError } = require('..')
5
5
 
6
6
  test('Create error with zero parameter', (t) => {
7
7
  t.plan(6)
@@ -221,3 +221,12 @@ test('Create an error with last argument null', (t) => {
221
221
  t.assert.ok(err instanceof Error)
222
222
  t.assert.ifError(err.cause)
223
223
  })
224
+
225
+ test('check if FastifyError is instantiable', (t) => {
226
+ t.plan(2)
227
+
228
+ const err = new FastifyError()
229
+
230
+ t.assert.ok(err instanceof FastifyError)
231
+ t.assert.ok(err instanceof Error)
232
+ })
@@ -0,0 +1,263 @@
1
+ 'use strict'
2
+
3
+ const cp = require('node:child_process')
4
+ const fs = require('node:fs')
5
+ const path = require('node:path')
6
+ const os = require('node:os')
7
+ const test = require('node:test')
8
+ const { createError, FastifyError } = require('..')
9
+
10
+ test('Readme: All errors created with `createError` will be instances of the base error constructor you provided, or `Error` if none was provided.', (t) => {
11
+ t.plan(3)
12
+
13
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
14
+ const customError = new CustomError('world')
15
+
16
+ t.assert.ok(customError instanceof CustomError)
17
+ t.assert.ok(customError instanceof TypeError)
18
+ t.assert.ok(customError instanceof Error)
19
+ })
20
+
21
+ test('Readme: All instantiated errors will be instances of the `FastifyError` class. The `FastifyError` class can be required from the module directly.', (t) => {
22
+ t.plan(1)
23
+
24
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
25
+ const customError = new CustomError('world')
26
+
27
+ t.assert.ok(customError instanceof FastifyError)
28
+ })
29
+
30
+ test('Readme: It is possible to create a `FastifyError` that extends another `FastifyError`, created by `createError`, while instanceof working correctly.', (t) => {
31
+ t.plan(5)
32
+
33
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
34
+ const ChildCustomError = createError('CHILD_ERROR_CODE', 'Hello %s', 500, CustomError)
35
+
36
+ const customError = new ChildCustomError('world')
37
+
38
+ t.assert.ok(customError instanceof ChildCustomError)
39
+ t.assert.ok(customError instanceof CustomError)
40
+ t.assert.ok(customError instanceof FastifyError)
41
+ t.assert.ok(customError instanceof TypeError)
42
+ t.assert.ok(customError instanceof Error)
43
+ })
44
+
45
+ test('Readme: Changing the code of an instantiated Error will not change the result of the `instanceof` operator.', (t) => {
46
+ t.plan(3)
47
+
48
+ const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
49
+ const AnotherCustomError = createError('ANOTHER_ERROR_CODE', 'Hello %s', 500, CustomError)
50
+
51
+ const customError = new CustomError('world')
52
+ customError.code = 'ANOTHER_ERROR_CODE'
53
+
54
+ t.assert.ok(customError instanceof CustomError)
55
+ t.assert.ok(customError instanceof AnotherCustomError === false)
56
+ t.assert.ok(customError instanceof FastifyError)
57
+ })
58
+
59
+ test('check if createError creates an Error which is instanceof Error', (t) => {
60
+ t.plan(3)
61
+
62
+ const CustomFastifyError = createError('CODE', 'Not available')
63
+ const err = CustomFastifyError()
64
+
65
+ t.assert.ok(err instanceof Error)
66
+ t.assert.ok(err instanceof SyntaxError === false)
67
+ t.assert.ok(err instanceof TypeError === false)
68
+ })
69
+
70
+ test('check if createError creates an Error which is instanceof FastifyError', (t) => {
71
+ t.plan(4)
72
+
73
+ const CustomFastifyError = createError('CODE', 'Not available')
74
+ const err = CustomFastifyError()
75
+
76
+ t.assert.ok(err instanceof Error)
77
+ t.assert.ok(err instanceof FastifyError)
78
+ t.assert.ok(err instanceof SyntaxError === false)
79
+ t.assert.ok(err instanceof TypeError === false)
80
+ })
81
+
82
+ test('check if createError creates an Error with the right BaseConstructor', (t) => {
83
+ t.plan(2)
84
+
85
+ const CustomFastifyError = createError('CODE', 'Not available', 500, TypeError)
86
+ const err = CustomFastifyError()
87
+
88
+ t.assert.ok(err instanceof Error)
89
+ t.assert.ok(err instanceof TypeError)
90
+ })
91
+
92
+ test('check if createError creates an Error with the right BaseConstructor, which is a FastifyError', (t) => {
93
+ t.plan(6)
94
+
95
+ const BaseFastifyError = createError('CODE', 'Not available', 500, TypeError)
96
+ const CustomFastifyError = createError('CODE', 'Not available', 500, BaseFastifyError)
97
+ const err = CustomFastifyError()
98
+
99
+ t.assert.ok(err instanceof Error)
100
+ t.assert.ok(err instanceof TypeError)
101
+ t.assert.ok(err instanceof FastifyError)
102
+ t.assert.ok(err instanceof BaseFastifyError)
103
+ t.assert.ok(err instanceof CustomFastifyError)
104
+ t.assert.ok(err instanceof SyntaxError === false)
105
+ })
106
+
107
+ // for more information see https://github.com/fastify/fastify-error/pull/86#issuecomment-1301466407
108
+ test('ensure that instanceof works accross different installations of the fastify-error module', async (t) => {
109
+ const assertsPlanned = 5
110
+ t.plan(assertsPlanned)
111
+
112
+ // We need to create a test environment where fastify-error is installed in two different locations
113
+ // and then we will check if the error created in one location is instanceof the error created in the other location
114
+ // This is done by creating a test directory with the following structure:
115
+
116
+ // /
117
+ // ├── index.js
118
+ // └── node_modules/
119
+ // ├── fastify-error/
120
+ // │ └── index.js
121
+ // └── dep/
122
+ // ├── index.js
123
+ // └── node_modules/
124
+ // └── fastify-error/
125
+ // └── index.js
126
+
127
+ const testDirectoryPrefix = 'fastify-error-instanceof-test-'
128
+
129
+ const testCwd = path.resolve(os.tmpdir(), `${testDirectoryPrefix}${Math.random().toString(36).substring(2, 15)}`)
130
+ fs.mkdirSync(testCwd, { recursive: true })
131
+
132
+ // Create the index.js. It will be executed as a forked process, so we need to
133
+ // use process.send to send messages back to the parent process.
134
+ fs.writeFileSync(path.resolve(testCwd, 'index.js'), `
135
+ 'use strict'
136
+
137
+ const path = require('node:path')
138
+ const { createError, FastifyError } = require('fastify-error')
139
+ const { foo } = require('dep')
140
+
141
+ const actualPathOfFastifyError = require.resolve('fastify-error')
142
+ const expectedPathOfFastifyError = path.resolve('node_modules', 'fastify-error', 'index.js')
143
+
144
+ // Ensure that fastify-error is required from the node_modules directory of the test-project
145
+ if (actualPathOfFastifyError !== expectedPathOfFastifyError) {
146
+ console.error('actualPathOfFastifyError', actualPathOfFastifyError)
147
+ console.error('expectedPathOfFastifyError', expectedPathOfFastifyError)
148
+ throw new Error('fastify-error should be required from the node_modules directory of the test-project')
149
+ }
150
+
151
+ const Boom = createError('Boom', 'Boom', 500)
152
+ const ChildBoom = createError('ChildBoom', 'Boom', 500, Boom)
153
+ const NotChildBoom = createError('NotChildBoom', 'NotChildBoom', 500, Boom)
154
+
155
+ try {
156
+ foo()
157
+ } catch (err) {
158
+ process.send(err instanceof Error)
159
+ process.send(err instanceof FastifyError)
160
+ process.send(err instanceof NotChildBoom)
161
+ process.send(err instanceof Boom)
162
+ process.send(err instanceof ChildBoom)
163
+ }
164
+ `)
165
+
166
+ // Create /node_modules/fastify-error directory
167
+ // Copy the index.js file to the fastify-error directory
168
+ fs.mkdirSync(path.resolve(testCwd, 'node_modules', 'fastify-error'), { recursive: true })
169
+ fs.copyFileSync(path.resolve(process.cwd(), 'index.js'), path.resolve(testCwd, 'node_modules', 'fastify-error', 'index.js'))
170
+
171
+ // Create /node_modules/dep/node_modules/fastify-error directory
172
+ // Copy the index.js to the fastify-error directory
173
+ fs.mkdirSync(path.resolve(testCwd, 'node_modules', 'dep', 'node_modules', 'fastify-error'), { recursive: true })
174
+ fs.copyFileSync(path.resolve(process.cwd(), 'index.js'), path.resolve(testCwd, 'node_modules', 'dep', 'node_modules', 'fastify-error', 'index.js'))
175
+
176
+ // Create /node_modules/dep/index.js. It will export a function foo which will
177
+ // throw an error when called. The error will be an instance of ChildBoom, created
178
+ // by the fastify-error module in the node_modules directory of dep.
179
+ fs.writeFileSync(path.resolve(testCwd, 'node_modules', 'dep', 'index.js'), `
180
+ 'use strict'
181
+
182
+ const path = require('node:path')
183
+ const { createError } = require('fastify-error')
184
+
185
+ const actualPathOfFastifyError = require.resolve('fastify-error')
186
+ const expectedPathOfFastifyError = path.resolve('node_modules', 'dep', 'node_modules', 'fastify-error', 'index.js')
187
+
188
+ // Ensure that fastify-error is required from the node_modules directory of the test-project
189
+ if (actualPathOfFastifyError !== expectedPathOfFastifyError) {
190
+ console.error('actualPathOfFastifyError', actualPathOfFastifyError)
191
+ console.error('expectedPathOfFastifyError', expectedPathOfFastifyError)
192
+ throw new Error('fastify-error should be required from the node_modules directory of dep')
193
+ }
194
+
195
+ const Boom = createError('Boom', 'Boom', 500)
196
+ const ChildBoom = createError('ChildBoom', 'Boom', 500, Boom)
197
+
198
+ module.exports.foo = function foo () {
199
+ throw new ChildBoom('foo go Boom')
200
+ }
201
+ `)
202
+
203
+ const finishedPromise = {
204
+ promise: undefined,
205
+ reject: undefined,
206
+ resolve: undefined,
207
+ }
208
+
209
+ finishedPromise.promise = new Promise((resolve, reject) => {
210
+ finishedPromise.resolve = resolve
211
+ finishedPromise.reject = reject
212
+ })
213
+
214
+ const child = cp.fork(path.resolve(testCwd, 'index.js'), {
215
+ cwd: testCwd,
216
+ stdio: 'inherit',
217
+ env: {
218
+ ...process.env,
219
+ NODE_OPTIONS: '--no-warnings'
220
+ },
221
+ })
222
+
223
+ let messageCount = 0
224
+ child.on('message', message => {
225
+ try {
226
+ switch (messageCount) {
227
+ case 0:
228
+ t.assert.strictEqual(message, true, 'instanceof Error')
229
+ break
230
+ case 1:
231
+ t.assert.strictEqual(message, true, 'instanceof FastifyError')
232
+ break
233
+ case 2:
234
+ t.assert.strictEqual(message, false, 'instanceof NotChildBoom')
235
+ break
236
+ case 3:
237
+ t.assert.strictEqual(message, true, 'instanceof Boom')
238
+ break
239
+ case 4:
240
+ t.assert.strictEqual(message, true, 'instanceof ChildBoom')
241
+ break
242
+ }
243
+ if (++messageCount === assertsPlanned) {
244
+ finishedPromise.resolve()
245
+ }
246
+ } catch (err) {
247
+ finishedPromise.reject(err)
248
+ }
249
+ })
250
+
251
+ child.on('error', err => {
252
+ finishedPromise.reject(err)
253
+ })
254
+
255
+ await finishedPromise.promise
256
+
257
+ // Cleanup
258
+ // As we are creating the test-setup on the fly in the /tmp directory, we can remove it
259
+ // safely when we are done. It is not relevant for the test if the deletion fails.
260
+ try {
261
+ fs.rmSync(testCwd, { recursive: true, force: true })
262
+ } catch {}
263
+ })
package/types/index.d.ts CHANGED
@@ -40,6 +40,8 @@ declare namespace createError {
40
40
  readonly prototype: FastifyError & E
41
41
  }
42
42
 
43
+ export const FastifyError: FastifyErrorConstructor
44
+
43
45
  export const createError: CreateError
44
46
  export { createError as default }
45
47
  }
@@ -77,3 +77,16 @@ expectError(new CustomTypedArgError6('a', 'b', 'c', 'd', 'e'))
77
77
  const CustomErrorWithErrorConstructor = createError('ERROR_CODE', 'message', 500, TypeError)
78
78
  expectType<FastifyErrorConstructor<{ code: 'ERROR_CODE', statusCode: 500 }>>(CustomErrorWithErrorConstructor)
79
79
  CustomErrorWithErrorConstructor({ cause: new Error('Error') })
80
+ const customErrorWithErrorConstructor = CustomErrorWithErrorConstructor()
81
+ if (customErrorWithErrorConstructor instanceof FastifyError) {
82
+ expectType<'ERROR_CODE'>(customErrorWithErrorConstructor.code)
83
+ expectType<string>(customErrorWithErrorConstructor.message)
84
+ expectType<500>(customErrorWithErrorConstructor.statusCode)
85
+ }
86
+
87
+ const error = new FastifyError('ERROR_CODE', 'message', 500)
88
+ if (error instanceof FastifyError) {
89
+ expectType<string>(error.code)
90
+ expectType<string>(error.message)
91
+ expectType<number | undefined>(error.statusCode)
92
+ }