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 = 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:
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 also provides negative assertions to match the above:
Results
You can handle the results of your assertions in two different
ways. Firstly, the unchainable passes
method:
// true // false
Secondly, the error
method can be used to throw when the test
does not pass:
// doesn't throw // throws a new `Error` with the passed in string as a message // 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.
all // trueall // false // true // 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:
otherwiseandor
Example
Here's an example of Pledge in use!
{ otherwise; orotherwise; 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.