installed-check-core

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: Type PackageJsonLike – the content of the package.json file to check
• key: Type string – the key of the version range to check, eg engines.node
• installed: Type InstalledDependencies – the package.json files of the installed dependencies
• options: Type VersionRangeOptions – 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 dependency
• noDev = false – dev dependencies won't be included in the check
• ignore = string[]|((test: string) => boolean) – names of modules to exclude from checks or a function that returns true for 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:

• key is for a collection of range, eg engines rather than engines.node
• The results for every individual version range is returned in an object keyed with the full key for that range, eg: { 'engines.node': ... }
• Accepts an additional optional defaultKeys option that's used if the collection for key is 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: Type InstalledChecks[] – the checks to run, an array of one or more of: 'engine', 'peer', 'version'
• lookupOptions: Type LookupOptions – optional – defaults to cwd='.' and includeWorkspaceRoot: true
• options: Type InstalledCheckOptions – 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 the package.json and suggest an alternative requirement if the installed modules don't comply.
• peer – like engine but for peerDependencies instead. Will check that the promised peerDependencies are not wider than those of ones required dependencies.
• version – will check that the installed modules comply with the version requirements set for them the package.json.

Lookup options

The same as from read-workspaces / list-installed

Options

• fix = false – when set it will modify the package.json files to apply fixes whenever possible
• ignores = string[] – names of modules to exclude from checks. Supports picomatch globbing syntax, eg. @types/*. (Not supported by version checks)
• noDev = false – exclude devDependencies from checks. devDependencies that are also in peerDependencies will not be ignored. (Not supported by version checks)
• 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: Type InstalledChecks[] – same as for installedCheck()
• pkg: Type PackageJsonLike – the content of the package.json file to check
• installed: Type InstalledDependencies – the package.json files of the installed dependencies
• options: Type InstalledCheckOptions – same as for installedCheck(), but without the cwd option

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-check CLI tool
  • ...and eg. pretty much all of my (@voxpelli's) node.js projects uses the installed-check CLI tool
• 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 to installed-check