js-build-tools 2.2.3 → 2.2.5

package/README.md

@@ -1,29 +1,38 @@
 # js-build-tools
-Centralize the build process for node.js and JS projects into a single tool suite.
+
+Centralize the build process for Node.js, JS and TypeScript projects into a single tool suite.
 
 ### Goals
+
 Using this tool suite, you can:
+
+* Parse TypeScript into JS distribution files
 * Create formatted distribution files to be used in a node / commonjs environment.
 * Bundle your distribution files to be used in a browser environment.
 * Run tests and watch for changes.
 * Generate jsdoc readme files.
 
 ## Installation
+
 In your project's root directory, run: `npm install --save-dev gulp js-build-tools`
 (or `yarn add --dev gulp js-build-tools` if you use Yarn).
 
-It is recommended to install gulp with the `-g` flag, so that you can run it with `gulp` instead of `node_modules/.bin/gulp`.
+It is recommended to install gulp with the `-g` flag, so that you can run it with `gulp` instead
+of `node_modules/.bin/gulp`.
 
 ## Configuration
-In your project's root directory, create a `build-tools.config.js` file. This can contain any of the following (values provided are the defaults):
-```
+
+In your project's root directory, create a `build-tools.config.js` file. This can contain any of the following (values
+provided are the defaults):
+
+```js
 module.exports = {
   // The name to use for the browser-bundled output file (.js will be appended).
   browserName: 'my-package',
 
   // The output directory for browser-bundled files.
   browserPath: 'browser',
-  
+
   // The paths for directories to delete before build.
   cleanPaths: ['dist', 'browser'],
 
@@ -34,55 +43,71 @@ module.exports = {
   distPath: 'dist',
 
   // The search pattern used for retrieving compiled distribution files.
-  distSearch: 'dist/**/*.js',]\
-  
+  distSearch: 'dist/**/*.js',
+
   // 'true' to only generate node environment files.
   nodeOnly: false,
-  
+
   // The name of the output documentation markdown file.
   readmeFile: 'README.md',
-  
+
   // The directory to output the readme file in.
   readmePath: './',
-  
+
   // Options for formatting the output readme.
   readmeOptions: 'utf8',
 
   // The file which will be pre-fixed to your README.md output.
   readmeTemplate: 'MAIN.md',
-  
+
   // Location of files to use for compiling documentation into the readme.
   readmeSearch: ['gulpfile.base.js', 'gulp.config.js', 'functions/**/!(*.test).js'],
 
   // Base directory of the project.
   rootPath: './',
-  
+
   // The directory where your source files are stored (the files you manually created).
   srcPath: 'src',
 
   // The search pattern used for gathering source files for distribution.
   srcSearch: 'src/**/!(*.test).js',
-  
+
   // Additional flags for programatically running Jest Cli.
   testOptions: null,
 
   // The directory where Jest test files are stored.
   // By default stored as *.test.js adjacent with the files they are testing).
   testPath: 'src',
-  
+
+  // Pattern for finding the TypeScript files
+  tsSearch: 'src/**/*.ts',
+
   // The path the tsconfig file for running typescript or false if no ts file given.
   useTsConfig: 'tsconfig.json',
-  
+
   // The search pattern for watching files for changes.
   watchSearch: 'src/**/*.js',
 }
 ```
 
 ### Create your local gulpfile.js
-In your project's root directory, create a `gulpfile.js` file, in here you can require any of the functions you need. For example:
-```
+
+In your project's root directory, create a `gulpfile.js` file, in here you can require any of the functions you need.
+For example:
+
+```js
 // Your local gulpfile.js
-const { build, defaultCmd, readme, testFull, testQuick, watchFull, watchTest } = require('js-build-tools')
+const {
+  build,
+  defaultCmd,
+  partials,
+  readme,
+  testFull,
+  testQuick,
+  typescript,
+  watchFull,
+  watchTest
+} = require('js-build-tools')
 
 // Everything you export will be created as a gulp task.
 // You can build your own tasks here as well by using some of the functions `js-build-tools/functions`.
@@ -99,19 +124,67 @@ exports.watchTest = watchTest
 Verify your tasks are available by running `gulp --tasks`.
 
 ### Configure Babel
+
 Depending on how you wrote your test files, Jest may require some Babel configuration.
 Create a `babel.config.js` file in the root directory of your project.
-You can then use the recommended configuration by requiring the babel.config.js file into your own configuration file.
+You can then use the recommended configuration by requiring the `babel.config.js` file into your own configuration file.
 Example:
-```
+
+```js
 const babelConfig = require('js-build-tools/babel.config')
 // You may add additional configuration here. Example: babelConfig.presets.push('@babel/preset-env')
 module.exports = babelConfig
 ```
 
