Skip to content

πŸ“¦ Get latest versions of packages

License

Notifications You must be signed in to change notification settings

Badisi/latest-version

Repository files navigation

@badisi/latest-version

πŸ“¦ Get latest versions of packages.

npm version npm donwloads license

build status PRs welcome


Features

βœ… Get installed versions of packages (if installed locally or globally with npm or yarn)
βœ… Get latest and next versions of packages (from package registries)
βœ… Get wanted version of packages (if a version range or a tag is provided)
βœ… Check if any updates are available
βœ… Cache support to increase data retrieval performance
βœ… Support public/private repositories and proxies
βœ… Command line tool that helps visualize packages updates

Installation

npm install @badisi/latest-version --save
yarn add @badisi/latest-version

Usage

Example

/** CommonJS */
// const { readFileSync } = require('fs');
// const latestVersion = require('@badisi/latest-version');

/** ESM / Typescript */
import { readFileSync } from 'fs';
import latestVersion from '@badisi/latest-version';

(async () => {
    // Single package
    const pkg = await latestVersion('npm');

    // List of packages
    const pkgs = await latestVersion(['npm', '[email protected]', 'npm@beta', '@scope/name@^5.0.2']);

    // Package.json
    const pkgs = await latestVersion(JSON.parse(readFileSync('package.json').toString()));

    // Using cache
    const pkg = await latestVersion('npm@^5.0.2', { useCache: true });
})();

Return

Either a collection or a single LatestVersionPackage object:

interface LatestVersionPackage {
    /**
     * The name of the package.
     */
    name: string;
    /**
     * The current local installed version of the package (if installed).
     */
    local?: string;
    /**
     * The current npm global installed version of the package (if installed).
     */
    globalNpm?: string;
    /**
     * The current yarn global installed version of the package (if installed).
     */
    globalYarn?: string;
    /**
     * The latest version of the package found on the registry (if found).
     */
    latest?: string;
    /**
     * The next version of the package found on the registry (if found).
     */
    next?: string;
    /**
     * The tag or version range that was provided (if provided).
     *
     * @default "latest"
     */
    wantedTagOrRange?: string;
    /**
     * The latest version of the package found on the registry and satisfied by the wanted tag or version range.
     */
    wanted?: string;
    /**
     * Whether the local or global installed versions (if any) could be upgraded or not, based on the wanted version.
     */
    updatesAvailable: {
        local: string | false;
        globalNpm: string | false;
        globalYarn: string | false;
    } | false;
    /**
     * Any error that might have occurred during the process.
     */
    error?: Error;
}

Options

interface LatestVersionOptions {
    /**
     * Awaiting the api to return might take time, depending on the network, and might impact your package loading performance.
     * You can use the cache mechanism to improve load performance and reduce unnecessary network requests.
     * If `useCache` is not supplied, the api will always check for updates and wait for every requests to return before returning itself.
     * If `useCache` is used, the api will either (for each provided packages):
     * 1) return immediately if a cache was found.
     * 2) fetch and wait for updates of that particular package then creates a cache for it so that it is available for the next call to the api.
     *
     * @default false
     */
    useCache?: boolean;

    /**
     * How long the cache for each provided packages should be used before being refreshed (in milliseconds).
     * If `useCache` is not supplied, this option has no effect.
     * If `0` is used, this will force the cache to refresh immediately:
     * 1) New updates will be fetched and waited
     * 2) The cache for each provided packages will be refreshed and made available for the next call to the api
     *
     * @default ONE_DAY
     */
    cacheMaxAge?: number;

    /**
     * A JavaScript package registry url that implements the CommonJS Package Registry specification.
     *
     * @default "Looks at any registry urls in the .npmrc file or fallback to the default npm registry instead"
     * @example <caption>.npmrc</caption>
     * registry = 'https://custom-registry.com/'
     * @pkgscope:registry = 'https://custom-registry.com/'
     */
    registryUrl?: string;

    /**
     * Set of options to be passed down to Node.js http/https request.
     *
     * @example <caption>Behind a proxy with self-signed certificate</caption>
     * { ca: fs.readFileSync('proxy-cert.pem') }
     * @example <caption>Bypassing certificate validation</caption>
     * { rejectUnauthorized: false }
     */
    requestOptions?: RequestOptions;
}

Command line tool

The CLI utility will help you visualize any available updates for a given package.json file, a local package.json file or any provided package names.

$ latest-version <packageJson|packageName...>

  Examples:
    $ lv
    $ latest-version path/to/package.json
    $ latest-version package1 package2 package3 --skip-missing

CLI utility preview

Development

See the developer docs.

Contributing

> Want to Help ?

Want to file a bug, contribute some code or improve documentation ? Excellent!

But please read up first on the guidelines for contributing, and learn about submission process, coding rules and more.

> Code of Conduct

Please read and follow the Code of Conduct and help me keep this project open and inclusive.