@modernpoacher/deps 2.2.18 → 2.2.20

package/src/common/index.mjs

@@ -1,50 +1,18 @@
 /**
- *  Package or configuration dependencies
- *
- *  @typedef {Record<string, string>} Dependencies
- */
-
-/**
- *  A dependency descriptor
- *
- *  @typedef {Object} DependencyDescriptor
- *  @property {string} name - Dependency name in NPM.
- *  @property {string} version - Dependency version or "latest".
- */
-
-/**
- *  A package
- *
- *  @typedef {Object} Package
- *  @property {string|{name: string, email: string}} author
- *  @property {Dependencies} dependencies - Production dependencies.
- *  @property {Dependencies} devDependencies - Development dependencies.
- *  @property {Dependencies} optionalDependencies - Optional dependencies.
- *  @property {Dependencies} bundleDependencies - Bundle dependencies.
- *  @property {Dependencies} peerDependencies - Peer dependencies
+ *  @typedef {DepsTypes.Dependencies} Dependencies
+ *  @typedef {DepsTypes.DependencyDescriptor} DependencyDescriptor
+ *  @typedef {DepsTypes.Package} Package
+ *  @typedef {DepsTypes.Configuration} Configuration
  */
 
-/**
- *  A configuration
- *
- *  @typedef {Object} Configuration
- *  @property {string|{name: string, email: string}} author
- *  @property {boolean} ignore
- *  @property {Dependencies} dependencies - Production dependencies.
- *  @property {Dependencies} devDependencies - Development dependencies.
- *  @property {Dependencies} optionalDependencies - Optional dependencies.
- *  @property {Dependencies} bundleDependencies - Bundle dependencies.
- *  @property {Dependencies} peerDependencies - Peer dependencies
- */
-
-import debug from 'debug'
-
-import PATH from '#where-am-i'
-
 import {
   join
 } from 'node:path'
 
+import PATH from '#where-am-i'
+
+import debug from '#deps/src/common/debug'
+
 import {
   VERSION,
   PLATFORM
@@ -62,35 +30,49 @@ const log = debug('@modernpoacher/deps')
 
 log(`\`common\` (${VERSION} - ${PLATFORM}) is awake`)
 
-export const tidy = (v) => v.replace(/\n{2,}}/gm, String.fromCharCode(10)).trim()
+const LF = String.fromCharCode(10)
+const SP = String.fromCharCode(32)
 
-export const trim = (v) => v.split(String.fromCharCode(10)).map((v) => v.trimEnd()).join(String.fromCharCode(10)).trim()
+/**
+ *  @param {string} v
+ *  @returns {string}
+ */
+export const tidy = (v) => v.replace(/\n{2,}}/gm, LF).trim()
+
+/**
+ *  @param {string} v
+ *  @returns {string}
+ */
+export const trimEnd = (v) => v.trimEnd()
+
+/**
+ *  @param {string} v
+ *  @returns {string}
+ */
+export const trim = (v) => v.split(LF).map(trimEnd).join(LF).trim()
 
 /**
  *  @function getSaveProdParameter
- *
+ *  @description
  *  Get the `--save-prod` parameter
- *
- *  @param {string} current commands string
+ *  @param {string} commands commands string
  *  @returns {string}
  */
 export const getSaveProdParameter = (commands) => commands.concat(' --save-prod')
 
 /**
  *  @function getSaveDevParameter
- *
+ *  @description
  *  Get the `--save-dev` parameter
- *
- *  @param {string} current commands string
+ *  @param {string} commands commands string
  *  @returns {string}
  */
 export const getSaveDevParameter = (commands) => commands.concat(' --save-dev')
 
 /**
  *  @function getSaveBundleParameter
- *
+ *  @description
  *  Get the "save bundle" parameter
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -98,9 +80,8 @@ export const getSaveBundleParameter = (commands) => commands.concat(' --save-bun
 
 /**
  *  @function getSaveOptionalParameter
- *
+ *  @description
  *  Get the `--save-optional` parameter
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -108,9 +89,8 @@ export const getSaveOptionalParameter = (commands) => commands.concat(' --save-o
 
 /**
  *  @function getRegistryParameter
- *
+ *  @description
  *  Get the "registry" parameter and argument
- *
  *  @param {string} r - Registry
  *  @param {string} commands - Current commands string
  *  @returns {string}
@@ -119,9 +99,8 @@ export const getRegistryParameter = (r, commands) => r ? commands.concat(` --reg
 
 /**
  *  @function getForceParameter
- *
+ *  @description
  *  Get the "force" parameter and argument
- *
  *  @param {boolean} f - Force
  *  @param {string} commands - Current commands string
  *  @returns {string}
@@ -130,9 +109,8 @@ export const getForceParameter = (f, commands) => f ? commands.concat(' --force'
 
 /**
  *  @function getNoSaveParameter
- *
+ *  @description
  *  Get the `--no-save` parameter
- *
  *  @param {boolean} s - Save
  *  @param {string} commands - Current commands string
  *  @returns {string}
@@ -141,9 +119,8 @@ export const getNoSaveParameter = (s, commands) => s ? commands : commands.conca
 
 /**
  *  @function getSaveExactParameter
- *
+ *  @description
  *  Get the `--save-exact` parameter
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -151,9 +128,8 @@ export const getSaveExactParameter = (commands) => commands.concat(' --save-exac
 
 /**
  *  @function getExportPath
- *
+ *  @description
  *  Get the export PATH shell script
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -164,9 +140,8 @@ ${commands}
 
 /**
  *  @function getNvm
- *
+ *  @description
  *  Get the NVM shell script
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -177,9 +152,8 @@ ${commands}
 
 /**
  *  @function getCommands
- *
+ *  @description
  *  Get the installation shell script
- *
  *  @param {string} commands - Current commands string
  *  @returns {string}
  */
