bundle chunks

README.md

@@ -17,7 +17,10 @@ yarn add @depack/depack
 - [`async Compile(options, runOptions=, compilerArgs=): string`](#async-compileoptions-compileconfigrunoptions-runconfigcompilerargs-arraystring-string)
   * [`CompileConfig`](#type-compileconfig)
 - [`async Bundle(options, runOptions=, compilerArgs=): string`](#async-bundleoptions-bundleconfigrunoptions-runconfigcompilerargs-arraystring-string)
+  * [`BundleBase`](#type-bundlebase)
   * [`BundleConfig`](#type-bundleconfig)
+- [`async BundleChunks(options, runOptions=, compilerArgs=): string`](#async-bundlechunksoptions-chunksconfigrunoptions-runconfigcompilerargs-arraystring-string)
+  * [`ChunksConfig`](#type-chunksconfig)
 - [`getOptions(options): !Array<string>`](#getoptionsoptions-getoptions-array)
   * [`GetOptions`](#type-getoptions)
 - [`getOutput(output, src): string`](#getoutputoutput-stringsrc-string-string)
@@ -302,28 +305,17 @@ Running Google Closure Compiler 20190709<a id="_ind0" href="#_ind0"><img src=".d
 ## <code>async <ins>Bundle</ins>(</code><sub><br/>&nbsp;&nbsp;`options: !BundleConfig,`<br/>&nbsp;&nbsp;`runOptions=: !RunConfig,`<br/>&nbsp;&nbsp;`compilerArgs=: !Array<string>,`<br/></sub><code>): <i>string</i></code>
 Bundles the browser source code into a _JavaScript_ file. If there are any _JSX_ dependencies, the bundler will transpile them first using [ÀLaMode/JSX](https://github.com/a-la/jsx). Returns the `stdout` of the compiler, and prints to the console if output is not given in `runOptions`.
 
- - <kbd><strong>options*</strong></kbd> <em><code><a href="#type-bundleconfig" title="Options for the web bundler.">!BundleConfig</a></code></em>: Options for the web bundler. Must have the `src` prop at least.
+ - <kbd><strong>options*</strong></kbd> <em><code><a href="#type-bundleconfig" title="Options for the Bundle method.">!BundleConfig</a></code></em>: Options for the web bundler. Must have the `src` prop at least.
  - <kbd>runOptions</kbd> <em><code><a href="1-run.md#type-runconfig" title="General options for running of the compiler.">!RunConfig</a></code></em> (optional): General options for running of the compiler.
  - <kbd>compilerArgs</kbd> <em><code>!Array&lt;string&gt;</code></em> (optional): The compiler args got with `getOptions` and/or manually extended.
 
-__<a name="type-bundleconfig">`BundleConfig`</a>__: Options for the web bundler.
+__<a name="type-bundlebase">`BundleBase`</a>__: Options for the web bundler.
 <table>
  <thead><tr>
   <th>Name</th>
   <th>Type &amp; Description</th>
   <th>Default</th>
  </tr></thead>
- <tr>
-  <td rowSpan="3" align="center"><strong>src*</strong></td>
-  <td><em>string</em></td>
-  <td rowSpan="3">-</td>
- </tr>
- <tr></tr>
- <tr>
-  <td>
-   The entry file to bundle. Currently only single files are supported.
-  </td>
- </tr>
  <tr>
   <td rowSpan="3" align="center">tempDir</td>
   <td><em>string</em></td>
@@ -370,6 +362,24 @@ __<a name="type-bundleconfig">`BundleConfig`</a>__: Options for the web bundler.
  </tr>
 </table>
 
+__<a name="type-bundleconfig">`BundleConfig`</a> extends <a href="#type-bundlebase" title="Options for the web bundler.">`BundleBase`</a>__: Options for the Bundle method.
+<table>
+ <thead><tr>
+  <th>Name</th>
+  <th>Type &amp; Description</th>
+ </tr></thead>
+ <tr>
+  <td rowSpan="3" align="center"><strong>src*</strong></td>
+  <td><em>string</em></td>
+ </tr>
+ <tr></tr>
+ <tr>
+  <td>
+   The entry file to bundle. Only a single file is accepted. To compile multiple files at once, use chunks.
+  </td>
+ </tr>
+</table>
+
 _For example, given the following single JS source:_
 
 ```js
@@ -451,6 +461,37 @@ Running Google Closure Compiler 20190709<a id="_ind1" href="#_ind1"><img src=".d
   <img src="/.documentary/section-breaks/4.svg?sanitize=true">
 </a></p>
 
+## <code>async <ins>BundleChunks</ins>(</code><sub><br/>&nbsp;&nbsp;`options: !ChunksConfig,`<br/>&nbsp;&nbsp;`runOptions=: !RunConfig,`<br/>&nbsp;&nbsp;`compilerArgs=: !Array<string>,`<br/></sub><code>): <i>string</i></code>
+Bundles the browser source code into multiple _JavaScript_ file. Works in the same way as `Bundle`, generating a temp dir for JSX dependencies.
+
+ - <kbd><strong>options*</strong></kbd> <em><code><a href="#type-chunksconfig" title="Options for the BundleChunks method.">!ChunksConfig</a></code></em>: Options for the web bundler. Must have the `srcs` prop with paths to source files at least.
+ - <kbd>runOptions</kbd> <em><code><a href="1-run.md#type-runconfig" title="General options for running of the compiler.">!RunConfig</a></code></em> (optional): General options for running of the compiler.
+ - <kbd>compilerArgs</kbd> <em><code>!Array&lt;string&gt;</code></em> (optional): The compiler args got with `getOptions` and/or manually extended.
+
+__<a name="type-chunksconfig">`ChunksConfig`</a> extends <a href="#type-bundlebase" title="Options for the web bundler.">`BundleBase`</a>__: Options for the BundleChunks method.
+<table>
+ <thead><tr>
+  <th>Name</th>
+  <th>Type &amp; Description</th>
+ </tr></thead>
+ <tr>
+  <td rowSpan="3" align="center"><strong>srcs*</strong></td>
+  <td><em>!Array&lt;string&gt;</em></td>
+ </tr>
+ <tr></tr>
+ <tr>
+  <td>
+   The entry files to bundle. Chunks will be created according to the strategy (only <code>common</code> strategy is supported at the moment, which places any dependency which is required in more than one file in a <code>common</code> chunk).
+  </td>
+ </tr>
+</table>
+
+_For example, given the following single JS source:_
+
+<p align="center"><a href="#table-of-contents">
+  <img src="/.documentary/section-breaks/5.svg?sanitize=true">
+</a></p>
+
 ## <code><ins>getOptions</ins>(</code><sub><br/>&nbsp;&nbsp;`options: !GetOptions,`<br/></sub><code>): <i>!Array<string></i></code>
 Returns an array of options to pass to the compiler for `Compile`, `Bundle` and `BundleChunks` methods. [Full list of supported arguments](https://github.com/google/closure-compiler/wiki/Flags-and-Options).
 
@@ -658,7 +699,7 @@ console.log(opts)
 </td></tr></table>
 
 <p align="center"><a href="#table-of-contents">
-  <img src="/.documentary/section-breaks/5.svg?sanitize=true">
+  <img src="/.documentary/section-breaks/6.svg?sanitize=true">
 </a></p>
 
 ## <code><ins>getOutput</ins>(</code><sub><br/>&nbsp;&nbsp;`output: string,`<br/>&nbsp;&nbsp;`src: string,`<br/></sub><code>): <i>string</i></code>
@@ -681,22 +722,22 @@ Dir: output/index.js
 ```
 
 <p align="center"><a href="#table-of-contents">
-  <img src="/.documentary/section-breaks/6.svg?sanitize=true">
+  <img src="/.documentary/section-breaks/7.svg?sanitize=true">
 </a></p>
 
 ## `GOOGLE_CLOSURE_COMPILER: string`
 
 If the `GOOGLE_CLOSURE_COMPILER` was set using the environment variable, it will be returned in this named exported.
 
 <p align="center"><a href="#table-of-contents">
-  <img src="/.documentary/section-breaks/7.svg?sanitize=true">
+  <img src="/.documentary/section-breaks/8.svg?sanitize=true">
 </a></p>
 
 ## <code>async <ins>getCompilerVersion</ins>(): <i>string</i></code>
 If `GOOGLE_CLOSURE_COMPILER` was set using an environment variable, returns `target`, otherwise reads the version from the `google-closure-compiler-java` package.json file.
 
 <p align="center"><a href="#table-of-contents">
-  <img src="/.documentary/section-breaks/8.svg?sanitize=true">
+  <img src="/.documentary/section-breaks/9.svg?sanitize=true">
 </a></p>
 
 

compile/index.js

@@ -1,6 +1,6 @@
 const {
   _run, _Compile, _Bundle, _getOptions, _getOutput, _getCompilerVersion,
-  _GOOGLE_CLOSURE_COMPILER,
+  _GOOGLE_CLOSURE_COMPILER, _BundleChunks,
 } = require('./depack')
 
 /**
@@ -47,12 +47,8 @@ function Compile(options, runOptions, compilerArgs) {
 
 /**
  * Bundles the browser source code into a _JavaScript_ file. If there are any _JSX_ dependencies, the bundler will transpile them first using [ÀLaMode/JSX](https://github.com/a-la/jsx). Returns the `stdout` of the compiler, and prints to the console if output is not given in `runOptions`.
- * @param {!_depack.BundleConfig} options Options for the web bundler.
- * @param {string} options.src The entry file to bundle. Currently only single files are supported.
- * @param {string} [options.tempDir="depack-temp"] Where to save prepared JSX files. Default `depack-temp`.
- * @param {boolean} [options.preact=false] Adds `import { h } from 'preact'` automatically, so that the bundle will be compiled **together** with _Preact_. Default `false`.
- * @param {boolean} [options.silent=false] If output is not given, don't print to `stdout`. By default, the output will be printed. Default `false`.
- * @param {boolean} [options.preactExtern=false] Adds `import { h } from '＠preact/extern'` automatically, assuming that `preact` will be available in the global scope and won't be included in the compilation. It will also rename any `preact` imports into `＠externs/preact`, so that the actual source code does not need manual editing. Default `false`.
+ * @param {!_depack.BundleConfig} options Options for the Bundle method.
+ * @param {string} options.src The entry file to bundle. Only a single file is accepted. To compile multiple files at once, use chunks.
  * @param {!_depack.RunConfig} [runOptions] General options for running of the compiler.
  * @param {string} [runOptions.output] The path where the output will be saved. Prints to `stdout` if not passed.
  * @param {string} [runOptions.debug] The name of the file where to save sources after each pass. Useful when there's a potential bug in _GCC_.
@@ -64,6 +60,21 @@ function Compile(options, runOptions, compilerArgs) {
 function Bundle(options, runOptions, compilerArgs) {
   return _Bundle(options, runOptions, compilerArgs)
 }
+/**
+ * Bundles the browser source code into multiple _JavaScript_ file. Works in the same way as `Bundle`, generating a temp dir for JSX dependencies.
+ * @param {!_depack.ChunksConfig} options Options for the BundleChunks method.
+ * @param {!Array<string>} options.srcs The entry files to bundle. Chunks will be created according to the strategy (only `common` strategy is supported at the moment, which places any dependency which is required in more than one file in a `common` chunk).
+ * @param {!_depack.RunConfig} [runOptions] General options for running of the compiler.
+ * @param {string} [runOptions.output] The path where the output will be saved. Prints to `stdout` if not passed.
+ * @param {string} [runOptions.debug] The name of the file where to save sources after each pass. Useful when there's a potential bug in _GCC_.
+ * @param {string} [runOptions.compilerVersion] Used in the display message. Obtained with the `getCompilerVersion` method.
+ * @param {boolean} [runOptions.noSourceMap=false] Disables source maps. Default `false`.
+ * @param {!Array<string>=} [compilerArgs] The compiler args got with `getOptions` and/or manually extended.
+ * @return {Promise<string>}
+ */
+function BundleChunks(options, runOptions, compilerArgs) {
+  return _BundleChunks(options, runOptions, compilerArgs)
+}
 
 /**
  * Returns an array of options to pass to the compiler for `Compile`, `Bundle` and `BundleChunks` methods. [Full list of supported arguments](https://github.com/google/closure-compiler/wiki/Flags-and-Options).
@@ -97,12 +108,20 @@ function getOutput(output, src) {
   return _getOutput(output, src)
 }
 
+/**
+ * If the `GOOGLE_CLOSURE_COMPILER` jar path was set using the environment variable, it will be returned in this named exported.
+ * @type {string}
+ */
+const GOOGLE_CLOSURE_COMPILER = _GOOGLE_CLOSURE_COMPILER
+
 module.exports.run = run
 module.exports.Compile = Compile
 module.exports.Bundle = Bundle
+module.exports.BundleChunks = BundleChunks
 module.exports.getOptions = getOptions
 module.exports.getOutput = getOutput
 module.exports.getCompilerVersion = getCompilerVersion
+module.exports.GOOGLE_CLOSURE_COMPILER = GOOGLE_CLOSURE_COMPILER
 
 /* typal types/index.xml namespace */
 /**
@@ -146,11 +165,18 @@ module.exports.getCompilerVersion = getCompilerVersion
 
 /* typal types/bundle.xml namespace */
 /**
- * @typedef {_depack.BundleConfig} BundleConfig Options for the web bundler.
- * @typedef {Object} _depack.BundleConfig Options for the web bundler.
- * @prop {string} src The entry file to bundle. Currently only single files are supported.
+ * @typedef {_depack.BundleBase} BundleBase `＠record` Options for the web bundler.
+ * @typedef {Object} _depack.BundleBase `＠record` Options for the web bundler.
  * @prop {string} [tempDir="depack-temp"] Where to save prepared JSX files. Default `depack-temp`.
  * @prop {boolean} [preact=false] Adds `import { h } from 'preact'` automatically, so that the bundle will be compiled **together** with _Preact_. Default `false`.
  * @prop {boolean} [silent=false] If output is not given, don't print to `stdout`. By default, the output will be printed. Default `false`.
  * @prop {boolean} [preactExtern=false] Adds `import { h } from '＠preact/extern'` automatically, assuming that `preact` will be available in the global scope and won't be included in the compilation. It will also rename any `preact` imports into `＠externs/preact`, so that the actual source code does not need manual editing. Default `false`.
+ * @typedef {_depack.BundleConfig} BundleConfig `＠record` Options for the Bundle method.
+ * @typedef {BundleBase & _depack.$BundleConfig} _depack.BundleConfig `＠record` Options for the Bundle method.
+ * @typedef {Object} _depack.$BundleConfig `＠record` Options for the Bundle method.
+ * @prop {string} src The entry file to bundle. Only a single file is accepted. To compile multiple files at once, use chunks.
+ * @typedef {_depack.ChunksConfig} ChunksConfig `＠record` Options for the BundleChunks method.
+ * @typedef {BundleBase & _depack.$ChunksConfig} _depack.ChunksConfig `＠record` Options for the BundleChunks method.
+ * @typedef {Object} _depack.$ChunksConfig `＠record` Options for the BundleChunks method.
+ * @prop {!Array<string>} srcs The entry files to bundle. Chunks will be created according to the strategy (only `common` strategy is supported at the moment, which places any dependency which is required in more than one file in a `common` chunk).
  */

compile/template.js

@@ -1,6 +1,6 @@
 const {
   _run, _Compile, _Bundle, _getOptions, _getOutput, _getCompilerVersion,
-  _GOOGLE_CLOSURE_COMPILER,
+  _GOOGLE_CLOSURE_COMPILER, _BundleChunks,
 } = require('./depack')
 
 /**
@@ -30,6 +30,12 @@ function Compile(options, runOptions, compilerArgs) {
 function Bundle(options, runOptions, compilerArgs) {
   return _Bundle(options, runOptions, compilerArgs)
 }
+/**
+ * @methodType {_depack.BundleChunks}
+ */
+function BundleChunks(options, runOptions, compilerArgs) {
+  return _BundleChunks(options, runOptions, compilerArgs)
+}
 
 /**
  * @methodType {_depack.getOptions}
@@ -54,6 +60,7 @@ const GOOGLE_CLOSURE_COMPILER = _GOOGLE_CLOSURE_COMPILER
 module.exports.run = run
 module.exports.Compile = Compile
 module.exports.Bundle = Bundle
+module.exports.BundleChunks = BundleChunks
 module.exports.getOptions = getOptions
 module.exports.getOutput = getOutput
 module.exports.getCompilerVersion = getCompilerVersion

documentary/1-API/3-bundle.md

@@ -1,6 +1,8 @@
 <typedef name="Bundle" noArgTypesInToc>types/api.xml</typedef>
 
-<typedef narrow>types/bundle.xml</typedef>
+<typedef narrow name="BundleBase">types/bundle.xml</typedef>
+
+<typedef narrow name="BundleConfig">types/bundle.xml</typedef>
 
 _For example, given the following single JS source:_
 

documentary/1-API/3.5-chunks.md

@@ -0,0 +1,23 @@
+<typedef name="BundleChunks" noArgTypesInToc>types/api.xml</typedef>
+
+<!-- <typedef narrow name="BundleBase">types/bundle.xml</typedef> -->
+<typedef narrow name="ChunksConfig">types/bundle.xml</typedef>
+
+_For example, given the following single JS source:_
+
+<!-- %EXAMPLE: example/bundle-src%
+
+_Depack is used to make a JS file in ES2015 understood by old browsers:_
+
+%EXAMPLE: example/bundle, ../src => @depack/depack%
+
+_The bundled output:_
+%FORK-js example/bundle%
+
+_Stderr:_
+%FORKERR example/bundle% -->
+
+<!-- %EXAMPLE: example, ../src => @depack/depack%
+%FORK example% -->
+
+%~%

src/lib/bundle.js

@@ -108,9 +108,9 @@ export default Bundle
 
 /**
  * @suppress {nonStandardJsDocs}
- * @typedef {import('../..').BundleConfig} _depack.BundleConfig
+ * @typedef {import('../../compile').BundleConfig} _depack.BundleConfig
  */
 /**
  * @suppress {nonStandardJsDocs}
- * @typedef {import('../..').RunConfig} _depack.RunConfig
+ * @typedef {import('../../compile').RunConfig} _depack.RunConfig
  */

src/lib/chunks.js

@@ -1,15 +1,21 @@
 import { join, basename } from 'path'
 import { rm } from '@wrote/wrote'
+import staticAnalysis, { sort } from 'static-analysis'
 import { getBundleArgs, updateTempDirArgs, getCommand, unique, createExternsArgs, hasJsonFiles, detectExterns } from './'
 import run from './run'
-import staticAnalysis, { sort } from 'static-analysis'
 import { prepareTemp, doesSrcHaveJsx } from './bundle'
 
+/**
+ * Bundle the source code into chunks.
+ * @param {_depack.ChunksConfig} options Options for the web bundler.
+ * @param {_depack.RunConfig} [runOptions] General options for running of the compiler.
+ * @param {!Array<string>} [compilerArgs] Extra arguments for the compiler, including the ones got with `getOptions`.
+ */
 export default async function BundleChunks(options, runOptions, compilerArgs = []) {
   const { srcs, tempDir = 'depack-temp', preact, preactExtern } = options
   const { output, compilerVersion, debug, noSourceMap } = runOptions
   if (!srcs) throw new Error('Entry files are not given.')
-  if (!Array.isArray(srcs)) throw new Error('Expecting chunks.')
+  if (!Array.isArray(srcs)) throw new Error('Expecting an array of source files to generate chunks.')
 
   let deps = []
   let processCommonJs = false
@@ -100,3 +106,12 @@ export default async function BundleChunks(options, runOptions, compilerArgs = [
 }
 
 export const addJsArg = (a, v) => [...a, '--js', v]
+
+/**
+ * @suppress {nonStandardJsDocs}
+ * @typedef {import('../../compile').ChunksConfig} _depack.ChunksConfig
+ */
+/**
+ * @suppress {nonStandardJsDocs}
+ * @typedef {import('../../compile').RunConfig} _depack.RunConfig
+ */

src/lib/compile.js

@@ -223,9 +223,9 @@ export default Compile
 
 /**
  * @suppress {nonStandardJsDocs}
- * @typedef {import('../..').CompileConfig} _depack.CompileConfig
+ * @typedef {import('../../compile').CompileConfig} _depack.CompileConfig
  */
 /**
  * @suppress {nonStandardJsDocs}
- * @typedef {import('../..').RunConfig} _depack.RunConfig
+ * @typedef {import('../../compile').RunConfig} _depack.RunConfig
  */