check-installed 2.1.0 → 2.2.0

package/README.md

@@ -10,58 +10,97 @@ Minimal Node package to check that dependencies are installed ✅
 $ npm i check-installed --save-dev
 ```
 
-## Usage
-- Run this before npm scripts to make sure that the environment is set up correctly
-- It checks that engines and node modules are installed and are the correct versions
+## Checks
+### Engines Check
+- Compares the installed version of engines to the versions specified in `package.json`
+- Engines can be things like node, dotnet, or anything that responds to `--version`
 - Version are checked with `semver.satisfies()`, so you can use any valid semver range
   - See [semver](https://www.npmjs.com/package/semver) for more info
-
-### Engine Check
-- Compares the installed version of an engine to the version specified in `package.json`
-- Engines can be things like node, dotnet, or anything that responds to `--version`
-
-### Node Module Check
-- Compares the installed version of a node module to the version specified in `package.json`
-- Versions for modules that have `latest` are not checked, only that they are installed
-- Optional node module dependencies are only checked if they are installed
-- Git URL versions are skipped
-
-## Example
-In `package.json`:
 ```json
   "engines": {
     "node": ">=12.x",
     "npm": ">=6",
     "dotnet": "^6.0.410"
   },
+```
+
+### Modules Check
+- Compares the installed versions of node modules to the versions specified in `package.json`
+- Versions for modules that have `latest` are not checked, only that they are installed
+- Optional node module dependencies are only checked if they are installed
+- Git URL versions are skipped
+
+## Usage
+
+### CLI
+Run `check-installed` before npm scripts or directly to ensure that the environment is set up correctly.
+If any check fails, the process will throw and exit with a non-zero exit code.
+
+#### NPM Scripts
+You can add a check script and run with `npm run check` or call it from other commands:
+```json
   "scripts": {
     "check": "check-installed",
     "start": "npm run check && node index.js",
     "test": "npm run check && jest"
   }
 ```
+This repo actually uses `check-installed` directly 🤯.
 
-## Options
-- Use `npx` to test out options like: `npx check-installed --help`
-- Update `package.json` to use options like:
-```json
-    "check": "check-installed --show-engines"
+#### Command Line
+```bash
+npx check-installed
+```
+
+### API
+You can call the checks directly from node programatically if needed like:
+```js
+const { checkEngines, checkModules } = require('check-installed')
+const json = require('./package.json')
+
+await checkEngines(json)
+await checkModules(json)
+await checkEngines(json, { showEngines: true })
+await checkModules(json, { showSuccess: true })
 ```
+Each check returns a `Promise<void>` that throws if any check fails.
+They are typed to accept the entire `options` object, but only use options they need.
+
+### Options
+- All options are optional and will be defaulted
+- CLI formats to change default values:
+  - `boolean`:
+    - `true`: `--option-name` or `--option-name=true`
+    - `false`: `--option-name=false` or `--option-name=` or `--option-name=anythingelse`
+  - `string`: `--option-name=value`
+- Options for `checkEngines` and `checkModules` are the same as CLI options but `camelCased`
 
 #### `--help`
 Show help (skips check)
 
+*Type: `boolean`, Default: `false`*
+
 #### `--skip-engines`
 Skip checking engines
 
+*Type: `boolean`, Default: `false`*
+
 #### `--skip-modules`
 Skip checking node modules
 
+*Type: `boolean`, Default: `false`*
+
 #### `--show-success`
 Show success message on successful checks
 
+*Type: `boolean`, Default: `false`*
+
 #### `--show-engines`
 Show installed engines on successful check
 
-### `--show-modules`
+*Type: `boolean`, Default: `false`*
+
+#### `--show-modules`
 Show installed node modules on successful check
+
+*Type: `boolean`, Default: `false`*

package/lib/checkEngines.js