@@ -189,74 +163,68 @@ export const getCommands = PLATFORM === 'win32'
 
 /**
  *  @function getProdDependencies
- *
+ *  @description
  *  Get the production dependencies by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
+ *  @param {Package | Configuration} deps
  *  @returns {Dependencies}
  */
 export const getProdDependencies = ({ dependencies = {} } = {}) => dependencies
 
 /**
  *  @function getDevDependencies
- *
+ *  @description
  *  Get the development dependencies by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
+ *  @param {Package | Configuration} deps
  *  @returns {Dependencies}
  */
 export const getDevDependencies = ({ devDependencies = {} } = {}) => devDependencies
 
 /**
  *  @function getOptionalDependencies
- *
+ *  @description
  *  Get the optional dependencies by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
+ *  @param {Package | Configuration} deps
  *  @returns {Dependencies}
  */
 export const getOptionalDependencies = ({ optionalDependencies = {} } = {}) => optionalDependencies
 
 /**
  *  @function getBundleDependencies
- *
+ *  @description
  *  Get the bundle dependencies by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
+ *  @param {Package | Configuration} deps
  *  @returns {Dependencies}
  */
 export const getBundleDependencies = ({ bundleDependencies = {} } = {}) => bundleDependencies
 
 /**
  *  @function getPeerDependencies
- *
+ *  @description
  *  Get the peer dependencies by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
+ *  @param {Package | Configuration} deps
  *  @returns {Dependencies}
  */
