@fnet/npm-list-versions

@fnet/npm-list-versions

This project provides a simple utility to retrieve and manage the version history of a specified npm package. It allows users to efficiently view all versions of a package available on the npm repository, and provides options for grouping these versions based on major, minor, or patch-level changes.

How It Works

The tool fetches the version list of a specified npm package directly from the npm registry using the npm view command. The results are then processed to provide a neat, reverse-sorted list of all available versions. If required, the versions can also be grouped by major, minor, or patch releases to better analyze the release pattern.

Key Features

• Version Retrieval: Accesses the full list of versions for a given npm package.
• Version Sorting: Provides versions in descending order for easy analysis.
• Pre-release Filtering: Optionally excludes pre-release versions to focus on stable releases.
• Version Grouping: Groups versions by major, minor, or patch increments to help users track progress at different levels of detail.

Conclusion

The @fnet/npm-list-versions utility offers a straightforward way to examine and categorize npm package versions, providing clarity and insight into the update history of any selected package. This can be especially helpful for developers seeking to understand version progression or determine compatibility with different versions.

Developer Guide for @fnet/npm-list-versions

Overview

The @fnet/npm-list-versions library is a helpful tool for developers who need to retrieve and organize version information for npm packages. This library allows you to list all available versions of a specified npm package and provides options to sort and group them by major, minor, or patch numbers. It also enables filtering out pre-release versions, providing you with a clean version history for your package management tasks.

Installation

You can install the @fnet/npm-list-versions library using either npm or yarn. Simply run one of the following commands in your terminal:

npm install @fnet/npm-list-versions

or

yarn add @fnet/npm-list-versions

Usage

Here's how you can use @fnet/npm-list-versions to fetch and organize package version information:

Basic Usage

To get a list of all stable versions of a package, you can simply call the exported index function with the package name:

import listVersions from '@fnet/npm-list-versions';

(async () => {
    try {
        const versions = await listVersions({ name: 'express' });
        console.log(versions);
    } catch (error) {
        console.error(error.message);
    }
})();

Excluding Pre-release Versions

If you want to exclude pre-release versions, ensure your call does not specify the prerelease option or sets it to false (which is the default behavior).

Grouping Versions

You can group versions by major, minor, or patch numbers by setting the corresponding options:

import listVersions from '@fnet/npm-list-versions';

(async () => {
    try {
        // Group by major version numbers
        const groupedByMajor = await listVersions({
            name: 'react',
            groupBy: { major: true }
        });
        console.log(groupedByMajor);

        // Group by minor version numbers
        const groupedByMinor = await listVersions({
            name: 'react',
            groupBy: { minor: true }
        });
        console.log(groupedByMinor);
    } catch (error) {
        console.error(error.message);
    }
})();

Examples

Retrieving All Versions

(async () => {
    try {
        const versions = await listVersions({ name: 'lodash' });
        console.log('All Stable Versions of Lodash:', versions);
    } catch (error) {
        console.error('Error:', error.message);
    }
})();

Grouping by Major Version

(async () => {
    try {
        const versions = await listVersions({
            name: 'vue',
            groupBy: { major: true }
        });
        console.log('Versions Grouped by Major:', versions);
    } catch (error) {
        console.error('Error:', error.message);
    }
})();

Acknowledgements

The @fnet/npm-list-versions library uses shelljs for executing shell commands and semver for version comparison and sorting, making it easier to handle version strings effectively.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  name:
    type: string
    description: The name of the npm package to query for versions.
  groupBy:
    type: object
    properties:
      major:
        type: boolean
        default: false
        description: Group versions by major version.
      minor:
        type: boolean
        default: false
        description: Group versions by minor version.
      patch:
        type: boolean
        default: false
        description: Group versions by patch version.
    description: Options for grouping versions.
  prerelease:
    type: boolean
    default: false
    description: Include prerelease versions in the results.
required:
  - name