GRAPHISOFT/jsdoc-to-assert

JSDoc to assert

jsdoc-to-assert

Convert JSDoc to assert that runtime assert.

Easy to use it with Babel.

• azu/babel-plugin-jsdoc-to-assert: Babel plugin for jsdoc-to-assert.

Example

jsdoc-to-assert create detection expression string:

Array.isArray(x) && x.every(function (item) {
    return typeof item === 'number';
});

from following JSDoc comment:

/**
 * @param {number[]} x 
 */

Installation

npm install jsdoc-to-assert

Usage

import {AssertGenerator, CommentConverter, CodeGenerator} from "jsdoc-to-assert";

AssertGenerator class

Create assertion AST from comment nodes.

/**
 * @typedef {Object} AssertGeneratorOptions
 * @property {Function} generator
 */
const defaultOptions = {
    Generator: CodeGenerator
};
/**
 *
 * @param {Array<Object>} comments AST's comment nodes. it should be BlockComment
 * @param {AssertGeneratorOptions} options
 * @returns {Array<String>} array of assertion
 */
static createAsserts(comments, options = {});
/**
 * @param tagNode tagNode is defined by doctorin
 * @param {CodeGenerator} Generator
 * @return {string|undefined} return assertion code string
 * Reference https://esdoc.org/tags.html#type-syntax
 * https://github.com/eslint/doctrine/blob/master/test/parse.js
 */
static createAssertFromTag(tagNode, Generator = CodeGenerator);

CommentConverter class

/**
 * Parse comment nodes which is provided by JavaScript parser like esprima, babylon 
 * and return assertions code strings.
 * This is mutable function.
 * @param {Array<Object>} comment
 * @param {AssertGeneratorOptions} [options]
 * @returns {string[]}
 */
static toAsserts(comment, options);    

CodeGenerator class

Assertion code generator class

/**
 * @param commentTagNode commentTagNode is doctrine tag node
 */
constructor(commentTagNode);
/**
 * wrap assert function
 * @param {string} expression
 * @returns {string}
 */
assert(expression) {
    return `console.assert(${expression},'${expression}');`;
}

Tests

npm test

Realated

• FlowType: codemix/babel-plugin-typecheck: Static and runtime type checking for JavaScript in the form of a Babel plugin.
• TypeScript: Proposal: Run-time Type Checks · Issue #7607 · Microsoft/TypeScript

Comment to assert

• azu/comment-to-assert: convert single line comment to assert.
• azu/power-doctest: JavaScript: doctest + power-assert.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

License

MIT