npm-toolkit

A programmatic wrapper around key npm functions and package data manipulation utilities.

Installation

npm i @liquid-labs/npm-toolkit

Usage

import * as fsPath from 'node:path'

import * as npm from '@liquid-labs/npm-toolkit'

const pkgDir = fsPath.join('path', 'to', 'package')
const pkgJSON = await npm.getPackageJSON(( pkgDir ))
const { name, org, basename, version } = npm.getPackageOrgBasenameAndVersion({ pkgJSON })
// alt forms:
// const { name, org, basename, version } = await getPackageOrgBasenameAndVersion({ pkgDir })
// const { name, org, basename, version } = await getPackageOrgBasenameAndVersion('@acme/foo@^1.0')

await nmp.update({ global: true })
await npm.install({ global: true, packages: ['npm-check@latest' ]})

API reference

API generated with dmd-readme-api.

• Functions:
  • getPackageJSON(): Find and parses the package.json associated with the package containing pkgDir.
  • getPackageOrgBasenameAndVersion(): xtracts the package name, organization, basename, and version from a project's package.json file.
  • getVersion(): Retrieves the version of Node.js and npm installed on the system.
  • install(): Installs packages using npm install.
  • update(): Updates project dependencies or global installs.
  • validatePackageSpec(): Validates that a package specification is safe for use in shell commands and file operations.
  • view(): Retrieves package metadata from the npm registry using npm view.

getPackageJSON(pkgDir) ⇒ Promise.<Object> ↱source code ⇧global index

Find and parses the package.json associated with the package containing pkgDir. The method will check parent directories until it finds a package.json file or runs out of parent directories.

| Param | Type | Description | | --- | --- | --- | | pkgDir | string | The path to the package directory or sub-directory. |

Returns: Promise.<Object> - A promise that resolves to the parsed package.json file.

getPackageOrgBasenameAndVersion(input) ⇒ Promise.<{name: string, org: string, basename: string, version: string}> ↱source code ⇧global index

xtracts the package name, organization, basename, and version from a project's package.json file.

| Param | Type | Description | | --- | --- | --- | | input | string | Object | If a string, it's treated as a package spec (e.g. '@acme/foo@^1.0'). Otherwise, input is an object with exactly one of pkgDir, pkgJSON, or pkgSpec specified. | | [input.pkgDir] | string | The path to the package directory. | | [input.pkgJSON] | Object | The parsed package.json file. | | [input.pkgSpec] | string | The package spec to extract the package name, organization, basename, and version from. This can be a scoped package spec (e.g., @acme/foo@^1.0) or an unscoped package spec (e.g., [email protected]). |

Returns: Promise.<{name: string, org: string, basename: string, version: string}> - A promise that resolves to an object with the package name, organization, basename, and version.

getVersion() ⇒ Promise.<{nodeVer: string, npmVer: string}> ↱source code ⇧global index

Retrieves the version of Node.js and npm installed on the system.

Returns: Promise.<{nodeVer: string, npmVer: string}> - A promise that resolves to an object with the Node.js and npm versions as strings without the v prefix.

install(params) ⇒ Promise.<{installedPackages: Array.<string>, localPackages: Array.<string>, productionPackages: Array.<string>}> ↱source code ⇧global index

Installs packages using npm install.

| Param | Type | Default | Description | | --- | --- | --- | --- | | params | Object | | The parameters for the install function. | | [params.allowFilePackages] | boolean | false | Whether to allow 'file:' protocol package specs (e.g., 'file:../pkg'). | | [params.devPaths] | Array.<string> | | An array of paths to search for local packages. Any local packages found will be used instead of installing from the registry. | | [params.global] | boolean | | Whether to install globally. | | params.packages | Array.<string> | | List of package specifiers to install. At least one package must be specified. | | [params.projectPath] | string | | The path to the project to install. | | [params.saveDev] | boolean | | Whether to save the package as a development dependency. | | [params.saveProd] | boolean | | Whether to save the package as a production dependency. This is the default behavior. | | [params.verbose] | boolean | | Whether to print verbose output. |

Returns: Promise.<{installedPackages: Array.<string>, localPackages: Array.<string>, productionPackages: Array.<string>}> - A promise that resolves to a summary of the installed packages.

update(params) ⇒ Promise.<{updated: boolean, actions: Array.<string>, result: Object}> ↱source code ⇧global index

Updates project dependencies or global installs. Requires at 'global' and/or projectPath be provided.

| Param | Type | Description | | --- | --- | --- | | params | Object | The parameters for the update function. | | [params.dryRun] | boolean | Check for outdated dependecies and display results, but don't actually update. | | [params.global] | boolean | Operate on the globally installed packages instead of projectPath dependencies. One of global and projectPath must be provided. | | [params.packages] | Array.<string> | Only check the named packages. If global is true, this would be a list of global packages and otherwise a list of projectPath dependencies. | | [params.projectPath] | string | The path to the project to update. One of global and projectPath must be provided. |

Returns: Promise.<{updated: boolean, actions: Array.<string>, result: Object}> - A promise that resolves to a summary of the updates.

validatePackageSpec(packageSpec, [options]) ⇒ Object ↱source code ⇧global index

Validates that a package specification is safe for use in shell commands and file operations. Supports standard npm package specs and file: protocol packages when allowFilePackages is true.

| Param | Type | Default | Description | | --- | --- | --- | --- | | packageSpec | string | | The package specification to validate (e.g., '[email protected]', '@scope/pkg', 'file:../pkg') | | [options] | Object | | Validation options | | [options.allowFilePackages] | boolean | false | Whether to allow 'file:' protocol package specs | | [options.throwIfInvalid] | boolean | false | If true, throws an error on validation failure. If false, returns result object with isValid=false. |

Returns: Object - Validation result with { isValid: boolean, errorMsg?: string, isFilePackage?: boolean, cleanSpec?: string, packageName?: string, versionPart?: string, resolvedPath?: string }

Throws: Validates that a package specification is safe for use in shell commands and file operations. Supports standard npm package specs and file: protocol packages when allowFilePackages is true.

view(params) ⇒ Promise.<(Object|null)> ↱source code ⇧global index

Retrieves package metadata from the npm registry using npm view.

| Param | Type | Description | | --- | --- | --- | | params | Object | The parameters for the view function. | | params.packageName | string | The name of the package to view. | | [params.throwOnNotFound] | boolean | If true, then a '404' error will throw rather than return null. | | [params.version] | string | The specific version to view. If omitted, returns data for the latest version. |

Returns: Promise.<(Object|null)> - A promise that resolves to the parsed JSON object returned by npm view --json or null if no package info is found.