List Installed

A modern typed async alternative to read-installed and readdir-scoped-modules. Used to list and return all modules installed in node_modules, either just their names or their package.json files.

Usage

Simple

npm install list-installed

import { listInstalled } from 'list-installed';

const pkgMap = await listInstalled(__dirname);

// Eg. iterate over the map
for (const [moduleName, pkg] of pkgMap.entries()) {
  // "moduleName" is identical to pkg.name
}

Methods

readdirScoped(path)

• path: A string pointing to the path of a directory, either absolute or relative to the current working directory. Eg: ./node_modules/

Returns: AsyncGenerator that emits string of the name of each found directory

Similar functionality to readdir() from readdir-scoped-modules.

Returns all directories in path, with the scoped directories (like @foo) expanded and joined with the directories directly beneath them (like eg. @foo/abc and @foo/bar if abc and bar are the two directories in @foo, though it will never expand to @- or .-prefixed subdirectories and will hence never return @foo/@xyz or @foo/.bin).

Will not return any directory with a name that begins with ..

readdirModuleTree(path, depth=0)

• path: A string pointing to the path of a directory, either absolute or relative to the current working directory. Eg: * ./node_modules/
• depth: If set to 0, then this method is identical to readdirScoped(path), else this will return also modules found this many layers deep

Returns: AsyncGenerator that emits string paths, relative to the provided path, for each found module

Works the same as readdirScoped with the addition that if depth is set to higher than 0, then for every result of readdirScoped a node_modules subdirectory is looked for and if found, readdirScoped is run on that directory as well, prefixing all results with the parent name/prefix followed by /node_modules/.

For a two level deep tree the name returned would be like foo/node_modules/bar/node_modules/xyz, which one can do .split('/node_modules/') on to get in array shape.

listInstalled(path, [{ filter(pkg, alias) }])

• path: A string pointing to the path of a module, either absolute or relative to the current working directory. Eg: ./*
• filter: An optional callback that's similar to Array.prototype.filter(). Called with the resolved package file + if the module is aliased also the alias. Like Array.prototype.filter() it expects a truthy value back to include the item and a falsy to skip it. If the value returned is a Promise it will be resolved before the value is checked.

Returns: Promise that resolves to a Map that has string keys of the names of the found dependencies and values being the parsed package.json files.

Similar functionality to readInstalled() from read-installed.

Returns all top level dependencies found installed for a module.

Parses all package.json in parallell using read-pkg with results corresponding to the read-pkg NormalizedPackageJson type.

listInstalledGenerator(path, [{ filter }])

• path: A string pointing to the path of a module, either absolute or relative to the current working directory. Eg: ./*
• filter: An optional callback that's similar to Array.prototype.filter(). Called with the resolved package file + if the module is aliased also the alias. Like Array.prototype.filter() it expects a truthy value back to include the item and a falsy to skip it. If the value returned is a Promise it will be resolved before the value is checked.

Returns: AsyncGenerator that emits an object for each of the found dependencies. The object has two properties: alias, containing the alias when the module has been installed under an alias, and pkg, containing the parsed package.json files of the found dependencies.

Same as listInstalled(path), but rather than parsing package.json in parallell, it parses it sequentially at the pace that it is consumed.

workspaceLookup([options])

• options.includeWorkspaceRoot=true: If set to false, then the workspace root will not be returned
• options.path='.': A string pointing to the path of the module to look up the package.json and installed modules for
• options.skipWorkspaces=false: If set, then no workspace lookup will be done and no workspaces be returned
• options.workspace: An array of strings that should match the name of a workspace, its path or its path prefix. Only matching workspaces will be returned (as well as the root if includeWorkspaceRoot is true). If a workspace can't be found, then an error will be thrown when the generator has been fully iterated through.

Returns: AsyncGenerator that emits { cwd, installed, pkg, workspace } for the root (if includeWorkspaceRoot is true) and each matching workspace (if skipWorkspaces isn't true). cwd is the path to the workspace or root, installed is an object that's the combined result of a listInstalled for the root and that cwd, pkg is the package.json of the workspace or root and workspace is the name of the workspace and is not set on the root result.

Used by

• installed-check / installed-check-core

Similar modules

• list-dependents – looks up the the modules depending on a provided module them and returns them in a similar way to this module
• read-workspaces – provides the workspace lookup functionality that this module uses