perror
Smart named Error objects with HTTP compatibility.
Key features:
- Error object presets
- Predefined codes and messages
- HTTP-compatible errors
- Errors can contain additional debug data
- JSON-friendly
- Automatically wraps other error objects
- Extremely lightweight
- Unit-tested
Table of Contents
Example
var perror = ; // Create an error with code, name and predefined title.// The associated HTTP code is optionalvar NotFoundError = ; // Another error with no code and message: both are `undefined`var GenericError = ; // Throw ittry // Set a message, provide some debug context data throw 'Page was not found' page_url: '/index' ;// Catch itcatche ename; // Error name: 'NotFound' ecode; // Code: 1 emessage; // Error message: 'Not found: Page was not found' ehttpCode; // HTTP error code: 404 edata; // Debug data: { page_url: '/index' } (if provided) estack; // stack trace still available
perror()
perror()
builds an Error object constructor with some presents and fine-tuning.
The errors are indistinguishable from generic Error
objects, including names and stack traces.
The generic signature is:
perror([code, ] name [, message] [, superCtor])
Arguments:
-
code: Number?
: Optional numeric error code, stored into thecode
property. When not provided - the property is not set.Note: only numeric error codes are supported!
-
name: String
: Error object name. Is stored into thename
property. -
message: String?
: Optional error message prefix. If specified - is prepended to the error message. -
superCtor: Function?
: Optional parent superclass constructor. Use to inherit from specific error objects.
It returns an Error object which accepts the following arguments:
message: String|Error
: Error message string, or another Error object to wrap.data: *?
: Arbitrary metadata to store into thedata
property
In addition, the following chain methods are available:
httpCode(Number)
: Associate an HTTP code with the error. Is stored into thehttpCode
property.extra(Object)
: Add arbitrary fields to error instances: the provided object fields are copied into the error instance.
An error instance has the following properties:
name: String
: Error namemessage: String
: Error messagecode: Number?
: Error code, if setdata: *?
: Error debug data, if providedhttpCode: Number?
: HTTP error code, if set
Use Cases
Generic Errors
You can use perror()
to create generic error objects.
perror(name[, superCtor])
Arguments:
name: String
: Name for the error objectsuperCtor: Function?
: Optional parent Error object to inherit from. By default, it inherits fromError
.
The function returns a generic Error object constructor.
Example:
var RuntimeError = ; try throw 'something bad'; catche // Standard Error object fields ename; emessage; // Convertible to string console; // -> 'RuntimeError: something bad'
Code and Message
You can associate numeric error codes and message prefixes with the error object.
perror([code, ], name[, message] [, superCtor])
Example:
var NotFoundError = ; try throw 'page'; catche ename; // -> 'NotFoundError' ecode; // -> 10 emessage; // -> 'Not Found: page'
Error Instances
Throwing Errors
Each Error constructor built by perror()
accepts two arguments: the message, and the optional debug data.
Example:
var RuntimeError = ; try throw 'broken' a: 1 ;catche edata; // -> { a: 1 }
Wrapping Errors
Error objects from perror()
can wrap other objects: all properties are copied to the wrapper, saving the original message prefix.
Is useful when you need to make sure the value got from elsewhere is an Error object with some known fields,
like httpCode
(see below).
Example:
// An error with defaults var GenericError = ; // A specific error with overrides var CustomError = ; try throw 'Hey!' ; catche ecode; // -> 10 -- copied ename; // -> 'CustomError' -- copied emessage; // -> 'Generic Error: Custom Error: Hey!' -- merged
HTTP-compatible errors
The Error constructor has a httpCode(Number)
method which allows you to specify an associated HTTP error code.
This comes extremely handy when the exception is to be reported via HTTP.
Combine it with Wrapping and get defaults for your HTTP response codes in case of errors!
Example:
var ServerError = ; app;
perror.Lookup
Having all those names and codes at hand, it's natural to desire a tool that creates Error objects by name or code.
perror.Lookup does precisely this: construct it with an object of Errors (most probably - a module), and enjoy the lookup!
var perror =
Note: both code()
and name()
use the generic Error
object when no matching Error is found!