js-build-tools 5.2.0 → 5.3.1

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
-const _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
-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) }
+'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

@@ -3,6 +3,7 @@ import { bundleLint } from './bundleLint.mjs'
 import { bundleMinify } from './bundleMinify.mjs'
 import { clean, distSeries } from './partials.mjs'
 import { compileReadme } from './compileReadme.mjs'
+import { typeDocs } from './typeDocs.mjs'
 import { distLint } from './distLint.mjs'
 import { distMinify } from './distMinify.mjs'
 import { parallel, series } from 'gulp'
@@ -22,7 +23,11 @@ export const build = (done = null) => {
   const distLintMinify = parallel(distLint, distMinify)
   const bundleLintMinify = parallel(bundleLint, bundleMinify)
   const buildActions = [distSeries(), distLintMinify]
-  if (gulpConfig.get('typescript.enabled')) {
+  const generateDocs = gulpConfig.get('docs.enabled')
+  if (generateDocs) {
+    // The documentation is generated from the TypeScript source itself, the readme is written by hand
+    buildActions.push(typeDocs)
+  } else 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)
   }
@@ -34,7 +39,7 @@ export const build = (done = null) => {
   const runActions = [
     series(...buildActions),
   ]
-  if (!gulpConfig.get('typescript.enabled')) {
+  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
     // 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)
   }

package/functions/build.test.mjs

@@ -3,6 +3,7 @@ import * as setUp from './test-helpers/setUp.mjs'
 import { build } from './build.mjs'
 import { clean } from './partials/clean.mjs'
 import { testFull } from './testFull.mjs'
+import { typeDocs } from './typeDocs.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.
@@ -15,6 +16,8 @@ const genericFunction = () => Promise.resolve(true)
 
 jest.mock('./partials/clean.mjs', () => ({ clean: jest.fn(genericFunction) }))
 jest.mock('./testFull.mjs', () => ({ testFull: jest.fn(genericFunction) }))
+// The documentation is generated by TypeDoc, whose own tests cover that (see typeDocsFor.test.mjs)
+jest.mock('./typeDocs.mjs', () => ({ typeDocs: jest.fn(genericFunction) }))
 // tsFor's real implementation loads gulp-ts-compile (a genuine ESM-only package) via a dynamic import() hidden
 // from babel's static analysis - necessary for production correctness (see tsFor.mjs's own comments), but this
 // project's current CommonJS-transform-based Jest setup can't execute a real dynamic import at all: it doesn't
@@ -625,6 +628,31 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('when docs.enabled is set: generates the documentation from the TypeScript source instead of the readme', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const rootPath = gulpConfig.get('rootPath')
+    const tsConfig = `${rootPath}/tsconfig.json`
+    const readmePath = gulpConfig.get('readme.to')
+    const readmeFile = gulpConfig.get('readme.file')
+    fs.writeFileSync(`${srcPath}/main.ts`, mainTypescript)
+    fs.writeFileSync(tsConfig, tsConfigContents)
+    fs.rmSync(`${readmePath}/${readmeFile}`, { force: true })
+    typeDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.config', tsConfig)
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.enabled', true)
+    expect.assertions(3)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      expect(typeDocs).toHaveBeenCalledTimes(1)
+      // The readme is not generated, it is written by hand
+      expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
+      expect(testFull).toHaveBeenCalled()
+      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`
@@ -647,6 +675,7 @@ describe('build', () => {
     gulpConfig.set('images.enabled', false)
     gulpConfig.set('sass.enabled', false)
     gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.enabled', false)
     build(() => {
       expect(events).toEqual(['clean finished', 'testFull started'])
       done()

package/functions/partials/imagesFor.mjs

@@ -1,5 +1,5 @@
 import cache from 'gulp-cache'
-import { createRequire } from 'node:module'
+import { requirePeer } from './loadPeer.mjs'
 import { dest, src } from 'gulp'
 import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
@@ -17,18 +17,12 @@ const installHint = 'Add it to your project with: npm install --save-dev github:
  * @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
-  }
+  const loaded = requirePeer('gulp-imagemin', {
+    task: 'images',
+    installHint,
+    esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
+    projectPath
+  })
   return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded
 }
 

package/functions/partials/loadPeer.mjs

@@ -0,0 +1,75 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Several dependencies ship ESM-only (standard, gulp-ts-compile, typedoc), but this package also publishes a CommonJS
+// build (dist/*.js) whose babel transform would turn even a dynamic import() into a require() that cannot load an ES
+// module. Hiding the import() inside a Function constructor keeps it a genuine dynamic import that works from either
+// build, because babel cannot see (and so cannot rewrite) an import expression which only exists as a runtime string.
+const dynamicImport = new Function('specifier', 'return import(specifier)')
+
+/**
+ * Import an ES module (or any module) with a real dynamic import(), whichever build (ESM or CommonJS) this runs from.
+ * @memberOf module:partials
+ * @param {string} specifier - The package name, or the URL of a file.
+ * @returns {Promise<Object>} The module namespace.
+ */
+export const importModule = specifier => dynamicImport(specifier)
+
+const isMissing = (error, name) => error.code === 'MODULE_NOT_FOUND' && error.message.includes(`'${name}'`)
+
+const notInstalled = (name, { task, installHint }) => new Error(
+  `The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`
+)
+
+/**
+ * Load an optional peer dependency (one which is only needed once a task runs, so projects which never use that task
+ * do not have to install it) with require(), from the project being built rather than from this package. When it is
+ * missing the error explains how to install it.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.esmOnlyMessage] - The error message when the package turns out to be ESM-only (it cannot be require()d).
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {*} Whatever the package exports.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+export const requirePeer = (name, { task, installHint, esmOnlyMessage, projectPath = process.cwd() }) => {
+  try {
+    return createRequire(path.join(projectPath, 'package.json'))(name)
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, { task, installHint })
+    }
+    if (error.code === 'ERR_REQUIRE_ESM' && esmOnlyMessage) {
+      throw new Error(esmOnlyMessage)
+    }
+    throw error
+  }
+}
+
+/**
+ * Import an optional peer dependency which ships ESM-only, from the project being built. See {@link requirePeer}.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Object>} The module namespace.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+export const importPeer = async (name, { task, installHint, projectPath = process.cwd() }) => {
+  let resolved
+  try {
+    resolved = createRequire(path.join(projectPath, 'package.json')).resolve(name)
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, { task, installHint })
+    }
+    throw error
+  }
+  return importModule(pathToFileURL(resolved).href)
+}

package/functions/partials/loadPeer.test.mjs

@@ -0,0 +1,58 @@
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { importModule, importPeer, requirePeer } from './loadPeer.mjs'
+
+setUp.setDefaults('test-load-peer')
+
+const options = { task: 'example', installHint: 'Install it with: npm install --save-dev fake-peer' }
+
+// A project with its own node_modules, so the packages are found from the project rather than from this package
+const projectWith = (name, files) => {
+  const project = path.resolve('test-load-peer/project')
+  fs.mkdirSync(`${project}/node_modules/${name}`, { recursive: true })
+  fs.writeFileSync(`${project}/package.json`, '{}')
+  Object.entries(files).forEach(([file, contents]) => fs.writeFileSync(`${project}/node_modules/${name}/${file}`, contents))
+  return project
+}
+
+beforeEach(setUp.beforeEach)
+afterEach(setUp.afterEach)
+
+describe('requirePeer', () => {
+  test('loads the package from the project being built', () => {
+    const project = projectWith('fake-peer', { 'package.json': '{"name":"fake-peer","main":"index.js"}', 'index.js': 'module.exports = { found: true }' })
+    expect(requirePeer('fake-peer', { ...options, projectPath: project })).toEqual({ found: true })
+  })
+
+  test('explains how to install the package when the project does not have it', () => {
+    expect(() => requirePeer('fake-peer', { ...options, projectPath: '/' })).toThrow(
+      'The example task needs the optional peer dependency fake-peer, which is not installed. Install it with: npm install --save-dev fake-peer'
+    )
+  })
+
+  test('does not hide other errors, and explains a package which is ESM-only when it has a message for that', () => {
+    const project = projectWith('broken-peer', { 'package.json': '{"name":"broken-peer","main":"index.js"}', 'index.js': 'throw new Error("boom")' })
+    expect(() => requirePeer('broken-peer', { ...options, projectPath: project })).toThrow('boom')
+    // A missing dependency of the peer is not the peer being missing
+    const inner = projectWith('inner-peer', { 'package.json': '{"name":"inner-peer","main":"index.js"}', 'index.js': 'require("something-else-missing")' })
+    expect(() => requirePeer('inner-peer', { ...options, projectPath: inner })).toThrow(/something-else-missing/)
+    expect(() => requirePeer('inner-peer', { ...options, projectPath: inner })).not.toThrow(/optional peer dependency/)
+  })
+})
+
+describe('importPeer', () => {
+  test('explains how to install the package when the project does not have it', async () => {
+    await expect(importPeer('fake-peer', { ...options, projectPath: '/' })).rejects.toThrow(
+      /needs the optional peer dependency fake-peer, which is not installed. Install it with/
+    )
+  })
+})
+
+describe('importModule', () => {
+  // The real import() cannot run under this project's CommonJS-transform-based Jest setup (see tsFor.mjs), so the
+  // loaders are checked by running the tasks for real, see the pull request.
+  test('is a function', () => {
+    expect(importModule).toBeInstanceOf(Function)
+  })
+})

package/functions/partials/standardLint.mjs

@@ -1,11 +1,9 @@
 import path from 'node:path'
 import through from 'through2'
+import { importModule } from './loadPeer.mjs'
 
-// `standard` (17+) ships ESM-only, but this package also publishes a CommonJS build (dist/*.js) whose babel
-// transform would turn even a dynamic import() into a require() that cannot load an ES module. Hiding the import()
-// inside a Function constructor keeps it a genuine dynamic import that works from either build (same escape hatch
-// as tsFor.mjs uses for gulp-ts-compile).
-const importStandard = new Function('return import(\'standard\')')
+// `standard` (17+) ships ESM-only, see importModule for how it is imported.
+const importStandard = () => importModule('standard')
 
 /**
  * Print a file's lint messages, if it has any.

package/functions/partials/tsFor.mjs

@@ -1,17 +1,10 @@
 import { dest, src } from 'gulp'
 import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
-import { createRequire } from 'node:module'
+import { importModule, requirePeer } from './loadPeer.mjs'
 
-// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json) since it's meant to be consumed by
-// gulpfiles running under a real ESM loader, same as this project's own gulpfile.mjs does. This project also
-// compiles itself to a CommonJS build (dist/*.js, this file's own compiled counterpart) for consumers using
-// require() though, and even a dynamic `import()` gets downleveled by babel's CommonJS transform into a
-// require() call - which can't load a real ES module. Hiding the import() call inside a Function constructor is
-// the standard escape hatch: babel can't see (and so can't rewrite) an import expression that only exists as a
-// runtime-evaluated string, so it survives as a genuine dynamic import, capable of loading gulp-ts-compile from
-// either build.
-const importGulpTsCompile = new Function('return import(\'gulp-ts-compile\')')
+// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json), see importModule for how it is imported.
+const importGulpTsCompile = () => importModule('gulp-ts-compile')
 
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
@@ -29,16 +22,7 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @returns {Object} The TypeScript compiler API module.
  * @throws {Error} With install instructions when typescript is not installed.
  */
-export const loadTypescript = (projectPath = process.cwd()) => {
-  try {
-    return createRequire(path.join(projectPath, 'package.json'))('typescript')
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'typescript'/.test(error.message)) {
-      throw new Error(`The typescript task needs the optional peer dependency typescript, which is not installed. ${installHint}`)
-    }
-    throw error
-  }
-}
+export const loadTypescript = (projectPath = process.cwd()) => requirePeer('typescript', { task: 'typescript', installHint, projectPath })
 
 const streamToPromise = (stream) => new Promise((resolve, reject) => {
   stream.on('finish', resolve)