js-build-tools 6.6.0 → 6.7.0

package/functions/utilities/convertMjsFilesForDocs.test.mjs

@@ -1,58 +1,58 @@
-/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
-import fs from 'fs'
-import * as setUp from '../test-helpers/setUp.mjs'
-import { convertMjsFilesForDocs } from './convertMjsFilesForDocs.mjs'
-
-setUp.setDefaults('test-temp-convert-mjs-for-docs')
-const gulpConfig = setUp.gulpConfig
-
-const rawContents = '/**\n' +
-  ' * Say hello with a given name.\n' +
-  ' * @memberOf module:greet\n' +
-  ' * @param {string} name\n' +
-  ' * @returns {string}\n' +
-  ' */\n' +
-  'export const sayHello = name => `Hello from ${name}`\n'
-
-beforeEach(() => setUp.beforeEach()
-  .then(() => fs.writeFileSync(gulpConfig.get('srcPath') + '/greet.mjs', rawContents)))
-
-afterEach(setUp.afterEach)
-
-describe('convertMjsFilesForDocs', () => {
-  test('returns an empty result, with a safe no-op cleanUp, for an empty list', () => {
-    const { filePaths, cleanUp } = convertMjsFilesForDocs([])
-    expect(filePaths).toEqual([])
-    expect(() => cleanUp()).not.toThrow()
-  })
-
-  test('writes a rewritten, doc-parseable .js copy outside the project tree', () => {
-    const mjsFilePath = gulpConfig.get('srcPath') + '/greet.mjs'
-    const { filePaths, cleanUp } = convertMjsFilesForDocs([mjsFilePath])
-
-    expect(filePaths).toHaveLength(1)
-    expect(filePaths[0]).toMatch(/greet\.js$/)
-    expect(filePaths[0]).not.toContain(process.cwd())
-
-    const converted = fs.readFileSync(filePaths[0], 'utf8')
-    expect(converted).toContain('const sayHello = name => `Hello from ${name}`')
-    expect(converted).toContain('module.exports = { sayHello }')
-
-    cleanUp()
-    expect(fs.existsSync(filePaths[0])).toBe(false)
-  })
-
-  test('converts several files into the same temp directory', () => {
-    fs.writeFileSync(gulpConfig.get('srcPath') + '/greetAgain.mjs', rawContents.replace('sayHello', 'sayHelloAgain'))
-    const { filePaths, cleanUp } = convertMjsFilesForDocs([
-      gulpConfig.get('srcPath') + '/greet.mjs',
-      gulpConfig.get('srcPath') + '/greetAgain.mjs'
-    ])
-
-    expect(filePaths).toHaveLength(2)
-    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(true))
-
-    cleanUp()
-    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(false))
-  })
-})
+/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
+import fs from 'fs'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { convertMjsFilesForDocs } from './convertMjsFilesForDocs.mjs'
+
+setUp.setDefaults('test-temp-convert-mjs-for-docs')
+const gulpConfig = setUp.gulpConfig
+
+const rawContents = '/**\n' +
+  ' * Say hello with a given name.\n' +
+  ' * @memberOf module:greet\n' +
+  ' * @param {string} name\n' +
+  ' * @returns {string}\n' +
+  ' */\n' +
+  'export const sayHello = name => `Hello from ${name}`\n'
+
+beforeEach(() => setUp.beforeEach()
+  .then(() => fs.writeFileSync(gulpConfig.get('srcPath') + '/greet.mjs', rawContents)))
+
+afterEach(setUp.afterEach)
+
+describe('convertMjsFilesForDocs', () => {
+  test('returns an empty result, with a safe no-op cleanUp, for an empty list', () => {
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([])
+    expect(filePaths).toEqual([])
+    expect(() => cleanUp()).not.toThrow()
+  })
+
+  test('writes a rewritten, doc-parseable .js copy outside the project tree', () => {
+    const mjsFilePath = gulpConfig.get('srcPath') + '/greet.mjs'
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([mjsFilePath])
+
+    expect(filePaths).toHaveLength(1)
+    expect(filePaths[0]).toMatch(/greet\.js$/)
+    expect(filePaths[0]).not.toContain(process.cwd())
+
+    const converted = fs.readFileSync(filePaths[0], 'utf8')
+    expect(converted).toContain('const sayHello = name => `Hello from ${name}`')
+    expect(converted).toContain('module.exports = { sayHello }')
+
+    cleanUp()
+    expect(fs.existsSync(filePaths[0])).toBe(false)
+  })
+
+  test('converts several files into the same temp directory', () => {
+    fs.writeFileSync(gulpConfig.get('srcPath') + '/greetAgain.mjs', rawContents.replace('sayHello', 'sayHelloAgain'))
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([
+      gulpConfig.get('srcPath') + '/greet.mjs',
+      gulpConfig.get('srcPath') + '/greetAgain.mjs'
+    ])
+
+    expect(filePaths).toHaveLength(2)
+    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(true))
+
+    cleanUp()
+    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(false))
+  })
+})