@@ -53,6 +53,7 @@ async function checkEngineVersion (name, version) {
  * Checks engines in `package.json` are installed
  * @param {object} json - The `package.json` JSON object
  * @param {Partial<typeof import('./constants').OPTIONS>} options - Options for the CLI
+ * @returns {Promise<void>} - Resolves when all engines are checked (throws on check fail)
  */
 async function checkEngines (json = {}, options) {
   const { showSuccess, showEngines } = { ...OPTIONS, ...options }
@@ -72,6 +73,10 @@ async function checkEngines (json = {}, options) {
       console.log(`${name}: ${installed} (${version})`)
     }
   }
+
+  if (showSuccess || showEngines) {
+    console.log('')
+  }
 }
 
 module.exports = {

package/lib/checkModules.js

@@ -56,6 +56,7 @@ function checkModuleVersion (name, version, optional) {
  * Checks node modules in `package.json` are installed
  * @param {object} json - The `package.json` JSON object
  * @param {Partial<typeof import('./constants').OPTIONS>} options - Options for the CLI
+ * @returns {Promise<void>} - Resolves when all modules are checked (throws on check fail)
  */
 async function checkModules (json = {}, options) {
   const { showSuccess, showModules } = { ...OPTIONS, ...options }
@@ -79,6 +80,10 @@ async function checkModules (json = {}, options) {
       console.log(`${name}: ${installed} (${aliased}${version})`)
     }
   }
+
+  if (showSuccess || showModules) {
+    console.log('')
+  }
 }
 
 module.exports = {

package/lib/cli.js

@@ -1,33 +1,13 @@
 const { resolve } = require('path')
-const { HELP, OPTIONS } = require('./constants')
+const { HELP } = require('./constants')
+const { getOptions } = require('./getOptions')
 const { checkEngines } = require('./checkEngines')
 const { checkModules } = require('./checkModules')
 
-/**
- * Get options from CLI arguments
- * @param {string[]} args - CLI arguments
- * @returns {typeof OPTIONS} - Options for the CLI with defaults
- */
-function getOptions (args) {
-  const options = {}
-
-  for (const arg of args) {
-    if (arg.startsWith('--')) {
-      const [key, value] = arg.slice(2).split('=')
-      const keyCamelCase = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
-
-      if (OPTIONS[keyCamelCase] != null) {
-        options[keyCamelCase] = value ?? true
-      }
-    }
-  }
-
-  return options
-}
-
 /**
  * check-installed CLI entry point
  * @param {string[]} argv - CLI arguments
+ * @returns {Promise<void>} - Promise that resolves when the CLI is done (throws on check fail)
  */
 async function cli (argv = process.argv) {
   const json = require(resolve(process.cwd(), 'package.json'))

package/lib/getOptions.js

@@ -0,0 +1,42 @@
+const { OPTIONS } = require('./constants')
+
+/**
+ * Get check-installed options from CLI arguments
+ * @param {string[]} args - CLI arguments
+ * @returns {typeof OPTIONS} - Options for the CLI with defaults
+ */
+function getOptions (args = []) {
+  const options = {}
+
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const [key, value] = arg.slice(2).split('=')
+      const keyCamelCase = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+      const option = OPTIONS[keyCamelCase]
+
+      // Only set if the option is defined in `OPTIONS`
+      if (option !== undefined) {
+        let newValue
+
+        // If boolean, `true` only if no value or value is "true"
+        // Otherwise, only if value provided
+        if (typeof option === 'boolean') {
+          newValue = value == null ? true : value === 'true'
+        } else if (value != null) {
+          newValue = value
+        }
+
+        // Set only if valid and not already default
+        if (newValue !== undefined && newValue !== option) {
+          options[keyCamelCase] = newValue
+        }
+      }
+    }
+  }
+
+  return options
+}
+
+module.exports = {
+  getOptions
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "check-installed",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Minimal Node package to check that dependencies are installed ✅",
   "author": "Phillip Lanclos <check-installed@flippidippi.com>",
   "license": "Unlicense",
@@ -32,7 +32,7 @@
     "npm": ">=6"
   },
   "scripts": {
-    "check": "./bin/check-installed",
+    "check": "./bin/check-installed --show-engines",
     "lint": "standard",
     "lint:fix": "npm run lint -- --fix",
     "test": "npm run check && jest",