1 | /**
|
2 | * An Error object used to return an HTTP response error (4xx, 5xx)
|
3 | */
|
4 | export class Boom<Data = any> extends Error {
|
5 |
|
6 | /**
|
7 | * Creates a new Boom object using the provided message
|
8 | */
|
9 | constructor(message?: string | Error, options?: Options<Data>);
|
10 |
|
11 | /**
|
12 | * Custom error data with additional information specific to the error type
|
13 | */
|
14 | data?: Data;
|
15 |
|
16 | /**
|
17 | * isBoom - if true, indicates this is a Boom object instance.
|
18 | */
|
19 | isBoom: boolean;
|
20 |
|
21 | /**
|
22 | * Convenience boolean indicating status code >= 500
|
23 | */
|
24 | isServer: boolean;
|
25 |
|
26 | /**
|
27 | * The error message
|
28 | */
|
29 | message: string;
|
30 |
|
31 | /**
|
32 | * The formatted response
|
33 | */
|
34 | output: Output;
|
35 |
|
36 | /**
|
37 | * The constructor used to create the error
|
38 | */
|
39 | typeof: Function;
|
40 |
|
41 | /**
|
42 | * Specifies if an error object is a valid boom object
|
43 | *
|
44 | * @param debug - A boolean that, when true, does not hide the original 500 error message. Defaults to false.
|
45 | */
|
46 | reformat(debug?: boolean): string;
|
47 | }
|
48 |
|
49 |
|
50 | export interface Options<Data> {
|
51 | /**
|
52 | * The HTTP status code
|
53 | *
|
54 | * @default 500
|
55 | */
|
56 | statusCode?: number;
|
57 |
|
58 | /**
|
59 | * Additional error information
|
60 | */
|
61 | data?: Data;
|
62 |
|
63 | /**
|
64 | * Constructor reference used to crop the exception call stack output
|
65 | */
|
66 | ctor?: Function;
|
67 |
|
68 | /**
|
69 | * Error message string
|
70 | *
|
71 | * @default none
|
72 | */
|
73 | message?: string;
|
74 |
|
75 | /**
|
76 | * If false, the err provided is a Boom object, and a statusCode or message are provided, the values are ignored
|
77 | *
|
78 | * @default true
|
79 | */
|
80 | override?: boolean;
|
81 | }
|
82 |
|
83 |
|
84 | export interface Decorate<Decoration> {
|
85 |
|
86 | /**
|
87 | * An option with extra properties to set on the error object
|
88 | */
|
89 | decorate?: Decoration;
|
90 | }
|
91 |
|
92 |
|
93 | export interface Payload {
|
94 | /**
|
95 | * The HTTP status code derived from error.output.statusCode
|
96 | */
|
97 | statusCode: number;
|
98 |
|
99 | /**
|
100 | * The HTTP status message derived from statusCode
|
101 | */
|
102 | error: string;
|
103 |
|
104 | /**
|
105 | * The error message derived from error.message
|
106 | */
|
107 | message: string;
|
108 |
|
109 | /**
|
110 | * Custom properties
|
111 | */
|
112 | [key: string]: unknown;
|
113 | }
|
114 |
|
115 |
|
116 | export interface Output {
|
117 | /**
|
118 | * The HTTP status code
|
119 | */
|
120 | statusCode: number;
|
121 |
|
122 | /**
|
123 | * An object containing any HTTP headers where each key is a header name and value is the header content
|
124 | */
|
125 | headers: { [header: string]: string | string[] | number | undefined };
|
126 |
|
127 | /**
|
128 | * The formatted object used as the response payload (stringified)
|
129 | */
|
130 | payload: Payload;
|
131 | }
|
132 |
|
133 |
|
134 | /**
|
135 | * Specifies if an object is a valid boom object
|
136 | *
|
137 | * @param obj - The object to assess
|
138 | * @param statusCode - Optional status code
|
139 | *
|
140 | * @returns Returns a boolean stating if the error object is a valid boom object and it has the provided statusCode (if present)
|
141 | */
|
142 | export function isBoom(obj: unknown, statusCode?: number): obj is Boom;
|
143 |
|
144 |
|
145 | /**
|
146 | * Specifies if an error object is a valid boom object
|
147 | *
|
148 | * @param err - The error object to decorate
|
149 | * @param options - Options object
|
150 | *
|
151 | * @returns A decorated boom object
|
152 | */
|
153 | export function boomify<Data, Decoration>(err: Error, options?: Options<Data> & Decorate<Decoration>): Boom<Data> & Decoration;
|
154 |
|
155 |
|
156 | // 4xx Errors
|
157 |
|
158 | /**
|
159 | * Returns a 400 Bad Request error
|
160 | *
|
161 | * @param message - Optional message
|
162 | * @param data - Optional additional error data
|
163 | *
|
164 | * @returns A 400 bad request error
|
165 | */
|
166 | export function badRequest<Data>(message?: string, data?: Data): Boom<Data>;
|
167 |
|
168 |
|
169 | /**
|
170 | * Returns a 401 Unauthorized error
|
171 | *
|
172 | * @param message - Optional message
|
173 | *
|
174 | * @returns A 401 Unauthorized error
|
175 | */
|
176 | export function unauthorized<Data>(message?: string | null): Boom<Data>;
|
177 |
|
178 |
|
179 | /**
|
180 | * Returns a 401 Unauthorized error
|
181 | *
|
182 | * @param message - Optional message
|
183 | * @param scheme - the authentication scheme name
|
184 | * @param attributes - an object of values used to construct the 'WWW-Authenticate' header
|
185 | *
|
186 | * @returns A 401 Unauthorized error
|
187 | */
|
188 | export function unauthorized<Data>(message: '' | null, scheme: string, attributes?: string | unauthorized.Attributes): Boom<Data> & unauthorized.MissingAuth;
|
189 | export function unauthorized<Data>(message: string | null, scheme: string, attributes?: string | unauthorized.Attributes): Boom<Data>;
|
190 |
|
191 |
|
192 | export namespace unauthorized {
|
193 |
|
194 | interface Attributes {
|
195 | [index: string]: number | string | null | undefined;
|
196 | }
|
197 |
|
198 | interface MissingAuth {
|
199 |
|
200 | /**
|
201 | * Indicate whether the 401 unauthorized error is due to missing credentials (vs. invalid)
|
202 | */
|
203 | isMissing: boolean;
|
204 | }
|
205 | }
|
206 |
|
207 |
|
208 | /**
|
209 | * Returns a 401 Unauthorized error
|
210 | *
|
211 | * @param message - Optional message
|
212 | * @param wwwAuthenticate - array of string values used to construct the wwwAuthenticate header
|
213 | *
|
214 | * @returns A 401 Unauthorized error
|
215 | */
|
216 | export function unauthorized<Data>(message: string | null, wwwAuthenticate: string[]): Boom<Data>;
|
217 |
|
218 |
|
219 | /**
|
220 | * Returns a 402 Payment Required error
|
221 | *
|
222 | * @param message - Optional message
|
223 | * @param data - Optional additional error data
|
224 | *
|
225 | * @returns A 402 Payment Required error
|
226 | */
|
227 | export function paymentRequired<Data>(message?: string, data?: Data): Boom<Data>;
|
228 |
|
229 |
|
230 | /**
|
231 | * Returns a 403 Forbidden error
|
232 | *
|
233 | * @param message - Optional message
|
234 | * @param data - Optional additional error data
|
235 | *
|
236 | * @returns A 403 Forbidden error
|
237 | */
|
238 | export function forbidden<Data>(message?: string, data?: Data): Boom<Data>;
|
239 |
|
240 |
|
241 | /**
|
242 | * Returns a 404 Not Found error
|
243 | *
|
244 | * @param message - Optional message
|
245 | * @param data - Optional additional error data
|
246 | *
|
247 | * @returns A 404 Not Found error
|
248 | */
|
249 | export function notFound<Data>(message?: string, data?: Data): Boom<Data>;
|
250 |
|
251 |
|
252 | /**
|
253 | * Returns a 405 Method Not Allowed error
|
254 | *
|
255 | * @param message - Optional message
|
256 | * @param data - Optional additional error data
|
257 | * @param allow - Optional string or array of strings which is used to set the 'Allow' header
|
258 | *
|
259 | * @returns A 405 Method Not Allowed error
|
260 | */
|
261 | export function methodNotAllowed<Data>(message?: string, data?: Data, allow?: string | string[]): Boom<Data>;
|
262 |
|
263 |
|
264 | /**
|
265 | * Returns a 406 Not Acceptable error
|
266 | *
|
267 | * @param message - Optional message
|
268 | * @param data - Optional additional error data
|
269 | *
|
270 | * @returns A 406 Not Acceptable error
|
271 | */
|
272 | export function notAcceptable<Data>(message?: string, data?: Data): Boom<Data>;
|
273 |
|
274 |
|
275 | /**
|
276 | * Returns a 407 Proxy Authentication error
|
277 | *
|
278 | * @param message - Optional message
|
279 | * @param data - Optional additional error data
|
280 | *
|
281 | * @returns A 407 Proxy Authentication error
|
282 | */
|
283 | export function proxyAuthRequired<Data>(message?: string, data?: Data): Boom<Data>;
|
284 |
|
285 |
|
286 | /**
|
287 | * Returns a 408 Request Time-out error
|
288 | *
|
289 | * @param message - Optional message
|
290 | * @param data - Optional additional error data
|
291 | *
|
292 | * @returns A 408 Request Time-out error
|
293 | */
|
294 | export function clientTimeout<Data>(message?: string, data?: Data): Boom<Data>;
|
295 |
|
296 |
|
297 | /**
|
298 | * Returns a 409 Conflict error
|
299 | *
|
300 | * @param message - Optional message
|
301 | * @param data - Optional additional error data
|
302 | *
|
303 | * @returns A 409 Conflict error
|
304 | */
|
305 | export function conflict<Data>(message?: string, data?: Data): Boom<Data>;
|
306 |
|
307 |
|
308 | /**
|
309 | * Returns a 410 Gone error
|
310 | *
|
311 | * @param message - Optional message
|
312 | * @param data - Optional additional error data
|
313 | *
|
314 | * @returns A 410 gone error
|
315 | */
|
316 | export function resourceGone<Data>(message?: string, data?: Data): Boom<Data>;
|
317 |
|
318 |
|
319 | /**
|
320 | * Returns a 411 Length Required error
|
321 | *
|
322 | * @param message - Optional message
|
323 | * @param data - Optional additional error data
|
324 | *
|
325 | * @returns A 411 Length Required error
|
326 | */
|
327 | export function lengthRequired<Data>(message?: string, data?: Data): Boom<Data>;
|
328 |
|
329 |
|
330 | /**
|
331 | * Returns a 412 Precondition Failed error
|
332 | *
|
333 | * @param message - Optional message
|
334 | * @param data - Optional additional error data
|
335 | *
|
336 | * @returns A 412 Precondition Failed error
|
337 | */
|
338 | export function preconditionFailed<Data>(message?: string, data?: Data): Boom<Data>;
|
339 |
|
340 |
|
341 | /**
|
342 | * Returns a 413 Request Entity Too Large error
|
343 | *
|
344 | * @param message - Optional message
|
345 | * @param data - Optional additional error data
|
346 | *
|
347 | * @returns A 413 Request Entity Too Large error
|
348 | */
|
349 | export function entityTooLarge<Data>(message?: string, data?: Data): Boom<Data>;
|
350 |
|
351 |
|
352 | /**
|
353 | * Returns a 414 Request-URI Too Large error
|
354 | *
|
355 | * @param message - Optional message
|
356 | * @param data - Optional additional error data
|
357 | *
|
358 | * @returns A 414 Request-URI Too Large error
|
359 | */
|
360 | export function uriTooLong<Data>(message?: string, data?: Data): Boom<Data>;
|
361 |
|
362 |
|
363 | /**
|
364 | * Returns a 415 Unsupported Media Type error
|
365 | *
|
366 | * @param message - Optional message
|
367 | * @param data - Optional additional error data
|
368 | *
|
369 | * @returns A 415 Unsupported Media Type error
|
370 | */
|
371 | export function unsupportedMediaType<Data>(message?: string, data?: Data): Boom<Data>;
|
372 |
|
373 |
|
374 | /**
|
375 | * Returns a 416 Request Range Not Satisfiable error
|
376 | *
|
377 | * @param message - Optional message
|
378 | * @param data - Optional additional error data
|
379 | *
|
380 | * @returns A 416 Request Range Not Satisfiable error
|
381 | */
|
382 | export function rangeNotSatisfiable<Data>(message?: string, data?: Data): Boom<Data>;
|
383 |
|
384 |
|
385 | /**
|
386 | * Returns a 417 Expectation Failed error
|
387 | *
|
388 | * @param message - Optional message
|
389 | * @param data - Optional additional error data
|
390 | *
|
391 | * @returns A 417 Expectation Failed error
|
392 | */
|
393 | export function expectationFailed<Data>(message?: string, data?: Data): Boom<Data>;
|
394 |
|
395 |
|
396 | /**
|
397 | * Returns a 418 I'm a Teapot error
|
398 | *
|
399 | * @param message - Optional message
|
400 | * @param data - Optional additional error data
|
401 | *
|
402 | * @returns A 418 I'm a Teapot error
|
403 | */
|
404 | export function teapot<Data>(message?: string, data?: Data): Boom<Data>;
|
405 |
|
406 |
|
407 | /**
|
408 | * Returns a 422 Unprocessable Entity error
|
409 | *
|
410 | * @param message - Optional message
|
411 | * @param data - Optional additional error data
|
412 | *
|
413 | * @returns A 422 Unprocessable Entity error
|
414 | */
|
415 | export function badData<Data>(message?: string, data?: Data): Boom<Data>;
|
416 |
|
417 |
|
418 | /**
|
419 | * Returns a 423 Locked error
|
420 | *
|
421 | * @param message - Optional message
|
422 | * @param data - Optional additional error data
|
423 | *
|
424 | * @returns A 423 Locked error
|
425 | */
|
426 | export function locked<Data>(message?: string, data?: Data): Boom<Data>;
|
427 |
|
428 |
|
429 | /**
|
430 | * Returns a 424 Failed Dependency error
|
431 | *
|
432 | * @param message - Optional message
|
433 | * @param data - Optional additional error data
|
434 | *
|
435 | * @returns A 424 Failed Dependency error
|
436 | */
|
437 | export function failedDependency<Data>(message?: string, data?: Data): Boom<Data>;
|
438 |
|
439 | /**
|
440 | * Returns a 425 Too Early error
|
441 | *
|
442 | * @param message - Optional message
|
443 | * @param data - Optional additional error data
|
444 | *
|
445 | * @returns A 425 Too Early error
|
446 | */
|
447 | export function tooEarly<Data>(message?: string, data?: Data): Boom<Data>;
|
448 |
|
449 |
|
450 | /**
|
451 | * Returns a 428 Precondition Required error
|
452 | *
|
453 | * @param message - Optional message
|
454 | * @param data - Optional additional error data
|
455 | *
|
456 | * @returns A 428 Precondition Required error
|
457 | */
|
458 | export function preconditionRequired<Data>(message?: string, data?: Data): Boom<Data>;
|
459 |
|
460 |
|
461 | /**
|
462 | * Returns a 429 Too Many Requests error
|
463 | *
|
464 | * @param message - Optional message
|
465 | * @param data - Optional additional error data
|
466 | *
|
467 | * @returns A 429 Too Many Requests error
|
468 | */
|
469 | export function tooManyRequests<Data>(message?: string, data?: Data): Boom<Data>;
|
470 |
|
471 |
|
472 | /**
|
473 | * Returns a 451 Unavailable For Legal Reasons error
|
474 | *
|
475 | * @param message - Optional message
|
476 | * @param data - Optional additional error data
|
477 | *
|
478 | * @returns A 451 Unavailable for Legal Reasons error
|
479 | */
|
480 | export function illegal<Data>(message?: string, data?: Data): Boom<Data>;
|
481 |
|
482 |
|
483 | // 5xx Errors
|
484 |
|
485 | /**
|
486 | * Returns a internal error (defaults to 500)
|
487 | *
|
488 | * @param message - Optional message
|
489 | * @param data - Optional additional error data
|
490 | * @param statusCode - Optional status code override. Defaults to 500.
|
491 | *
|
492 | * @returns A 500 Internal Server error
|
493 | */
|
494 | export function internal<Data>(message?: string, data?: Data, statusCode?: number): Boom<Data>;
|
495 |
|
496 |
|
497 | /**
|
498 | * Returns a 500 Internal Server Error error
|
499 | *
|
500 | * @param message - Optional message
|
501 | * @param data - Optional additional error data
|
502 | *
|
503 | * @returns A 500 Internal Server error
|
504 | */
|
505 | export function badImplementation<Data>(message?: string, data?: Data): Boom<Data>;
|
506 |
|
507 |
|
508 | /**
|
509 | * Returns a 501 Not Implemented error
|
510 | *
|
511 | * @param message - Optional message
|
512 | * @param data - Optional additional error data
|
513 | *
|
514 | * @returns A 501 Not Implemented error
|
515 | */
|
516 | export function notImplemented<Data>(message?: string, data?: Data): Boom<Data>;
|
517 |
|
518 |
|
519 | /**
|
520 | * Returns a 502 Bad Gateway error
|
521 | *
|
522 | * @param message - Optional message
|
523 | * @param data - Optional additional error data
|
524 | *
|
525 | * @returns A 502 Bad Gateway error
|
526 | */
|
527 | export function badGateway<Data>(message?: string, data?: Data): Boom<Data>;
|
528 |
|
529 |
|
530 | /**
|
531 | * Returns a 503 Service Unavailable error
|
532 | *
|
533 | * @param message - Optional message
|
534 | * @param data - Optional additional error data
|
535 | *
|
536 | * @returns A 503 Service Unavailable error
|
537 | */
|
538 | export function serverUnavailable<Data>(message?: string, data?: Data): Boom<Data>;
|
539 |
|
540 |
|
541 | /**
|
542 | * Returns a 504 Gateway Time-out error
|
543 | *
|
544 | * @param message - Optional message
|
545 | * @param data - Optional additional error data
|
546 | *
|
547 | * @returns A 504 Gateway Time-out error
|
548 | */
|
549 | export function gatewayTimeout<Data>(message?: string, data?: Data): Boom<Data>;
|