This package has been deprecated

    Author message:

    This module is no longer maintained. If you're interested in taking over maintenance of this repo, please contact the author

    pledge

    0.2.0 • Public • Published

    Pledge

    Pledge is a pretty little argument validation library for your browser and server. It has a simple and expressive syntax which makes validating variables and arguments an enjoyable task!

    Installation

    Browser
    To use pledge in your browser, copy/link to dist/pledge.js or dist/pledge.min.js and start using. Pledge will work fine if you use a dependency manager like Browserify too.

    Server (Node.js):
    Just install with npm install pledge or add it to your package.json.

    Usage

    Pledge exposes a function which can be used to validate arguments and optionally error if the validation fails. It's useful for testing input sanity.

    You can use pledge with Node.js (JavaScript or CoffeeScript):

    var pledge = require('pledge').pledge;
    {pledge} = require 'pledge'

    or in-browser the pledge function is exposed as window.pledge.

    Pledge Function

    The pledge function can be called with any argument, the argument being the subject of the test:

    pledge('foo')
    pledge(123)
    pledge([1, 2, 3])

    This function returns a Test object.

    Assertions

    The test object has many assertion methods which are chainable, use these to assert that the test subject fits within certain parameters:

    pledge([]).isArray()
    pledge(true).isBoolean()
    pledge(Date).isFunction()
    pledge(null).isNull()
    pledge(123).isNumber()
    pledge({}).isObject()
    pledge('foo').isString()
    pledge(undefined).isUndefined()
    pledge(new Date()).isInstanceOf(Date)

    Pledge also provides negative assertions to match the above:

    pledge(123).isNotArray()
    pledge('foo').isNotBoolean()
    pledge({}).isNotFunction()
    pledge([]).isNotNull()
    pledge(Date).isNotNumber()
    pledge(true).isNotObject()
    pledge(undefined).isNotString()
    pledge(new Date()).isDefined()
    pledge(null).isNotInstanceOf(Date)

    Results

    You can handle the results of your assertions in two different ways. Firstly, the unchainable passes method:

    pledge('foo').isString().passes() // true
    pledge(123).isString().passes() // false

    Secondly, the error method can be used to throw when the test does not pass:

    pledge('foo').isString().error('Not a string!') // doesn't throw
    pledge(123).isString().error('Not a string!') // throws a new `Error` with the passed in string as a message
    pledge(123).isString().error(new Error('Oops')) // throws the error passed into the method

    Logic Modes

    For multiple assertions, pledge supports and and or logic modes. These can be set with the methods all or either, called before any assertions.

    pledge('foo').all().isDefined().isString().passes() // true
    pledge('foo').all().isNumber().isString().passes() // false
    pledge('foo').either().isNumber().isString().passes() // true
    pledge('foo').either().isArray().isObject().passes() // false

    It's worth noting that all is the default logic mode, so there's not often a need to add this.

    Sugar

    Pledge provides a little (optional) sugar with a couple of properties that just alias the pledge object, and, or and otherwise. You can use them like this:

    pledge('foo').isString().otherwise.error('Oops')
    pledge('foo').isString().and.isDefined()
    pledge('foo').either().isNumber().or.isString()

    Example

    Here's an example of Pledge in use!

    function createPerson (name, age) {
        pledge(name).isString().otherwise.error('Invalid name, string expected');
        pledge(age).either().isNumber().or.isNull().otherwise.error('Invalid age, number or null expected');
        return {name: name, age: age};
    }

    Development

    In order to develop Pledge, you'll need to install the following npm modules globally like so:

    npm install -g coffee-script
    npm install -g jake
    

    And then install development dependencies locally with:

    npm install
    

    Once you have these dependencies, you will be able to run the following commands:

    jake build: Build JavaScript from the CoffeeScript source.

    jake dist: Build browser JavaScript from the built JavaScript.

    jake functional: Run all functional tests.

    jake lint: Lint all CoffeeScript source with CoffeeLint.

    jake test: Run all unit tests.

    License

    Dual licensed under the MIT or GPL Version 2 licenses.

    Keywords

    none

    Install

    npm i pledge

    DownloadsWeekly Downloads

    3

    Version

    0.2.0

    License

    none

    Last publish

    Collaborators

    • rowanmanning