Type checking

Since version 1.2 Cerny.js provides a mechanism to specify the signature of function. This improves code quality by having the signature documented. Additionally it opens up the possibility that during runtime the signature of a function being called is checked via Interception. This document shows us how to use this feature.

Specifying the signature of a function

To specify the signature of a function we must call the CERNY.signature function. The first argument must be the function on which the signature is specified. The second one is the type of the return value. Beginning with the third argument the types of the parameters are given. Let's have a look at the following example.

function parseIsoDate(isoDateString) { // Do what's necessary to parse the date out of isoDateString return parsedDate; } CERNY.signature(parseIsoDate, Date, "string");

This example defines a function parseIsoDate which takes one parameter of type string and returns a Date. The implementation of the function is left out, because it contributes nothing to the purpose of the example.

The type of a parameter or the return value can be either a function or a string. In case of a function the value is tested with instanceof against the type. If the type is specified as a string the list of meaningful values is: boolean, function, number, object, string, undefined, null or any. The last value any means that no type check will be performed, any value is permitted.

To make things more flexible any combination of types can be put in an array and be used as a compound type. In the next example a search function accepts either a primitive string or an object of type RegExp as its parameter and returns an Array.

CERNY.signature(someSearch, Array, ["string", RegExp]);

If a function might return null, it must be explicitly declared in the signature. If the author of parseIsoDate chooses to return null instead of throwing an exception (if the string cannot be parsed into a Date), he must declare the signature like this:

CERNY.signature(parseIsoDate, ["null", Date], "string");

If a function call has more arguments than parameters declared in the signature, all arguments that exceed the signature are checked against the type of the last parameter.

Activating type checking

Type checking is based on the interception mechanism. To activate it, we configure the Cerny.js library. In particular we must push the TypeChecker interceptor on the array of active interceptors. Here is the fragment of the cerny.conf.js.

CERNY.configure = function() { var active = CERNY.Configuration.Interception.active; active.push(CERNY.Interceptors.LogIndenter); active.push(CERNY.Interceptors.TypeChecker); };

To make a method subject of interception, one must either use the CERNY.method function to attach the method to it's object or call CERNY.intercept on the object after all methods have been assigned. Only then, type checking will be performed.

Type errors are reported to the logger on the FATAL level. In order to see these messages, logging must be configured accordingly.

Once the TypeChecker is activated, the log level is set and our methods are subject to interception, the signature of function will be checked on calls and type errors will be reported. Here is a sample output:

1173824346796, FATAL: arg 0: Type error: Tue Mar 13 2007 23:19:06 GMT+0100 (object) should be of type string | NONE

When to use type checking

Type checking is a mechanism, that will simplify the development of JavaScript projects in large teams. It improves the communication between the author and the consumer of a function. With the help of the signature the consumer will receive additional information on how to use the function. The type checking put in place will inform the consumer early about errors he made in using the function. Type checking should always be activated during development and the team members will benefit from it. During production it can be deactivated.

API Documentation for version