js-build-tools 1.2.3 → 2.1.0

package/functions/testHelpers.js

@@ -1,142 +1,32 @@
 /**
- * Log out an object in a nicely formatted way.
- * @param {Object} object
- * @param {string} [label='logging']
+ * An assortment of objects that can be used in tests and some functions to help debug and write tests.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 2.0.0
+ * @module testHelpers
+ * @memberOf module:js-build-tools
  */
-export const logObject = (object, label = 'logging') => {
-  if (typeof require === 'undefined') {
-    console.log(label, object)
-    return
-  }
-  console.log(label, require('util').inspect(object, false, null, true))
-}
-
-/**
- * Multilayered node tree-like structure with parent references
- * @type {Object.<string, string|Object|Array>}
- */
-export const circularObject = { name: 'root', parent: {}, body: {}, head: {}, children: [] }
-circularObject.children = [
-  { name: 'body', parent: {}, children: [] },
-  { name: 'head', parent: {}, children: [] }
-]
-circularObject.body = circularObject.children[0]
-circularObject.head = circularObject.children[1]
-circularObject.body.parent = circularObject
-circularObject.head.parent = circularObject
-circularObject.body.children = [
-  { name: 'body child one', parent: {}, children: [] },
-  { name: 'body child two', parent: {}, children: [] }
-]
-circularObject.body.children[0].parent = circularObject.body
-circularObject.body.children[1].parent = circularObject.body
-circularObject.head.children = [
-  { name: 'head child one', parent: {}, children: [] },
-  { name: 'head child two', parent: {}, children: [] }
-]
-circularObject.head.children[0].parent = circularObject.head
-circularObject.head.children[1].parent = circularObject.head
-
-/**
- * Sample object with deep references.
- * @type {Object.<string, string|number|Object>}
- */
-export const deepReferenceObject = {
-  object1: {
-    name: 'someName',
-    object2: {
-      age: 12,
-      array1: [
-        'someString',
-        'anotherString'
-      ]
-    },
-    array2: [
-      89,
-      32
-    ]
-  },
-  title: 'Some Title',
-  item: 45
-}
-
-/**
- * Sample LinkedList for testing circular references.
- * @type {Object.<string, string|Object>}
- */
-export const linkedList = { name: 'one', prev: null, next: null }
-linkedList.next = { name: 'two', prev: linkedList, next: null }
-linkedList.next.next = { name: 'three', prev: linkedList.next, next: null }
 
-/**
- * Sample of jsonDom object containing empty nested array and objects
- */
-export const jsonDom = {
-  tagName: 'div',
-  attributes: { style: {}, className: 'column' },
-  element: null,
-  eventListeners: {},
-  parentItem: {},
-  children: [],
-  axis: 'x'
-}
-
-/**
- * Sample of domItem child with nested child and optional details
- */
-export const domItem = [
-  {
-    attributes: { className: 'row', style: {} },
-    axis: 'y',
-    children: [
-      {
-        attributes: { style: {} },
-        axis: 'x',
-        children: [],
-        element: {},
-        eventListeners: {},
-        hasShip: false,
-        isHit: false,
-        parentItem: {},
-        point: {},
-        tagName: 'div'
-      }
-    ],
-    element: null,
-    eventListeners: {},
-    parentItem: {},
-    tagName: 'div'
-  }
-]
+const circularObject = require('./test-helpers/circularObject')
+const countMatches = require('./test-helpers/countMatches')
+const deepReferenceObject = require('./test-helpers/deepReferenceObject')
+const domItem = require('./test-helpers/domItem')
+const jsonDom = require('./test-helpers/jsonDom')
+const linkedList = require('./test-helpers/linkedList')
+const logObject = require('./test-helpers/logObject')
+const multiReferenceObject = require('./test-helpers/multiReferenceObject')
+const nodeTree = require('./test-helpers/nodeTree')
+const setUp = require('./test-helpers/setUp')
 
