Babel jsDoc runtime typecheck
Overview
This plugin will add runtime typecheck, based on jsDoc annotation. It transform code like this:
// from /** * @param * @returns * @typecheck */ { return a;} // to { ; return ;}
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
js code - global directive
// @typecheck /** * @param * @returns */ { return str + ' - ha-ha-ha!';}
js code - local directive
/** * @param * @returns * @typecheck */ { 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 * @returns */
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 * @param * @returns * @typecheck */ { return a + b + c;}
Result in console:
SyntaxError: input.js: [TYPECHECK STRICT MODE]: Function argument type annotation missing. 5 | * @typecheck 6 | */> 7 |
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 array -
Check 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 * @returns */ { return a;} /** * @param * @returns */let { return a;}; /** * @param * @returns */let { return a;}; /** * @param * @returns * In this case it will transform body to "{ return a; }" block */let a;
Object method
let myObject = /** * @param * @returns */ { return a; } /** * @param * @returns * Will use object field name as function name ("myField" here) */ { return a; }
Class constructor and method
/** * @param */ { this_a = a; } /** * @param * @returns */ { return a; } /** * @param * @returns */ static { return a; } /** * @param */ { this_a = a; } /** * @returns */ { return this_a; }