Common error classes and utility functions
npm install common-errorscommon-errors
===========
> Common error classes and utility functions
* Full suite of node.js Error classes like most other modern languages
* Append stack traces from other asynchronously generated Errors
* Generate your own custom Error classes in one line
* Map HTTP status codes to Errors for automatic handling in web services and applications
npm install common-errors`Class Directory
$3
* AlreadyInUseError
* ArgumentError
* ArgumentNullError
* AuthenticationRequiredError
* ConnectionError
* DataError
* MemcacedError
* MongoDBError
* RedisError
* RollbackError
* SQLError
* TransactionError
* Error
* HttpStatusError
* InvalidOperationError
* IOError
* DirectoryNotFoundError
* DriveNotFoundError
* EndOfStreamError
* FileLoadError
* FileNotFoundError
* SocketError
* NotFoundError
* NotImplementedError
* NotPermittedError
* NotSupportedError
* OutOfMemoryError
* RangeError
* ReferenceError
* StackOverflowError
* SyntaxError
* TimeoutError
* TypeError
* URIError
* ValidationError
$3
* log
* prependCurrentStack
* generateClass
$3
* Crash Protector
* Error Handler
Common Error Classes
$3
Applicable when a resource is already in use, for example unique key constraints like a username.
new AlreadyInUseError(entityName, arg1, [arg2, arg3, arg4, ...])
__Arguments__
*
- the entity that owns the protected resource
* args - the fields or attributes that are already in use`js
// Example
throw new errors.AlreadyInUseError('user', 'username');
`---------------------------------------
$3
Applicable when there's a generic problem with an argument received by a function call.
new ArgumentError(argumentName[, inner_error])
__Arguments__
*
- the name of the argument that has a problem
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.ArgumentError('username', err);
`---------------------------------------
$3
Applicable when an argument received by a function call is null/undefined or empty.
new ArgumentNullError(argumentName[, inner_error])
__Arguments__
*
- the name of the argument that is null
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.ArgumentNullError('username', err);
`---------------------------------------
$3
Applicable when an operation requires authentication
new AuthenticationRequiredError(message, [inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.AuthenticationRequiredError("Please provide authentication.", err)
`---------------------------------------
$3
Applicable when an error occurs on a connection.
new ConnectionError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.ConnectionError('database connection no longer available', err);
`---------------------------------------
$3
Applicable when an error occurs on or with an external data source.
new DataError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.DataError('Too many rows returned from database', err);
`---------------------------------------
$3
Applicable when an error occurs while using memcached.
new MemcachedError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.MemcachedError('Expected value not found', err);
`---------------------------------------
$3
Applicable when an error occurs while using MongoDB.
new MongoDBError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.MongoDBError('Retrieved value not in expected format', err);
`---------------------------------------
$3
Applicable when an error occurs while using redis.
new RedisError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.RedisError('expected value not found in redis', err);
`---------------------------------------
$3
Applicable when a transaction was unexpectedly rolled back.
new RollbackError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.RollbackError('database transaction was unexpectedly rolled back', err);
`---------------------------------------
$3
Applicable when an error occurs while using a SQL database.
new SQLError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.SQLError('foreign key constraint violated', err);
`---------------------------------------
$3
Applicable when an error unexpectedly interrupts a transaction.
new TransactionError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.data.TransactionError('transaction already complete', err);
`---------------------------------------
$3
This is roughly the same as the native Error class. It additionally supports an inner_error attribute.
new Error(message, [inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.Error("Please provide authentication.", err)
`---------------------------------------
$3
Represents a message and a HTTP status code.
new HttpStatusError(status_code[, message])
__Arguments__
*
- any HTTP status code integer
* message - any message`js
// Example
throw new errors.HttpStatusError(404, "Not Found");
` new HttpStatusError(err[, req])
Figure out a proper status code and message from a given error. The current mapping of error codes
to HTTP status codes is as follows:
javascript
{
"ValidationError": 400,
"ArgumentError": 400,
"AuthenticationRequiredError": 401,
"NotPermittedError": 403,
"ArgumentNullError": 404 // , or 400 depending on what's wrong with the request
"NotFoundError": 404,
"NotSupportedError": 405,
"AlreadyInUseError": 409,
}
`To change the mappings, modify
and HttpStatusError.code_map__Arguments__
*
- any instanceof Error
* req - the request object`js
// Example
throw new errors.HttpStatusError(err, req);
`---------------------------------------
$3
Applicable when an invalid operation occurs.
new InvalidOperationError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.InvalidOperationError('divide by zero', err);
`---------------------------------------
$3
Base class for Errors while accessing information using streams, files and directories.
new IOError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.IOError("Could not open file", err)
`---------------------------------------
$3
Applicable when part of a file or directory cannot be found.
new DirectoryNotFoundError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.DirectoryNotFoundError("/var/log", err)
`---------------------------------------
$3
Applicable when trying to access a drive or share that is not available.
new DriveNotFoundError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.DriveNotFoundError("c", err)
`---------------------------------------
$3
Applicable when reading is attempted past the end of a stream.
new EndOfStreamError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.EndOfStreamError("EOS while reading header", err)
`---------------------------------------
$3
Applicable when a file is found and read but cannot be loaded.
new FileLoadError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.FileLoadError("./package.json", err)
`---------------------------------------
$3
Applicable when an attempt to access a file that does not exist on disk fails.
new FileNotFoundError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.io.FileNotFoundError("./package.json", err)
`---------------------------------------
$3
Applicable when an error occurs on a socket.
new SocketError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.SocketError('socket no longer available', err);
`---------------------------------------
$3
Applicable when an attempt to retrieve data yielded no result.
new NotFoundError(entity_name[, inner_error])
__Arguments__
*
- a description for what was not found
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.NotFoundError("User", err)
`---------------------------------------
$3
Applicable when a requested method or operation is not implemented.
new NotImplementedError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.NotImplementedError("Method is not yet implemented.", err)
`---------------------------------------
$3
Applicable when an operation is not permitted
new NotPermittedError(message[, inner_error])
__Arguments__
*
- any message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.NotPermittedError("username cannot be changed once set.", err)
`---------------------------------------
$3
Applicable when a certain condition is not supported by your application.
new NotSupportedError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.NotSupportedError('Zero values', err);
`---------------------------------------
$3
Applicable when there is not enough memory to continue the execution of a program.
new OutOfMemoryError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.OutOfMemoryError('Maximum mem size exceeded.', err);
`---------------------------------------
$3
Represents an error that occurs when a numeric variable or parameter is outside of its valid range. This is roughly the same as the native RangeError class. It additionally supports an inner_error attribute.
new RangeError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.RangeError("Value must be between " + MIN + " and " + MAX, err);
`---------------------------------------
$3
Represents an error when a non-existent variable is referenced. This is roughly the same as the native ReferenceError class. It additionally supports an inner_error attribute.
new ReferenceError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.ReferenceError("x is not defined", err);
`---------------------------------------
$3
Applicable when the execution stack overflows because it contains too many nested method calls.
new StackOverflowError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.StackOverflowError('Stack overflow detected.', err);
`---------------------------------------
$3
Represents an error when trying to interpret syntactically invalid code. This is roughly the same as the native SyntaxError class. It additionally supports an inner_error attribute.
new SyntaxError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.SyntaxError("Unexpected token a", err);
`---------------------------------------
$3
Applicable when an operation takes longer than the alloted amount.
new TimeoutError(time[, inner_error])
__Arguments__
*
- a time duration
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.TimeoutError('100ms', err);
`---------------------------------------
$3
Represents an error when a value is not of the expected type. This is roughly the same as the native TypeError class. It additionally supports an inner_error attribute.
new TypeError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.TypeError("number is not a function", err);
`---------------------------------------
$3
Represents an error when a value is not of the expected type. This is roughly the same as the native URIError class. It additionally supports an inner_error attribute.
new URIError(message[, inner_error])
__Arguments__
*
- a message
* inner_error - the Error instance that caused the current error. Stack trace will be appended.`js
// Example
throw new errors.URIError("URI malformed", err);
`---------------------------------------
$3
Useful for denoting a problem with a user-defined value. Generally, you won't throw this error.
It serializes to JSON, and it can also function as an envelope for multiple errors.
new ValidationError(message, [code], [field])
__Arguments__
*
- any message
* code - an optional error code
* field - an optional description of the data__Methods__
*
addError(error) - add an error object to the errors array, and return this.
* addErrors(errors) - append an array of error objects to the errors array, and return this.`js
// Example
function validateUsername(username){
var errors = new errors.ValidationError();
if(username.length < 3) errors.addError(new errors.ValidationError("username must be at least two characters long", "VAL_MIN_USERNAME_LENGTH", "username"));
if(/-%$*&!/.test(username)) errors.addError(new errors.ValidationError("username may not contain special characters", "VAL_USERNAME_SPECIALCHARS", "username"));
return errors;
}
`Utility Functions
$3
Modifies an error's stack to include the current stack and logs it to stderr. Useful for logging errors received by a callback.
log(err[, message])
__Arguments__
*
- any error or error message received from a callback
* message - any message you'd like to prepend`js
// Example
mysql.query('SELECT * FROM users', function(err, results){
if(err) return errors.log(err, "Had trouble retrieving users.");
console.log(results);
});
`$3
Modifies an error's stack to include the current stack without logging it. Useful for logging errors received by a callback.
prependCurrentStack(err)
__Arguments__
*
- any error or error message received from a callback`js
// Example
mysql.query('SELECT * FROM users', function(err, results){
if(err) {
return errors.prependCurrentStack(err); // caller has better idea of source of err
}
console.log(results);
});
`$3
Simple interface for generating a new Error class type.
helpers.generateClass(name[, options])
__Arguments__
*
- The full name of the new Error class
* options
* - The base class for the new Error class. Default is Error.
* globalize - Boolean (default true) to store the Error in global space so that the Error is equivalent to others included from other versions of the module.
* args - Array of names of values to accept and store from the class constructor. Default is ['message', 'inner_error'].
* generateMessage - A function for defining a custom error message.`js
// Example
var ArgumentNullError = helpers.generateClass("ArgumentNullError", {
extends: ArgumentError,
args: ['argumentName'],
generateMessage: function(){
return "Missing argument: " + this.argumentName;
}
});throw new ArgumentNullError("username");
`
Express Middleware Functions
$3
Express middleware for preventing the web server from crashing when an error is thrown from an asynchronous context.
Any error that would have caused a crash is logged to stderr.
js
// Example
var app = express();app.use(express.static(__dirname + '/../public'));
app.use(express.bodyParser());
app.use(errors.middleware.crashProtector());
//insert new middleware here
app.get('/healthcheck', function (req, res, next){res.send('YESOK')});
app.use(app.router);
app.use(errors.middleware.errorHandler);
module.exports = app;
`$3
Express middleware that translates common errors into HTTP status codes and messages.
js
// Example
var app = express();app.use(express.static(__dirname + '/../public'));
app.use(express.bodyParser());
app.use(errors.middleware.crashProtector());
//insert new middleware here
app.get('/healthcheck', function (req, res, next){res.send('YESOK')});
app.use(app.router);
app.use(errors.middleware.errorHandler);
module.exports = app;
``This library was developed by David Fenster at Shutterstock
Please do! Check out our Contributing guidelines.
MIT © 2013-2017 Shutterstock Images, LLC