1 | // Type definitions for boom 7.3
|
2 | // Project: https://github.com/hapijs/boom
|
3 | // Definitions by: AJP <https://github.com/AJamesPhillips>
|
4 | // Jinesh Shah <https://github.com/jineshshah36>
|
5 | // Timon van Spronsen <https://github.com/TimonVS>
|
6 | // Daniel Machado <https://github.com/danielmachado>
|
7 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
8 | // TypeScript Version: 2.4
|
9 |
|
10 | export = Boom;
|
11 | /**
|
12 | * boom provides a set of utilities for returning HTTP errors. Each utility returns a Boom error response object (instance of Error) which includes the following properties:
|
13 | * @see {@link https://github.com/hapijs/boom#boom}
|
14 | */
|
15 | declare class Boom<Data = any> extends Error {
|
16 | /** Creates a new Boom object using the provided message and then calling boomify() to decorate the error with the Boom properties. */
|
17 | constructor(message?: string | Error, options?: Boom.Options<Data>);
|
18 | /** isBoom - if true, indicates this is a Boom object instance. */
|
19 | isBoom: boolean;
|
20 | /** isServer - convenience bool indicating status code >= 500. */
|
21 | isServer: boolean;
|
22 | /** message - the error message. */
|
23 | message: string;
|
24 | /** output - the formatted response. Can be directly manipulated after object construction to return a custom error response. Allowed root keys: */
|
25 | output: Boom.Output;
|
26 | /** typeof - the constructor used to create the error (e.g. Boom.badRequest). */
|
27 | readonly typeof: () => any;
|
28 | /** reformat() - rebuilds error.output using the other object properties. */
|
29 | reformat(): string;
|
30 | /**
|
31 | * "If message is unset, the 'error' segment of the header will not be present and
|
32 | * isMissing will be true on the error object." mentioned in
|
33 | * @see {@link https://github.com/hapijs/boom#boomunauthorizedmessage-scheme-attributes}
|
34 | */
|
35 | isMissing?: boolean | undefined;
|
36 | /** https://github.com/hapijs/boom#createstatuscode-message-data and https://github.com/hapijs/boom/blob/v4.3.0/lib/index.js#L99 */
|
37 | data: Data;
|
38 | }
|
39 | declare namespace Boom {
|
40 | interface Options<Data> {
|
41 | /** statusCode - the HTTP status code. Defaults to 500 if no status code is already set. */
|
42 | statusCode?: number | undefined;
|
43 | /** data - additional error information (assigned to error.data). */
|
44 | data?: Data | undefined;
|
45 | /** decorate - an option with extra properties to set on the error object. */
|
46 | decorate?: object | undefined;
|
47 | /** ctor - constructor reference used to crop the exception call stack output. */
|
48 | ctor?: any;
|
49 | /** message - error message string. If the error already has a message, the provided message is added as a prefix. Defaults to no message. */
|
50 | message?: string | undefined;
|
51 | /**
|
52 | * override - if false, the err provided is a Boom object, and a statusCode or message are
|
53 | * provided, the values are ignored. Defaults to true (apply the provided statusCode and
|
54 | * message options to the error regardless of its type, Error or Boom object).
|
55 | */
|
56 | override?: boolean | undefined;
|
57 | }
|
58 |
|
59 | interface Output {
|
60 | /** statusCode - the HTTP status code (typically 4xx or 5xx). */
|
61 | statusCode: number;
|
62 | /**
|
63 | * headers - an object containing any HTTP headers where each key is a header name and
|
64 | * value is the header content. (Limited value type to string
|
65 | * https://github.com/hapijs/boom/issues/151 )
|
66 | */
|
67 | headers: {[index: string]: string};
|
68 | /**
|
69 | * payload - the formatted object used as the response payload (stringified).
|
70 | * Can be directly manipulated but any changes will be lost if reformat() is called.
|
71 | * Any content allowed and by default includes the following content:
|
72 | */
|
73 | payload: Payload;
|
74 | }
|
75 |
|
76 | interface Payload {
|
77 | /** statusCode - the HTTP status code, derived from error.output.statusCode. */
|
78 | statusCode: number;
|
79 | /** error - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from statusCode. */
|
80 | error: string;
|
81 | /** message - the error message derived from error.message. */
|
82 | message: string;
|
83 | /**
|
84 | * "Every key/value pair will be included ... in the response payload under the attributes key."
|
85 | * [see docs](https://github.com/hapijs/boom#boomunauthorizedmessage-scheme-attributes)
|
86 | */
|
87 | attributes?: any;
|
88 | // Excluded this to aid typing of the other values. See tests for example casting to a custom interface to manipulate the payload
|
89 | // [anyContent: string]: any;
|
90 | }
|
91 |
|
92 | /**
|
93 | * Decorates an error with the boom properties
|
94 | * @param error the error object to wrap. If error is already a boom object, it defaults to overriding the object with the new status code and message.
|
95 | * @param options optional additional options
|
96 | * @see {@link https://github.com/hapijs/boom#boomifyerror-options}
|
97 | */
|
98 | function boomify(error: Error, options?: { statusCode?: number | undefined, message?: string | undefined, override?: boolean | undefined }): Boom<null>;
|
99 |
|
100 | /**
|
101 | * Identifies whether an error is a Boom object. Same as calling instanceof Boom.
|
102 | * @param error the error object to identify.
|
103 | */
|
104 | function isBoom(error: Error): error is Boom;
|
105 |
|
106 | // 4xx
|
107 | /**
|
108 | * Returns a 400 Bad Request error
|
109 | * @param message optional message.
|
110 | * @param data optional additional error data.
|
111 | * @see {@link https://github.com/hapijs/boom#boombadrequestmessage-data}
|
112 | */
|
113 | function badRequest<Data = null>(message?: string, data?: Data): Boom<Data>;
|
114 |
|
115 | /**
|
116 | * Returns a 401 Unauthorized error
|
117 | * @param message optional message.
|
118 | * @param scheme can be one of the following:
|
119 | * * an authentication scheme name
|
120 | * * an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
|
121 | * @param attributes an object of values to use while setting the 'WWW-Authenticate' header.
|
122 | * This value is only used when scheme is a string, otherwise it is ignored.
|
123 | * Every key/value pair will be included in the 'WWW-Authenticate' in the format of
|
124 | * 'key="value"' as well as in the response payload under the attributes key.
|
125 | * Alternatively value can be a string which is use to set the value of the scheme,
|
126 | * for example setting the token value for negotiate header.
|
127 | * If string is used message parameter must be null.
|
128 | * null and undefined will be replaced with an empty string. If attributes is set,
|
129 | * message will be used as the 'error' segment of the 'WWW-Authenticate' header.
|
130 | * If message is unset, the 'error' segment of the header will not be present and isMissing will be true on the error object.
|
131 | * @see {@link https://github.com/hapijs/boom#boomunauthorizedmessage-scheme-attributes}
|
132 | */
|
133 | function unauthorized(message?: string, scheme?: string, attributes?: {[index: string]: string}): Boom<null>;
|
134 | function unauthorized(message?: string, scheme?: string[]): Boom<null>;
|
135 | function unauthorized(message?: null, scheme?: string, attributes?: {[index: string]: string} | string): Boom<null>;
|
136 |
|
137 | /**
|
138 | * Returns a 402 Payment Required error
|
139 | * @param message optional message.
|
140 | * @param data optional additional error data.
|
141 | * @see {@link https://github.com/hapijs/boom#boompaymentrequiredmessage-data}
|
142 | */
|
143 | function paymentRequired<Data = null>(message?: string, data?: Data): Boom<Data>;
|
144 |
|
145 | /**
|
146 | * Returns a 403 Forbidden error
|
147 | * @param message optional message.
|
148 | * @param data optional additional error data.
|
149 | * @see {@link https://github.com/hapijs/boom#boomforbiddenmessage-data}
|
150 | */
|
151 | function forbidden<Data = null>(message?: string, data?: Data): Boom<Data>;
|
152 |
|
153 | /**
|
154 | * Returns a 404 Not Found error
|
155 | * @param message optional message.
|
156 | * @param data optional additional error data.
|
157 | * @see {@link https://github.com/hapijs/boom#boomnotfoundmessage-data}
|
158 | */
|
159 | function notFound<Data = null>(message?: string, data?: Data): Boom<Data>;
|
160 |
|
161 | /**
|
162 | * Returns a 405 Method Not Allowed error
|
163 | * @param message optional message.
|
164 | * @param data optional additional error data.
|
165 | * @param allow optional string or array of strings (to be combined and separated by ', ') which is set to the 'Allow' header.
|
166 | * @see {@link https://github.com/hapijs/boom#boommethodnotallowedmessage-data-allow}
|
167 | */
|
168 | function methodNotAllowed<Data = null>(message?: string, data?: Data, allow?: string | string[]): Boom<Data>;
|
169 |
|
170 | /**
|
171 | * Returns a 406 Not Acceptable error
|
172 | * @param message optional message.
|
173 | * @param data optional additional error data.
|
174 | * @see {@link https://github.com/hapijs/boom#boomnotacceptablemessage-data}
|
175 | */
|
176 | function notAcceptable<Data = null>(message?: string, data?: Data): Boom<Data>;
|
177 |
|
178 | /**
|
179 | * Returns a 407 Proxy Authentication Required error
|
180 | * @param message optional message.
|
181 | * @param data optional additional error data.
|
182 | * @see {@link https://github.com/hapijs/boom#boomproxyauthrequiredmessage-data}
|
183 | */
|
184 | function proxyAuthRequired<Data = null>(message?: string, data?: Data): Boom<Data>;
|
185 |
|
186 | /**
|
187 | * Returns a 408 Request Time-out error
|
188 | * @param message optional message.
|
189 | * @param data optional additional error data.
|
190 | * @see {@link https://github.com/hapijs/boom#boomclienttimeoutmessage-data}
|
191 | */
|
192 | function clientTimeout<Data = null>(message?: string, data?: Data): Boom<Data>;
|
193 |
|
194 | /**
|
195 | * Returns a 409 Conflict error
|
196 | * @param message optional message.
|
197 | * @param data optional additional error data.
|
198 | * @see {@link https://github.com/hapijs/boom#boomconflictmessage-data}
|
199 | */
|
200 | function conflict<Data = null>(message?: string, data?: Data): Boom<Data>;
|
201 |
|
202 | /**
|
203 | * Returns a 410 Gone error
|
204 | * @param message optional message.
|
205 | * @param data optional additional error data.
|
206 | * @see {@link https://github.com/hapijs/boom#boomresourcegonemessage-data}
|
207 | */
|
208 | function resourceGone<Data = null>(message?: string, data?: Data): Boom<Data>;
|
209 |
|
210 | /**
|
211 | * Returns a 411 Length Required error
|
212 | * @param message optional message.
|
213 | * @param data optional additional error data.
|
214 | * @see {@link https://github.com/hapijs/boom#boomlengthrequiredmessage-data}
|
215 | */
|
216 | function lengthRequired<Data = null>(message?: string, data?: Data): Boom<Data>;
|
217 |
|
218 | /**
|
219 | * Returns a 412 Precondition Failed error
|
220 | * @param message optional message.
|
221 | * @param data optional additional error data.
|
222 | * @see {@link https://github.com/hapijs/boom#boompreconditionfailedmessage-data}
|
223 | */
|
224 | function preconditionFailed<Data = null>(message?: string, data?: Data): Boom<Data>;
|
225 |
|
226 | /**
|
227 | * Returns a 413 Request Entity Too Large error
|
228 | * @param message optional message.
|
229 | * @param data optional additional error data.
|
230 | * @see {@link https://github.com/hapijs/boom#boomentitytoolargemessage-data}
|
231 | */
|
232 | function entityTooLarge<Data = null>(message?: string, data?: Data): Boom<Data>;
|
233 |
|
234 | /**
|
235 | * Returns a 414 Request-URI Too Large error
|
236 | * @param message optional message.
|
237 | * @param data optional additional error data.
|
238 | * @see {@link https://github.com/hapijs/boom#boomuritoolongmessage-data}
|
239 | */
|
240 | function uriTooLong<Data = null>(message?: string, data?: Data): Boom<Data>;
|
241 |
|
242 | /**
|
243 | * Returns a 415 Unsupported Media Type error
|
244 | * @param message optional message.
|
245 | * @param data optional additional error data.
|
246 | * @see {@link https://github.com/hapijs/boom#boomunsupportedmediatypemessage-data}
|
247 | */
|
248 | function unsupportedMediaType<Data = null>(message?: string, data?: Data): Boom<Data>;
|
249 |
|
250 | /**
|
251 | * Returns a 416 Requested Range Not Satisfiable error
|
252 | * @param message optional message.
|
253 | * @param data optional additional error data.
|
254 | * @see {@link https://github.com/hapijs/boom#boomrangenotsatisfiablemessage-data}
|
255 | */
|
256 | function rangeNotSatisfiable<Data = null>(message?: string, data?: Data): Boom<Data>;
|
257 |
|
258 | /**
|
259 | * Returns a 417 Expectation Failed error
|
260 | * @param message optional message.
|
261 | * @param data optional additional error data.
|
262 | * @see {@link https://github.com/hapijs/boom#boomexpectationfailedmessage-data}
|
263 | */
|
264 | function expectationFailed<Data = null>(message?: string, data?: Data): Boom<Data>;
|
265 |
|
266 | /**
|
267 | * Returns a 418 I'm a Teapot error
|
268 | * @param message optional message.
|
269 | * @param data optional additional error data.
|
270 | * @see {@link https://github.com/hapijs/boom#boomteapotmessage-data}
|
271 | */
|
272 | function teapot<Data = null>(message?: string, data?: Data): Boom<Data>;
|
273 |
|
274 | /**
|
275 | * Returns a 422 Unprocessable Entity error
|
276 | * @param message optional message.
|
277 | * @param data optional additional error data.
|
278 | * @see {@link https://github.com/hapijs/boom#boombaddatamessage-data}
|
279 | */
|
280 | function badData<Data = null>(message?: string, data?: Data): Boom<Data>;
|
281 |
|
282 | /**
|
283 | * Returns a 423 Locked error
|
284 | * @param message optional message.
|
285 | * @param data optional additional error data.
|
286 | * @see {@link https://github.com/hapijs/boom#boomlockedmessage-data}
|
287 | */
|
288 | function locked<Data = null>(message?: string, data?: Data): Boom<Data>;
|
289 |
|
290 | /**
|
291 | * Returns a 424 Failed Dependency error
|
292 | * @param message optional message.
|
293 | * @param data optional additional error data.
|
294 | * @see {@link https://github.com/hapijs/boom#boomfaileddependencymessage-data}
|
295 | */
|
296 | function failedDependency<Data = null>(message?: string, data?: Data): Boom<Data>;
|
297 |
|
298 | /**
|
299 | * Returns a 428 Precondition Required error
|
300 | * @param message optional message.
|
301 | * @param data optional additional error data.
|
302 | * @see {@link https://github.com/hapijs/boom#boompreconditionrequiredmessage-data}
|
303 | */
|
304 | function preconditionRequired<Data = null>(message?: string, data?: Data): Boom<Data>;
|
305 |
|
306 | /**
|
307 | * Returns a 429 Too Many Requests error
|
308 | * @param message optional message.
|
309 | * @param data optional additional error data.
|
310 | * @see {@link https://github.com/hapijs/boom#boomtoomanyrequestsmessage-data}
|
311 | */
|
312 | function tooManyRequests<Data = null>(message?: string, data?: Data): Boom<Data>;
|
313 |
|
314 | /**
|
315 | * Returns a 451 Unavailable For Legal Reasons error
|
316 | * @param message optional message.
|
317 | * @param data optional additional error data.
|
318 | * @see {@link https://github.com/hapijs/boom#boomillegalmessage-data}
|
319 | */
|
320 | function illegal<Data = null>(message?: string, data?: Data): Boom<Data>;
|
321 |
|
322 | // 5xx
|
323 | /**
|
324 | * Returns a 500 Internal Server Error error
|
325 | * Only 500 errors will hide your message from the end user. Your message is recorded in the server log.
|
326 | * @param message optional message.
|
327 | * @param data optional additional error data.
|
328 | * @see {@link https://github.com/hapijs/boom#boombadimplementationmessage-data---alias-internal}
|
329 | */
|
330 | function badImplementation<Data = null>(message?: string, data?: Data): Boom<Data>;
|
331 |
|
332 | /**
|
333 | * Returns a 500 Internal Server Error error
|
334 | * Only 500 errors will hide your message from the end user. Your message is recorded in the server log.
|
335 | * @param message optional message.
|
336 | * @param data optional additional error data.
|
337 | * @see {@link https://github.com/hapijs/boom#boombadimplementationmessage-data---alias-internal}
|
338 | */
|
339 | function internal<Data = null>(message?: string, data?: Data): Boom<Data>;
|
340 |
|
341 | /**
|
342 | * Returns a 501 Not Implemented error with your error message to the user
|
343 | * @param message optional message.
|
344 | * @param data optional additional error data.
|
345 | * @see {@link https://github.com/hapijs/boom#boomnotimplementedmessage-data}
|
346 | */
|
347 | function notImplemented<Data = null>(message?: string, data?: Data): Boom<Data>;
|
348 |
|
349 | /**
|
350 | * Returns a 502 Bad Gateway error with your error message to the user
|
351 | * @param message optional message.
|
352 | * @param data optional additional error data.
|
353 | * @see {@link https://github.com/hapijs/boom#boombadgatewaymessage-data}
|
354 | */
|
355 | function badGateway<Data = null>(message?: string, data?: Data): Boom<Data>;
|
356 |
|
357 | /**
|
358 | * Returns a 503 Service Unavailable error with your error message to the user
|
359 | * @param message optional message.
|
360 | * @param data optional additional error data.
|
361 | * @see {@link https://github.com/hapijs/boom#boomserverunavailablemessage-data}
|
362 | */
|
363 | function serverUnavailable<Data = null>(message?: string, data?: Data): Boom<Data>;
|
364 |
|
365 | /**
|
366 | * Returns a 504 Gateway Time-out error with your error message to the user
|
367 | * @param message optional message.
|
368 | * @param data optional additional error data.
|
369 | * @see {@link https://github.com/hapijs/boom#boomgatewaytimeoutmessage-data}
|
370 | */
|
371 | function gatewayTimeout<Data = null>(message?: string, data?: Data): Boom<Data>;
|
372 | }
|