-### Configure Scripts
-In your package.json file, add the following scripts:
+### Configure TypeScript (optional)
+
+Create a `tsconfig.json` file in your project root with the following:
+
+```json
+{
+  "files": [
+    "src/**/*.ts"
+  ],
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "target": "es6",
+    "moduleResolution": "node",
+    "declaration": true
+  }
+}
+```
+
+The pattern for `"files"` should match your .ts files, but the essential thing is that it is wrapped in an array.
+The actual pattern used comes from `babel.config.js` as `'tsSearch'` setting. In order to create the ts declaration
+files you must add the `"declaration": true`.
+
+Add the following to the exports in your `babel.config.js`:
+
+```js
+module.exports = {
+  readmeSearch: 'dist/**/!(*.min).js',
+  useTsConfig: 'tsconfig.json',
+}
+```
+
+The `js-to-markdown` only works on .js files, so we run the readme search on the built dist files. Also, we want to
+register the tsconfig.json we created earlier and will alter the processes to build for TypeScript.
+
+Update `babel.config.js` with the following:
+
+```js
+const babelConfig = require('js-build-tools/babel.config')
+// This is the important line, we need to add compatibility for Jest to run tests on .ts files
+babelConfig.presets.push('@babel/preset-typescript')
+module.exports = babelConfig
 ```
+
+### Configure Scripts
+
+In your `package.json` file, add the following scripts:
+
+```json
+{
   "scripts": {
     "build": "gulp build",
     "dev": "gulp",
@@ -120,12 +193,13 @@ In your package.json file, add the following scripts:
     "test:quick": "gulp testQuick",
     "watch": "gulp watchFull",
     "watch:test": "gulp watchTest"
-  },
+  }
+}
 ```
 
 ## Usage
-Run any of the above commands with `gulp` or `npm run`.
 
+Run any of the above commands with `gulp` or `npm run`.
 
 # Available functions documentation
 
