voxpelli
Checks that the installed modules fulfill the requirements of package.json, both when it comes to the version ranges of the modules themselves and when it comes to the version range of their engine requirements.
Exists as a CLI as well: installed-check
Usage
import { installedCheck } from 'installed-check-core';
const { errors, suggestions } = await installedCheck(['version']);
if (result.errors.length) {
console.error('Dependency errors: \n\n' + result.errors.join('\n') + '\n');
}
if (result.suggestions.length) {
console.error('Suggestions: \n\n' + result.suggestions.join('\n') + '\n');
}
In CommonJS using dynamic import() expression
const { installedCheck } = await import('installed-check-core');
API
checkVersionRange()
The rich version range check that installed-check itself uses.
Syntax
checkVersionRange(pkg, key, installed, [options]) => VersionRangeResult
Arguments
pkg: TypePackageJsonLike– the content of thepackage.jsonfile to checkkey: Typestring– the key of the version range to check, egengines.nodeinstalled: TypeInstalledDependencies– thepackage.jsonfiles of the installed dependenciesoptions: TypeVersionRangeOptions– optional options
Types
type VersionRangeItem = {
valid: boolean | undefined,
suggested?: string | undefined,
note: string | undefined,
}
type VersionRangeResult = VersionRangeItem & {
packageNotes: Array<
VersionRangeItem & { name: string }
>
}
Options
expectedInDependencies = false– a warning will be issued when the key is empty or not found in a dependencynoDev = false– dev dependencies won't be included in the checkignore = string[]|((test: string) => boolean)– names of modules to exclude from checks or a function that returnstruefor those that should be ignores (the latter handy for supporting eg. glob patterns)strict = false– converts most warnings into failures.
Example
import { checkVersionRange } from 'installed-check-core';
import { listInstalled } from 'list-installed';
import { readPackage } from 'read-pkg';
const cwd = '.';
const [pkg, installed] = await Promise.all([
readPackage({ cwd }),
listInstalled(cwd),
]);
const result = await checkVersionRange(
pkg,
'engines.node',
installed,
{
expectedInDependencies: true,
noDev: true,
ignore: ['example'],
strict: true,
}
);
for (const item of result.packageNotes) {
if (item.note) {
console.log(`${item.valid === false ? 'Error' : 'Warning'} in ${item.name}: ${item.note}`);
}
}
if (result.note) {
console.log(`${result.valid === false ? 'Error' : 'Warning'}: ${result.note}`);
}
if (result.valid === true) {
console.log('All good!');
} else if (result.suggested) {
console.log('Combined engines.node needs to be narrower:', result.suggested);
} else {
console.log('Incompatible combined engines.node requirements.');
}
checkVersionRangeCollection()
Wrapper around as checkVersionRange() that differs from it in three ways:
keyis for a collection of range, egenginesrather thanengines.node- The results for every individual version range is returned in an
objectkeyed with the full key for that range, eg:{ 'engines.node': ... } - Accepts an additional optional
defaultKeysoption that's used if the collection forkeyis empty. Eg:{ defaultKeys: ['node'] }
Syntax
checkVersionRangeCollection(pkg, key, installed, [options]) => VersionRangeCollectionResult
Arguments
See main description of checkVersionRangeCollection() and full docs for checkVersionRange().
installedCheck()
The full on installed-check experience, returning error and warning strings only.
Syntax
installedCheck(checks, [lookupOptions], [options]) => Promise<InstalledCheckResult>
Arguments
checks: TypeInstalledChecks[]– the checks to run, an array of one or more of:'engine','peer','version'lookupOptions: TypeLookupOptions– optional – defaults tocwd='.'andincludeWorkspaceRoot: trueoptions: TypeInstalledCheckOptions– optional
Types
type LookupOptions = {
cwd?: string | undefined;
ignorePaths?: string[] | undefined;
includeWorkspaceRoot?: boolean | undefined;
skipWorkspaces?: boolean | undefined;
workspace?: string[] | undefined;
};
type InstalledChecks = 'engine' | 'peer' | 'version'
type InstalledCheckOptions = {
fix?: boolean | undefined;
ignore?: string[] | undefined;
noDev?: boolean | undefined;
prefix?: string | undefined;
strict?: boolean | undefined;
};
type InstalledCheckResult = {
errors: string[],
warnings: string[],
suggestions: string[],
}
Checks
engine– will check that the installed modules comply with the engines requirements of thepackage.jsonand suggest an alternative requirement if the installed modules don't comply.peer– likeenginebut forpeerDependenciesinstead. Will check that the promisedpeerDependenciesare not wider than those of ones required dependencies.version– will check that the installed modules comply with the version requirements set for them thepackage.json.
Lookup options
The same as from read-workspaces / list-installed
Options
fix = false– when set it will modify thepackage.jsonfiles to apply fixes whenever possibleignores = string[]– names of modules to exclude from checks. Supportspicomatchglobbing syntax, eg.@types/*. (Not supported byversionchecks)noDev = false– excludedevDependenciesfrom checks.devDependenciesthat are also inpeerDependencieswill not be ignored. (Not supported byversionchecks)strict = false– converts most warnings into failures
Example
import { installedCheck } from 'installed-check-core';
const { errors, warnings, suggestions } = await installedCheck(['engine', 'version'], {
cwd: 'path/to/module',
ignore: ['foo'],
noDev: true,
});
performInstalledCheck()
Similar to installedCheck() but expects to be given package data instead of looking it up itself..
Syntax
performInstalledCheck(checks, pkg, installed, options) => Promise<PerformInstalledCheckResult>
Arguments
checks: TypeInstalledChecks[]– same as forinstalledCheck()pkg: TypePackageJsonLike– the content of thepackage.jsonfile to checkinstalled: TypeInstalledDependencies– thepackage.jsonfiles of the installed dependenciesoptions: TypeInstalledCheckOptions– same as forinstalledCheck(), but without thecwdoption
Types
PackageJsonLike
// Subset of import('type-fest').PackageJson / import('read-pkg').NormalizedPackageJson
export type PackageJsonLike = {
name?: string | undefined;
version?: string | undefined;
engines?: Record<string, string | undefined>;
dependencies?: Record<string, string | undefined>;
devDependencies?: Record<string, string | undefined>;
optionalDependencies?: Record<string, string | undefined>;
peerDependencies?: Record<string, string | undefined>;
};
InstalledDependencies
// A map is allowed since that's what import('list-installed).listInstalled returns
export type InstalledDependencies = Map<string, PackageJsonLike> | Record<string, PackageJsonLike>;
Used by
- Used by the
installed-checkCLI tool- ...and eg. pretty much all of my (@voxpelli's) node.js projects uses the
installed-checkCLI tool
- ...and eg. pretty much all of my (@voxpelli's) node.js projects uses the
- Find more on GitHub or npm
Similar modules
knip– finds unused files, dependencies and exports in your JavaScript and TypeScript projects – a great companion module toinstalled-check