doctyr v0.0.6-b

doctyr v0.0.6b

DOCument, TYpe, Runtime - Runtime type checking and document generation for JavaScript.

doctyr supports runtime type checking and documentation generation for JavaScript functions and return values. Types can be directly specified or infered from default arguments. Type checking can go beyond basic types and includes support for instanceof checks and custom validation functions.

The API has been designed with simplicity in mind.

1) Primitive and complex object type checking can be accomplished without learning a schema system.

3) Re-writing existing code is not required.

3) Types can be infered from default arguments.

4) Any boolean functions from existing libraries or custom written ones can be used to check types.

5) Using the live documentation facility is completely optional and incurs no compute or substative memory overhead if no documentation for functions is provided.

6) The type checking can be optionally included or excluded from production builds and dynamically turned on and off.

Installation

npm install doctyr

There are browser based files in the browser sub-directory.

Basic Usage

The call signature for doctyr is (function,thisType,[argType[,...]],returnType). That is a function followed by an array, the first element of which is the type of the this argument, an array of types of the arguments, and a final arguments that is the type of the return value.

The type specifications can be undefined, strings, objects, or instances of doctyr.spec. If the value undefined is used, then the type is unconstrained. See API section for more detail.

You can use multiple coding styles to take advantage of doctyr including:

Direct function defintion, e.g.

const myFunction = doctyr(function(arg1) { ...; return arg1; },undefined,["string"],"string");

Re-defining functions by assigning a return value, e.g.

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,["string"],"string"); // this could be done conditionally for non-production

Re-writing functions to include guard calls and return conform checks, e.g.

function myFunction(arg1) {
	const returns = doctyr.guard(this,myFunction,[undefined,"string","string"]);
	... // your code that assigns something to returnValue
	return doctyr.conforms(returnValue,returns);
}

Type Inference

You can rely on default arguments to determine the types. Both the below allow any type for this and return value, but constrain the argument to a string.

function myFunction(arg1="myArg") { ...; return arg1; }

myFunction = doctyr(func);

function myFunction(arg1="myArg") {
	doctyr.guard(this,myFunction,arguments);
	... // your code
	return doctyr.conforms(arg1,"string");
}

Test Functions and Instances

You can provide functions to do type checks, e.g. ensure a value is even

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[value => value % 2 ===0]); 

If the function is a constructor, then the check will be satisfied if the argument is an object that satisfies instanceof, e.g. ensure an argument is an instanceof a Date:

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[Date]); 

Polymorphic Values

Polymorphic arguments and return values are supported through the use of an array to contain the types. The example below will allow a string or number as the function argument:

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[["string","number"]],"string");

Complex Objects

Complex object type checking just requires the provision of an object having the expected surface with property values being types. The example below ensures that the argument has a name property with a value of type string, an age property with a value of type number, and an address that is either undefined or an instanceof Object, i.e. it is optional. The below ensure the argument has a string name property, and age number sproperty, and an optional address that if provided is an instance of an Object.

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(func,undefined,[{name:"string",age:"number",address:[undefined,Object]}]);

Code As Documentation

By using doctyr.spec(config) instead on primitive values, you can add documentation to your code for runtime generation, e.g.

function myFunction(arg1) { ...; return arg1; }

myFunction = doctyr(myFunction,doctyr.spec({type:undefined,doc:{description:"No 'this' context is expected."}}),
						["string"],
						doctyr.spec({type:"string",doc:{description:"The original string argument is returned."}}));
							
const html = doctyr.toHTML(myFunction);

will return HTML that renders as:

Turning doctyr off

Just set doctyr.on = false.

Developed and Tested With

Eclipse, Mocha, Chai, and Browserstack.

Release History (reverse chronological order)

2018-11-14 v0.0.6b Synchronized version numbers.

2018-11-14 v0.0.5b Reintroduced HTML generation.

2018-11-13 v0.0.4b Removed JavaScript parser and changed API to dramatically simplify. HTML generation temporarily removed.

2018-08-12 v0.0.3b Documentation updates.

2018-08-12 v0.0.2b Documentation updates.

2018-08-11 v0.0.1b First public release.

License

MIT License

Copyright (c) 2018 Simon Y. Blackwell, AnyWhichWay, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.