@@ -158,7 +232,7 @@ Export these functions to your own project in order to customize your build pipe
     * [.compileReadme](#module_js-build-tools.compileReadme) ⇒ <code>stream.Stream</code>
     * [.watchTest()](#module_js-build-tools.watchTest) ⇒ <code>\*</code>
     * [.watchFull()](#module_js-build-tools.watchFull) ⇒ <code>FSWatcher</code>
-    * [.typeScript()](#module_js-build-tools.typeScript) ⇒ <code>stream.Stream</code>
+    * [.typeScript()](#module_js-build-tools.typeScript) ⇒ <code>function</code>
     * [.testQuick()](#module_js-build-tools.testQuick) ⇒ <code>Promise.&lt;\*&gt;</code>
     * [.testFull()](#module_js-build-tools.testFull) ⇒ <code>Promise.&lt;\*&gt;</code>
     * [.distMinify()](#module_js-build-tools.distMinify) ⇒ <code>\*</code>
@@ -190,7 +264,7 @@ Watch for changes and run the distribution for the changed files, then bundle an
 **Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
 <a name="module_js-build-tools.typeScript"></a>
 
-### js-build-tools.typeScript() ⇒ <code>stream.Stream</code>
+### js-build-tools.typeScript() ⇒ <code>function</code>
 Simplified typescript task using tsFor.
 
 **Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
@@ -537,7 +611,7 @@ Micro-functions used as components for the main gulp functions.
 **Author**: Joshua Heagle <joshuaheagle@gmail.com>  
 
 * [partials](#module_partials)
-    * [.tsFor([srcPath], [distPath])](#module_partials.tsFor) ⇒ <code>stream.Stream</code>
+    * [.tsFor([srcPath], [distPath])](#module_partials.tsFor) ⇒ <code>function</code>
     * [.runOnChange(path)](#module_partials.runOnChange) ⇒ <code>stream.Stream</code>
         * [~pathRegex](#module_partials.runOnChange..pathRegex)
     * [.removeDirectory(dirPath)](#module_partials.removeDirectory) ⇒ <code>Promise.&lt;\*&gt;</code>
@@ -552,7 +626,7 @@ Micro-functions used as components for the main gulp functions.
 
 <a name="module_partials.tsFor"></a>
 
-### partials.tsFor([srcPath], [distPath]) ⇒ <code>stream.Stream</code>
+### partials.tsFor([srcPath], [distPath]) ⇒ <code>function</code>
 Starting at the source directory, find all the ts files and convert them into the distribution directory.
 
 **Kind**: static method of [<code>partials</code>](#module_partials)  

package/dist/build.js

@@ -27,14 +27,17 @@ var build = function build () {
   var bundleLintMinify = parallel(bundleLint, bundleMinify)
   var buildActions = [clean, distSeries(), distLintMinify]
   if (gulpConfig.get('useTsConfig')) {
+    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
     buildActions.push(compileReadme)
   }
   if (!gulpConfig.get('nodeOnly')) {
+    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
     buildActions.push(bundle)
     buildActions.push(bundleLintMinify)
   }
   var runActions = [series.apply(void 0, buildActions)]
   if (!gulpConfig.get('useTsConfig')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
     runActions.push(compileReadme)
   }
   runActions.push(testFull)

package/dist/partials/distSeries.js

@@ -20,9 +20,7 @@ var distSeries = function distSeries() {
   var srcPath = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : distForSrc();
   var distFinalPath = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : gulpConfig.get('distPath');
   var tsSearch = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : gulpConfig.get('tsSearch');
-  var typescript = function typescript() {
-    return tsFor(tsSearch, distFinalPath);
-  };
+  var typescript = tsFor(tsSearch, distFinalPath);
   var dist = function dist() {
     return distFor(srcPath, distFinalPath);
   };

package/dist/partials/tsFor.js

@@ -2,10 +2,10 @@
 
 var _require = require('gulp'),
   dest = _require.dest,
+  parallel = _require.parallel,
   src = _require.src;
 var gulpConfig = require('../../gulp.config.js');
 var ts = require('gulp-typescript');
-var tsProject = ts.createProject(gulpConfig.get('useTsConfig'));
 
 /**
  * Starting at the source directory, find all the ts files and convert them into the distribution directory.
@@ -13,12 +13,20 @@ var tsProject = ts.createProject(gulpConfig.get('useTsConfig'));
  * @memberOf module:partials
  * @param {string|array} [srcPath='']
  * @param {string} [distPath='']
- * @returns {stream.Stream}
+ * @returns {Function}
  * @see `https://www.typescriptlang.org/docs/handbook/gulp.html` for more info
  */
 var tsFor = function tsFor() {
   var srcPath = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : gulpConfig.get('tsSearch');
   var distPath = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : gulpConfig.get('distPath');
-  return src(srcPath).pipe(tsProject()).js.pipe(dest(distPath));
+  var declarationProject = ts.createProject(gulpConfig.get('useTsConfig'));
+  var tsProject = ts.createProject(gulpConfig.get('useTsConfig'));
+  var makeDeclarations = function makeDeclarations() {
+    return src(srcPath).pipe(declarationProject()).dts.pipe(dest(distPath));
+  };
+  var compileJS = function compileJS() {
+    return src(srcPath).pipe(tsProject()).js.pipe(dest(distPath));
+  };
+  return parallel(makeDeclarations, compileJS);
 };
 module.exports = tsFor;

package/dist/typeScript.js

@@ -6,9 +6,7 @@ var tsFor = require('./partials/tsFor')
  * Simplified typescript task using tsFor.
  * @function
  * @memberOf module:js-build-tools
- * @returns {stream.Stream}
+ * @returns {Function}
  */
-var typeScript = function typeScript () {
-  return tsFor()
-}
+var typeScript = tsFor()
 module.exports = typeScript

package/dist/typeScript.min.js

@@ -1 +1 @@
-"use strict";var tsFor=require("./partials/tsFor"),typeScript=function(){return tsFor()};module.exports=typeScript;
+"use strict";var tsFor=require("./partials/tsFor"),typeScript=tsFor();module.exports=typeScript;

package/functions/build.test.js

@@ -12,14 +12,6 @@ const genericFunction = () => Promise.resolve(true)
 jest.mock('./partials/clean', () => jest.fn(genericFunction))
 jest.mock('./testFull', () => jest.fn(genericFunction))
 
-const file1Typescript = '/**\n' +
-  ' * Console log out a greeting with given input.\n' +
-  ' * @param {string} input\n' +
-  ' */\n' +
-  'const file1 = (input: string): void => console.log(`Hello from file1 with ${input}`)\n' +
-  '\n' +
-  'module.exports = file1\n'
-
 const file1Contents = '/**\n' +
   ' * Console log out a greeting with given input.\n' +
   ' * @param {string} input\n' +
@@ -28,20 +20,6 @@ const file1Contents = '/**\n' +
   '\n' +
   'module.exports = file1\n'
 
-const file2Typescript = '/**\n' +
-  ' * Farewell with a summation of two numbers returned.\n' +
-  ' * @param {number} a\n' +
-  ' * @param {number} b\n' +
-  ' * @returns {number}\n' +
-  ' */\n' +
-  'const file2 = (a: number, b: number): number => {\n' +
-  '  const sum = a + b\n' +
-  '  console.log(`Good-bye from file2 with sum ${sum}`)\n' +
-  '  return sum\n' +
-  '}\n' +
-  '\n' +
-  'module.exports = file2\n'
-
 const file2Contents = '/**\n' +
   ' * Farewell with a summation of two numbers returned.\n' +
   ' * @param {number} a\n' +
@@ -94,7 +72,9 @@ const tsConfigContents = '{\n' +
   '  "files": ["test-build/src/**/*.ts"],\n' +
   '  "compilerOptions": {\n' +
   '    "noImplicitAny": true,\n' +
-  '    "target": "es5"\n' +
+  '    "target": "es6",\n' +
+  '    "moduleResolution": "node",\n' +
+  '    "declaration": true,\n' +
   '  }\n' +
   '}'
 
@@ -228,13 +208,15 @@ describe('build', () => {
     gulpConfig.set('nodeOnly', true)
     gulpConfig.set('useTsConfig', tsConfig)
     gulpConfig.set('readmeSearch', `${distPath}/**/*.js`)
-    expect.assertions(7)
+    expect.assertions(8)
     build(() => {
       // Called 'clean'
       expect(clean).toHaveBeenCalled()
 
       // Created dist directory (distSeries)
       expect(fs.existsSync(distPath)).toBeTruthy()
+      // Created declaration file
+      expect(fs.existsSync(`${distPath}/main.d.ts`)).toBeTruthy()
 
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
@@ -253,7 +235,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when nodeOnly false and useTsConfig false: calls clean, tsFor, distFor, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull', done => {
+  test('when nodeOnly false and useTsConfig set: calls clean, tsFor, distFor, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')
     const tsConfig = `${rootPath}/tsconfig.json`
@@ -268,13 +250,15 @@ describe('build', () => {
     gulpConfig.set('nodeOnly', false)
     gulpConfig.set('useTsConfig', tsConfig)
     gulpConfig.set('readmeSearch', `${distPath}/**/*.js`)
-    expect.assertions(10)
+    expect.assertions(11)
     build(() => {
       // Called 'clean'
       expect(clean).toHaveBeenCalled()
 
       // Created dist directory (distSeries)
       expect(fs.existsSync(distPath)).toBeTruthy()
+      // Created declaration file
+      expect(fs.existsSync(`${distPath}/main.d.ts`)).toBeTruthy()
 
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()

package/functions/partials/distFor.test.js

@@ -99,27 +99,22 @@ describe('distFor', () => {
     const oldContents = fs.readFileSync(srcFile).toString()
     expect(countMatches(oldContents, 'const ')).toEqual(3)
     const distPath = gulpConfig.get('distPath')
-    typeScript()
-      .on('finish', () => {
-        distFor()
-          .on('finish', () => {
-            expect(fs.existsSync(distPath)).toBeTruthy()
-            const babelifiedContents = fs.readFileSync(`${distPath}/distFor.js`).toString()
-            expect(countMatches(babelifiedContents, '"use strict"')).toEqual(1)
-            expect(countMatches(babelifiedContents, 'const ')).toEqual(0)
-            expect(countMatches(babelifiedContents, 'var ')).toEqual(8)
-            expect(countMatches(babelifiedContents, 'function')).toEqual(1)
-            expect(countMatches(babelifiedContents, 'Object.defineProperty(exports, "__esModule", { value: true })')).toEqual(1)
-            done()
-          })
-          .on('error', error => {
-            console.error('Encountered error with distFor', error)
-            done()
-          })
-      })
-      .on('error', error => {
-        console.error('Encountered error with typeScript', error)
-        done()
-      })
+    typeScript(() => {
+      distFor()
+        .on('finish', () => {
+          expect(fs.existsSync(distPath)).toBeTruthy()
+          const babelifiedContents = fs.readFileSync(`${distPath}/distFor.js`).toString()
+          expect(countMatches(babelifiedContents, '"use strict"')).toEqual(1)
+          expect(countMatches(babelifiedContents, 'const ')).toEqual(0)
+          expect(countMatches(babelifiedContents, 'var ')).toEqual(8)
+          expect(countMatches(babelifiedContents, 'function')).toEqual(1)
+          expect(countMatches(babelifiedContents, 'Object.defineProperty(exports, "__esModule", { value: true })')).toEqual(1)
+          done()
+        })
+        .on('error', error => {
+          console.error('Encountered error with distFor', error)
+          done()
+        })
+    })
   }, 60000)
 })

package/functions/partials/distSeries.js

@@ -14,7 +14,7 @@ const tsFor = require('./tsFor')
  * @returns {function(null=): stream.Stream}
  */
 const distSeries = (srcPath = distForSrc(), distFinalPath = gulpConfig.get('distPath'), tsSearch = gulpConfig.get('tsSearch')) => {
-  const typescript = () => tsFor(tsSearch, distFinalPath)
+  const typescript = tsFor(tsSearch, distFinalPath)
   const dist = () => distFor(srcPath, distFinalPath)
   return gulpConfig.get('useTsConfig')
     ? series(typescript, dist)

package/functions/partials/distSeries.test.js

@@ -7,7 +7,7 @@ const distFor = require('./distFor')
 const genericFunction = () => Promise.resolve(true)
 
 jest.mock('./distFor', () => jest.fn(genericFunction))
-jest.mock('./tsFor', () => jest.fn(genericFunction))
+jest.mock('./tsFor', () => jest.fn(() => genericFunction))
 
 describe('distSeries', () => {
   test('when not using ts config only returns runnable distFor', done => {

package/functions/partials/runOnChange.test.js

@@ -12,7 +12,7 @@ const genericFunction = () => Promise.resolve(true)
 
 jest.mock('../bundle', () => jest.fn(genericFunction))
 jest.mock('./distFor', () => jest.fn(genericFunction))
-jest.mock('./tsFor', () => jest.fn(genericFunction))
+jest.mock('./tsFor', () => jest.fn(() => genericFunction))
 jest.mock('../testQuick', () => jest.fn(genericFunction))
 
 const rawContents = 'export function sayHello(name: string) {\n' +

package/functions/partials/tsFor.js

@@ -1,21 +1,22 @@
-const { dest, src } = require('gulp')
+const { dest, parallel, src } = require('gulp')
 const gulpConfig = require('../../gulp.config.js')
 const ts = require('gulp-typescript')
 
-const tsProject = ts.createProject(gulpConfig.get('useTsConfig'))
-
 /**
  * Starting at the source directory, find all the ts files and convert them into the distribution directory.
  * @function
  * @memberOf module:partials
  * @param {string|array} [srcPath='']
  * @param {string} [distPath='']
- * @returns {stream.Stream}
+ * @returns {Function}
  * @see `https://www.typescriptlang.org/docs/handbook/gulp.html` for more info
  */
-const tsFor = (srcPath = gulpConfig.get('tsSearch'), distPath = gulpConfig.get('distPath')) => src(srcPath)
-    .pipe(tsProject())
-    .js
-    .pipe(dest(distPath))
+const tsFor = (srcPath = gulpConfig.get('tsSearch'), distPath = gulpConfig.get('distPath')) => {
+  const declarationProject = ts.createProject(gulpConfig.get('useTsConfig'))
+  const tsProject = ts.createProject(gulpConfig.get('useTsConfig'))
+  const makeDeclarations = () => src(srcPath).pipe(declarationProject()).dts.pipe(dest(distPath))
+  const compileJS = () => src(srcPath).pipe(tsProject()).js.pipe(dest(distPath))
+  return parallel(makeDeclarations, compileJS)
+}
 
 module.exports = tsFor

package/functions/partials/tsFor.test.js

@@ -29,16 +29,11 @@ describe('tsFor', () => {
     expect.assertions(3)
     const oldContents = fs.readFileSync(srcFile).toString()
     expect(countMatches(oldContents, 'sayHello(name: string)')).toEqual(1)
-    tsFor(srcFile, distPath)
-      .on('finish', () => {
-        expect(fs.existsSync(distPath)).toBeTruthy()
-        const compiledContents = fs.readFileSync(`${distPath}/typeScript.js`).toString()
-        expect(countMatches(compiledContents, 'sayHello(name)')).toEqual(1)
-        done()
-      })
-      .on('error', error => {
-        console.error('Encountered error', error)
-        done()
-      })
+    tsFor(srcFile, distPath)(() => {
+      expect(fs.existsSync(distPath)).toBeTruthy()
+      const compiledContents = fs.readFileSync(`${distPath}/typeScript.js`).toString()
+      expect(countMatches(compiledContents, 'sayHello(name)')).toEqual(1)
+      done()
+    })
   }, 60000)
 })

package/functions/typeScript.js

@@ -4,8 +4,8 @@ const tsFor = require('./partials/tsFor')
  * Simplified typescript task using tsFor.
  * @function
  * @memberOf module:js-build-tools
- * @returns {stream.Stream}
+ * @returns {Function}
  */
-const typeScript = () => tsFor()
+const typeScript = tsFor()
 
 module.exports = typeScript

package/functions/typeScript.test.js

@@ -1,9 +1,11 @@
 const typeScript = require('./typeScript')
 const tsFor = require('./partials/tsFor')
-jest.mock('./partials/tsFor', () => jest.fn())
+const { logObject } = require('./testHelpers')
+jest.mock('./partials/tsFor', () => jest.fn(() => () => null))
 
 describe('typeScript', () => {
   test('calls tsFor with no parameters', () => {
+    logObject(typeScript, 'typescript')
     typeScript()
     expect(tsFor).toHaveBeenCalled()
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "scripts": {