Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/olov/defs

Static scope analysis and transpilation of ES6 block scoped const and let variables to ES3 vars
https://github.com/olov/defs

Last synced: about 1 month ago
JSON representation

Static scope analysis and transpilation of ES6 block scoped const and let variables to ES3 vars

Awesome Lists containing this project

README 

        
# SO LONG AND THANKS FOR ALL THE BITS

**defs is done. I recommend migrating to the TypeScript `tsc` compiler because

it does what defs does as good or better, and it does much more.**



# defs.js

Static scope analysis and transpilation of ES6 block scoped `const` and `let`

variables, to ES3.



Node already supports `const` and `let` so you can use that today

(run `node --harmony` and `"use strict"`). `defs.js` enables you to do the same

for browser code. While developing you can rely on the experimental support

in Chrome (chrome://flags, check Enable experimental JavaScript). `defs.js` is

also a pretty decent static scope analyzer/linter.



The talk

[LET's CONST together, right now (with ES3)](http://vimeo.com/66501924)

from Front-Trends 2013

([slides](http://blog.lassus.se/files/lets_const_together_ft2013.pdf)) includes

more information about `let`, `const` and `defs.js`. See also the blog post

[ES3 <3 block scoped const and let => defs.js](http://blog.lassus.se/2013/05/defsjs.html).



## Installation and usage

    npm install -g defs



Then run it as `defs file.js`. The errors (if any) will go to stderr,

the transpiled source to `stdout`, so redirect it like `defs file.js > output.js`.

More command line options are coming.



There's also a [Grunt](http://gruntjs.com/) plugin, see [grunt-defs](https://npmjs.org/package/grunt-defs).



See [BUILD.md](BUILD.md) for a description of the self-build and the browser bundle.



## License

`MIT`, see [LICENSE](LICENSE) file.



## Changes

See [CHANGES.md](CHANGES.md).



## Configuration

`defs` looks for a `defs-config.json` configuration file in your current

directory. If not found there, it searches parent directories until it hits `/`.

You may instead pass a custom `defs-config.json` using `--config`, i.e.

`defs --config path/to/defs-config.json file.js > output.js`.



Example `defs-config.json`:



    {

        "environments": ["node", "browser"],



        "globals": {

            "my": false,

            "hat": true

        },

        "loopClosures": "iife",

        "disallowVars": false,

        "disallowDuplicated": true,

        "disallowUnknownReferences": true

    }



`globals` lets you list your program's globals, and indicate whether they are

writable (`true`) or read-only (`false`), just like `jshint`.



`environments` lets you import a set of pre-defined globals, here `node` and

`browser`. These default environments are borrowed from `jshint` (see

[jshint_globals/vars.js](https://github.com/olov/defs/blob/master/jshint_globals/vars.js)).



`loopClosures` (defaults to `false`) can be set to "iife" to enable transformation

of loop-closures via immediately-invoked function expressions.



`disallowVars` (defaults to `false`) can be enabled to make

usage of `var` an error.



`disallowDuplicated` (defaults to `true`) errors on duplicated

`var` definitions in the same function scope.



`disallowUnknownReferences` (defaults to `true`) errors on references to

unknown global variables.



`ast` (defaults to `false`) produces an AST instead of source code

(experimental).



`stats` (defaults to `false`) prints const/let statistics and renames

(experimental).



`parse` (defaults to `null`) lets you provide a custom parse function if you

use defs as an API. By default it will use `require("esprima").parse`.



## Example



Input `example.js`:



```javascript

"use strict";

function fn() {

    const y = 0;

    for (let x = 0; x < 10; x++) {

        const y = x * 2;

        const z = y;

    }

    console.log(y); // prints 0

}

fn();

```



Output from running `defs example.js`:



```javascript

"use strict";

function fn() {

    var y = 0;

    for (var x = 0; x < 10; x++) {

        var y$0 = x * 2;

        var z = y$0;

    }

    console.log(y); // prints 0

}

fn();

```



## defs.js used as a library

`npm install defs`, then:



```javascript

const defs = require("defs");

const options = {};

const src = "const x = 1";

const res = defs(src, options);

assert(res.src === "var x = 1");



// you can also pass an AST (with loc and range) instead of a string to defs

const ast = require("esprima").parse(src, {loc: true, range: true});

const res = defs(ast, {ast: true}); // AST-in, AST-out

// inspect res.ast

```



res object:



    {

        src: string // on success

        errors: array of error messages // on errors

        stats: statistics object (toStringable)

        ast: transformed ast // when options.ast is set

    }



## Compatibility

`defs.js` strives to transpile your program as true to ES6 block scope semantics as

possible while being as maximally non-intrusive as possible.



It can optionally transform loop closures via IIFE's (when possible), if you include

`"loopClosures": "iife"` in your `defs-config.json`. More info in

[loop-closures.md](loop-closures.md).



See [semantic-differences.md](semantic-differences.md) for other minor differences.