js-build-tools 4.1.1 → 5.1.0

package/dist/utilities/dotNotate.js

@@ -1,43 +1,43 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.dotNotate = void 0;
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.map.js");
-var _isObject = require("./isObject.js");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dotNotate = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var _isObject = require("./isObject.js");
 /**
  * Convert an array of keys into a regex, return a function to test if incoming keys match.
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Function} The dot-notated array
- */
-const handleRetainObjects = (retainObjects = []) => {
-  if (!retainObjects.length) {
+ */
+const handleRetainObjects = (retainObjects = []) => {
+  if (!retainObjects.length) {
     /**
      * Bypass the test function if there are no retainObjects.
      * @returns {false}
-     */
-    return (currentKey, value, results) => false;
-  }
-  retainObjects = retainObjects.map(key => key.replace('\.', '\\.'));
-  const retainRegex = new RegExp(`(${retainObjects.join('|')})$`);
+     */
+    return (currentKey, value, results) => false;
+  }
+  retainObjects = retainObjects.map(key => key.replace('\.', '\\.'));
+  const retainRegex = new RegExp(`(${retainObjects.join('|')})$`);
   /**
    * Test if a key should be retained as an object.
    * @param {string} currentKey - The key to test
    * @param {*} value - The value of the key
    * @param {Object} results - The result object to add to
    * @returns {boolean}
-   */
-  return (currentKey, value, results) => {
-    if (!currentKey.match(retainRegex)) {
-      return false;
-    }
-    results[currentKey] = value;
-    return true;
-  };
-};
-
+   */
+  return (currentKey, value, results) => {
+    if (!currentKey.match(retainRegex)) {
+      return false;
+    }
+    results[currentKey] = value;
+    return true;
+  };
+};
+
 /**
  * The underlying logic function for converting arrays to dot-notation.
  * @param {Object} arrayObject - The array or object to dot-notate
@@ -45,29 +45,29 @@ const handleRetainObjects = (retainObjects = []) => {
  * @param {string} [prepend=''] - The path for the property being processed
  * @param {Object<string, *>} [results={}] - The final notated object to return
  * @returns {Object<string, *>} The dot-notated object
- */
-const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
-  for (let key in arrayObject) {
-    const value = arrayObject[key];
-    const currentKey = `${prepend}${key}`;
-    if (didRetain(currentKey, value, results)) {
-      continue;
-    }
-    if ((0, _isObject.isObject)(value)) {
-      performDotNotate(value, didRetain, `${currentKey}.`, results);
-      continue;
-    }
-    results[currentKey] = value;
-  }
-  return results;
-};
-
+ */
+const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
+  for (let key in arrayObject) {
+    const value = arrayObject[key];
+    const currentKey = `${prepend}${key}`;
+    if (didRetain(currentKey, value, results)) {
+      continue;
+    }
+    if ((0, _isObject.isObject)(value)) {
+      performDotNotate(value, didRetain, `${currentKey}.`, results);
+      continue;
+    }
+    results[currentKey] = value;
+  }
+  return results;
+};
+
 /**
  * Convert an array or object to a single dimensional associative array with dot notation.
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/dotNotate.ts Sí, funciona}
  * @param {Object} arrayObject - The array or object to dot-notate
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Object<string, *>} The dot-notated object
- */
-const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects));
+ */
+const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects));
 exports.dotNotate = dotNotate;

package/dist/utilities/dotSet.js

