@badisi/latest-version 2.0.5 → 2.1.2

package/README.md

@@ -3,7 +3,7 @@
 📦 Get latest versions of packages.
 
 [![npm version](https://img.shields.io/npm/v/@badisi/latest-version.svg?color=blue&logo=npm)][npm]
-[![npm downloads](https://img.shields.io/npm/dw/@badisi/latest-version.svg?color=blue&logo=npm)][npm-dl]
+[![npm downloads](https://img.shields.io/npm/dw/@badisi/latest-version.svg?color=7986CB&logo=npm)][npm-dl]
 [![license](https://img.shields.io/npm/l/@badisi/latest-version.svg?color=ff69b4)][license]
 
 [![build status](https://github.com/badisi/latest-version/workflows/CI%20tests/badge.svg)][ci-tests]
@@ -11,34 +11,39 @@
 <!--[![dependencies status](https://img.shields.io/david/badisi/latest-version.svg)][deps]-->
 <!--[![devDependencies status](https://img.shields.io/david/dev/badisi/latest-version.svg)][dev-deps]-->
 
-<hr>
+<hr/>
 
 ## Features
 
-* Get latest versions of packages *(from package registries)*
-  * `latest`, `next` and `wanted` 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
+✅ Get `latest` and `next` versions of packages *(from package registries)*<br/>
+✅ Get `wanted` version of packages *(if a version range or a tag is provided)*<br/>
+✅ Get `installed` version of packages *(if installed locally or globally)*<br/>
+✅ Check if `updates` are available<br/>
+✅ Cache support to increase data retrieval performance<br/>
+✅ Support public/private repositories and proxies<br/>
 
 ## Installation
 
 ```sh
-$ npm install @badisi/latest-version --save
+npm install @badisi/latest-version --save
 ```
 
 ```sh
-$ yarn add @badisi/latest-version
+yarn add @badisi/latest-version
 ```
 
 ## Usage
 
 __Example__
 
-```js
-const { readFileSync } = require('fs');
-const latestVersion = require('@badisi/latest-version');
+```ts
+/** 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
@@ -159,13 +164,13 @@ See the [developer docs][developer].
 
 ## Contributing
 
-### Want to Help ?
+#### > 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][contributing], and learn about submission process, coding rules and more.
 
-### Code of Conduct
+#### > Code of Conduct
 
 Please read and follow the [Code of Conduct][codeofconduct] and help me keep this project open and inclusive.
 
@@ -177,8 +182,8 @@ Please read and follow the [Code of Conduct][codeofconduct] and help me keep thi
 [ci-tests]: https://github.com/badisi/latest-version/actions?query=workflow:CI%20tests
 [deps]: https://david-dm.org/badisi/latest-version
 [dev-deps]: https://david-dm.org/badisi/latest-version?type=dev
-[pullrequest]: https://github.com/badisi/latest-version/blob/master/CONTRIBUTING.md#-submitting-a-pull-request-pr
-[license]: https://github.com/badisi/latest-version/blob/master/LICENSE
-[developer]: https://github.com/badisi/latest-version/blob/master/DEVELOPER.md
-[contributing]: https://github.com/badisi/latest-version/blob/master/CONTRIBUTING.md
-[codeofconduct]: https://github.com/badisi/latest-version/blob/master/CODE_OF_CONDUCT.md
+[pullrequest]: https://github.com/badisi/latest-version/blob/main/CONTRIBUTING.md#-submitting-a-pull-request-pr
+[license]: https://github.com/badisi/latest-version/blob/main/LICENSE
+[developer]: https://github.com/badisi/latest-version/blob/main/DEVELOPER.md
+[contributing]: https://github.com/badisi/latest-version/blob/main/CONTRIBUTING.md
+[codeofconduct]: https://github.com/badisi/latest-version/blob/main/CODE_OF_CONDUCT.md

package/{index.js → cjs/index.js}

@@ -32,7 +32,7 @@ const downloadMetadata = (pkgName, options) => {
             requestOptions.headers.authorization = `${authInfo.type} ${authInfo.token}`;
         }
         if (options === null || options === void 0 ? void 0 : options.requestOptions) {
-            requestOptions = { ...requestOptions, ...options.requestOptions };
+            requestOptions = Object.assign(Object.assign({}, requestOptions), options.requestOptions);
         }
         const { get } = require((pkgUrl.protocol === 'https:') ? 'https' : 'http');
         const request = get(requestOptions, (res) => {
@@ -98,7 +98,7 @@ const getMetadataFromCache = (pkgName, options) => {
     }
     return undefined;
 };
-const getLatestVersions = async (pkgName, tagOrRange, options) => {
+const getLatestVersions = (pkgName, tagOrRange, options) => (0, tslib_1.__awaiter)(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     let pkgMetadata;
     if (pkgName.length && (options === null || options === void 0 ? void 0 : options.useCache)) {
@@ -108,7 +108,7 @@ const getLatestVersions = async (pkgName, tagOrRange, options) => {
         }
     }
     else if (pkgName.length) {
-        pkgMetadata = await downloadMetadata(pkgName, options);
+        pkgMetadata = yield downloadMetadata(pkgName, options);
     }
     const versions = {
         latest: (_a = pkgMetadata === null || pkgMetadata === void 0 ? void 0 : pkgMetadata.distTags) === null || _a === void 0 ? void 0 : _a.latest,
@@ -121,18 +121,18 @@ const getLatestVersions = async (pkgName, tagOrRange, options) => {
         versions.wanted = (0, semver_1.maxSatisfying)(pkgMetadata.versions, tagOrRange) || undefined;
     }
     return versions;
-};
+});
 const getInstalledVersion = (pkgName) => {
     var _a;
     try {
         const paths = ['.', global_dirs_1.npm.packages, global_dirs_1.yarn.packages];
         return (_a = require(require.resolve((0, path_1.join)(pkgName, 'package.json'), { paths }))) === null || _a === void 0 ? void 0 : _a.version;
     }
-    catch {
+    catch (_b) {
         return undefined;
     }
 };
-const getInfo = async (pkg, options) => {
+const getInfo = (pkg, options) => (0, tslib_1.__awaiter)(void 0, void 0, void 0, function* () {
     const i = pkg.lastIndexOf('@');
     let pkgInfo = {
         name: (i > 1) ? pkg.slice(0, i) : pkg,
@@ -140,11 +140,7 @@ const getInfo = async (pkg, options) => {
         updatesAvailable: { latest: false, next: false, wanted: false }
     };
     try {
-        pkgInfo = {
-            ...pkgInfo,
-            installed: getInstalledVersion(pkgInfo.name),
-            ...(await getLatestVersions(pkgInfo.name, pkgInfo.wantedTagOrRange, options))
-        };
+        pkgInfo = Object.assign(Object.assign(Object.assign({}, pkgInfo), { installed: getInstalledVersion(pkgInfo.name) }), (yield getLatestVersions(pkgInfo.name, pkgInfo.wantedTagOrRange, options)));
         pkgInfo.updatesAvailable = {
             latest: (pkgInfo.installed && pkgInfo.latest) ? (0, semver_1.gt)(pkgInfo.latest, pkgInfo.installed) : false,
             next: (pkgInfo.installed && pkgInfo.next) ? (0, semver_1.gt)(pkgInfo.next, pkgInfo.installed) : false,
@@ -155,8 +151,8 @@ const getInfo = async (pkg, options) => {
         pkgInfo.error = (err === null || err === void 0 ? void 0 : err.message) || err;
     }
     return pkgInfo;
-};
-const latestVersion = async (arg, options) => {
+});
+const latestVersion = (arg, options) => (0, tslib_1.__awaiter)(void 0, void 0, void 0, function* () {
     const pkgs = [];
     if (typeof arg === 'string') {
         pkgs.push(arg);
@@ -174,9 +170,9 @@ const latestVersion = async (arg, options) => {
         addDeps(arg.devDependencies);
         addDeps(arg.peerDependencies);
     }
-    const jobs = await Promise.allSettled(pkgs.map((pkg) => getInfo(pkg, options)));
+    const jobs = yield Promise.allSettled(pkgs.map((pkg) => getInfo(pkg, options)));
     const results = jobs.map((jobResult) => jobResult.value);
     return (typeof arg === 'string') ? results[0] : results;
-};
+});
 exports.default = latestVersion;
 module.exports = latestVersion;

package/cjs/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "commonjs"
+}

package/esm/index.d.ts

@@ -0,0 +1,142 @@
+/// <reference types="node" />
+import { Agent } from 'http';
+interface LatestVersions {
+    /**
+     * 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;
+}
+interface LatestVersionPackage extends LatestVersions {
+    /**
+     * The name of the package.
+     */
+    name: string;
+    /**
+     * The current local or global installed version of the package (if installed).
+     */
+    installed?: 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;
+}
+interface RequestOptions {
+    readonly ca?: string | Buffer | Array<string | Buffer>;
+    readonly rejectUnauthorized?: boolean;
+    readonly agent?: Agent | boolean;
+    readonly timeout?: number;
+}
+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
+     */
+    readonly 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
+     */
+    readonly 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/'
+     */
+    readonly 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 }
+     */
+    readonly requestOptions?: RequestOptions;
+}
+declare type LatestVersion = {
+    /**
+     * Get latest versions of packages from of a package json like object.
+     *
+     * @param {PackageJson} item - A package json like object (with dependencies, devDependencies and peerDependencies attributes).
+     * @example { dependencies: { 'npm': 'latest' }, devDependencies: { 'npm': '1.3.2' }, peerDependencies: { '@scope/name': '^5.0.2' } }
+     * @param {LatestVersionOptions} [options] - An object optionally specifying the use of the cache, the max age of the cache, the registry url and the http or https options.
+     * If `useCache` is not supplied, the default of `false` is used.
+     * If `cacheMaxAge` is not supplied, the default of `one day` is used.
+     * If `registryUrl` is not supplied, the default from `.npmrc` is used or a fallback to the `npm registry url` instead.
+     * @returns {Promise<LatestVersionPackage[]>}
+     */
+    (item: PackageJson, options?: LatestVersionOptions): Promise<LatestVersionPackage[]>;
+    /**
+     * Get latest version of a single package.
+     *
+     * @param {Package} item - A single package object (represented by a string that should match the following format: `${'@' | ''}${string}@${string}`)
+     * @example 'npm', 'npm@1.3.2', '@scope/name@^5.0.2'
+     * @param {LatestVersionOptions} [options] - An object optionally specifying the use of the cache, the max age of the cache, the registry url and the http or https options.
+     * If `useCache` is not supplied, the default of `false` is used.
+     * If `cacheMaxAge` is not supplied, the default of `one day` is used.
+     * If `registryUrl` is not supplied, the default from `.npmrc` is used or a fallback to the npm registry url instead.
+     * @returns {Promise<LatestVersionPackage>}
+     */
+    (item: Package, options?: LatestVersionOptions): Promise<LatestVersionPackage>;
+    /**
+     * Get latest versions of a collection of packages.
+     *
+     * @param {Package[]} items - A collection of package object (represented by a string that should match the following format: `${'@' | ''}${string}@${string}`)
+     * @example ['npm', 'npm@1.3.2', '@scope/name@^5.0.2']
+     * @param {LatestVersionOptions} [options] - An object optionally specifying the use of the cache, the max age of the cache, the registry url and the http or https options.
+     * If `useCache` is not supplied, the default of `false` is used.
+     * If `cacheMaxAge` is not supplied, the default of `one day` is used.
+     * If `registryUrl` is not supplied, the default from `.npmrc` is used or a fallback to the npm registry url instead.
+     * @returns {Promise<LatestVersionPackage[]>}
+     */
+    (items: Package[], options?: LatestVersionOptions): Promise<LatestVersionPackage[]>;
+};
+declare type PackageRange = `${'@' | ''}${string}@${string}`;
+declare type Package = string | PackageRange;
+declare type PackageJsonDependencies = Record<string, string>;
+declare type PackageJson = Record<string, any> & ({
+    dependencies: PackageJsonDependencies;
+} | {
+    devDependencies: PackageJsonDependencies;
+} | {
+    peerDependencies: PackageJsonDependencies;
+});
+declare const latestVersion: LatestVersion;
+export { LatestVersion, Package, PackageRange, PackageJson, PackageJsonDependencies, LatestVersions, LatestVersionPackage, RequestOptions, LatestVersionOptions };
+export default latestVersion;

package/esm/index.js

@@ -0,0 +1,177 @@
+import getRegistryUrl from 'registry-auth-token/registry-url';
+import registryAuthToken from 'registry-auth-token';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { gt, maxSatisfying } from 'semver';
+import { npm, yarn } from 'global-dirs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { URL } from 'url';
+const ONE_DAY = 1000 * 60 * 60 * 24; // eslint-disable-line @typescript-eslint/naming-convention
+const isPackageJson = (obj) => {
+    return (obj.dependencies !== undefined) ||
+        (obj.devDependencies !== undefined) ||
+        (obj.peerDependencies !== undefined);
+};
+const downloadMetadata = (pkgName, options) => {
+    return new Promise((resolve, reject) => {
+        const i = pkgName.indexOf('/');
+        const pkgScope = (i !== -1) ? pkgName.slice(0, i) : '';
+        const registryUrl = options?.registryUrl || getRegistryUrl(pkgScope);
+        const pkgUrl = new URL(encodeURIComponent(pkgName).replace(/^%40/, '@'), registryUrl);
+        let requestOptions = {
+            headers: { accept: 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*' },
+            host: pkgUrl.hostname,
+            path: pkgUrl.pathname,
+            port: pkgUrl.port
+        };
+        const authInfo = registryAuthToken(pkgUrl.toString(), { recursive: true });
+        if (authInfo && requestOptions.headers) {
+            requestOptions.headers.authorization = `${authInfo.type} ${authInfo.token}`;
+        }
+        if (options?.requestOptions) {
+            requestOptions = { ...requestOptions, ...options.requestOptions };
+        }
+        const { get } = require((pkgUrl.protocol === 'https:') ? 'https' : 'http');
+        const request = get(requestOptions, (res) => {
+            if (res.statusCode === 200) {
+                let rawData = '';
+                res.setEncoding('utf8');
+                res.on('data', (chunk) => rawData += chunk);
+                res.once('end', () => {
+                    res.setTimeout(0);
+                    res.removeAllListeners();
+                    try {
+                        const pkgMetadata = JSON.parse(rawData);
+                        return resolve({
+                            name: pkgName,
+                            lastUpdateDate: Date.now(),
+                            versions: Object.keys(pkgMetadata.versions),
+                            distTags: pkgMetadata['dist-tags']
+                        });
+                    }
+                    catch (err) {
+                        return reject(err);
+                    }
+                });
+            }
+            else {
+                res.removeAllListeners();
+                res.resume(); // consume response data to free up memory
+                return reject(`Request error (${res.statusCode}): ${pkgUrl}`);
+            }
+        });
+        const abort = (error) => {
+            request.removeAllListeners();
+            request.destroy();
+            return reject(error);
+        };
+        request.once('timeout', () => abort(`Request timed out: ${pkgUrl}`));
+        request.once('error', (err) => abort(err));
+    });
+};
+const getCacheDir = (name = '@badisi/latest-version') => {
+    const homeDir = homedir();
+    switch (process.platform) {
+        case 'darwin': return join(homeDir, 'Library', 'Caches', name);
+        case 'win32': return join(process.env.LOCALAPPDATA || join(homeDir, 'AppData', 'Local'), name, 'Cache');
+        default: return join(process.env.XDG_CACHE_HOME || join(homeDir, '.cache'), name);
+    }
+};
+const saveMetadataToCache = (pkg) => {
+    const filePath = join(getCacheDir(), `${pkg.name}.json`);
+    if (!existsSync(dirname(filePath))) {
+        mkdirSync(dirname(filePath), { recursive: true });
+    }
+    writeFileSync(filePath, JSON.stringify(pkg));
+};
+const getMetadataFromCache = (pkgName, options) => {
+    const pkgCacheFilePath = join(getCacheDir(), `${pkgName}.json`);
+    if (existsSync(pkgCacheFilePath)) {
+        const pkg = JSON.parse(readFileSync(pkgCacheFilePath).toString());
+        const maxAge = (options?.cacheMaxAge !== undefined) ? options.cacheMaxAge : ONE_DAY;
+        if ((Date.now() - pkg.lastUpdateDate) < maxAge) {
+            return pkg;
+        }
+    }
+    return undefined;
+};
+const getLatestVersions = async (pkgName, tagOrRange, options) => {
+    let pkgMetadata;
+    if (pkgName.length && options?.useCache) {
+        pkgMetadata = getMetadataFromCache(pkgName, options);
+        if (!pkgMetadata) {
+            return downloadMetadata(pkgName, options).then(saveMetadataToCache);
+        }
+    }
+    else if (pkgName.length) {
+        pkgMetadata = await downloadMetadata(pkgName, options);
+    }
+    const versions = {
+        latest: pkgMetadata?.distTags?.latest,
+        next: pkgMetadata?.distTags?.next
+    };
+    if (tagOrRange && pkgMetadata?.distTags && pkgMetadata?.distTags[tagOrRange]) {
+        versions.wanted = pkgMetadata.distTags[tagOrRange];
+    }
+    else if (tagOrRange && pkgMetadata?.versions?.length) {
+        versions.wanted = maxSatisfying(pkgMetadata.versions, tagOrRange) || undefined;
+    }
+    return versions;
+};
+const getInstalledVersion = (pkgName) => {
+    try {
+        const paths = ['.', npm.packages, yarn.packages];
+        return require(require.resolve(join(pkgName, 'package.json'), { paths }))?.version;
+    }
+    catch {
+        return undefined;
+    }
+};
+const getInfo = async (pkg, options) => {
+    const i = pkg.lastIndexOf('@');
+    let pkgInfo = {
+        name: (i > 1) ? pkg.slice(0, i) : pkg,
+        wantedTagOrRange: (i > 1) ? pkg.slice(i + 1) : undefined,
+        updatesAvailable: { latest: false, next: false, wanted: false }
+    };
+    try {
+        pkgInfo = {
+            ...pkgInfo,
+            installed: getInstalledVersion(pkgInfo.name),
+            ...(await getLatestVersions(pkgInfo.name, pkgInfo.wantedTagOrRange, options))
+        };
+        pkgInfo.updatesAvailable = {
+            latest: (pkgInfo.installed && pkgInfo.latest) ? gt(pkgInfo.latest, pkgInfo.installed) : false,
+            next: (pkgInfo.installed && pkgInfo.next) ? gt(pkgInfo.next, pkgInfo.installed) : false,
+            wanted: (pkgInfo.installed && pkgInfo.wanted) ? gt(pkgInfo.wanted, pkgInfo.installed) : false
+        };
+    }
+    catch (err) {
+        pkgInfo.error = err?.message || err;
+    }
+    return pkgInfo;
+};
+const latestVersion = async (arg, options) => {
+    const pkgs = [];
+    if (typeof arg === 'string') {
+        pkgs.push(arg);
+    }
+    else if (Array.isArray(arg)) {
+        pkgs.push(...arg);
+    }
+    else if (isPackageJson(arg)) {
+        const addDeps = (deps) => {
+            if (deps) {
+                pkgs.push(...Object.keys(deps).map((key) => `${key}@${deps[key]}`));
+            }
+        };
+        addDeps(arg.dependencies);
+        addDeps(arg.devDependencies);
+        addDeps(arg.peerDependencies);
+    }
+    const jobs = await Promise.allSettled(pkgs.map((pkg) => getInfo(pkg, options)));
+    const results = jobs.map((jobResult) => jobResult.value);
+    return (typeof arg === 'string') ? results[0] : results;
+};
+export default latestVersion;
+module.exports = latestVersion;

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}

package/package.json

@@ -1,14 +1,21 @@
 {
     "name": "@badisi/latest-version",
-    "version": "2.0.5",
+    "version": "2.1.2",
     "description": "Get latest versions of packages",
     "homepage": "https://github.com/badisi/latest-version",
     "license": "MIT",
     "author": {
         "name": "Badisi"
     },
-    "main": "./index.js",
-    "types": "./index.d.ts",
+    "main": "cjs/index.js",
+    "module": "esm/index.js",
+    "types": "esm/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./cjs/index.js",
+            "import": "./esm/index.js"
+        }
+    },
     "repository": {
         "type": "git",
         "url": "https://github.com/badisi/latest-version.git"
@@ -31,5 +38,8 @@
         "global-dirs": "^3.0.0",
         "registry-auth-token": "^4.2.1",
         "semver": "^7.3.5"
+    },
+    "engines": {
+        "node": ">= 12"
     }
 }