node package manager

preconditions

Support for Precondition error checking in Node.js

Preconditions Library

view on npm npm module downloads Build Status Gitter

Support for Precondition error checking in Node.js

Ensuring a fail fast development environment can help developers find bugs quicker and easier. Ensuring all invariants are true at an initial point of contact will help you ensure this fail fast environment. The Preconditions library will assist you in doing just that by immediately throwing an Error if any of your invariants fail. You can mix and match standard Guava API with convenience functions both with and without chaining.

Version 2 Additions

Version 2 adds a new entry point on the interface, 'errr'. The errr interface decorates the errr node module and helps to solve some important issues with Node, listed below. See https://www.npmjs.com/package/errr. This version also updates the module to Node 5 paradigms.

  1. When templating / generating an error message, we must not string concat strings that are never used. Building an error message before it is needed, will take away cycles from more important tasks in the event queue. There are great performance gains to be found here if you are templating error messages.
  2. Appends Error stack traces together. If you append errors at each layer of your code, and only print the stack trace at the top most layer of your code, you will have stack traces that paint a much clearer picture when debugging. Allows you to get a more informative stack trace when using promise chains.
  3. Add debug params to stack traces to assist with bug resolution.

Install

npm install preconditions

Preconditions Interface

There are four functions that are exposed from the library.

  1. errr() - Verify a one value at a time while building an 'errr' object. You can append errors together and add debug params to the stack trace.
  2. singleton() - Verify one value at a time with a chainable preconditions interface.
  3. instance() - Create a testing suite passing in a single object. Run a single, or multiple tests on the passed in object. Shouldn't be used in production code.
  4. constructor() - Get the constructor function so you can extend the Preconditions library (see below for example). Shouldn't be used in production code.

Examples Using the Errr Interface (.errr())

You can use a static instance to verify one value at a time while using the errr module to build an errr. For more on the errr module see here https://github.com/corybill/Preconditions#errrdecorator and here https://github.com/corybill/errr#errr.

  
    var preconditions = require("preconditions").errr();
  
    preconditions.shouldBeDefined(someObj.valueOne).test();
    preconditions.shouldBeDefined(someObj.valueOne, "Custom error message.").test();
    preconditions.shouldBeDefined(someObj.valueOne, "Error (%s:%s): Error Message.", [errType, errCode]).test();
    preconditions.shouldBeDefined(someObj.valueOne, "Custom error message.").debug({param1: "someDebugParam"}).test();
    preconditions.shouldBeDefined(someObj.valueOne, "Custom error message.").appendTo(someErrorObj).test();
    preconditions.shouldBeDefined(someObj.valueTwo, "Error (%s:%s): Error Message.", [errType, errCode]);
      .debug({param1: "someDebugParam"})
      .appendTo(someErrorObj)
      .test();
  

Examples Using In Promise Chain

