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.
