node-jsat

J**avaScript **Annotation Transforms, or, js-@

Installation

npm install --save-dev jsat

Purpose

Empower your JSDoc annotations by transforming your JavaScript to actually enforce them.

Say you maintain a package on npm with a well documented API. You have an API method that you'd like to deprecate, so you annotate it in your JSDoc block.

/**
 * Add two numbers
 * @deprecated addTwoNumbers() will be removed in v2.0.0; please use add()
 */
exports.addTwoNumbers(firstNumber, secondNumber) {
    return firstNumber + secondNumber;
};

Awesome. Your documentation clear. But what if you wanted to actually make sure your users were aware of the upcoming breaking change? You could add a message in the function.

/**
 * Add two numbers
 * @deprecated addTwoNumbers() will be removed in v2.0.0; please use add()
 */
exports.addTwoNumbers(firstNumber, secondNumber) {
    console.warn('addTwoNumbers() will be removed in v2.0.0; please use add()');
    return firstNumber + secondNumber;
};

Better, but awfully repetitive. jsat solves this problem by reading your source code's JSDoc comment blocks and automatically adding helpful logic that assists in enforcing supported annotations.

Usage

var jsat = require('jsat');
var fs = require('fs');
var source = fs.readFileSync('path/to/sourcefile.js', 'utf8');
var output = jsat.transform(source);
fs.writeFileSync('path/to/outputfile.js', output);

Calling jsat.transform on the string containing your source code will do the following:

1. Parse source code into an abstract syntax tree (AST) using recast
2. Traverse the AST, looking for nodes containing supported annotations in their comment blocks
3. Transform annotated nodes using the included transformer template defined by each annotation type
4. Print the AST back to a string and return it

API

For documentation on jsat's API, please read the API Reference.

Examples

You can find example source and output files for these annotations in the examples directory.

Custom Annotations

In future releases, I hope to provide a robust API allowing developers to create their own custom annotation types and extract oft-repeated code snippets or control structures into jsat transformer templates.

Build Plugins

I will also be working on plugins to allow injecting jsat into existing build tools, such as grunt and gulp.

0.0.6 (April 5, 2015)

• Made console method called by @deprecated transform configurable (defaults to .trace)

0.0.5 (April 5, 2015)

• @deprecated transform now calls console.warn on all function calls
• Added ability to transform function declarations and object properties

0.0.4 (April 3, 2015)

• Added ability to configure jsat.transform with options
• Made @param transform more robust, accounting for missing annotations or annotations in the wrong order

0.0.3 (April 3, 2015)

• Added type-checking transform using @param annotation
• Added more tests

0.0.2 (April 2, 2015)

• Added support for single line JSDoc comments
• Fixed bugs in annotation detection
• Added unit tests for Annotation constructor

0.0.1 (April 1, 2015)

• Initial development release