Call by Contract (CbC) JavaScript library

Posted on 11.03.12

0



The Call by Contract (CbC) JavaScript library is a Design by Contract (DbC) JavaScript implementation. Here is the definition of Design by Contract at Wikipedia:

Design by contract (DbC), also known as contract programming, programming by contract and design-by-contract programming, is an approach for designing software. It prescribes that software designers should define formal, precise and verifiable interface specifications for software components, which extend the ordinary definition of abstract data types with preconditions, postconditions and invariants. …

http://en.wikipedia.org/wiki/Design_by_contract

At the moment Call by Contract implements preconditions. Before we go into details about these preconditions lets have a look at the motivation behind CbC.

JavaScript parameter assertions

You have this API level function f:

function f (a) {
}

You would like to assert that the parameter a is always specified, that arguments are not null and allways of type String. To be able to create very specific error messages, which may be important in an API level function, you would have to do something like this:

function f (a) {
    if (typeof a === "undefined") {
        throw new Error("Parameter a must be specified. ");
    }
    if (a === null) {
        throw new Error("Parameter a must not be null.");
    }
    if (typeof a !== "string") {
        throw new Error("Parameter a must be of type string.");
    }
}

This is pretty verbose, and it gets even worse if you have more than one parameter. The assertion functionality in the cbc.assert CbC namespace was created to make it more convenient to do parameter assertions. Here are the same assertions using CbC assert that produces the exact same error messages:

function f (a) {
    cbc.assert.param("a", a).is.defined().and.notNull().and.string();
}

This is more convenient, but we can do better with a JavaScript DbC precondition implementation. But first let’s have a look at Visual Studio JavaScript doc comments.

Visual Studio JavaScript doc comments

With Visual Studio JavaScript doc comments you get JavaScript IntelliSense. Let’s decorate the f function with doc comments:

A function’s toString method returns the function’s source code. That means that we have access to all the doc comments at runtime. The cbc.parse.func function takes advantage of this and makes it easy to get at this information. Here is a sample:

Note that based on the information specified in the doc comment, we also know what kind of assertions we should apply.

Call by Contract precondition implementation

The definition of a precondition at Wikipedia is:

In computer programming, a precondition is a condition or predicate that must always be true just prior to the execution of some section of code or before an operation in a formal specification.

If a precondition is violated, the effect of the section of code becomes undefined and thus may or may not carry out its intended work. Security problems can arise due to incorrect preconditions.

Often, preconditions are simply included in the documentation of the affected section of code. Preconditions are sometimes tested using assertions within the code itself, and some languages have specific syntactic constructions for doing so.

http://en.wikipedia.org/wiki/Precondition

The CbC implementation of the precondition uses doc comments to create a wrapper function that is executed just prior to the execution of a wrapped function. The parameter constraints found in the doc comments, using cbc.parse.func, are asserted using cbc.assert assertions. Here is a sample of usage:

The wrapper function is created dynamically. In this case the wrapper function source code is:

The function func, which is a reference to the wrapped f function, is part of the wrapper function’s closure.

Here is a greater sample on how to use cbc.contract.wrap:

Note that a minified version of your scripts will not contain doc comments. Then cbc.contract.wrap does not create a wrapper, it just returns the function it is supposed to wrap. That means no side effects when you have a production version. Great for performance.

Summary

Basically you get function parameter assertions for free with CbC. You just have to specify Visual Studio JavaScript doc comments and wrap your functions with cbc.contract.wrap.

Links

Advertisements
Tagged:
Posted in: Uncategorized