babel-plugin-jsdoc-runtime-typecheck
v1.2.1
Published
Babel plugin, that adds typecheck, based on jsDoc.
Downloads
29
Maintainers
Readme
#Babel jsDoc runtime typecheck
Overview
This plugin will add runtime typecheck, based on jsDoc annotation. It transform code like this:
// from
/**
* @param {Number} a
* @returns {Number}
* @typecheck
*/
function test(a) {
return a;
}
// to
function test(a) {
__executeTypeCheck__('test', 'a', a, 'Number');
return __executeTypeCheck__('test', 'return', a, 'Number');
}
Result:
CAUTION: Use this plugin only in development, it will slow down your code (a lot of additional function calls and large helper function).
Motivation
Flow is good solution, but it adds custom syntax to javascript code and adding it to existing project is quite hard. IDE's like Webstorm has good support of jsDoc and can add cool code completion tips, based on users comments. So, with this plugin, you can easy start to use benefits of strong typing in javascript code without any pain. Using this plugin in development also will speed up development, because it will reduce number of weird errors and behaviors.
How to
Install
npm install babel-plugin-jsdoc-runtime-typecheck --save-dev
Use
.babelrc
{
"plugins": ["jsdoc-runtime-typecheck"]
}
js code - global directive
// @typecheck
/**
* @param {String} str
* @returns {String}
*/
function makeMeLaugh(str) {
return str + ' - ha-ha-ha!';
}
js code - local directive
/**
* @param {String} str
* @returns {String}
* @typecheck
*/
function makeMeLaugh(str) {
return str + ' - ha-ha-ha!';
}
Configure
useDirective
By default, plugin will only parse docs with special directive @typecheck
, you can change it like this:
{
"plugins": [
["jsdoc-runtime-typecheck",
{
//useDirective: 'typecheck' - this is default
//useDirective: false - if you want to check all functions with jsDoc (useful for new projects)
useDirective: 'makeMeHappy' - your custom directive
}
]
]
}
Then, use it:
// @makeMeHappy
// or
/**
* @makeMeHappy
* @param {Number} a
* @returns {Number}
*/
useStrict
You can enable strict mode - in this mode plugin throw compilation exception when it can find error by static analyze.
Setup:
{
"plugins": [
["jsdoc-runtime-typecheck",
{
//useStrict: false - default
useStrict: true
}
]
]
}
Use:
Code:
/**
* @param {Number} a
* @param {Number} b
* @returns {Number}
* @typecheck
*/
function test(a, b, c) {
return a + b + c;
}
Result in console:
SyntaxError: input.js: [TYPECHECK STRICT MODE]: Function argument type annotation missing.
5 | * @typecheck
6 | */
> 7 | function test(a, b, c) {
| ^
8 | return a + b + c;
9 | }
10 |
Supports:
jsDoc tags
@params
can be optional, supported declarations:@param {*} name
- no check@param {Number=} name
- optional@param {Number} [name]
- optional@param {?Number} name
@param {!Number} name
@param {Number|String} id
@param {Array<Number>} collection
- check every item in arrayCheck defined keys in Object:
@param {Object} data @param {Number} data.id @param {String} data.name //or @param {{id: Number, name: String}} data
@param {function(Array<Number>)} name
- check type of function
@returns
or@return
- type annotation are same as in params.
Language constructions
Function declaration
/**
* @param {Number} a
* @returns {Number}
*/
function myDeclaredFunction(a) {
return a;
}
/**
* @param {Number} a
* @returns {Number}
*/
let myExpressionFunction = function(a) {
return a;
};
/**
* @param {Number} a
* @returns {Number}
*/
let myArrowFunction = (a) => {
return a;
};
/**
* @param {Number} a
* @returns {Number}
* In this case it will transform body to "{ return a; }" block
*/
let myArrowExpressionFunction = (a) => a;
Object method
let myObject = {
/**
* @param {Number} a
* @returns {Number}
*/
myMethod(a) {
return a;
},
/**
* @param {Number} a
* @returns {Number}
* Will use object field name as function name ("myField" here)
*/
myField: function(a) {
return a;
}
}
Class constructor and method
class MyClass {
/**
* @param {Number} a
*/
constructor(a) {
this._a = a;
}
/**
* @param {Number} a
* @returns {Number}
*/
myMethod(a) {
return a;
}
/**
* @param {Number} a
* @returns {Number}
*/
static myStaticMethod(a) {
return a;
}
/**
* @param {Number} a
*/
set a(a) {
this._a = a;
}
/**
* @returns {Number} a
*/
get a() {
return this._a;
}
}