package/functions/utilities/dotGet.mjs

@@ -1,49 +1,49 @@
-import { isObject } from './isObject.mjs'
-import { strAfter } from './strAfter.mjs'
-import { strBefore } from './strBefore.mjs'
-
-/**
- * Get a nested property value from an object.
- * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/dotGet.ts Sí, funciona}
- * @param {Object} [arrayObject={}] - The array or object to get the property from
- * @param {string} [dotNotation=''] - The path to the property
- * @param {string|null} [defaultValue=null] - The default value to return if the property is not found
- * @returns {*} The value of the property
- * @private
- */
-export const dotGet = (arrayObject = {}, dotNotation = '', defaultValue = null) => {
-  if (!dotNotation) {
-    return arrayObject
-  }
-  let key = strBefore(dotNotation, '.')
-  const lastKey = !key
-  if (lastKey) {
-    key = dotNotation
-  }
-  if (key === '*') {
-    const result = []
-    for (const wildKey in arrayObject) {
-      const wildValue = arrayObject[wildKey]
-      if (lastKey) {
-        result[wildKey] = wildValue
-        continue
-      }
-      if (!isObject(wildValue)) {
-        continue
-      }
-      result[wildKey] = dotGet(wildValue, strAfter(dotNotation, '.'), defaultValue)
-    }
-    return result
-  }
-  if (lastKey) {
-    return arrayObject[dotNotation] ?? defaultValue
-  }
-  if (typeof arrayObject[key] === 'undefined') {
-    return defaultValue
-  }
-  const next = arrayObject[key]
-  if (!isObject(next)) {
-    return defaultValue
-  }
-  return dotGet(next, strAfter(dotNotation, '.'), defaultValue)
-}
+import { isObject } from './isObject.mjs'
+import { strAfter } from './strAfter.mjs'
+import { strBefore } from './strBefore.mjs'
+
+/**
+ * Get a nested property value from an object.
+ * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/dotGet.ts Sí, funciona}
+ * @param {Object} [arrayObject={}] - The array or object to get the property from
+ * @param {string} [dotNotation=''] - The path to the property
+ * @param {string|null} [defaultValue=null] - The default value to return if the property is not found
+ * @returns {*} The value of the property
+ * @private
+ */
+export const dotGet = (arrayObject = {}, dotNotation = '', defaultValue = null) => {
+  if (!dotNotation) {
+    return arrayObject
+  }
+  let key = strBefore(dotNotation, '.')
+  const lastKey = !key
+  if (lastKey) {
+    key = dotNotation
+  }
+  if (key === '*') {
+    const result = []
+    for (const wildKey in arrayObject) {
+      const wildValue = arrayObject[wildKey]
+      if (lastKey) {
+        result[wildKey] = wildValue
+        continue
+      }
+      if (!isObject(wildValue)) {
+        continue
+      }
+      result[wildKey] = dotGet(wildValue, strAfter(dotNotation, '.'), defaultValue)
+    }
+    return result
+  }
+  if (lastKey) {
+    return arrayObject[dotNotation] ?? defaultValue
+  }
+  if (typeof arrayObject[key] === 'undefined') {
+    return defaultValue
+  }
+  const next = arrayObject[key]
+  if (!isObject(next)) {
+    return defaultValue
+  }
+  return dotGet(next, strAfter(dotNotation, '.'), defaultValue)
+}