-export const getPeerDependencies = ({ peerDependencies } = {}) => peerDependencies
+export const getPeerDependencies = ({ peerDependencies = {} } = {}) => peerDependencies
 
 /**
  *  @function getIgnore
- *
+ *  @description
  *  Get the ignore flag by destructuring the configuration
- *
- *  @param {Configuration}
+ *  @param {Configuration} deps
  *  @returns {boolean}
  */
 export const getIgnore = ({ ignore = false } = {}) => ignore === true
 
 /**
  *  @function getAuthor
- *
+ *  @description
  *  Get the author by destructuring the package or configuration
- *
- *  @param {Package|Configuration}
- *  @returns {string|null}
+ *  @param {Package | Configuration} deps
+ *  @returns {string | null}
  */
 export const getAuthor = ({ author = '' } = {}) => {
-  if ((author || false) instanceof Object) {
+  if (typeof author === 'string') return author
+  if (typeof (author || false) === 'object') {
     const {
       name: NAME = '',
       email: EMAIL = ''
@@ -272,24 +240,22 @@ export const getAuthor = ({ author = '' } = {}) => {
     )
   }
 
-  return author || null
+  return null
 }
 
 /**
  *  @function getMessage
- *
+ *  @description
  *  Get the message by destructuring the configuration
- *
- *  @param {Configuration}
- *  @returns {string|null}
+ *  @param {Configuration} deps
+ *  @returns {string | null}
  */
 export const getMessage = ({ message = '' } = {}) => message || null
 
 /**
  *  @function isPreRelease
- *
+ *  @description
  *  Determine whether the dependency is a pre-release with a Regular Expression
- *
  *  @param {string} v
  *  @returns {boolean}
  */
@@ -297,9 +263,8 @@ export const isPreRelease = (v) => /-/.test(v)
 
 /**
  *  @function isExact
- *
+ *  @description
  *  Determine whether the dependency is exact with a Regular Expression
- *
  *  @param {string} v
  *  @returns {boolean}
  */
@@ -323,7 +288,7 @@ function excludeVersionIsExact ([name, version]) {
 
 /**
  *  @function getMapToDepsExactVersionFromConfiguration
- *
+ *  @description
  *  Produces an array of objects from the entries of `packageDependencies` which have
  *  exact versions
  *
@@ -331,7 +296,6 @@ function excludeVersionIsExact ([name, version]) {
  *
  *  Each entry is mapped to the same package name in `configurationDependencies` if it
  *  appears there. Otherwise, the `packageDependencies` version is used
- *
  *  @param {Record<string, string>} configurationDependencies
  *  @returns {(entry: [name: string, version: string]) => {
  *    name: string,
@@ -365,13 +329,12 @@ function getMapToDepsExactVersionFromConfiguration (configurationDependencies) {
 
 /**
  *  @function mapToDepsVersion
- *
+ *  @description
  *  Produces an array of objects from the entries of `packageDependencies` which do not have
  *  exact versions
  *
  *  Where the version is a pre-release, that version is used. Otherwise the version is
  *  set to `latest` to ensure that package is updated
- *
  *  @param {[name: string, version: string]} entry
  *  @returns {{
  *    name: string,
@@ -399,9 +362,8 @@ function mapToDepsVersion (entry) {
 
 /**
  *  @function getDepsExact
- *
+ *  @description
  *  Get an array of dependencies to be installed with the `--save-exact` parameter
- *
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @param {Dependencies} configurationDependencies - Configuration dependencies
  *  @returns {DependencyDescriptor[]}
@@ -418,9 +380,8 @@ export function getDepsExact (packageDependencies, configurationDependencies) {
 
 /**
  *  @function getDeps
- *
+ *  @description
  *  Get an array of dependencies to be installed
- *
  *  @param {Dependencies} packageDependencies - Package dependencies
  *  @returns {DependencyDescriptor[]}
  */
@@ -436,40 +397,37 @@ export function getDeps (packageDependencies) {
 
 /**
  *  @function normalizeCommands
- *
+ *  @description
  *  Normalise the commands string
- *
- *  @param {string} value
+ *  @param {string} commands
  *  @returns {string}
  */
 export function normalizeCommands (commands) {
-  const s = String.fromCharCode(32)
+  let c = commands
 
-  while (/\s{2,}|\n+/.test(commands)) {
-    commands = commands.replace(/\s{2,}/gm, s).replace(/\n+/gm, s)
+  while (/\s{2,} | \n+/.test(c)) {
+    c = c.replace(/\s{2,}/gm, SP).replace(/\n+/gm, SP)
   }
 
   return (
-    commands.trim()
+    c.trim()
   )
 }
 
 /**
  *  @function transformDependency
- *
+ *  @description
  *  Transform by destructuring the value
- *
- *  @param {DependencyDescriptor}
+ *  @param {DependencyDescriptor | { name?: string, version?: string }} dependencyDescriptor
  *  @returns {string}
  */
 export const transformDependency = ({ name = '@modernpoacher/deps', version = 'latest' } = {}) => `${name}@${version}`
 
 /**
  *  @function transform
- *
+ *  @description
  *  Transform the parameter to a string
- *
- *  @param {DependencyDescriptor|DependencyDescriptor[]} value
+ *  @param {DependencyDescriptor | DependencyDescriptor[]} value
  *  @returns {string}
  */
 export function transform (value) {
@@ -477,7 +435,7 @@ export function transform (value) {
 
   return (
     Array.isArray(value)
-      ? value.map(transformDependency).join(String.fromCharCode(32)).trim()
+      ? value.map(transformDependency).join(SP).trim()
       : transformDependency(value)
   )
 }

package/src/common/options/index.mjs

@@ -1,4 +1,8 @@
-import debug from 'debug'
+/**
+ *  @typedef {DepsTypes.Options} Options
+ */
+
+import debug from '#deps/src/common/debug'
 
 import {
   VERSION,
@@ -14,14 +18,17 @@ const {
   }
 } = process
 
+/**
+ *  @type {Options}
+ */
 export const OPTIONS = {
   maxBuffer: 1024 * 2000,
   stdio: 'inherit',
   env: {
     DEBUG_COLORS: 'yes',
     FORCE_COLOR: PLATFORM === 'win32'
-      ? 3
-      : 2,
+      ? '3'
+      : '2',
     NODE_OPTIONS,
     SSH_AUTH_SOCK,
     HOME,
@@ -35,23 +42,10 @@ log(`\`common/options\` (${VERSION} - ${PLATFORM}) is awake`)
 
 /**
  *  @function getOptions
- *
- *  Get the installation `exec` child process options
- *
- *  @param {string} cwd normalized directory
- *  @returns {{
- *    maxBuffer: number,
- *    stdio: string
- *    env: {
- *      DEBUG_COLORS: string,
- *      FORCE_COLOR: number,
- *      NODE_OPTIONS: string,
- *      SSH_AUTH_SOCK?: string,
- *      HOME?: string,
- *      PATH?: string
- *    }
- *    cwd: string
- *  }}
+ *  @description
+ *  `exec` shell options
+ *  @param {string} [cwd] normalized directory
+ *  @returns {Options & { cwd?: string }}
  */
 export function getOptions (cwd) {
   log('getOptions')