# npm-utils Set of utilities for working with npm and npm packages. ## API Most functions assume the user is logged into the npm account with access to the relevant packages and that they are signed in to git with access to the repository being updated. ### Listing #### Functions - validPackage - isNodeModules - findPackageRoot - findAllPackages - packageDependencies - findDependencies - packageDependants - findDependants - updateChangeLog - updateDependency - publishPackage - updateVersion - updatePackage - packageDependencyChain - updatePackageChain - initPackage #### Types - PackageLocation - PackagesLocations - PackageDependencies - PackagesDependencies - PackageVersion - UpdateType - PackageChain ### Details #### Functions ##### validPackage Takes a `string` package name and returns true if it is a valid package name. Valid package names are of the form word(-word)*, containing no numbers. ```typescript const validPackage = (pack: string) => boolean ``` ##### isNodeModules Takes a path and determines if it's a path to a `node_modules` directory. ```typescript const isNodeModules = (path: string) => boolean ``` ##### findPackageRoot Takes a path and finds the package it belongs to by searching each parent directory for a `package.json`. Throws if no package root is found. ```typescript const findPackageRoot = (path: string) => string ``` ##### findAllPackages Takes a string representing a root path from which is recursively finds all node packages. A directory is a package if it has a `package.json` file. All packages in `node_modules` are ignored, but it will find packages within packages. Returns a `PackagesLocations` which contains the name and path of every package found. ```typescript const findAllPackages = (path: string) => PackagesLocations ``` ##### packageDependencies Takes a `PackageLocation` and `string[]` and returns a `PackageDependencies` which contains both the dependencies and devDependencies of the package in `PackageLocation`. If the `string[]` is non-empty, any packages not listed will be filtered out. ```typescript const packageDependencies = (pack: PackageLocation, filterOn: string[] = []) => PackageDependencies ``` ##### findDependencies Takes a `PackagesLocations` and `string[]` and returns a `PackagesDependencies` which contains both the dependencies and devDependencies of every package in `PackagesLocations`. If the `string[]` is non-empty, any packages not listed will be filtered out. ```typescript const findDependencies = (packs: PackagesLocations, filterOn: string[] = []) => PackagesDependencies ``` ##### packageDependants Takes a `string` package name and `PackagesDependencies` and returns a `PackageDependencies` which contains all the packages that depend on the provided package. ```typescript const packageDependants = (pack: string, deps: PackagesDependencies) => PackageDependencies ``` ##### findDependants Takes a `PackagesDependencies` which finds the dependants of every package listed and returns a `PackagesDependencies`. ```typescript const findDependants = (packs: PackagesDependencies) => PackagesDependencies ``` ##### updateChangeLog Takes a `version: string` and `desc: string` and updates the `CHANGELOG.md` of the current working directory. It assumes the changelog begins with `# Changelog` as the first line, and will add new entries below it in the following format: An error is thrown if the current working directory doesn't contain a `CHANGELOG.md`. ``` ## - ``` ```typescript const updateChangeLog = (version: string, desc: string) => Void ``` ##### updateDependency Takes a `pack: string` representing the dependency to update along with an optional `version: string`. If `version: string` is non-empty the function will update using `npm install @`. If empty it will use `npm update `. An error is thrown if the current working directory doesn't contain a `package.json`. ```typescript const updateDependency = (pack: string, version: string = "") => Void ``` ##### publishPackage Publishes the npm package. An error is thrown if the current working directory doesn't contain a `package.json`. ```typescript const publishPackage = () => Void ``` ##### updateVersion Takes an `UpdateType` bumps the version of a package in the current working directory using `npm version ` If `type` is `UpdateType.INITIAL` the function returns `v1.0.0` without calling `npm version`. An error is thrown if the current working directory doesn't contain a `package.json`. ```typescript const updateVersion = (type: UpdateType) => string ``` ##### updatePackage Takes a directory, description and `UpdateType`, changes directory to the provided one and updates the package using `updateVersion`. Returns a `PackageVersion` object. ```typescript const updatePackage = (directory: string, desc: string, type: UpdateType) => PackageVersion ``` ##### packageDependencyChain Takes a root path and package name and finds the dependency chain for that package and all the packages it updates. The chain is ordered so that no package is updated before all a dependency earlier in the chain is updated to prevent double publishes. ```typescript const packageDependencyChain = (root: string, pack: string) => PackageChain ``` ##### updatePackageChain Takes a root path, description, `UpdateType` and optional shouldChain parameter and updates the current working directory package and its chain of dependencies. If shouldChain is false no update chain occurs. Throws if root is not a directory, if root is not the parent of the current working directory, and if current working directory is not a package (doesn't have package.json file). ```typescript const updatePackageChain = (root: string, desc: string, type: UpdateType, shouldChain: boolean = true) => Void ``` ##### initPackage Takes a folder name and attempts to create a package with all necessary files to begin package development. ```typescript const initPackage = (folderName: string) => Void ``` #### Types ##### PackageLocation Represents a npm package storing package name and path. ```typescript interface PackageLocation { name: string; path: string; } ``` ##### PackagesLocations Represents an `Array` of `PackageLocation`s. ```typescript type PackagesLocations = Array ``` ##### PackageDependencies Represents a set of dependencies for an npm package, storing package name and its associated dependencies. ```typescript interface PackageDependencies { name: string; dependencies: PackagesVersions; } ``` ##### PackagesDependencies Represents an `Array` of `PackageDependencies`. ```typescript type PackagesDependencies = Array ``` ##### PackageVersion Represents a npm package version, stores name of package and version. ```typescript interface PackageVersion { name: string; version: string; } ``` ##### PackageVersions Represents an `Array` of `PackageVersion`s. ```typescript type PackagesVersions = Array; ``` ##### UpdateType Represents the type of package updates that can occur. ```typescript enum UpdateType { MAJOR = 'major', MINOR = 'minor', PATCH = 'patch', INITIAL = 'initial' } ``` ##### PackageChain Stores a dependency chain, and the set dependencies of all packages found from a root path. A dependency chain is the most efficient path for updating dependant packages that may be encountered multiple times. ```typescript interface PackageChain { chain: PackagesLocations, dependencies: PackagesDependencies } ```