package/functions/utilities/dotNotate.mjs

@@ -1,73 +1,73 @@
-import { isObject } from './isObject.mjs'
-
-/**
- * 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
- * @private
- */
-const handleRetainObjects = (retainObjects = []) => {
-  if (!retainObjects.length) {
-    /**
-     * Bypass the test function if there are no retainObjects.
-     * @returns {false}
-     * @private
-     */
-    return (currentKey, value, results) => false
-  }
-  retainObjects = retainObjects.map(key => key.replaceAll('.', '\\.'))
-  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}
-   * @private
-   */
-  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
- * @param {Function} didRetain - The test function to see if a key should be retained
- * @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
- * @private
- */
-const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
-  for (const key in arrayObject) {
-    const value = arrayObject[key]
-    const currentKey = `${prepend}${key}`
-    if (didRetain(currentKey, value, results)) {
-      continue
-    }
-    // An empty object/array has no keys to flatten into - recursing into one would silently drop currentKey
-    // from the result entirely, rather than keeping it as the empty value it actually is. Treat it as a leaf.
-    if (isObject(value) && Object.keys(value).length) {
-      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
- * @private
- */
-export const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects))
+import { isObject } from './isObject.mjs'
+
+/**
+ * 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
+ * @private
+ */
+const handleRetainObjects = (retainObjects = []) => {
+  if (!retainObjects.length) {
+    /**
+     * Bypass the test function if there are no retainObjects.
+     * @returns {false}
+     * @private
+     */
+    return (currentKey, value, results) => false
+  }
+  retainObjects = retainObjects.map(key => key.replaceAll('.', '\\.'))
+  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}
+   * @private
+   */
+  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
+ * @param {Function} didRetain - The test function to see if a key should be retained
+ * @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
+ * @private
+ */
+const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
+  for (const key in arrayObject) {
+    const value = arrayObject[key]
+    const currentKey = `${prepend}${key}`
+    if (didRetain(currentKey, value, results)) {
+      continue
+    }
+    // An empty object/array has no keys to flatten into - recursing into one would silently drop currentKey
+    // from the result entirely, rather than keeping it as the empty value it actually is. Treat it as a leaf.
+    if (isObject(value) && Object.keys(value).length) {
+      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
+ * @private
+ */
+export const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects))

package/functions/utilities/dotNotate.test.mjs