@@ -1,12 +1,12 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.dotSet = void 0;
-var _isObject = require("./isObject.js");
-var _strAfter = require("./strAfter.js");
-var _strBefore = require("./strBefore.js");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dotSet = void 0;
+var _isObject = require("./isObject.js");
+var _strAfter = require("./strAfter.js");
+var _strBefore = require("./strBefore.js");
 /**
  * Set a nested property value an object.
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/dotSet.ts Sí, funciona}
@@ -14,32 +14,32 @@ var _strBefore = require("./strBefore.js");
  * @param {string} dotNotation - The path for the property
  * @param {*} value - The default value to return if the property is not found
  * @returns {Object} The modified object
- */
-const dotSet = (arrayObject, dotNotation, value = null) => {
-  let key = (0, _strBefore.strBefore)(dotNotation, '.');
-  const lastKey = !key;
-  if (lastKey) {
-    key = dotNotation;
-  }
-  if (key === '*') {
-    for (let wildKey in arrayObject) {
-      if (lastKey) {
-        arrayObject[wildKey] = value;
-        continue;
-      }
-      if (!(0, _isObject.isObject)(arrayObject[wildKey])) {
-        continue;
-      }
-      dotSet(arrayObject[wildKey], (0, _strAfter.strAfter)(dotNotation, '.'), value);
-    }
-    return arrayObject;
-  }
-  if (lastKey) {
-    arrayObject[dotNotation] = value;
-    return arrayObject;
-  }
-  const next = arrayObject[key] ?? [];
-  arrayObject[key] = dotSet(next, (0, _strAfter.strAfter)(dotNotation, '.'), value);
-  return arrayObject;
-};
+ */
+const dotSet = (arrayObject, dotNotation, value = null) => {
+  let key = (0, _strBefore.strBefore)(dotNotation, '.');
+  const lastKey = !key;
+  if (lastKey) {
+    key = dotNotation;
+  }
+  if (key === '*') {
+    for (let wildKey in arrayObject) {
+      if (lastKey) {
+        arrayObject[wildKey] = value;
+        continue;
+      }
+      if (!(0, _isObject.isObject)(arrayObject[wildKey])) {
+        continue;
+      }
+      dotSet(arrayObject[wildKey], (0, _strAfter.strAfter)(dotNotation, '.'), value);
+    }
+    return arrayObject;
+  }
+  if (lastKey) {
+    arrayObject[dotNotation] = value;
+    return arrayObject;
+  }
+  const next = arrayObject[key] ?? [];
+  arrayObject[key] = dotSet(next, (0, _strAfter.strAfter)(dotNotation, '.'), value);
+  return arrayObject;
+};
 exports.dotSet = dotSet;

package/dist/utilities/isObject.js

@@ -1,14 +1,14 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.isObject = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isObject = void 0;
 /**
  * Check if the provided thing is an object / array.
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/isObject.ts Sí, funciona}
  * @param {*} object
  * @returns {boolean}
- */
-const isObject = object => typeof object === 'object' && object !== null;
+ */
+const isObject = object => typeof object === 'object' && object !== null;
 exports.isObject = isObject;

package/dist/utilities/strAfter.js

@@ -1,18 +1,18 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.strAfter = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.strAfter = void 0;
 /**
  * Retrieve the string part after the search match.
  * Original source from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/strings/strAfter.ts Sí, funciona}
  * @param {string} str
  * @param {string} search
  * @returns {string}
- */
-const strAfter = (str, search) => {
-  const index = str.indexOf(search);
-  return index === -1 ? '' : str.substring(index + search.length);
-};
+ */
+const strAfter = (str, search) => {
+  const index = str.indexOf(search);
+  return index === -1 ? '' : str.substring(index + search.length);
+};
 exports.strAfter = strAfter;

package/dist/utilities/strBefore.js

@@ -1,18 +1,18 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.strBefore = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.strBefore = void 0;
 /**
  * Retrieve the string part before the search match.
  * Original source from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/strings/strBefore.ts Sí, funciona}
  * @param {string} str
  * @param {string} search
  * @returns {string}
- */
-const strBefore = (str, search) => {
-  const index = str.indexOf(search);
-  return index === -1 ? '' : str.slice(0, index);
-};
+ */
+const strBefore = (str, search) => {
+  const index = str.indexOf(search);
+  return index === -1 ? '' : str.slice(0, index);
+};
 exports.strBefore = strBefore;

package/dist/watchFull.js

@@ -1,14 +1,14 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.watchFull = void 0
-var _partials = require('./partials.js')
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.watchFull = void 0
+const _partials = require('./partials.js')
 /**
  * Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
  * @memberOf module:js-build-tools
  * @returns {FSWatcher}
- */
-const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange)
-exports.watchFull = watchFull
+ */
+const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange)
+exports.watchFull = watchFull

package/dist/watchTest.js

@@ -1,20 +1,20 @@
-'use strict'
-
-require('core-js/modules/esnext.weak-map.delete-all.js')
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.watchTest = void 0
-var gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
-var _gulp = require('gulp')
-var _testQuick = require('./testQuick.js')
-function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(); var n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o; var i; var f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
+'use strict'
+
+require('core-js/modules/esnext.weak-map.delete-all.js')
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.watchTest = void 0
+const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
+const _gulp = require('gulp')
+const _testQuick = require('./testQuick.js')
+function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
 /**
  * Watch for changes and run the tests.
  * @memberOf module:js-build-tools
  * @returns {*}
- */
-const watchTest = () => (0, _gulp.watch)(gulpConfig.get('test.watch'), {
-  ignoreInitial: false
-}, _testQuick.testQuick)
-exports.watchTest = watchTest
+ */
+const watchTest = () => (0, _gulp.watch)(gulpConfig.get('test.watch'), {
+  ignoreInitial: false
+}, _testQuick.testQuick)
+exports.watchTest = watchTest

