@modernpoacher/deps 2.2.18 → 2.2.20

package/src/index.mjs

@@ -1,3 +1,7 @@
+/**
+ *  @typedef {import('node:child_process').ExecException} ExecException
+ */
+
 /**
  *  Package or configuration dependencies
  *  @typedef {import('./common/index.mjs').Dependencies} Dependencies
@@ -8,7 +12,12 @@
  *  @typedef {import('./common/index.mjs').DependencyDescriptor} DependencyDescriptor
  */
 
-import debug from 'debug'
+/**
+ *  @callback HandleComplete
+ *  @param {ExecException | null} e
+ *  @param {string} v
+ *  @returns {void}
+ */
 
 import stripAnsi from 'strip-ansi'
 
@@ -20,6 +29,8 @@ import {
   exec
 } from 'node:child_process'
 
+import debug from '#deps/src/common/debug'
+
 import {
   VERSION,
   PLATFORM
@@ -51,13 +62,25 @@ const info = debug('@modernpoacher/deps:info')
 
 log(`\`deps\` (${VERSION} - ${PLATFORM}) is awake`)
 
+/**
+ *  @param {string} v
+ *  @returns {boolean}
+ */
 function filter (v) {
   return Boolean(stripAnsi(v).trim())
 }
 
+/**
+ *  @param {string} key
+ *  @returns {(value: string) => void}
+ */
 export function use (key) {
   const log = debug(`@modernpoacher/deps:${key}`)
 
+  /**
+   *  @param {string} v
+   *  @returns {void}
+   */
   function write (v) {
     log(v.trimEnd())
   }
@@ -71,10 +94,9 @@ export function use (key) {
 
 /**
  *  @function getInstallSaveExactCommands
- *
+ *  @description
  *  Get the `npm install --save-exact` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -89,10 +111,9 @@ export function getInstallSaveExactCommands (deps, r, f) {
 
 /**
  *  @function getInstallCommands
- *
+ *  @description
  *  Get the `npm install` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -107,10 +128,9 @@ export function getInstallCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveBundleSaveExactCommands
- *
+ *  @description
  *  Get the `npm install --save-bundle --save-exact` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -129,10 +149,9 @@ export function getInstallSaveBundleSaveExactCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveBundleCommands
- *
+ *  @description
  *  Get the `npm install --save-bundle` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -151,10 +170,9 @@ export function getInstallSaveBundleCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveOptionalSaveExactCommands
- *
+ *  @description
  *  Get the `npm install --save-optional --save-exact` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -173,10 +191,9 @@ export function getInstallSaveOptionalSaveExactCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveOptionalCommands
- *
+ *  @description
  *  Get the `npm install --save-optional` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -195,10 +212,9 @@ export function getInstallSaveOptionalCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveDevSaveExactCommands
- *
+ *  @description
  *  Get the `npm install --save-dev --save-exact` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -217,10 +233,9 @@ export function getInstallSaveDevSaveExactCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveDevCommands
- *
+ *  @description
  *  Get the `npm install --save-dev` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -239,10 +254,9 @@ export function getInstallSaveDevCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveProdSaveExactCommands
- *
+ *  @description
  *  Get the `npm install --save-prod --save-exact` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -261,10 +275,9 @@ export function getInstallSaveProdSaveExactCommands (deps, r, f) {
 
 /**
  *  @function getInstallSaveProdCommands
- *
+ *  @description
  *  Get the `npm install --save-prod` commands as a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {string}
@@ -283,11 +296,10 @@ export function getInstallSaveProdCommands (deps, r, f) {
 
 /**
  *  @function installSaveBundleSaveExact
- *
+ *  @description
  *  Spawn the `npm install --save-bundle --save-exact` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -297,35 +309,42 @@ export function installSaveBundleSaveExact (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveBundleSaveExactCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-bundle-save-exact')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveBundle
- *
+ *  @description
  *  Spawn the `npm install --save-bundle` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -335,35 +354,42 @@ export function installSaveBundle (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveBundleCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-bundle')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveOptionalSaveExact
- *
+ *  @description
  *  Spawn the `npm install --save-optional --save-exact` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -373,73 +399,87 @@ export function installSaveOptionalSaveExact (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveOptionalSaveExactCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-otional-save-exact')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveOptional
- *
+ *  @description
  *  Spawn the `npm install --save-optional` commands
- *
  *  @param {string} d - Directory
- *  @param {Dependencies} dependencies - Dependencies
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependencies
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
  */
-export function installSaveOptional (d, dependencies, r, f) {
+export function installSaveOptional (d, deps, r, f) {
   log('installSaveOptional')
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
-      const commands = getCommands(getInstallSaveOptionalCommands(dependencies, r, f))
+      const commands = getCommands(getInstallSaveOptionalCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-otional')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveDevSaveExact
- *
+ *  @description
  *  Spawn the `npm install --save-dev --save-exact` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -449,35 +489,42 @@ export function installSaveDevSaveExact (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveDevSaveExactCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-dev-save-exact')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveDev
- *
+ *  @description
  *  Spawn the `npm install --save-dev` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -487,35 +534,42 @@ export function installSaveDev (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveDevCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-dev')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveProdSaveExact
- *
+ *  @description
  *  Spawn the `npm install --save-prod --save-exact` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -525,35 +579,42 @@ export function installSaveProdSaveExact (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveProdSaveExactCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-prod-save-exact')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function installSaveProd
- *
+ *  @description
  *  Spawn the `npm install --save-prod` commands
- *
  *  @param {string} d - Directory
- *  @param {DependencyDescriptor|DependencyDescriptor[]} deps - Dependency descriptor(s)
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} deps - Dependency descriptor(s)
  *  @param {string} r - Registry
  *  @param {boolean} f - Force
  *  @returns {Promise<string>}
@@ -563,33 +624,40 @@ export function installSaveProd (d, deps, r, f) {
 
   const directory = normalize(d.trim())
 
-  log(`Directory is "${directory}"`)
+  info(`Directory is "${directory}"`)
 
   return (
     new Promise((resolve, reject) => {
       const commands = getCommands(getInstallSaveProdCommands(deps, r, f))
       const options = getOptions(directory)
+      /**
+       *  @type {HandleComplete}
+       */
+      function handleComplete (e, v) {
+        if (!e) {
+          resolve(v)
+        } else {
+          reject(e)
+        }
+      }
 
       const {
         stdout,
         stderr
-      } = exec(commands, options, (e, v) => {
-        return (!e) ? resolve(v) : reject(e)
-      })
+      } = exec(commands, options, handleComplete)
 
       const log = use('install-save-prod')
 
-      stdout.on('data', log)
-      stderr.on('data', log)
+      if (stdout) stdout.on('data', log)
+      if (stderr) stderr.on('data', log)
     })
   )
 }
 
 /**
  *  @function executeBundle
- *
+ *  @description
  *  Execute the `npm install --save-bundle --save-exact` and `npm install --save-bundle` commands
- *
  *  @param {string} d - Directory
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @param {Dependencies} configurationDependencies - Configuration dependencies
@@ -611,9 +679,8 @@ export async function executeBundle (d = DIRECTORY, packageDependencies = {}, co
 
 /**
  *  @function executeOptional
- *
+ *  @description
  *  Execute the `npm install --save-optional --save-exact` and `npm install --save-optional` commands
- *
  *  @param {string} d - Directory
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @param {Dependencies} configurationDependencies - Configuration dependencies
@@ -635,9 +702,8 @@ export async function executeOptional (d = DIRECTORY, packageDependencies = {},
 
 /**
  *  @function executeDev
- *
+ *  @description
  *  Execute the `npm install --save-dev --save-exact` and `npm install --save-dev` commands
- *
  *  @param {string} d - Directory
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @param {Dependencies} configurationDependencies - Configuration dependencies
@@ -659,9 +725,8 @@ export async function executeDev (d = DIRECTORY, packageDependencies = {}, confi
 
 /**
  *  @function executeProd
- *
+ *  @description
  *  Execute the `npm install --save-prod --save-exact` and `npm install --save-prod` commands
- *
  *  @param {string} d - Directory
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @param {Dependencies} configurationDependencies - Configuration dependencies