js-build-tools 1.2.3 → 2.1.1

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.1",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "scripts": {
@@ -47,6 +47,7 @@
     "gulp-babel": "^8.0.0",
     "gulp-rename": "^2.0.0",
     "gulp-standard": "^14.0.0",
+    "gulp-typescript": "^6.0.0-alpha.1",
     "gulp-uglify-es": "^3.0.0",
     "jest": "^29.6.4",
     "jest-environment-jsdom": "^29.6.4",

package/dist/addToReadme.js

@@ -1,22 +0,0 @@
-'use strict'
-
-const fs = require('fs')
-const gulpConfig = require('../gulp.config.js')
-const jsdoc2md = require('jsdoc-to-markdown')
-const {
-  globSync
-} = require('glob')
-
-/**
- * Appends all the jsdoc comments to the readme file. Assumes empty or templated file.
- * @returns {string|Uint8Array}
- */
-const addToReadme = done => {
-  const files = globSync(gulpConfig.srcSearch)
-  const readme = jsdoc2md.renderSync({
-    files: files
-  })
-  fs.appendFileSync('README.md', readme, 'utf8')
-  done()
-}
-module.exports = addToReadme

package/dist/addToReadme.min.js

@@ -1 +0,0 @@
-"use strict";const fs=require("fs"),gulpConfig=require("../gulp.config.js"),jsdoc2md=require("jsdoc-to-markdown"),{globSync:globSync}=require("glob"),addToReadme=e=>{const o=globSync(gulpConfig.srcSearch),d=jsdoc2md.renderSync({files:o});fs.appendFileSync("README.md",d,"utf8"),e()};module.exports=addToReadme;

package/dist/clean.js

@@ -1,11 +0,0 @@
-'use strict'
-
-const del = require('del')
-const gulpConfig = require('../gulp.config.js')
-
-/**
- * Deletes all the distribution and browser files (used before create a new build).
- * @returns {Promise<string[]> | *}
- */
-const clean = () => del([gulpConfig.distPath, gulpConfig.browserPath])
-module.exports = clean

package/dist/clean.min.js

@@ -1 +0,0 @@
-"use strict";const del=require("del"),gulpConfig=require("../gulp.config.js"),clean=()=>del([gulpConfig.distPath,gulpConfig.browserPath]);module.exports=clean;

package/dist/distFor.js

@@ -1,21 +0,0 @@
-'use strict'
-
-const babel = require('gulp-babel')
-const {
-  dest,
-  src
-} = require('gulp')
-const gulpConfig = require('../gulp.config.js')
-
-/**
- * Build the distribution for a given source pattern.
- * @param {string|array} srcPath
- * @param {string} destPath
- * @returns {*}
- */
-const distFor = function () {
-  const srcPath = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : gulpConfig.srcSearch
-  const destPath = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : gulpConfig.distPath
-  return src(srcPath).pipe(babel()).pipe(dest(destPath))
-}
-module.exports = distFor

package/dist/distFor.min.js

@@ -1 +0,0 @@
-"use strict";const babel=require("gulp-babel"),{dest:dest,src:src}=require("gulp"),gulpConfig=require("../gulp.config.js"),distFor=function(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:gulpConfig.srcSearch,r=arguments.length>1&&void 0!==arguments[1]?arguments[1]:gulpConfig.distPath;return src(e).pipe(babel()).pipe(dest(r))};module.exports=distFor;

package/dist/readmeTemplate.js

@@ -1,15 +0,0 @@
-'use strict'
-
-const {
-  dest,
-  src
-} = require('gulp')
-const gulpConfig = require('../gulp.config.js')
-const rename = require('gulp-rename')
-
-/**
- * Copy a readme template into the README.md file.
- * @returns {*}
- */
-const readmeTemplate = () => src(gulpConfig.readmeTemplate).pipe(rename('README.md')).pipe(dest('.'))
-module.exports = readmeTemplate

package/dist/readmeTemplate.min.js

@@ -1 +0,0 @@
-"use strict";const{dest:dest,src:src}=require("gulp"),gulpConfig=require("../gulp.config.js"),rename=require("gulp-rename"),readmeTemplate=()=>src(gulpConfig.readmeTemplate).pipe(rename("README.md")).pipe(dest("."));module.exports=readmeTemplate;

package/functions/addToReadme.js

@@ -1,17 +0,0 @@
-const fs = require('fs')
-const gulpConfig = require('../gulp.config.js')
-const jsdoc2md = require('jsdoc-to-markdown')
-const { globSync } = require('glob')
-
-/**
- * Appends all the jsdoc comments to the readme file. Assumes empty or templated file.
- * @returns {string|Uint8Array}
- */
-const addToReadme = done => {
-  const files = globSync(gulpConfig.srcSearch)
-  const readme = jsdoc2md.renderSync({ files: files })
-  fs.appendFileSync('README.md', readme, 'utf8')
-  done()
-}
-
-module.exports = addToReadme

package/functions/clean.js

@@ -1,10 +0,0 @@
-const del = require('del')
-const gulpConfig = require('../gulp.config.js')
-
-/**
- * Deletes all the distribution and browser files (used before create a new build).
- * @returns {Promise<string[]> | *}
- */
-const clean = () => del([gulpConfig.distPath, gulpConfig.browserPath])
-
-module.exports = clean

package/functions/distFor.js

@@ -1,15 +0,0 @@
-const babel = require('gulp-babel')
-const { dest, src } = require('gulp')
-const gulpConfig = require('../gulp.config.js')
-
-/**
- * Build the distribution for a given source pattern.
- * @param {string|array} srcPath
- * @param {string} destPath
- * @returns {*}
- */
-const distFor = (srcPath = gulpConfig.srcSearch, destPath = gulpConfig.distPath) => src(srcPath)
-  .pipe(babel())
-  .pipe(dest(destPath))
-
-module.exports = distFor

package/functions/readmeTemplate.js

@@ -1,13 +0,0 @@
-const { dest, src } = require('gulp')
-const gulpConfig = require('../gulp.config.js')
-const rename = require('gulp-rename')
-
-/**
- * Copy a readme template into the README.md file.
- * @returns {*}
- */
-const readmeTemplate = () => src(gulpConfig.readmeTemplate)
-  .pipe(rename('README.md'))
-  .pipe(dest('.'))
-
-module.exports = readmeTemplate