-/**
- * Sample of object containing multiple references.
- * @type {Object.<string, string|number|Object>}
- */
-export const multiReferenceObject = {
-  object1: {
-    name: 'someName'
-  },
-  object2: {
-    age: 12
-  },
-  array1: [
-    'someString',
-    'anotherString'
-  ],
-  array2: [
-    89,
-    32
-  ],
-  title: 'Some Title',
-  item: 45
+module.exports = {
+  circularObject,
+  countMatches,
+  deepReferenceObject,
+  domItem,
+  jsonDom,
+  linkedList,
+  logObject,
+  multiReferenceObject,
+  nodeTree,
+  setUp,
 }
-
-/**
- * Sample NodeTree for testing circular references and arrays.
- * @type {Object.<string, string|Object|Array>}
- */
-export const nodeTree = { name: 'one', parent: null, children: [] }
-nodeTree.children[0] = { name: 'child one', parent: nodeTree, children: [] }
-nodeTree.children[1] = { name: 'child two', parent: nodeTree, children: [] }
-nodeTree.children[0].children[0] = { name: 'grandchild one', parent: nodeTree.children[0], children: [] }

package/functions/testHelpers.test.js

@@ -1,100 +1,7 @@
-const {
-  circularObject,
-  deepReferenceObject,
-  domItem,
-  jsonDom,
-  linkedList,
-  logObject,
-  multiReferenceObject,
-  nodeTree
-} = require('./testHelpers.js')
-const util = require('util')
+const testHelpers = require('./testHelpers')
 
 describe('testHelpers', () => {
-  test('can nicely output objects with logObject', () => {
-    const logSpy = jest.spyOn(console, 'log')
-    const inspectSpy = jest.spyOn(util, 'inspect')
-    const someObject = { one: 1, two: 2, three: 3 }
-    logObject(someObject, 'someObject')
-    expect(inspectSpy).toHaveBeenCalledWith(someObject, false, null, true)
-    expect(logSpy).toHaveBeenCalledWith('someObject', util.inspect(someObject, false, null, true))
-  })
-
-  test('has sample circular object', () => {
-    expect(circularObject.body.parent).toBe(circularObject)
-    expect(circularObject.body.children[0].parent).toBe(circularObject.body)
-    expect(circularObject.body.children[1].parent).toBe(circularObject.body)
-    expect(circularObject.children[0]).toBe(circularObject.body)
-    expect(circularObject.head.parent).toBe(circularObject)
-    expect(circularObject.head.children[0].parent).toBe(circularObject.head)
-    expect(circularObject.head.children[1].parent).toBe(circularObject.head)
-    expect(circularObject.children[1]).toBe(circularObject.head)
-  })
-
-  test('has sample deep reference object', () => {
-    expect(deepReferenceObject).toHaveProperty('object1.object2.array1')
-  })
-
-  test('has sample domItem object', () => {
-    expect(domItem[0]).toHaveProperty('attributes')
-    expect(domItem[0]).toHaveProperty('children')
-    expect(domItem[0]).toHaveProperty('element')
-    expect(domItem[0]).toHaveProperty('eventListeners')
-    expect(domItem[0]).toHaveProperty('parentItem')
-    expect(domItem[0]).toHaveProperty('tagName')
-  })
-
-  test('has sample jsonDom object', () => {
-    expect(jsonDom).toHaveProperty('attributes')
-    expect(jsonDom).toHaveProperty('children')
-    expect(jsonDom).toHaveProperty('element')
-    expect(jsonDom).toHaveProperty('eventListeners')
-    expect(jsonDom).toHaveProperty('parentItem')
-    expect(jsonDom).toHaveProperty('tagName')
-  })
-
-  test('has sample linkedList object', () => {
-    expect(linkedList.name).toBe('one')
-    expect(linkedList).toHaveProperty('prev')
-    expect(linkedList.prev).toBeNull()
-
-    expect(linkedList).toHaveProperty('next')
-    expect(linkedList.next.name).toBe('two')
-    expect(linkedList).toHaveProperty('next.prev')
-    expect(linkedList.next.prev).toBe(linkedList)
-
-    expect(linkedList).toHaveProperty('next.next')
-    expect(linkedList.next.next.name).toBe('three')
-    expect(linkedList).toHaveProperty('next.prev')
-    expect(linkedList.next.next.prev).toBe(linkedList.next)
-
-    expect(linkedList).toHaveProperty('next.next.next')
-    expect(linkedList.next.next.next).toBeNull()
-  })
-
-  test('has sample multiReferenceObject object', () => {
-    expect(multiReferenceObject).toHaveProperty('object1.name')
-    expect(multiReferenceObject).toHaveProperty('object2.age')
-    expect(multiReferenceObject).toHaveProperty('array1.0')
-    expect(multiReferenceObject).toHaveProperty('array1.1')
-    expect(multiReferenceObject).toHaveProperty('array2.0')
-    expect(multiReferenceObject).toHaveProperty('array2.1')
-    expect(multiReferenceObject).toHaveProperty('title')
-    expect(multiReferenceObject).toHaveProperty('item')
-  })
-
-  test('has sample nodeTree object', () => {
-    expect(nodeTree.name).toBe('one')
-    expect(nodeTree.parent).toBeNull()
-    expect(nodeTree.children.length).toBe(2)
-    expect(nodeTree.children[0].name).toBe('child one')
-    expect(nodeTree.children[0].parent).toBe(nodeTree)
-    expect(nodeTree.children[0].children.length).toBe(1)
-    expect(nodeTree.children[0].children[0].name).toBe('grandchild one')
-    expect(nodeTree.children[0].children[0].parent).toBe(nodeTree.children[0])
-    expect(nodeTree.children[0].children[0].children.length).toBe(0)
-    expect(nodeTree.children[1].name).toBe('child two')
-    expect(nodeTree.children[1].parent).toBe(nodeTree)
-    expect(nodeTree.children[1].children.length).toBe(0)
+  test('is object with all helper exports', () => {
+    expect(Object.keys(testHelpers).length).toBe(10)
   })
 })

package/functions/testQuick.js

@@ -1,10 +1,20 @@
 const gulpConfig = require('../gulp.config.js')
-const { runCLI: jest } = require('jest')
+const { runCLI } = require('jest')
 
 /**
  * Run the Jest tests for files which have been modified (based on git status).
+ * @function
+ * @memberOf module:js-build-tools
+ * @param {function} [done=null]
+ * @param {Array.<string>|string} [testPath='path/config/test/files']
  * @returns {Promise<*>}
  */
-const testQuick = async () => await jest({ onlyChanged: true }, gulpConfig.testPath)
+const testQuick = (done = null, testPath = gulpConfig.get('testPath')) => {
+  if (!Array.isArray(testPath)) {
+    // The testPath must be an array of strings
+    testPath = [testPath]
+  }
+  return runCLI({ onlyChanged: true }, testPath)
+}
 
 module.exports = testQuick

package/functions/testQuick.test.js

@@ -0,0 +1,16 @@
+const { setUp } = require('./testHelpers')
+const gulpConfig = setUp.gulpConfig
+const { runCLI } = require('jest')
+const testQuick = require('./testQuick')
+
+jest.mock('jest', () => ({
+  'runCLI': jest.fn(() => Promise.resolve(true))
+}))
+
+describe('testQuick', () => {
+  test('runs the jest CLI with onlyChanged option', () => {
+    expect.assertions(1)
+    testQuick()
+    expect(runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('testPath')])
+  })
+})

package/functions/typeScript.js

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

package/functions/typeScript.test.js

@@ -0,0 +1,10 @@
+const typeScript = require('./typeScript')
+const tsFor = require('./partials/tsFor')
+jest.mock('./partials/tsFor', () => jest.fn())
+
+describe('typeScript', () => {
+  test('calls tsFor with no parameters', () => {
+    typeScript()
+    expect(tsFor).toHaveBeenCalled()
+  })
+})

package/functions/watchFull.js

@@ -1,18 +1,12 @@
-const bundle = require('./bundle')
-const distFor = require('./distFor')
-const gulpConfig = require('../gulp.config.js')
-const { parallel, series, watch } = require('gulp')
-const testQuick = require('./testQuick')
+const { beginWatcher, runOnChange } = require('./partials')
 
 /**
  * Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
- * @returns {*}
+ * @function
+ * @memberOf module:js-build-tools
+ * @returns {FSWatcher}
  */
-const watchFull = () => watch(gulpConfig.watchSearch)
-  .on('change', path => {
-    const pathRegex = new RegExp(`^${gulpConfig.srcPath}(.*\\/).+\\.js$`, 'i')
-    const distForPath = () => distFor(path, path.replace(pathRegex, `${gulpConfig.distPath}$1`))
-    return parallel(testQuick, series(distForPath, bundle))()
-  })
+const watchFull = () => beginWatcher()
+  .on('change', runOnChange)
 
 module.exports = watchFull

package/functions/watchFull.test.js

@@ -0,0 +1,40 @@
+const fs = require('fs')
+const setUp = require('./test-helpers/setUp')
+setUp.setDefaults('test-watch-full')
+const gulpConfig = setUp.gulpConfig
+const watchFull = require('./watchFull')
+const beginWatcher = require('./partials/beginWatcher')
+const runOnChange = require('./partials/runOnChange')
+
+jest.mock('./partials/beginWatcher', () => jest.fn(() => ({ on: (event, fn) => fn() })))
+jest.mock('./partials/runOnChange', () => jest.fn())
+
+const rawContents = 'const { beginWatcher, runOnChange } = require(\'./partials\')\n' +
+  '\n' +
+  '/**\n' +
+  ' * Watch for changes and run the distribution for the changed files, then bundle and test the changed files.\n' +
+  ' * @function\n' +
+  ' * @memberOf module:js-build-tools\n' +
+  ' * @returns {FSWatcher}\n' +
+  ' */\n' +
+  'const watchFull = () => beginWatcher()\n' +
+  '  .on(\'change\', runOnChange)\n' +
+  '\n' +
+  'module.exports = watchFull\n'
+
+beforeEach(setUp.beforeEach)
+
+afterEach(setUp.afterEach)
+
+describe('watchFull', () => {
+  test('should call beginWatcher and runOnChange for change event', () => {
+    const srcPath = gulpConfig.get('srcPath')
+    gulpConfig.set('watchSearch', `${srcPath}/*.js`)
+    const srcFile = `${srcPath}/watchFull.js`
+    fs.writeFileSync(srcFile, rawContents)
+    expect.assertions(2)
+    watchFull()
+    expect(beginWatcher).toHaveBeenCalled()
+    expect(runOnChange).toHaveBeenCalled()
+  })
+})

package/functions/watchTest.js

@@ -1,11 +1,13 @@
 const gulpConfig = require('../gulp.config.js')
-const { series, watch } = require('gulp')
+const { watch } = require('gulp')
 const testQuick = require('./testQuick')
 
 /**
  * Watch for changes and run the tests.
+ * @function
+ * @memberOf module:js-build-tools
  * @returns {*}
  */
-const watchTest = () => watch(gulpConfig.watchSearch, { ignoreInitial: false }, series(testQuick))
+const watchTest = () => watch(gulpConfig.get('watchSearch'), { ignoreInitial: false }, testQuick)
 
 module.exports = watchTest

package/functions/watchTest.test.js

@@ -0,0 +1,48 @@
+const setUp = require('./test-helpers/setUp')
+setUp.setDefaults('test-watch-test')
+const gulpConfig = setUp.gulpConfig
+gulpConfig.set('watchSearch', 'test-begin-watcher/*.js')
+const watchTest = require('./watchTest')
+const { EventEmitter } = require('node:events')
+const fs = require('fs')
+const testQuick = require('./testQuick')
+
+jest.mock('./testQuick', () => jest.fn(() => Promise.resolve(true)))
+
+const rawContents = 'const gulpConfig = require(\'../gulp.config.js\')\n' +
+  'const { watch } = require(\'gulp\')\n' +
+  'const testQuick = require(\'./testQuick\')\n' +
+  '\n' +
+  '/**\n' +
+  ' * Watch for changes and run the tests.\n' +
+  ' * @function\n' +
+  ' * @memberOf module:js-build-tools\n' +
+  ' * @returns {*}\n' +
+  ' */\n' +
+  'const watchTest = () => watch(gulpConfig.get(\'watchSearch\'), { ignoreInitial: false }, testQuick)\n' +
+  '\n' +
+  'module.exports = watchTest\n'
+
+const filePath = gulpConfig.get('srcPath') + '/watchTest.js'
+
+beforeEach(() => setUp.beforeEach()
+  .then(
+    () => fs.writeFileSync(filePath, rawContents)
+  )
+)
+
+afterEach(setUp.afterEach)
+
+describe('watchTest', () => {
+  test('returns instance of EventEmitter / FSWatcher and calls testQuick on change', done => {
+    expect.assertions(2)
+    const fsWatcher = watchTest()
+    expect(fsWatcher).toBeInstanceOf(EventEmitter)
+    fsWatcher.emit('change')
+    setTimeout(() => {
+      expect(testQuick).toHaveBeenCalled()
+      done()
+    }, 500)
+    fsWatcher.close()
+  })
+})

package/gulp.config.js

@@ -1,30 +1,175 @@
-const defaultConfig = (config, path, defaultValue) => {
+/**
+ * Modify these configurations to match your project specifications.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 2.0.0
+ * @module gulpConfig
+ * @memberOf module:js-build-tools
+ */
+
+/**
+ * Retrieve a value from an object with the path (key), return a given default if the key is not found.
+ * @memberOf module:gulpConfig
+ * @param {Object<string, *>} [config=[]]
+ * @param {string|null} [path=null]
+ * @param {*} [defaultValue=null]
+ * @returns {*|null}
+ */
+const defaultConfig = (config = {}, path = null, defaultValue = null) => {
+  if (!path) {
+    return config
+  }
   if (typeof config[path] === 'undefined') {
     return defaultValue
   }
   return config[path]
 }
-let parentConfig = {}
+
+/**
+ * A setting that may be an array of strings or a string only.
+ * @typedef {Array<string>|string} module:gulpConfig~ArrayableSetting
+ */
+
+/**
+ * A setting that may be true or false.
+ * @typedef {boolean} module:gulpConfig~BooleanSetting
+ */
+
+/**
+ * A setting that may be flag 'false' or provide a StringSetting
+ * @typedef {false|StringSetting} module:gulpConfig~FlagStringSetting
+ */
+
+/**
+ * An object of boolean settings used as flags.
+ * @typedef {Object<string, BooleanSetting>} module:gulpConfig~FlagsSetting
+ */
+
+/**
+ * Configure cli options for running Jest.
+ * @typedef {FlagsSetting} module:gulpConfig~JestTestFlags
+ * @property {BooleanSetting} clearCache
+ * @property {BooleanSetting} debug
+ * @property {BooleanSetting} ignoreProjects:
+ * @property {BooleanSetting} json
+ * @property {BooleanSetting} selectProjects
+ * @property {BooleanSetting} showConfig
+ * @property {BooleanSetting} useStderr
+ * @property {BooleanSetting} watch
+ * @property {BooleanSetting} watchAll
+ */
+
+/**
+ * A setting that may only be a string.
+ * @typedef {string} module:gulpConfig~StringSetting
+ */
+
+/**
+ * Any single configuration option is a Setting.
+ * @typedef {ArrayableSetting|BooleanSetting|FlagsSetting|StringSetting} Setting
+ */
+
+/**
+ * A set of Configurations options defined by Settings.
+ * @typedef {Object<string, Setting>} module:gulpConfig~Configurations
+ * @property {StringSetting} browserName
+ * @property {StringSetting} browserPath
+ * @property {StringSetting} distMain
+ * @property {StringSetting} distPath
+ * @property {ArrayableSetting} distSearch
+ * @property {BooleanSetting} nodeOnly
+ * @property {StringSetting} readmeTemplate
+ * @property {ArrayableSetting} readmeOptions
+ * @property {StringSetting} readmeFile
+ * @property {StringSetting} readmePath
+ * @property {ArrayableSetting} readmeSearch
+ * @property {StringSetting} rootPath
+ * @property {StringSetting} srcPath
+ * @property {ArrayableSetting} srcSearch
+ * @property {JestTestFlags} testOptions
+ * @property {ArrayableSetting} testPath
+ * @property {FlagStringSetting} useTsConfig
+ * @property {ArrayableSetting} watchSearch
+ */
+
+/**
+ * All the available configuration setting options for running the build.
+ * @memberOf module:gulpConfig` `
+ * @type {Configurations}
+ */
+let gulpConfigurations = {}
 try {
-  parentConfig = require('../../build-tools.config.js')
+  gulpConfigurations = require('../../build-tools.config.js')
 } catch (isUndefined) {
   try {
-    parentConfig = require('./build-tools.config.js')
-    console.info('Missing main project config, using default path')
+    // Missing main project config, using default path
+    gulpConfigurations = require('./build-tools.config.js')
   } catch (stillUndefined) {
     console.warn('Missing config path, ensure you have a build-tools.config.js file in you project root')
   }
 }
+
+const setDefaults = {
+  browserName: 'default',
+  browserPath: 'browser',
+  distMain: 'dist/main',
+  distPath: 'dist',
+  distSearch: 'dist/**/*.js',
+  nodeOnly: false,
+  readmeTemplate: 'MAIN.md',
+  readmeOptions: 'utf8',
+  readmeFile: 'README.md',
+  readmePath: './',
+  readmeSearch: 'src/**/!(*.test).js',
+  rootPath: './',
+  srcPath: 'src',
+  srcSearch: 'src/**/!(*.test).js',
+  testOptions: {
+    clearCache: false,
+    debug: false,
+    ignoreProjects: false,
+    json: false,
+    selectProjects: false,
+    showConfig: false,
+    useStderr: false,
+    watch: false,
+    watchAll: false,
+  },
+  testPath: ['src'],
+  tsSearch: 'src/**/*.ts',
+  useTsConfig: false,
+  watchSearch: 'src/**/*.js'
+}
+
+Object.keys(setDefaults).forEach(parentKey => {
+  gulpConfigurations[parentKey] = defaultConfig(gulpConfigurations, parentKey, setDefaults[parentKey])
+})
+
+/**
+ * Retrieve a value from teh configurations, default may be returned.
+ * @function
+ * @memberOf module:gulpConfig
+ * @param {string|null} path
+ * @param {*} defaultValue
+ * @returns {*|null}
+ */
+const get = (path = null, defaultValue = null) => defaultConfig(gulpConfigurations, path, defaultValue)
+
+/**
+ * Specify a value for the configurations to use.
+ * @function
+ * @memberOf module:gulpConfig
+ * @param path
+ * @param value
+ * @returns {*}
+ */
+const set = (path, value) => {
+  gulpConfigurations[path] = value
+  return value
+}
+
 module.exports = {
-  browserName: defaultConfig(parentConfig, 'browserName', 'default'),
-  browserPath: defaultConfig(parentConfig, 'browserPath', 'browser'),
-  distMain: defaultConfig(parentConfig, 'distMain', 'dist/main'),
-  distPath: defaultConfig(parentConfig, 'distPath', 'dist'),
-  distSearch: defaultConfig(parentConfig, 'distSearch', 'dist/**/*.js'),
-  nodeOnly: defaultConfig(parentConfig, 'nodeOnly', false),
-  readmeTemplate: defaultConfig(parentConfig, 'readmeTemplate', 'MAIN.md'),
-  srcPath: defaultConfig(parentConfig, 'srcPath', 'src'),
-  srcSearch: defaultConfig(parentConfig, 'srcSearch', 'src/**/!(*.test).js'),
-  testPath: defaultConfig(parentConfig, 'testPath', ['src']),
-  watchSearch: defaultConfig(parentConfig, 'watchSearch', 'src/**/*.js'),
+  defaultConfig,
+  get,
+  set
 }

package/gulpfile.base.js

@@ -1,3 +1,12 @@
+/**
+ * Export these functions to your own project in order to customize your build pipeline.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 2.0.0
+ * @module js-build-tools
+ */
+
+const gulpConfig = require('./gulp.config.js')
 const build = require('./functions/build.js')
 const compileReadme = require('./functions/compileReadme.js')
 const defaultCmd = require('./functions/default.js')

package/package.json

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