README

@badisi/latest-version

📦 Get latest versions of packages.

Features

✅ Get latest and next versions of packages (from package registries)
✅ Get wanted version of packages (if a version range or a tag is provided)
✅ Get installed version of packages (if installed locally or globally)
✅ Check if updates are available
✅ Cache support to increase data retrieval performance
✅ Support public/private repositories and proxies

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', 'npm@1.3.2', 'npm@beta', '@scope/name@^5.0.2']);

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

    // 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 or global installed version of the package (if installed).
     */
    installed?: string;
    /**
     * The latest version of the package found on the provided registry (if found).
     */
    latest?: string;
    /**
     * The next version of the package found on the provided registry (if found).
     */
    next?: string;
    /**
     * The latest version of the package found on the provided registry and satisfied by the provided tag or version range (if provided).
     */
    wanted?: string;
    /**
     * The tag or version range that was provided (if provided).
     */
    wantedTagOrRange?: string;
    /**
     * Whether the installed version (if any) could be upgraded or not.
     */
    updatesAvailable: {
        latest: boolean;
        next: boolean;
        wanted: boolean;
    };
    /**
     * 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 always returned immediately, with either (for each provided packages):
     * 1) a latest/next version available if a cache was found
     * 2) no latest/next version available if no cache was found - in such case updates will be fetched in the background and a cache will
     * be created for each provided packages and made available for the next call to the api.
     *
     * @default false
     */
    useCache?: boolean;

    /**
     * How long the cache for the 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) The api will returned immediately (without any latest nor next version available for the provided packages)
     * 2) New updates will be fetched in the background
     * 3) 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;
}

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.

Usage no npm install needed!