Update meta & prepare npm publish

Author: theseanl

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.npmignore

@@ -0,0 +1,3 @@
+node_modules
+src
+index.ts

README.md

@@ -0,0 +1,122 @@
+# Closure Tools Helper
+
+This module contains closure tools compiled `jar`s and various helper function to make dependency management easier.
+
+This module exports 4 functions:
+```js
+const closureTools = require('closure-tools-helper');
+
+closureTools.compiler(...);
+closureTools.templates(...);
+closureTools.stylesheets(...);
+closuretools.extractTemplateMsg(...);
+```
+
+## Closure Compiler api
+
+The closure compiler api abstracts the module system of closure compiler to something based on entry points, much similar to rollup.
+
+```js
+(await closureTools.compiler(baseCompilerFlags, sourceGlob, entryPoints)).src()
+    .pipe(...)
+```
+Note the requirements of `await`, due to building compiler flag being an async operation.
+The plugin controls `--module` and `-js` compiler flags. All the other flags must be provided with `baseCompilerFlags` argument.
+
+`sourceGlob` is a glob pattern that provides js sources to the compiler. All files referenced by entryPoints must be provided by the glob.
+
+`entryPoints` is an array where each element follows the below interface.
+```ts
+interface ICompilerEntryPoint {
+    /**
+     * This is what is used in `goog.require()`.
+     * `null` means there is no entry module, but it can have some extraSources.
+     */
+    id:string|null,
+    /**
+     * module name, used in specifying dependencies, and also used in output file name.
+     */
+    name:string,
+    /**
+     * Array of module names that this bundle depends on.
+     */
+    deps:string[],
+    /**
+     * Any files that are not reachable via `goog.require`s but still need to be provided
+     * to the compiler.
+     */
+    extraSources?:string[]
+}
+```
+
+
+## Closure Templates api
+
+```js
+const compiler = require('closure-tools-helper');
+
+gulp.task('build-soy', () => {
+    return compiler.templates([.../* Command line args passed to SoyToJsSrcCompiler.jar */])
+        .src()
+        .pipe(gulp.dest('build'));
+});
+
+gulp.task('extract-soy-messages', () => {
+    return compiler.extractTemplateMsg([.../* Command line args passed to SoyMsgExtractor.jar */])
+        .src();
+});
+```
+
+Compiler apis returns a readable stream of the stdout. Users of the package should explicitly call `.src()` in order to turn the stream into flowing mode (same as `google-closure-compiler` gulp plugin).
+
+### Runtime i18n
+
+Closure templates by default supports compile-time i18n. Provide a second argument `TemplatesI18nOptions` to post-process js files generated by soy compiler to enable i18n. Its interface is what follows:
+```ts
+interface ITemplatesI18nOptions {
+    /**
+     * This is a string to replace `goog.getMsg` with.
+     */
+    googGetMsg:string
+    /**
+     * This is a string that will be appended right after the `goog.module(..)` expression.
+     */
+    header?:string
+    /**
+     * This must match files generated by the compiler jar.
+     */
+    inputGlob:string|string[]
+    outputPath?:string // If provided, files will be written to `outputPath/fileName`.
+}
+```
+
+If runtime i18n is enabled, it will additionally transform legacy-style `goog.provide` modules into [`goog.module`](https://github.com/google/closure-library/wiki/goog.module:-an-ES6-module-like-alternative-to-goog.provide), so that a consumer can import the compiled templates by using `const templates = goog.require('namespace.to.the.template')`, or `import templates from 'goog:namespace.to.the.template'` if the consumer is using [tsickle](https://github.com/angular/tsickle).
+
+## SoyUtils
+
+Import or reference `./third-party/soyutils.js` or `./third-party/soyutils_usegoog.js`.
+
+## Closure Stylesheets api
+
+```js
+const compiler = require('closure-tools-helper');
+
+gulp.task('build-gss', () => {
+    return compiler.stylesheets([.../* Command line args passed to closure-stylesheets.jar */])
+        .src()
+})
+```
+
+Compiler apis returns a readable stream of the stdout. User of the package should explicitly call `.src()` to turn the stream into a flowing mode.
+
+## Installation
+
+```
+yarn add https://github.com/seanl-adg/closure-tools-helper.git
+yarn add https://github.com/seanl-adg/closure-tools-helper.git#<specific-tag>
+```
+
+## Build
+```
+tsc
+```

closure_library_deps.json

@@ -0,0 +1,46 @@
+{
+  "name": "closure-tools-helper",
+  "description": "Provides utility functionalities to call closure tools in nodejs.",
+  "keywords": [
+    "closure-library",
+    "closure-compiler",
+    "closure-stylesheets",
+    "closure-templates"
+  ],
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "LGPL",
+  "author": {
+    "name": "theseanl",
+    "email": "i73hi64d0wr5df8pckig@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theseanl/closure-tools-helper.git"
+  },
+  "homepage": "https://github.com/theseanl/closure-tools-helper",
+  "bugs": {
+    "url": "https://github.com/theseanl/closure-tools-helper/issues"
+  },
+  "scripts": {
+    "distill": "ts-node script/build_closure_deps.ts"
+  },
+  "dependencies": {
+    "closure-library.ts": "^1.0.0",
+    "esprima": "^4.0.0",
+    "estraverse": "^4.2.0",
+    "fancy-log": "^1.3.2",
+    "fast-glob": "^2.1.0",
+    "fs-extra": "^5.0.0",
+    "google-closure-compiler": "^20180610.0.2",
+    "google-closure-library": "20180506.0.0",
+    "vinyl": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^9.4.6",
+    "@types/vinyl": "^2.0.2",
+    "ts-node": "^7.0.0",
+    "typescript": "^2.9.2"
+  }
+}

package.json

@@ -0,0 +1,14 @@
+import DepsSorter from '../src/DepsSorter';
+import log = require('fancy-log');
+
+async function main() {
+    try {
+        await DepsSorter.distillClosureDeps();
+    } catch(e) {
+        log.error(e);
+        process.exit(1);        
+    }
+    process.exit(0);
+}
+
+main();

script/build_closure_deps.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations to call soyutils functions from TS to be closure compiled.
+ * 
+ * Currently this only contains limited declarations that are being used.
+ * @todo Use clutz https://github.com/angular/clutz to generate `.d.ts` from
+ * soyutils_usegoog.js.
+ */
+
+declare module 'goog:soydata.VERY_UNSAFE' {
+    namespace soydata.VERY_UNSAFE {
+        export function ordainSanitizedHtml(str:string):any
+        export function ordainSanitizedJs(str:string):any
+        export function ordainSanitizedJsStrChars(str:string):any
+        export function ordainSanitizedUri(str:string):any
+        export function ordainSanitizedHtmlAttribute(str:string):any
+        export function ordainSanitizedCss(str:string):any
+    }
+    export default soydata.VERY_UNSAFE;
+}

soyutils.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview It spawn a java process with provided arguments, and pipes stdout to
+ * a stream that can be used with gulp plugins.
+ * This is based on gulp plugin of google-closure-compiler package.
+ */
+
+import Vinyl = require('vinyl');
+import log = require('fancy-log');
+import { spawn } from 'child_process';
+import { Stream } from 'stream';
+
+export type TPostCompilationHook = (stdout:string) => Promise<string>
+
+export default class CompilerStream extends Stream.Transform {
+
+    constructor(
+        private jarPath,
+        private args:string[],
+        private outPath:string = 'dummy',
+        private postCompilationHook?:TPostCompilationHook
+    ) {
+        super({ objectMode: true });
+    }
+
+    _transform(file, enc, cb) {
+        // ignore empty files
+        if (file.isNull()) {
+            cb();
+            return;
+        }
+        this.emit('error', new Error(`Streaming not supported`));
+        cb();
+    }
+    _flush(cb) {
+        this.doCompilation()
+            .then((file) => {
+                if (file) { this.push(file); }
+                cb();
+            })
+            .catch((err) => {
+                log.error(`Unknown error from ${this.jarPath}\n${err.message}`);
+                cb();
+            });
+    }
+
+    /**
+     * This is to make api similar to google-closure-compiler
+     */
+    src() {
+        process.nextTick(() => {
+            let stdInStream = new Stream.Readable({
+                read: function() {
+                    return new Vinyl();
+                }
+            });
+            stdInStream.pipe(this);
+            stdInStream.push(null);
+        });
+        this.resume();
+        return this;
+    }
+
+    private async doCompilation():Promise<Vinyl> {
+        const process = spawn('java', ['-jar', this.jarPath,  ...this.args]);
+
+        let stdOutData = '';
+        let stdErrData = '';
+
+        process.stdout.on('data', (data) => {
+            stdOutData += data;
+        });
+        process.stderr.on('data', (data) => {
+            stdErrData += data;
+        });
+        process.on('error', (err) => {
+            this.emit('error', new Error(`Process spawn error. Is java in the path?\n${err.message}`));
+        });
+        process.stdin.on('error', (err) => {
+            this.emit('error', new Error(`Error writing to stdin of the compiler.\n${err.message}`));
+        });
+
+        const closed = new Promise((resolve) => {
+            process.on('close', resolve);
+        });
+        const stdOutEnded = new Promise((resolve) => {
+            process.stdout.on('end', () => { resolve() });
+        });
+        const stdErrEnded = new Promise((resolve) => {
+            process.stderr.on('end', () => { resolve() });
+        });
+
+        const [code] = await Promise.all([closed, stdOutEnded, stdErrEnded]);
+
+        if (stdErrData.trim().length > 0) {
+            log.warn(stdErrData);
+        }
+
+        if (code !== 0) {
+            this.emit('error', new Error(`Compilation error from ${this.jarPath}`));
+            return;
+        }
+
+        stdOutData = stdOutData.trim();
+
+        if (typeof this.postCompilationHook === 'function') {
+            stdOutData = await this.postCompilationHook(stdOutData);
+        }
+
+        if (stdOutData.length > 0) {
+            return new Vinyl({
+                path: this.outPath,
+                contents: new Buffer(stdOutData)
+            });
+        }
+    }
+}