@@ -1,41 +1,41 @@
-import { dotNotate } from './dotNotate.mjs'
-
-describe('dotNotate', () => {
-  test('flattens a nested object into dot-notation leaves', () => {
-    expect(dotNotate({ a: { b: 'c', d: { e: 'f' } } })).toEqual({ 'a.b': 'c', 'a.d.e': 'f' })
-  })
-
-  test('flattens a non-empty array into index-numbered leaves, same as a plain object', () => {
-    expect(dotNotate({ a: ['x', 'y'] })).toEqual({ 'a.0': 'x', 'a.1': 'y' })
-  })
-
-  test('keeps a primitive value (including null) as its own leaf, unflattened', () => {
-    expect(dotNotate({ a: 1, b: 'two', c: null })).toEqual({ a: 1, b: 'two', c: null })
-  })
-
-  test('keeps an empty object as a leaf value, rather than silently dropping its key', () => {
-    expect(dotNotate({ a: {}, b: 'c' })).toEqual({ a: {}, b: 'c' })
-  })
-
-  test('keeps an empty array as a leaf value, rather than silently dropping its key', () => {
-    expect(dotNotate({ a: [], b: 'c' })).toEqual({ a: [], b: 'c' })
-  })
-
-  test('keeps an empty object/array as a leaf even nested inside other objects', () => {
-    expect(dotNotate({ a: { b: [], c: {} } })).toEqual({ 'a.b': [], 'a.c': {} })
-  })
-
-  test('retains a matching key as a whole object instead of flattening into it', () => {
-    expect(dotNotate({ a: { b: 'c' }, options: { fix: true } }, ['options'])).toEqual({
-      'a.b': 'c',
-      options: { fix: true }
-    })
-  })
-
-  test('treats every dot in a retained key literally, not as a regex wildcard', () => {
-    expect(dotNotate({ a: { bXc: { d: 1 }, b: { c: { d: 2 } } } }, ['a.b.c'])).toEqual({
-      'a.bXc.d': 1,
-      'a.b.c': { d: 2 }
-    })
-  })
-})
+import { dotNotate } from './dotNotate.mjs'
+
+describe('dotNotate', () => {
+  test('flattens a nested object into dot-notation leaves', () => {
+    expect(dotNotate({ a: { b: 'c', d: { e: 'f' } } })).toEqual({ 'a.b': 'c', 'a.d.e': 'f' })
+  })
+
+  test('flattens a non-empty array into index-numbered leaves, same as a plain object', () => {
+    expect(dotNotate({ a: ['x', 'y'] })).toEqual({ 'a.0': 'x', 'a.1': 'y' })
+  })
+
+  test('keeps a primitive value (including null) as its own leaf, unflattened', () => {
+    expect(dotNotate({ a: 1, b: 'two', c: null })).toEqual({ a: 1, b: 'two', c: null })
+  })
+
+  test('keeps an empty object as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: {}, b: 'c' })).toEqual({ a: {}, b: 'c' })
+  })
+
+  test('keeps an empty array as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: [], b: 'c' })).toEqual({ a: [], b: 'c' })
+  })
+
+  test('keeps an empty object/array as a leaf even nested inside other objects', () => {
+    expect(dotNotate({ a: { b: [], c: {} } })).toEqual({ 'a.b': [], 'a.c': {} })
+  })
+
+  test('retains a matching key as a whole object instead of flattening into it', () => {
+    expect(dotNotate({ a: { b: 'c' }, options: { fix: true } }, ['options'])).toEqual({
+      'a.b': 'c',
+      options: { fix: true }
+    })
+  })
+
+  test('treats every dot in a retained key literally, not as a regex wildcard', () => {
+    expect(dotNotate({ a: { bXc: { d: 1 }, b: { c: { d: 2 } } } }, ['a.b.c'])).toEqual({
+      'a.bXc.d': 1,
+      'a.b.c': { d: 2 }
+    })
+  })
+})

package/functions/utilities/dotSet.mjs

@@ -1,40 +1,40 @@
-import { isObject } from './isObject.mjs'
-import { strAfter } from './strAfter.mjs'
-import { strBefore } from './strBefore.mjs'
-
-/**
- * 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}
- * @param {Object} arrayObject - The array or object to set the property on
- * @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
- * @private
- */
-export const dotSet = (arrayObject, dotNotation, value = null) => {
-  let key = strBefore(dotNotation, '.')
-  const lastKey = !key
-  if (lastKey) {
-    key = dotNotation
-  }
-  if (key === '*') {
-    for (const wildKey in arrayObject) {
-      if (lastKey) {
-        arrayObject[wildKey] = value
-        continue
-      }
-      if (!isObject(arrayObject[wildKey])) {
-        continue
-      }
-      dotSet(arrayObject[wildKey], strAfter(dotNotation, '.'), value)
-    }
-    return arrayObject
-  }
-  if (lastKey) {
-    arrayObject[dotNotation] = value
-    return arrayObject
-  }
-  const next = arrayObject[key] ?? []
-  arrayObject[key] = dotSet(next, strAfter(dotNotation, '.'), value)
-  return arrayObject
-}
+import { isObject } from './isObject.mjs'
+import { strAfter } from './strAfter.mjs'
+import { strBefore } from './strBefore.mjs'
+
+/**
+ * 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}
+ * @param {Object} arrayObject - The array or object to set the property on
+ * @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
+ * @private
+ */
+export const dotSet = (arrayObject, dotNotation, value = null) => {
+  let key = strBefore(dotNotation, '.')
+  const lastKey = !key
+  if (lastKey) {
+    key = dotNotation
+  }
+  if (key === '*') {
+    for (const wildKey in arrayObject) {
+      if (lastKey) {
+        arrayObject[wildKey] = value
+        continue
+      }
+      if (!isObject(arrayObject[wildKey])) {
+        continue
+      }
+      dotSet(arrayObject[wildKey], strAfter(dotNotation, '.'), value)
+    }
+    return arrayObject
+  }
+  if (lastKey) {
+    arrayObject[dotNotation] = value
+    return arrayObject
+  }
+  const next = arrayObject[key] ?? []
+  arrayObject[key] = dotSet(next, strAfter(dotNotation, '.'), value)
+  return arrayObject
+}

