check-kit

Checks if a newer version is available for command line interfaces.

It is designed to be extremely easy to use and for CLI's that want to be in control.

What check-kit does:

• Checks if there is a new version available
• Checks version for a specific dist tag
• Fetches latest version from npm based on time interval
• Persists the update metadata
• Supports HTTP proxies

What check-kit does not do:

• Display a message when a new version is available, that's up to you how you want it formatted

Installation

npm install check-kit --save

Example

Basic usage:

import check from 'check-kit';

(async () => {
    const { current, distTag, name, latest, updateAvailable } = await check();

    console.log(`Current version of package ${name} is ${current}`);

    if (updateAvailable) {
        console.log(`There is a new version available! ${current} -> ${latest}`);
    } else {
        console.log(`Version ${current} is the latest`);
    }
})();

If you know where the package.json is, you can pass it in:

const result = await check({
    pkg: require('./package.json')
});

By default, check-kit will store update metadata in /tmp/check-kit directory. You can override the directory, but not the metadata filename, by passing in the metadata directory:

const result = await check({
    metaDir: `${os.homedir()}/myapp/update`
});

API

async check(opts)

Checks if the specified package has a newer version available.

opts and all options are optional.

Option	Type	Default	Description
opts.applyOwner	Boolean	true	When true, determines the owner of the closest existing parent directory and apply the owner to the file and any newly created directories.
opts.caFile	String		A path to a PEM-formatted certificate authority bundle.
opts.certFile	String		A path to a client cert file used for authentication.
opts.checkInterval	Number	3600000	The amount of time in milliseconds before checking for an update. Defaults to 1 hour.
opts.cwd	String	"."	The current working directory used to locate the package.json if opts.pkg is not specified.
opts.distTag	String	"latest"	The tag to check for the latest version.
opts.force	Boolean	false	Forces an update check.
opts.keyFile	String		A path to a private key file used for authentication.
opts.metaDir	String	"/tmp/check-kit/"	The directory to store package update information. The filename is derived by the package name and the dist tag.
opts.pkg	Object | String		The parsed package.json, path to the package.json file, or falsey and it will scan parent directories looking for a package.json.
opts.proxy	String		A proxy server URL. Can be http or https.
opts.registryUrl	String		The npm registry URL. By default, it will autodetect the URL based on the package name/scope.
opts.strictSSL	Boolean	true	When falsey, disables TLS/SSL certificate validation for both https requests and https proxy servers.
opts.timeout	Number	1000	The number of milliseconds to wait to query npm before timing out.

Returns a Promise that resolves the following:

Property	Type	Description
current	String	The current version from the package.json.
distTag	String	The dist tag used to check the version.
lastCheck	Number	The timestamp the last check occurred.
latest	String | null	The latest version returned from the registry or null if the package is not found.
name	String	The package name.
updateAvailable	Boolean	Value is true if a new version is available.

Metadata file

The metadata file contains information about the package and whether an update is available based on the last check.

You can override the directory where the metadata file is stored, but you cannot override the metadata filename. The filename is derived from the package name and the distribution tag. For example, the package @foo/bar would resolve the filename @foo-bar-latest.json.

Comparison

	check-kit	update-notifier	update-check
Version	1.7.1	5.1.0	1.5.4
Default check interval	1 hour	24 hours	1 hour
Update check method	Async/await	Subprocess	Async/await
Notify of updates immediately	✅	❌	✅
Persist update available	✅	✅	✅
User-defined persistance directory	✅	❌	❌
Specify dist tag	✅	✅	✅
Specify package.json as object	✅	✅	✅
Specify package.json as path	✅	❌	❌
Automatically find package.json	✅	❌	❌
HTTP proxy support	✅	❌	❌
Force check for updates	✅	❌	❌
Automatic registry URL discovery	✅	✅	✅
Custom registry URL	✅	❌	❌
Registry auth token support	✅	✅	✅
Continuous integration check skip	✅	✅	❌
NODE_ENV=test check skip	✅	✅	❌
NO_UPDATE_NOTIFIER=1 check skip	✅	✅	❌
Graceful offline support	✅	✅	❌
Apply correct owner when sudo	✅	❌	❌
Type of semver update label	❌	✅	❌
Renders update available message	❌	✅	❌
Persisted opt-out setting	❌	✅	❌
License	Apache 2	BSD 2-clause	MIT

Legal

This project is open source under the Apache Public License v2 and is developed by Axway, Inc and the community. Please read the LICENSE file included in this distribution for more information.