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

Install

npm install common-errors

Class Directory

Common Error Classes

Utility Functions

Express Middleware Functions

Common Error Classes

AlreadyInUseError

Applicable when a resource is already in use, for example unique key constraints like a username.

new AlreadyInUseError(entityName, arg1, [arg2, arg3, arg4, ...])

Arguments

entityName - the entity that owns the protected resource

- the entity that owns the protected resource args - the fields or attributes that are already in use

throw new errors . AlreadyInUseError ( ' user ' , ' username ' ) ;

ArgumentError

Applicable when there's a generic problem with an argument received by a function call.

new ArgumentError(argumentName[, inner_error])

Arguments

argumentName - the name of the argument that has a problem

- the name of the argument that has a problem inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . ArgumentError ( ' username ' , err ) ;

ArgumentNullError

Applicable when an argument received by a function call is null/undefined or empty.

new ArgumentNullError(argumentName[, inner_error])

Arguments

argumentName - the name of the argument that is null

- the name of the argument that is null inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . ArgumentNullError ( ' username ' , err ) ;

AuthenticationRequiredError

Applicable when an operation requires authentication

new AuthenticationRequiredError(message, [inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . AuthenticationRequiredError ( " Please provide authentication. " , err )

ConnectionError

Applicable when an error occurs on a connection.

new ConnectionError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . ConnectionError ( ' database connection no longer available ' , err ) ;

DataError

Applicable when an error occurs on or with an external data source.

new DataError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . DataError ( ' Too many rows returned from database ' , err ) ;

MemcachedError

Applicable when an error occurs while using memcached.

new MemcachedError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . MemcachedError ( ' Expected value not found ' , err ) ;

MongoDBError

Applicable when an error occurs while using MongoDB.

new MongoDBError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . MongoDBError ( ' Retrieved value not in expected format ' , err ) ;

RedisError

Applicable when an error occurs while using redis.

new RedisError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . RedisError ( ' expected value not found in redis ' , err ) ;

RollbackError

Applicable when a transaction was unexpectedly rolled back.

new RollbackError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . RollbackError ( ' database transaction was unexpectedly rolled back ' , err ) ;

SQLError

Applicable when an error occurs while using a SQL database.

new SQLError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . SQLError ( ' foreign key constraint violated ' , err ) ;

TransactionError

Applicable when an error unexpectedly interrupts a transaction.

new TransactionError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . data . TransactionError ( ' transaction already complete ' , err ) ;

Error

This is roughly the same as the native Error class. It additionally supports an inner_error attribute.

new Error(message, [inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . Error ( " Please provide authentication. " , err )

HttpStatusError

Represents a message and a HTTP status code.

new HttpStatusError(status_code[, message])

Arguments

status_code - any HTTP status code integer

- any HTTP status code integer message - any message

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:

{ " ValidationError " : 400 , " ArgumentError " : 400 , " AuthenticationRequiredError " : 401 , " NotPermittedError " : 403 , " ArgumentNullError " : 404 " NotFoundError " : 404 , " NotSupportedError " : 405 , " AlreadyInUseError " : 409 , }

To change the mappings, modify HttpStatusError.message_map and HttpStatusError.code_map

Arguments

err - any instanceof Error

- any instanceof Error req - the request object

throw new errors . HttpStatusError ( err , req ) ;

InvalidOperationError

Applicable when an invalid operation occurs.

new InvalidOperationError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . InvalidOperationError ( ' divide by zero ' , err ) ;

IOError

Base class for Errors while accessing information using streams, files and directories.

new IOError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . IOError ( " Could not open file " , err )

DirectoryNotFoundError

Applicable when part of a file or directory cannot be found.

new DirectoryNotFoundError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . DirectoryNotFoundError ( " /var/log " , err )

DriveNotFoundError

Applicable when trying to access a drive or share that is not available.

new DriveNotFoundError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . DriveNotFoundError ( " c " , err )

EndOfStreamError

Applicable when reading is attempted past the end of a stream.

new EndOfStreamError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . EndOfStreamError ( " EOS while reading header " , err )

FileLoadError

Applicable when a file is found and read but cannot be loaded.

new FileLoadError(message[, inner_error])

Arguments

file_name - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . FileLoadError ( " ./package.json " , err )

FileNotFoundError

Applicable when an attempt to access a file that does not exist on disk fails.

new FileNotFoundError(message[, inner_error])

Arguments

file_name - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . io . FileNotFoundError ( " ./package.json " , err )

SocketError

Applicable when an error occurs on a socket.

new SocketError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . SocketError ( ' socket no longer available ' , err ) ;

NotFoundError

Applicable when an attempt to retrieve data yielded no result.

new NotFoundError(entity_name[, inner_error])

Arguments

entity_name - a description for what was not found

- a description for what was not found inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . NotFoundError ( " User " , err )

NotImplementedError

Applicable when a requested method or operation is not implemented.

new NotImplementedError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . NotImplementedError ( " Method is not yet implemented. " , err )

NotPermittedError

Applicable when an operation is not permitted

new NotPermittedError(message[, inner_error])

Arguments

message - any message

- any message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . NotPermittedError ( " username cannot be changed once set. " , err )

NotSupportedError

Applicable when a certain condition is not supported by your application.

new NotSupportedError(message[, inner_error])

Arguments

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . NotSupportedError ( ' Zero values ' , err ) ;

OutOfMemoryError

Applicable when there is not enough memory to continue the execution of a program.

new OutOfMemoryError(message[, inner_error])

Arguments

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . OutOfMemoryError ( ' Maximum mem size exceeded. ' , err ) ;

RangeError

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

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . RangeError ( " Value must be between " + MIN + " and " + MAX , err ) ;

ReferenceError

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

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . ReferenceError ( " x is not defined " , err ) ;

StackOverflowError

Applicable when the execution stack overflows because it contains too many nested method calls.

new StackOverflowError(message[, inner_error])

Arguments

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . StackOverflowError ( ' Stack overflow detected. ' , err ) ;

SyntaxError

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

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . SyntaxError ( " Unexpected token a " , err ) ;

TimeoutError

Applicable when an operation takes longer than the alloted amount.

new TimeoutError(time[, inner_error])

Arguments

time - a time duration

- a time duration inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . TimeoutError ( ' 100ms ' , err ) ;

TypeError

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

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . TypeError ( " number is not a function " , err ) ;

URIError

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

message - a message

- a message inner_error - the Error instance that caused the current error. Stack trace will be appended.

throw new errors . URIError ( " URI malformed " , err ) ;

ValidationError

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

message - any message

- any message code - an optional error 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 .

- add an error object to the array, and return . addErrors(errors) - append an array of error objects to the errors array, and return this .

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

Log

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

err - any error or error message received from a callback

- any error or error message received from a callback message - any message you'd like to prepend

mysql . query ( ' SELECT * `FROM` users ' , function ( err , results ) { if ( err ) return errors . log ( err , " Had trouble retrieving users. " ) ; console . log ( results ) ; } ) ;

prependCurrentStack

Modifies an error's stack to include the current stack without logging it. Useful for logging errors received by a callback.

prependCurrentStack(err)

Arguments

err - any error or error message received from a callback

mysql . query ( ' SELECT * `FROM` users ' , function ( err , results ) { if ( err ) { return errors . prependCurrentStack ( err ) ; } console . log ( results ) ; } ) ;

generateClass

Simple interface for generating a new Error class type.

helpers.generateClass(name[, options])

Arguments

name - The full name of the new Error class

- The full name of the new Error class options extends - 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.



var ArgumentNullError = helpers . generateClass ( " ArgumentNullError " , { extends : ArgumentError , args : [ ' argumentName ' ] , generateMessage : function ( ) { return " Missing argument: " + this . argumentName ; } } ) ; throw new ArgumentNullError ( " username " ) ;

Express Middleware Functions

Crash Protector

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.

var app = express ( ) ; app . use ( express . static ( __dirname + ' /../public ' ) ) ; app . use ( express . bodyParser ( ) ) ; app . use ( errors . middleware . crashProtector ( ) ) ; app . get ( ' /healthcheck ' , function ( req , res , next ) { res . send ( ' YESOK ' ) } ) ; app . use ( app . router ) ; app . use ( errors . middleware . errorHandler ) ; module . exports = app ;

Error Handler

Express middleware that translates common errors into HTTP status codes and messages.

var app = express ( ) ; app . use ( express . static ( __dirname + ' /../public ' ) ) ; app . use ( express . bodyParser ( ) ) ; app . use ( errors . middleware . crashProtector ( ) ) ; app . get ( ' /healthcheck ' , function ( req , res , next ) { res . send ( ' YESOK ' ) } ) ; app . use ( app . router ) ; app . use ( errors . middleware . errorHandler ) ; module . exports = app ;

Authors

This library was developed by David Fenster at Shutterstock

Contribute

Please do! Check out our Contributing guidelines.

License

MIT © 2013-2017 Shutterstock Images, LLC