package/functions/utilities/esmNamedExportsToCjs.mjs

@@ -1,30 +1,30 @@
-/**
- * Rewrites named `export const`/`export function`/`export class` declarations to plain declarations plus a
- * trailing `module.exports = { ... }` - the same shape jsdoc-to-markdown already documents cleanly (a plain
- * declaration with its own `@memberOf` tag, exported all at once at the bottom), rather than the "exports.name"
- * longname jsdoc-to-markdown's own ESM-compat layer produces for an inline `export const name = ...`.
- *
- * This is a narrow, text-level rewrite for documentation purposes only - it does not execute the module, so it
- * only has to look enough like the real thing for jsdoc-to-markdown's parser. It handles the common named-export
- * forms (`export const`, `export function`, `export class`) and leaves everything else (including `export
- * default`, re-exports, and `export { a, b }` lists) untouched in place - a file using one of those keeps its
- * own export line as-is, which jsdoc-to-markdown will document however it already does for ESM.
- * @memberOf module:utilities
- * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
- * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
- * @private
- */
-export const esmNamedExportsToCjs = (source) => {
-  const exportedNames = []
-  const rewritten = source.replace(
-    /^export (const|function|class) (\w+)/gm,
-    (match, keyword, name) => {
-      exportedNames.push(name)
-      return `${keyword} ${name}`
-    }
-  )
-  if (exportedNames.length === 0) {
-    return rewritten
-  }
-  return `${rewritten}\n\nmodule.exports = { ${exportedNames.join(', ')} }\n`
-}
+/**
+ * Rewrites named `export const`/`export function`/`export class` declarations to plain declarations plus a
+ * trailing `module.exports = { ... }` - the same shape jsdoc-to-markdown already documents cleanly (a plain
+ * declaration with its own `@memberOf` tag, exported all at once at the bottom), rather than the "exports.name"
+ * longname jsdoc-to-markdown's own ESM-compat layer produces for an inline `export const name = ...`.
+ *
+ * This is a narrow, text-level rewrite for documentation purposes only - it does not execute the module, so it
+ * only has to look enough like the real thing for jsdoc-to-markdown's parser. It handles the common named-export
+ * forms (`export const`, `export function`, `export class`) and leaves everything else (including `export
+ * default`, re-exports, and `export { a, b }` lists) untouched in place - a file using one of those keeps its
+ * own export line as-is, which jsdoc-to-markdown will document however it already does for ESM.
+ * @memberOf module:utilities
+ * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
+ * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ * @private
+ */
+export const esmNamedExportsToCjs = (source) => {
+  const exportedNames = []
+  const rewritten = source.replace(
+    /^export (const|function|class) (\w+)/gm,
+    (match, keyword, name) => {
+      exportedNames.push(name)
+      return `${keyword} ${name}`
+    }
+  )
+  if (exportedNames.length === 0) {
+    return rewritten
+  }
+  return `${rewritten}\n\nmodule.exports = { ${exportedNames.join(', ')} }\n`
+}