Skip to content
Babel plugin for type checking based on JSDoc comments.
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.eslintignore
.eslintrc.js
.gitignore
.npmignore
CHANGELOG.md
LICENSE
README.md
gulpfile.js
package.json
preprocess.js

README.md

babel-plugin-jsdoc-type-checker

Babel plugin that generates a type checking code based on JSDoc comments in supported environments (configurable by supportedEnvironments option).

Example

This ES6 code:

/**
 * Class Foo.
 */
class Foo {
  /**
   * Returns the sum of x, y (optional).
   *
   * @typechecked
   * @param {number} x The first number.
   * @param {number} [y=0] The second number.
   * @return {number} The sum of x and y.
   */
  sum(x, y = 0) {
    return x + y;
  }
}

Will be transformed to:

/**
 * Class Foo.
 */
class Foo {
  /**
   * Returns the sum of x, y (optional).
   *
   * @typechecked
   * @param {number} x The first number.
   * @param {number} [y=0] The second number.
   * @return {number} The sum of x and y.
   */
  sum(x, y = 0) {
    if (typeof x !== 'number') {
      throw new TypeError('Argument x must be a number.');
    }
		
    if (y !== null && y !== undefined && typeof y !== 'number') {
      throw new TypeError('Argument y (optional) must be a number.');
    }

    return x + y;
  }
}

It transforms only ES6 class methods that have JSDoc comment blocks with @typechecked tag (configurable by checkerTag option) or are members of a class with a JSDoc comment block containing @typechecked tag.

The generated code is configurable by checkingTemplate option. A custom generated code can look like this:

/**
 * Class Foo.
 */
class Foo {
  /**
   * Returns the sum of x, y (optional).
   *
   * @typechecked
   * @param {number} x The first number.
   * @param {number} [y=0] The second number.
   * @return {number} The sum of x and y.
   */
  sum(x, y = 0) {
    invariant(!(typeof x !== 'number'), 'Argument x must be a number.');
    invariant(!(y !== null && y !== undefined && typeof y !== 'number'), 'Argument y (optional) must be a number.');
    return x + y;
  }
}

This generated code contains Facebook's invariant. You could generate a code that like this, if you set checkingTemplate option to `invariant(!(\${condition}), \${errorMessage});`.

It also supports @typedef tags.

Installation

npm install babel-plugin-jsdoc-type-checker --save-dev

Usage

CLI

$ browserify script.js -o bundle.js -t [ babelify --plugins [ babel-plugin-jsdoc-type-checker ] ]

Node

var fs = require('fs');
var browserify = require('browserify');
browserify('./script.js')
  .transform('babelify', { plugins: ['babel-plugin-jsdoc-type-checker'] })
  .bundle()
  .pipe(fs.createWriteStream('bundle.js'));

Options

checkerTag

string, defaults to 'typechecked'

The plugin generates a type checking code only in class methods with a JSDoc comment block that contain a tag that equals to this option's value.

checkingTemplate

string, defaults to `if (\${condition}) { throw new TypeError(\${errorMessage}); }`

This option determinates how the generated code looks like. Its value is an ES6 template string with some escaped placeholders:

  • \${condition} is a placeholder for a generated condition,
  • \${errorMessage} is a placeholder for a generated error message.

importTemplate

string, defaults to ''

The plugin generates an import statement automatically if you set this option, but only if an identical import statement is not present in the code. Example value: `import invariant from 'invariant';`

supportedEnvironments

string[], defaults to ['dev', 'development', 'test']

An array of environments in which the plugin generates a type checking code. If process.env.NODE_ENV equals to some of these items, the plugin will generate the code.

You can’t perform that action at this time.