js-build-tools 6.0.0 → 6.2.0

package/functions/utilities/dotNotate.test.mjs

@@ -0,0 +1,34 @@
+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 }
+    })
+  })
+})

package/functions/utilities/getBundleConfigs.mjs

@@ -16,7 +16,7 @@ export const getBundleConfigs = () => {
     ignore: gulpConfig.get('browser.ignore'),
     exclude: gulpConfig.get('browser.exclude')
   }
-  const additional = gulpConfig.get('browser.bundles') || []
+  const additional = gulpConfig.get('browser.bundles')
   return [
     primary,
     ...additional.map((bundleConfig) => ({

package/gulp.config.mjs

@@ -45,6 +45,15 @@ import { fileExists } from 'test-filesystem'
  * Any single configuration option is a Setting.
  * @typedef {ArrayableSetting|BooleanSetting|FlagsSetting|StringSetting} Setting
  */
+/**
+ * One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
+ * @typedef {Object} module:gulpConfig~CopyFilesEntry
+ * @property {ArrayableSetting} from - The glob pattern(s) of files to copy.
+ * @property {StringSetting} to - The directory to copy them into.
+ * @property {FlagStringSetting} base - Optional base for gulp's own src(pattern, {base}), to preserve a glob's
+ * own subdirectory structure in the destination instead of flattening it. false (the default) uses gulp's own
+ * default base behaviour.
+ */
 /**
  * Configurations for building the browser files.
  * @typedef {Object<string, Setting>} module:gulpConfig~BrowserConfig
@@ -96,6 +105,16 @@ import { fileExists } from 'test-filesystem'
  * @property {StringSetting} from - Path to search for images.
  * @property {StringSetting} to - Path to output images.
  */
+/**
+ * Configurations for linting (see {@link module:partials.neostandardLint}).
+ * @typedef {Object<string, Setting>} module:gulpConfig~LintConfig
+ * @property {Object<string, *>} rules - ESLint rule overrides layered on top of neostandard's own config, scoped
+ * to the same files neostandard itself lints. For a rule that is wrong for your project specifically (for example
+ * a test fixture that deliberately contains text neostandard mistakes for a real syntax problem), rather than
+ * something to fix in your code. Empty by default: a project that never sets this gets exactly neostandard's own
+ * rules, unchanged. Keyed and valued exactly as ESLint's own `rules` object - see
+ * https://eslint.org/docs/latest/use/configure/rules.
+ */
 /**
  * Configurations to compile and generate the Readme file.
  * @typedef {Object<string, Setting>} module:gulpConfig~ReadmeConfig
@@ -109,16 +128,24 @@ import { fileExists } from 'test-filesystem'
  * @property {StringSetting} to - The directory to output the readme file in.
  */
 /**
- * Configurations for generating the HTML documentation of a TypeScript project (with TypeDoc, from the source).
+ * Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+ * TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
  * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
- * @property {BooleanSetting} enabled - Toggle generating the documentation from the TypeScript source. When it is on the
+ * @property {BooleanSetting} enabled - Toggle generating the documentation from the source. When it is on the
  * build does this instead of generating the readme from the jsdoc comments of the compiled files.
- * @property {StringSetting} from - The directory holding the TypeScript source, each folder in it becomes a module.
+ * @property {StringSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
+ * is scanned recursively (jsdoc).
  * @property {StringSetting} index - The markdown file used as the front page of the documentation.
- * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None.
+ * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
+ * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
+ * 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working
+ * exactly as it already does; set this explicitly to override that inference either way.
+ * @property {StringSetting} theme - The jsdoc theme package to use (only meaningful when method is 'jsdoc' - TypeDoc
+ * keeps its own default regardless). Defaults to 'clean-jsdoc-theme'.
  * @property {StringSetting} title - The name of the documentation, defaults to the name in the package.json.
  * @property {StringSetting} to - The directory to generate the documentation in (it is cleared first).
- * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with, defaults to the one of typescript.config.
+ * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with (TypeDoc only), defaults to the
+ * one of typescript.config.
  */
 /**
  * Configurations to compile and copy the sass files into css.
@@ -149,10 +176,14 @@ import { fileExists } from 'test-filesystem'
  * @typedef {Object<string, Setting>} module:gulpConfig~Configurations
  * @property {BrowserConfig} browser - Browser bundling configuration group.
  * @property {ArrayableSetting} cleanPaths - The paths for directories to delete before build.
+ * @property {Array<CopyFilesEntry>} copyFiles - Files to copy elsewhere, run via the copyFiles task - never
+ * automatically as part of build, since what this copies is often the live, publicly-reachable version of
+ * something (e.g. a bundle), and publishing it should be a deliberate step.
  * @property {DistConfig} dist - Distribution file generation configuration group.
  * @property {DocsConfig} docs - Generate the documentation of a TypeScript project configuration group.
  * @property {FontConfig} fonts - Fonts copy configuration group.
  * @property {ImageConfig} images - Minify and copy the images configuration.
+ * @property {LintConfig} lint - Linting configuration group.
  * @property {ReadmeConfig} readme - Build readme files configuration.
  * @property {StringSetting} rootPath - Base directory of the project.
  * @property {SassConfig} sass - Compile CSS from SASS configuration.
@@ -176,6 +207,7 @@ const setDefaults = {
     to: 'browser',
   },
   cleanPaths: ['dist', 'browser'],
+  copyFiles: [],
   dist: {
     from: 'src/**/!(*.test).js',
     main: 'dist/main',
@@ -186,6 +218,8 @@ const setDefaults = {
     from: 'src',
     index: 'MAIN.md',
     logLevel: 'Warn',
+    method: false,
+    theme: 'clean-jsdoc-theme',
     title: '',
     to: 'docs',
     tsconfig: false,
@@ -200,6 +234,9 @@ const setDefaults = {
     from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
     to: 'browser/img',
   },
+  lint: {
+    rules: {},
+  },
   readme: {
     file: 'README.md',
     from: 'src/**/!(*.test).js',

package/gulpfile.base.mjs

@@ -9,12 +9,14 @@ export { build } from './functions/build.mjs'
 export { bundle } from './functions/bundle.mjs'
 export { bundleMinify } from './functions/bundleMinify.mjs'
 export { compileReadme as readme } from './functions/compileReadme.mjs'
+export { copyFiles } from './functions/copyFiles.mjs'
 export { copyFonts } from './functions/copyFonts.mjs'
 export { defaultCmd } from './functions/default.mjs'
 export { dist } from './functions/dist.mjs'
 export { distMinify } from './functions/distMinify.mjs'
 export * as gulpConfig from './gulp.config.mjs'
 export { images } from './functions/images.mjs'
+export { jsdocDocs } from './functions/jsdocDocs.mjs'
 export * as partials from './functions/partials.mjs'
 export { sass } from './functions/sass.mjs'
 export { sourceLint } from './functions/sourceLint.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -79,14 +79,22 @@
     "vinyl-source-stream": "^2.0.0"
   },
   "peerDependencies": {
+    "clean-jsdoc-theme": ">=4.0.0",
     "gulp-imagemin": ">=9.0.0",
+    "jsdoc": ">=4.0.0",
     "typedoc": ">=0.28.0",
     "typescript": ">=5.0.0 <7.0.0"
   },
   "peerDependenciesMeta": {
+    "clean-jsdoc-theme": {
+      "optional": true
+    },
     "gulp-imagemin": {
       "optional": true
     },
+    "jsdoc": {
+      "optional": true
+    },
     "typedoc": {
       "optional": true
     },
@@ -106,7 +114,9 @@
   ],
   "funding": "https://www.paypal.com/donate/?business=LRYR6SZRWKXVY&no_recurring=0&item_name=Let%27s+build+together+today+to+simplify+our+jobs+tomorrow.&currency_code=CAD",
   "devDependencies": {
+    "clean-jsdoc-theme": "^5.2.0",
     "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
+    "jsdoc": "^4.0.5",
     "typedoc": "^0.28.20",
     "typescript": "^6.0.3"
   },