package/functions/build.mjs

@@ -21,7 +21,7 @@ import { testFull } from './testFull.mjs'
 export const build = (done = null) => {
   const distLintMinify = parallel(distLint, distMinify)
   const bundleLintMinify = parallel(bundleLint, bundleMinify)
-  const buildActions = [clean, distSeries(), distLintMinify]
+  const buildActions = [distSeries(), distLintMinify]
   if (gulpConfig.get('typescript.enabled')) {
     // 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)
@@ -51,7 +51,10 @@ export const build = (done = null) => {
     // Conditionally add SASS process
     runActions.push(sass)
   }
-  return parallel(
-    ...runActions
+  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
+  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
+  return series(
+    clean,
+    parallel(...runActions)
   )(done)
 }

package/functions/build.test.mjs

@@ -5,6 +5,9 @@ import { clean } from './partials/clean.mjs'
 import { testFull } from './testFull.mjs'
 import { countMatches } from 'test-filesystem'
 
+// Run the real Standard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
+jest.mock('./partials/standardLint.mjs', () => require('./test-helpers/standardLintWithRealStandard.mjs'))
+
 setUp.setDefaults('test-build')
 const gulpConfig = setUp.gulpConfig
 
@@ -621,4 +624,32 @@ describe('build', () => {
       done()
     })
   }, 30000)
+
+  test('finishes clean before starting the tasks that write into the output folders', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const sourcesPath = `${srcPath}/sources`
+    fs.writeFileSync(`${sourcesPath}/file1.js`, file1Contents)
+    fs.writeFileSync(`${sourcesPath}/file2.js`, file2Contents)
+    fs.writeFileSync(`${srcPath}/main.js`, mainFileContents)
+    expect.assertions(1)
+    const events = []
+    clean.mockImplementationOnce(() => new Promise(resolve => setTimeout(() => {
+      events.push('clean finished')
+      resolve(true)
+    }, 100)))
+    testFull.mockImplementationOnce(() => {
+      events.push('testFull started')
+      return Promise.resolve(true)
+    })
+    // Earlier tests leave these enabled, so state them explicitly to keep this test independent of test order.
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('fonts.enabled', false)
+    gulpConfig.set('images.enabled', false)
+    gulpConfig.set('sass.enabled', false)
+    gulpConfig.set('typescript.enabled', false)
+    build(() => {
+      expect(events).toEqual(['clean finished', 'testFull started'])
+      done()
+    })
+  }, 30000)
 })

package/functions/bundleLint.mjs

@@ -1,6 +1,6 @@
 import { dest, src } from 'gulp'
 import * as gulpConfig from '../gulp.config.mjs'
-import standard from 'gulp-standard'
+import { standardLint } from './partials/standardLint.mjs'
 
 /**
  * Applies Standard code style linting to bundled file.
@@ -8,9 +8,5 @@ import standard from 'gulp-standard'
  * @returns {stream.Stream}
  */
 export const bundleLint = () => src(`${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`)
-  .pipe(standard({ fix: true }))
-  .pipe(standard.reporter('default', {
-    fix: true,
-    quiet: true
-  }))
+  .pipe(standardLint({ fix: true }))
   .pipe(dest(gulpConfig.get('browser.to')))

package/functions/bundleLint.test.mjs

@@ -3,6 +3,9 @@ import * as setUp from './test-helpers/setUp.mjs'
 import { bundleLint } from './bundleLint.mjs'
 import { countMatches } from 'test-filesystem'
 
+// Run the real Standard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
+jest.mock('./partials/standardLint.mjs', () => require('./test-helpers/standardLintWithRealStandard.mjs'))
+
 setUp.setDefaults('test-bundle-lint')
 const gulpConfig = setUp.gulpConfig
 

package/functions/distLint.mjs

@@ -1,6 +1,6 @@
 import * as gulpConfig from '../gulp.config.mjs'
 import { dest, src } from 'gulp'
-import standard from 'gulp-standard'
+import { standardLint } from './partials/standardLint.mjs'
 
 /**
  * Applies Standard code style linting to distribution files.
@@ -8,9 +8,5 @@ import standard from 'gulp-standard'
  * @returns {*}
  */
 export const distLint = () => src(gulpConfig.get('browser.from'))
