errors.md 11.2 KB

Raw Blame History Permalink



JS_ERRORS

JavaScript Error constructors indexed by name
for convenience.

Examples:

new errors.JS_ERRORS.URIError('Malformed URI');


cache({String}, {Number}, {Function})

Cache the given error constructor indexed by the
given name and code.


Params:


name {String} name
code {Number} code
err {Function} err


nextCode()

Return the next free error code.


find(err)

Returns the error constructor by the given code or
name.

Examples:

errors.find(404);
 // => Http404Error

errors.find(500);
 // => Http500Error

errors.find('Http401Error');
 // => http401Error


Params:


String|Number err 


isError(err)

Determines if the given Error object was created using
the errors framework.


Params:


Object err The error to check


create

Create a new constructor instance based
on the given options.

This factory method allows consumers to build
parameterized error constructor function instances
which can then be used to instantiate new concrete
instances of the given error.

This method accepts jQuery style options argument
with the following properties (note that name is
the only required property, all others are optional).

The scope option can be used to change the default
namespace to create the constructor in. If unspecified
it defaults to the exports object of this module
(i.e. errors.exports).

The parent option specifies the parent to inherit
from. If unspecified it defaults to Error.

The defaultMessage, defaultExplanation and
defaultResponse define the default text to use
for the new errors message, explanation and
response respectively. These values can be
overridden at construction time.

The code specifies the error code for the new
error. If unspecified it defaults to a generated
error number which is greater than or equal to
600.

Examples:

// use all defaults
 errors.create({name: 'FileNotFoundError'});
 throw new errors.FileNotFoundError("Could not find file x");

// inheritance
 errors.create({
     name: 'FatalError',
     code: 900
 });
 errors.create({
     name: 'DatabaseError',
     parent: errors.FatalError
     code: 901
 });
 var dbe = new errors.DatabaseError("Internal database error");
 dbe instanceof errors.FatalError;
 // => true

// scoping to current module exports
 var MalformedEncodingError = errors.create({
     name: 'MalformedEncodingError',
     scope: exports
 });
 throw new MalformedEncodingError("Encoding not supported");

// default message
 errors.create({
     name: 'SocketReadError',
     code: 4000,
     defaultMessage: 'Could not read from socket'
 });
 var sre = new errors.SocketReadError();
 sre.message;
 // => 'Could not read from socket'
 sre.code;
 // => 4000
 sre instanceof Error;
 // => true

// explanation and response
 errors.create({
     name: 'SocketReadError',
     code: 4000,
     defaultMessage: 'Could not read from socket',
     defaultExplanation: 'Unable to obtain a reference to the socket',
     defaultResponse: 'Specify a different port or socket and retry the operation'
 });
 var sre = new errors.SocketReadError();
 sre.explanation;
 // => 'Unable to obtain a reference to the socket'
 sre.response;
 // => 'Specify a different port or socket and retry the operation'


Params:


String name The constructor name.
Object scope The scope (i.e. namespace).
Function parent The parent to inherit from.
String defaultMessage The default message.
Number code The error code.
String defaultExplanation The default explanation.
String defaultResponse The default operator response.


Return:


Function the newly created constructor


Create a new instance of the exception optionally
specifying a message, explanation and response
for the new instance. If any of the arguments are
null, their value will default to their respective
default value use on the create call, or will
be null if no default was specified.


Params:


String msg The message to use for the error.
String expl The explanation to use for the error.
String fix The response to use for the error.


Return:


Object The newly created error.


Return the stack tracks for the error.


Return:


String 


Return the explanation for this error.


Return:


String 


Return the operator response for this error.


Return:


String 


Return the error code.


Return:


Number 


HTTP status code of this error.

If the instance's code is not a valid
HTTP status code it's normalized to 500.s


Return:


Number 


Name of this error.


Return:


String 


Message for this error.


Return:


String 


Return the name of the prototype.


Return:


String 


Return a formatted string for this error which
includes the error's name, message and code.
The string will also include the explanation and
response if they are set for this instance.

Can be redefined by consumers to change formatting.


Return:


String 


Return the JSON representation of this error
which includes it's name, code, message
and status. The JSON object returned will
also include the explanation and response
if defined for this instance.

This method can be redefined for customized
behavior of JSON.stringify().


Return:


Object 


stacks(useStacks)

Get/set the module default behavior in terms of if
stack traces should be included in toString(),
send()ing errors, etc.

When called with no parameters this method will return
if the errors module is set to use stacks or not.

When called with a single boolean parameter this
method will interally set if stack traces should be used.


Params:


Boolean useStacks 


