README.md

angularjs-to-es6

Converts AngularJS code into ES6 modules.

DISCLAIMER

This project is a WIP. Only use this on projects under version control. Use this software at your own risk. I will not be held accountable for any lost, changed, or deleted code.

Overview

Module Conversion

The following AngularJS code does not use ES6 modules.

// Pre-conversion: NON ES6 MODULE
angular.module("someModule").controller("SomeController", ['$scope', '$http',
	function($scope, $http) {
		$scope.someFunction = function() {
                    // ...
		};
	}]);

When processed by angularjs-to-es6, the code will be converted into an ES6 module:

// Post conversion: ES6 MODULE
SomeController.$inject = ['$scope', '$http'];
export function SomeController($scope, $http) {
    $scope.someFunction = function() {
        // ...
    };
}

Dependency Conversion

angularjs-to-es6 also keeps track of a module's local dependencies and will generate a corresponding angularJS module. If the angularJS module definition looked like this:

// Pre-conversion: app.js (or equivalent)
var app = angular.module('someModule', ['someDep1', 'someDep2']);

it would be converted to:

// Post-conversion: app.js
import someModule from "../someModule";

var app = angular.module(someModule);

and would generate SomeModule as:

// New conversion: someModule.module.js

import {someController} from "../someController"; 

export default angular.module('someModule', ['someDep1', 'someDep2'])
    .controller("someController", someController)
    .name;

Diff Viewer

After running the program, a diff will be shown for each change and you will be asked to approve each file. The diffs do not include whitespace changes and for the sake of easy diffing, the diff of the original will be reformatted the same as the new file.

How To

Setup

1. Clone project.
2. cd into project directory.
3. Run npm install

CLI Args

Getting help npm run start -- -h:

usage: app.js [-h] [--log-level {error,warn,info,debug}] [--output-dir OUTPUT_DIR] [--mirror] [--overwrite] [--exclude-dirs EXCLUDE_DIRS [EXCLUDE_DIRS ...]]
              [--module-methods {factory,controller,directive,service,provider,decorator,filter,config,run,module} [{factory,controller,directive,service,provider,decorator,filter,config,run,module} ...]]
              [--exclude-module-methods {factory,controller,directive,service,provider,decorator,filter,config,run,module} [{factory,controller,directive,service,provider,decorator,filter,config,run,module} ...]] [--no-verify] [--append APPEND]
              [--deps-output DEPS_OUTPUT] [--deps-input DEPS_INPUT] [-v]
              input

Converts AngularJS structures to ES6 modules.

positional arguments:
  input                 Input file or directory to convert.

optional arguments:
  -h, --help            show this help message and exit
  --log-level {error,warn,info,debug}
                        Set verbosity.
  --output-dir OUTPUT_DIR
                        Output directory. If you want to overwrite the files in place instead, see --overwrite.
  --mirror              Mirror input directory to output directory when generating files.
  --overwrite           Overwrite files in place
  --exclude-dirs EXCLUDE_DIRS [EXCLUDE_DIRS ...]
                        Fuzzy exclude directories.
  --module-methods {factory,controller,directive,service,provider,decorator,filter,config,run,module} [{factory,controller,directive,service,provider,decorator,filter,config,run,module} ...]
                        Angular module methods to include. Space separated. By default includes all.
  --exclude-module-methods {factory,controller,directive,service,provider,decorator,filter,config,run,module} [{factory,controller,directive,service,provider,decorator,filter,config,run,module} ...]
                        Angular module methods to exclude. Space separated.
  --no-verify           Disable verifying the changes for each file.
  --append APPEND       Append a string to each output file name.
  --deps-output DEPS_OUTPUT
                        Output directory for dependencies map.
  --deps-input DEPS_INPUT
                        Input dependencies file.
  -v, --version         Get version number`

Run

npm run start -- app.js --output-dir ./output_dir

The input app.js is your apps entry point, or whichever file contains the main module instantiation, e.g.:

var app = angular.module('someModule', ['someDep1', 'someDep2']);

Features

• Presents a confirmation diff before converting a file.
• Tracks angular module dependencies for generating angular modules in ES6 module format.

Bugs

• Comments outside of statements will not be retained. This is an issue with esprima/escodegen.

Shortcomings

• Only imports for local dependencies will be automatically generated. Installed libraries are not processed, so those imports will have to be manually added to the generated ES6 module.

TODO

Source

• Manually insert comments based off of range provided by esprima. This would allow for capturing all comments instead of using losing some with escodegen.
• Come up with a better name for "dependencies vs imports". Maybe moduleMembers and imports?
• Finding modules by looking for var app = angular.module('someModule') isn't good enough. Sometimes there's no variable assignment. Look into this.
• Add injection params for all modules, services, and controllers. Any param inside the function should be injected since the user might use strict-di. (was this already done?)
• Dependencies in app.config([]) need to be added. (was this done already?)
• Add imports for module dependency list (['someDep1', 'someDep2']). We don't look through libraries yet, which is why this isn't implemented. Maybe user specifies library files? Not sure.
  • In the meantime, maybe add a comment about manually adding these imports when they're detected.

Tests

• Instead of relying on direct text comparison in tests, try comparing stringified asts. That way order doesn't have to be specified with something like imports
• Add test for chained angular module types.
• You can't have two "defaults" in a file, e.g., "export default..." (was this fixed already?)