Best practice for achieving fail fast concept when function must return promise;

  
    var preconditions = require("preconditions").errr();

    new BlueBirdProm(function (resolve, reject {

      // THIS WILL THROW AND BE CAUGHT AT THE NEXT LEVEL OF THE CHAIN
      // NOTICE YOU DO NOT HAVE TO CALL REJECT BECAUSE WE ARE THROWING WITHIN A PROMISE.
      preconditions.shouldBeDefined(someObj.valueTwo, "Error (%s:%s): Error Message.", [errType, errCode]);
            .debug({param1: "someDebugParam"})
            .appendTo(someErrorObj)
            .test();
              
      return someAsynchFunc().then(function (result) {
        resolve(result);
      }).catch(function (err) {
        reject(err);
      });
    });
  

Examples Using the Singleton Interface (.singleton())

You can use a static instance to verify one value at a time.

  
    var preconditions = require("preconditions").singleton();
  
    preconditions.shouldBeDefined(someObj.valueOne)
      .shouldBeDefined(someObj.valueTwo, "Error (%s:%s): Error Message.", [errType, errCode]).test();
      .shouldBeDefined(someObj.valueThree, "Custom error message.");
  

Examples Using Instance Interface (.instance())

Should not be used in production code!

Setup Instance

  
    var preconditions = require("preconditions").instance(this);
    
    preconditions.shouldBeDefined("foo.deep.stringValue", "Custom error message.")
      .checkArguments("FOO" === "FOO");
  

Examples Using The Constructor (.constructor())

Should not be used in production code!

The Preconditions object itself is exposed so that you can extend the Preconditions class.

  
    let Constructor = preconditions.constructor();
    let ChildClass = class extends Constructor {
      constructor(out) {
        super(out);
      }

      shouldBeFoo(value, message) {
        let msg = message || defaultMessage;

        if (value !== "FOO") {
          throw new Error(msg);
        }
      }
    };
    
    new ChildClass(this).shouldBeDefined("foo.deep.stringValue", "Custom error message.")
      .shouldBeFoo("foo.deep.foo");
  

NPM Scripts

  1. npm run test - Run linter and unit tests.
  2. npm run ut - Use Maddox to Run Unit Tests.
  3. npm run perf - Use Maddox to Performance metrics.
  4. npm run uap - Use Maddox to Unit Tests and Performance metrics.
  5. npm run lint - Run linter.
  6. npm run docs - Rebuild public API Docs.

Missing API or Bugs

Please reach out to me (Cory Parrish) if you would like a new precondition added or if you think you have found a bug.

Known Issues

  1. Release 1.0.2 has an npm install bug and has been deprecated! Please update!
  2. If you are using windows and are seeing npm install issues due to the '^' in the package.json, please update node to >= (v0.10.28).

Releases

  • 2.0.0
    • Adds errr interface which decorates errr node module
    • Allows templating in singleton interface.
    • Notes the poor performance in instance interface. Should not be used in production code.
    • Redesign of code.
    • Now uses maddox for unit testing.
    • Moves to Node 5 paradigms.
  • 1.0.8 - Removed 'underscore' and added 'lodash'.
    • Added a .jshintrc file and a more extensive linting process
    • Separated dependencies and dev-dependencies to reduce installation load (A big thanks to Esteban Ordano (eordano) for doing this work).
  • 1.0.7 - First official public release.

API

Preconditions

Preconditions entry point interface.

ErrrValidator

Validate single value with a buildable interface on top of the errr node module. Use this interface if you want to utilize the following functionality:

  1. Error message templating.
  2. Only templates error message if ErrrValidator fails which saves event queue cycles.
  3. Gives ability to append Stack traces to an existing error.
  4. Gives ability to append debug params to stack trace.
ErrrDecorator

Error Builder allows you to use optional functions to build an error object. The error can have appended stack traces and debug params to assist with debugging.

InstanceValidator

Validate values in a nested object using a dot notation structure (e.g. .shouldBeString("Person.Address.Street.zip")) System will validate the the Person, Person.Address, and Person.Address.Street objects exist, and will validate that zip is a String.

Use this interface if you want to utilize the following functionality:

  1. Nested object validation using a dot notation.
SingletonValidator

Validate single value with a chainable interface. Use this interface if you want to utilize the following functionality:

  1. Error message templating.
  2. Only templates error message if validation fails which saves event queue cycles.
  3. Chain together precondition validations.

Preconditions

Preconditions entry point interface.

Kind: global class

Preconditions.errr() ⇒

Validate single value with the buildable errr interface from the static errr Validation functionality.

Kind: static method of Preconditions
Returns: Error Validation Singleton.

Preconditions.singleton() ⇒

Validate single value with the chainable interface from the Error Validation Singleton.

Kind: static method of Preconditions
Returns: Error Validation Singleton.

Preconditions.instance(objectUnderTest) ⇒

Kind: static method of Preconditions
Returns: Error Validation instance.
Warning: This functionality has very poor performance. Please use the 'singleton' or 'errr' functionality instead.

Validate values of a given JSON object with the preconditions object.

Param Description
objectUnderTest Object Under Test

Preconditions.constructor() ⇒

Gives ability to extend and add other preconditions to the Error Validation constructor.

Kind: static method of Preconditions
Returns: Error Validation constructor.
Warning: This functionality only works with the 'instance' function which has very poor performance.

ErrrValidator

Validate single value with a buildable interface on top of the errr node module. Use this interface if you want to utilize the following functionality:

  1. Error message templating.
  2. Only templates error message if ErrrValidator fails which saves event queue cycles.
  3. Gives ability to append Stack traces to an existing error.
  4. Gives ability to append debug params to stack trace.

Kind: global class

ErrrValidator.shouldBeDefined(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not defined.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeUndefined(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is defined.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeArray(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Array.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeArray(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Array.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeObject(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Object.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeObject(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Object.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeEmpty(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not empty.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeEmpty(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is empty.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeFunction(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Function.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeFunction(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Function.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeString(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type String.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeString(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type String.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeNumber(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Number.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeNumber(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Number.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeFinite(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not finite.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeInfinite(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is finite.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeBoolean(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Boolean.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeBoolean(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Boolean.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeDate(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not of type Date.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeDate(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is of type Date.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeRegExp(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not a Regular Expression.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeRegExp(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is a Regular Expression.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeFalsey(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is not falsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeFalsey(val, [message], [template]) ⇒ ErrrDecorator

Throws an error if 'val' is falsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeFalsy(val, [message], [template]) ⇒ ErrrDecorator

Synonym for shouldBeFalsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeFalsy(val, [message], [template]) ⇒ ErrrDecorator

Synonym for shouldNotBeFalsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldBeTruthy(val, [message], [template]) ⇒ ErrrDecorator

Synonym for shouldNotBeFalsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.shouldNotBeTruthy(val, [message], [template]) ⇒ ErrrDecorator

Synonym for shouldBeFalsey.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.checkArgument(expression, [message], [template]) ⇒ ErrrDecorator

Ensures the truth of an expression involving one or more parameters to the calling method.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.checkState(expression, [message], [template]) ⇒ ErrrDecorator

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.checkElementIndex(index, size, [message], [template]) ⇒ ErrrDecorator

Ensures that index specifies a valid element in an array, list or string of size size.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.checkPositionIndex(index, size, [message], [template]) ⇒ ErrrDecorator

Ensures that index specifies a valid position in an array, list or string of size size.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrValidator.checkPositionIndexes(start, end, size, [message], [template]) ⇒ ErrrDecorator

Ensures that start and end specify a valid positions in an array, list or string of size size, and are in order.

Kind: static method of ErrrValidator
Returns: ErrrDecorator - - An object that decorates the errr node module.

Param Type Description
start Number
end Number
size Number
[message] String The error message or the error template string to use if the ErrrValidator fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

ErrrDecorator

Error Builder allows you to use optional functions to build an error object. The error can have appended stack traces and debug params to assist with debugging.

Kind: global class

new ErrrDecorator([message], [template])

Provides an interface to build an error. Then allows you to get or throw the error.

Param Type Description
[message] String Error message that will supplied to Error Object.
[template] Array Array of parameters. If given, util.format(message, template) will be applied to the message string.

errrDecorator.debug(params, [shouldDebug]) ⇒ ErrorBuilder

Decorated function from 'errr' module. Add parameters to the stack trace that will make it easier to debug the problem.

Kind: instance method of ErrrDecorator
Returns: ErrorBuilder - - Returns the instance of errorBuilder to allow chainability.

Param Type Description
params Object Object Map of key value parameters that will make it easier to debug the error.
[shouldDebug] Boolean If shouldDebug === false, then debug params will not print. Any other value (including undefined), and the debug params will be printed. Useful if you want to only print debugParams given an Environment Variable.

errrDecorator.appendTo(err) ⇒ ErrorBuilder

Decorated function from 'errr' module. Append the error being built, to the end of this error's stack trace.

Kind: instance method of ErrrDecorator
Returns: ErrorBuilder - - Returns the instance of errorBuilder to allow chainability.

Param Type Description
err Error The stack trace of the error being built, will be appended to this error's stack trace.

errrDecorator.test()

Validate preconditions check and throw an errr if it fails.

Kind: instance method of ErrrDecorator

errrDecorator.t()

Synonym for the test function.

Kind: instance method of ErrrDecorator

SingletonValidator

Validate single value with a chainable interface. Use this interface if you want to utilize the following functionality:

  1. Error message templating.
  2. Only templates error message if validation fails which saves event queue cycles.
  3. Chain together precondition validations.

Kind: global class

SingletonValidator.shouldBeDefined(val, [message], [template]) ⇒ this

Throws an error if 'val' is not defined.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeUndefined(val, [message], [template]) ⇒ this

Throws an error if 'val' is defined.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeArray(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Array.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeArray(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Array.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeObject(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Object.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeObject(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Object.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeEmpty(val, [message], [template]) ⇒ this

Throws an error if 'val' is not empty.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeEmpty(val, [message], [template]) ⇒ this

Throws an error if 'val' is empty.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeFunction(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Function.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeFunction(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Function.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeString(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type String.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeString(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type String.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeNumber(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Number.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeNumber(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Number.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeFinite(val, [message], [template]) ⇒ this

Throws an error if 'val' is not finite.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeInfinite(val, [message], [template]) ⇒ this

Throws an error if 'val' is not infinite.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeBoolean(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Boolean.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeBoolean(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Boolean.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeDate(val, [message], [template]) ⇒ this

Throws an error if 'val' is not of type Date.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeDate(val, [message], [template]) ⇒ this

Throws an error if 'val' is of type Date.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeRegExp(val, [message], [template]) ⇒ this

Throws an error if 'val' is not a Regular Expression.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeRegExp(val, [message], [template]) ⇒ this

Throws an error if 'val' is a Regular Expression.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeFalsey(val, [message], [template]) ⇒ this

Throws an error if 'val' is not falsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeFalsey(val, [message], [template]) ⇒ this

Throws an error if 'val' is falsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeFalsy(val, [message], [template]) ⇒ this

Synonym for shouldBeFalsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeFalsy(val, [message], [template]) ⇒ this

Synonym for shouldNotBeFalsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldBeTruthy(val, [message], [template]) ⇒ this

Synonym for shouldNotBeFalsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.shouldNotBeTruthy(val, [message], [template]) ⇒ this

Synonym for shouldBeFalsey.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
val String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.checkArgument(expression, [message], [template]) ⇒ this

Ensures the truth of an expression involving one or more parameters to the calling method.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.checkState(expression, [message], [template]) ⇒ this

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.checkElementIndex(index, size, [message], [template]) ⇒ this

Ensures that index specifies a valid element in an array, list or string of size size.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.checkPositionIndex(index, size, [message], [template]) ⇒ this

Ensures that index specifies a valid position in an array, list or string of size size.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

SingletonValidator.checkPositionIndexes(start, end, size, [message], [template]) ⇒ this

Ensures that start and end specify a valid positions in an array, list or string of size size, and are in order.

Kind: static method of SingletonValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
start Number
end Number
size Number
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

InstanceValidator

Validate values in a nested object using a dot notation structure (e.g. .shouldBeString("Person.Address.Street.zip")) System will validate the the Person, Person.Address, and Person.Address.Street objects exist, and will validate that zip is a String.

Use this interface if you want to utilize the following functionality:

  1. Nested object validation using a dot notation.

Kind: global class

new InstanceValidator(objectUnderTest)

Param Type Description
objectUnderTest Object Object to run validations against.

instanceValidator.shouldBeDefined(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is defined.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeUndefined(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not defined.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeNonEmptyArray(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not an array or is an empty array.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeArray(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is an array.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeArray(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not an array.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeObject(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type Object.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeObject(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type Object.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeEmpty(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not empty.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeEmpty(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is empty.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeFunction(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type Function.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeFunction(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type Function.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeString(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type String.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeString(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type String.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeNumber(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type Number.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeNumber(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type Number.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeFinite(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not finite.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeInfinite(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not infinte.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeBoolean(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type Boolean.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeBoolean(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type Boolean.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeDate(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not of type Date.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeDate(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is of type Date.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeRegExp(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not a Regular Expression.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeRegExp(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is a Regular Expression.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeFalsey(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is not falsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeFalsey(configPath, [message]) ⇒ this

Throws an error if any value does not exist in the objectToTest, from configPath. Throws an error if the last key from configPath is falsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeFalsy(configPath, [message]) ⇒ this

Synonym for shouldBeFalsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeFalsy(configPath, [message]) ⇒ this

Synonym for shouldNotBeFalsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldBeTruthy(configPath, [message]) ⇒ this

Synonym for shouldNotBeFalsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.shouldNotBeTruthy(configPath, [message]) ⇒ this

Synonym for shouldBeFalsey.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
configPath String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.checkArgument(expression, [message], [template]) ⇒ this

Ensures the truth of an expression involving one or more parameters to the calling method.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the validation fails.
[template] Array Template params. If provided, the error message will be generated using util.format(message, template).

instanceValidator.checkState(expression, [message]) ⇒ this

Ensures the truth of an expression involving the state of the calling InstanceValidator, but not involving any parameters to the calling method.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
expression String The value to validate.
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.checkElementIndex(index, size, [message]) ⇒ this

Ensures that index specifies a valid element in an array, list or string of size size.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.checkPositionIndex(index, size, [message]) ⇒ this

Ensures that index specifies a valid position in an array, list or string of size size.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
index Number
size Number
[message] String The error message or the error template string to use if the validation fails.

instanceValidator.checkPositionIndexes(start, end, size, [message]) ⇒ this

Ensures that start and end specify a valid positions in an array, list or string of size size, and are in order.

Kind: instance method of InstanceValidator
Returns: this - - Returns itself to allow chainable validations.

Param Type Description
start Number
end Number
size Number
[message] String The error message or the error template string to use if the validation fails.