title(title)

Gets/sets the module's default page title to use for
html based responses.

If called with no arguments, returns the current title
set. Otherwise when called with a single String argument
sets the title to use for html based responses.

The default title is 'Error'.


Params:


String title The title to use.


mixin(src, dest, skipEmpty)

Perform a top level mixing between and source
and destination object optionally skipping
undefined/null properties.

Examples:

mixin({a: 'A'}, {b: 'B});
 // => {a: 'A', b: 'B'}

mixin({'a': null}, {b: 'B}, true);
 // => {b: 'B'}


Params:


Object src 
Object dest 
Boolean skipEmpty 


Base Error for web app HTTP based
exceptions -- all 4xx and 5xx wrappered
errors are instances of HttpError.

HttpErrors for all 4xx-5xx HTTP based status codes
defined as Http[code]Error for convenience.

Examples:

// Accept: text/html
 res.send(new errors.Http404Error('Resource not found'));
 // => text/html
 // => "Resource not found"

// Accept: application/json
 res.send(new errors.Http423Error('Resource is currently locked'));
 // => application/json
 // {
 //      "name": "Http423Error",
 //      "code": 423,
 //      "status": 423,
 //      "message": "Resource is currently locked"
 // }

// Accept: text/plain
 // res.send(new errors.Http401Error('You do not have access'));
 // => text/plain
 // "You do not have access"


errorHandler(title, connectCompat, includeStack)

Custom error handler middleware based on connect's
errorHandler() middleware. Althought out of the box
connect or express errorHandler() works just fine,
its not as pretty as you might like due to the additional
details in custom error's toString().

Therefore errors exports its own errorHandler()
middleware which supports an options object to configure
it.

The options JSON object accepts the following properties:


Params:


String title The title to use for html based responses which overrides module title().
Boolean connectCompat True to create connect compat html responses.
Boolean includeStack True if the custom error handler should include the stack.


If Express is installed, patch response to
permit sending Error based objects. If
vanilla Error objects are used with send,
they are mapped by default to the Http500Error.

Prior to sending an error based response, any
mapper setup for the Error is invoked allowing
customization or transformation of the error.

The current implementation provides direct support
for text/html, text/plain and application/json
based accept types, otherwise it defaults to plain/text.

Examples:

// Accept: text/html
 res.send(new errors.Http404Error('Resource not found'));
 // => html
 // => html structured response

// Accept: application/json
 res.send(new errors.Http423Error('Resource is currently locked'));
 // => application/json
 // => {
 // =>   'name': 'Http423Error',
 // =>   'code': 423,
 // =>   'status': 423,
 // =>   'message': 'Resource is currently locked'
 // => }

// Accept: text/plain
 // res.send(new errors.Http401Error('You do not have access'));
 // => text/plain
 // => "You do not have access"

// Accept: text/xml
 // res.send(new errors.Http500Error('Something bad happened'));
 // => 500
 // => text/plain


defaultFormatter(title, includeStack)

Returns the default formatter which handles
responses for the middleware and send() method.
This code is based on connect's errorHandler.


Params:


String title The title to use for html response.
Boolean includeStack If we should include the stack trace.


asArray(obj)

Returns the argument as an Array. If
the argument is already an Array, it's
returned unchanged. Otherwise the given
argument is returned in a new Array.

Examples:

asArray('a');
 // => ['a']

asArray(null);
 // => []

asArray(['a', 'b']);
 // => ['a', 'b']


Params:


Object|Array obj The object to wrap in an array.


mapper

Adds or retrieves an error mappers.

When called with 2 arguments, this method is used to
add error mappers for the given error names.

When called with a single argument it's used to
retrieve the registered mapper for the given
error name.

Any bound mappers will be invoked
for express.send() integration and hence you
can define mappers used when sending error responses
with Express.

Examples:

// adding mappers
 errors.mapper('RangeError', function(rangeError) {
     return new errors.Http412Error('Invalid range requested');
 })
 .addmapper('ReferenceError', function(refError) {
     return new errors.Http424Error('Bad reference given');
 });

errors.mapper(['RangeError', 'ReferenceError'], function(err) {
     return new errors.Http500Error(err.message);
 });

// retrieve error mapper
 var rangeError = errors.mapper('RangeError');


Params:


String|Array errName The error name(s) to attach the mapper to.
Function fn The function to call for the mapping.


mapError

Maps the given error using the bound error mapper
and returns the mapped error as per the mappers
return value. If no mapper is bound to the given
errors name, the argument error is returned unchanged.

Examples:

errors.mapError(new RangeError());


Params:


Object err The error instance to map.