-  .pipe(standard({ fix: true }))
-  .pipe(standard.reporter('default', {
-    fix: true,
-    quiet: true
-  }))
+  .pipe(standardLint({ fix: true }))
   .pipe(dest(gulpConfig.get('dist.to')))

package/functions/distLint.test.mjs

@@ -3,6 +3,9 @@ import * as setUp from './test-helpers/setUp.mjs'
 import { distLint } from './distLint.mjs'
 import { countMatches } from 'test-filesystem'
 
+// Run the real Standard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
+jest.mock('./partials/standardLint.mjs', () => require('./test-helpers/standardLintWithRealStandard.mjs'))
+
 setUp.setDefaults('test-dist-lint')
 const gulpConfig = setUp.gulpConfig
 

package/functions/partials/copyFor.mjs

@@ -7,5 +7,6 @@ import { dest, src } from 'gulp'
  * @param {string} destPath
  * @returns {stream.Stream}
  */
-export const copyFor = (srcPath, destPath) => src(srcPath)
+// encoding: false copies the bytes untouched - Gulp 5's default utf8 handling corrupts binary files such as fonts.
+export const copyFor = (srcPath, destPath) => src(srcPath, { encoding: false })
   .pipe(dest(destPath))

package/functions/partials/copyFor.test.mjs

@@ -32,4 +32,22 @@ describe('copyFor', () => {
         done()
       })
   })
+
+  test('copies binary files byte for byte, including a leading BOM and bytes above 0x7f', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const binaryFile = `${srcPath}/font.woff`
+    const original = Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(Array.from({ length: 512 }, (_, i) => i % 256))])
+    fs.writeFileSync(binaryFile, original)
+    expect.assertions(1)
+    const browserPath = gulpConfig.get('browser.to')
+    copyFor(binaryFile, browserPath)
+      .on('finish', () => {
+        expect(fs.readFileSync(`${browserPath}/font.woff`).equals(original)).toBeTruthy()
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
 })

package/functions/partials/imagesFor.mjs

@@ -1,7 +1,36 @@
 import cache from 'gulp-cache'
+import { createRequire } from 'node:module'
 import { dest, src } from 'gulp'
+import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
-import imagemin from 'gulp-imagemin'
+
+const installHint = 'Add it to your project with: npm install --save-dev github:jheagle/gulp-imagemin#common-js-compatibility ' +
+  '(the CommonJS-compatible fork - upstream gulp-imagemin is ESM-only and cannot be require()d by this package\'s CommonJS build).'
+
+/**
+ * Load `gulp-imagemin`, an optional peer dependency: image optimization is off by default and its binary-download
+ * dependency chain is heavy, so it is only required once the images task actually runs, and it is resolved from the
+ * consuming project's own directory rather than from this package.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] - The project directory to resolve `gulp-imagemin` from.
+ * @returns {Function} The gulp-imagemin plugin factory.
+ * @throws {Error} With install instructions when gulp-imagemin is missing or is the ESM-only upstream release.
+ */
+export const loadImagemin = (projectPath = process.cwd()) => {
+  let loaded
+  try {
+    loaded = createRequire(path.join(projectPath, 'package.json'))('gulp-imagemin')
+  } catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'gulp-imagemin'/.test(error.message)) {
+      throw new Error(`The images task needs the optional peer dependency gulp-imagemin, which is not installed. ${installHint}`)
+    }
+    if (error.code === 'ERR_REQUIRE_ESM') {
+      throw new Error(`gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`)
+    }
+    throw error
+  }
+  return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded
+}
 
 /**
  * Move and optimize images into the browser directory.
@@ -10,8 +39,10 @@ import imagemin from 'gulp-imagemin'
  * @param {string} [imageDest=dest/image/folder]
  * @return {stream.Stream}
  */
-export const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest = gulpConfig.get('images.to')) =>
-  src(imageSrc)
+export const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest = gulpConfig.get('images.to')) => {
+  const imagemin = loadImagemin()
+  // Gulp 5 reads files as utf8 text unless told otherwise, which corrupts binary images (and makes gulp-cache drop them).
+  return src(imageSrc, { encoding: false })
     .pipe(
       // Caching images that ran through imagemin
       cache(
@@ -23,3 +54,4 @@ export const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest =
       )
     )
     .pipe(dest(imageDest))
+}