Agree: Contract programming for JavaScript

Agree is a library for implementing Contract Programming / Design by contract in JavaScript, including preconditions, postconditions and class invariants.

It is inspired by projects like contracts.coffee, but requires no build steps, no non-standard language features, and is introspectable.

Status

Experimental as of November 2016.

• Functions, method and class invariants work
• Support for asyncronous functions using Promise (ES6/A+ compatible)
• Contracts can be reusable, and used to define interfaces (having multiple implementations)
• Some proof-of-concept documentation and testing tools exists
• Library has not been used in any real applications yet

TODO 0.1 "minimally useful"

• Lock down the core contracts API
• Add more tests for core functionality
• Do use-case exploration of a browser/frontend example
• Remove CoffeeScript as run-time dependency
• Setup build automated tests for browser
• Stabilize and document the testing and documentation tools

Future

• Add support for more types of invariants, including on properties

For details see TODO/FIXME/XXX/MAYBE comments in the code.

Installing

Add Agree to your project using NPM

npm install --save agree
npm install --save-dev agree-tools

License

MIT, see LICENSE.md

Examples

HTTP server

See the tests under ./spec/ for full reference.

Tools

agree-tools uses the introspection features of Agree to provide support for testing and documentation, driven by the contracts/code.

Goals

• No special dependencies, works anywhere (browser, node.js, etc), usable as library
• That contracts are used is completely transparent to consuming code
• Can start using contracts stepwise, starting with just some functions/methods
• JavaScript-friendly fluent API (even if written with CoffeeScript)
• Preconditions can, and are encouraged to, be used for input validation

Usecases

• HTTP REST apis: specifying behavior, validating request, consistent error handling
• NoFlo components: verifying data on inports, specifying component behavior
• Interfaces: multiple implementations of same interface fully described

Introspection

Functions, classes and instances built with Agree know their associated contracts. This allows to query the code about its properties, to generate documentation, test-cases and aid in debugging of failures.

Agree is partially related other work by author on introspectable programming, including Finito (finite state machines) and NoFlo/MicroFlo (dataflow).