pkg-stats 0.3.0 → 0.4.0

package/dist/__tests__/chart.test.js

@@ -1,7 +1,7 @@
 import { expect, test } from 'vitest';
 import { renderChart } from '../chart.js';
 test('renderChart basic tests', () => {
-    expect(renderChart(0.0, { length: 10 })).toMatchInlineSnapshot(`"          "`);
+    expect(renderChart(0.0, { length: 10 })).toMatchInlineSnapshot(`"▏         "`);
     expect(renderChart(0.5, { length: 10 })).toMatchInlineSnapshot(`"█████     "`);
     expect(renderChart(1.0, { length: 10 })).toMatchInlineSnapshot(`"██████████"`);
 });

package/dist/bin.js

@@ -1,60 +1,22 @@
 import chalk from 'chalk';
-import { renderChart } from './chart.js';
-import { parseCliOptions } from './cli-options.js';
-import { getColors } from './colors.js';
-import { fetchNpmLastWeekDownloads } from './npm-api.js';
-import { groupByType, pickTopStats } from './stats.js';
-import { parseVersion, versionCompare } from './version.js';
+import { parseCliOptions, showHelp } from './cli-options.js';
+import { comparePackages } from './mode/compare-packages.js';
+import { printPackageStats } from './mode/package-stats.js';
 export async function pkgStats(argv) {
-    const options = parseCliOptions(argv);
-    let data;
+    let options;
     try {
-        data = await fetchNpmLastWeekDownloads(options.packageName);
+        options = parseCliOptions(argv);
     }
     catch (error) {
-        console.error(`Failed to fetch data for package "${options.packageName}"`, error);
-        return;
+        showHelp();
+        console.error(chalk.red(`Error parsing CLI options: ${error instanceof Error ? error.message : error}`));
+        process.exit(2);
     }
-    if (!Object.keys(data.downloads).length) {
-        console.error(`No data found for package "${options.packageName}".\n`);
-        process.exit(1);
+    if (options.packageNames.length === 1) {
+        await printPackageStats(options.packageNames[0], options);
     }
-    const rawStats = Object.keys(data.downloads)
-        .map((versionString) => {
-        const version = parseVersion(versionString);
-        return {
-            ...version,
-            downloads: data.downloads[versionString],
-        };
-    })
-        .sort(versionCompare);
-    const groupedStats = groupByType(options.group, rawStats);
-    const totalDownloads = Object.values(groupedStats).reduce((sum, version) => sum + version.downloads, 0);
-    const groupedStatsToDisplay = options.top
-        ? pickTopStats(groupedStats, options.top)
-        : groupedStats;
-    const colors = getColors(groupedStatsToDisplay.length, options.color);
-    const primaryColor = chalk.hex(colors[0]);
-    console.log(chalk.bold(`\nNPM weekly downloads for ${primaryColor(options.packageName)}\n`));
-    console.log(`Total: ${primaryColor(totalDownloads.toLocaleString())} last week\n`);
-    console.log(options.top ? `Top ${options.top} versions:\n` : 'By version:\n');
-    const maxDownloads = Math.max(...groupedStats.map((v) => v.downloads));
-    groupedStatsToDisplay.forEach((item, i) => {
-        const versionParts = item.versionString.split('.');
-        const version = versionParts.length < 3 ? `${item.versionString}.x` : item.versionString;
-        const chart = renderChart(item.downloads / maxDownloads);
-        const downloads = formatDownloads(item.downloads, maxDownloads);
-        const color = chalk.hex(colors[i]);
-        console.log(`${version.padStart(8)} ${color(chart)} ${color(downloads.padStart(6))}`);
-    });
-    console.log('');
-}
-function formatDownloads(downloads, maxDownloads) {
-    if (maxDownloads > 1000000) {
-        return `${(downloads / 1000000).toFixed(1)}M`;
+    else {
+        await comparePackages(options.packageNames, options);
     }
-    if (maxDownloads > 1000) {
-        return `${(downloads / 1000).toFixed(1)}K`;
-    }
-    return downloads.toString();
+    console.log('');
 }

package/dist/chart.js

@@ -1,5 +1,7 @@
 export function renderChart(value, { length = 50 } = {}) {
     const filledChars = Math.round(value * length);
-    const emptyChars = length - filledChars;
-    return '█'.repeat(filledChars) + ' '.repeat(emptyChars);
+    if (filledChars === 0) {
+        return '▏' + ' '.repeat(length - 1);
+    }
+    return '█'.repeat(filledChars) + ' '.repeat(length - filledChars);
 }

package/dist/cli-options.js

@@ -1,24 +1,106 @@
-import { program } from 'commander';
+import chalk from 'chalk';
+import meow from 'meow';
+import redent from 'redent';
 import { COLOR_SCHEMES } from './colors.js';
+const colorCommand = chalk.hex('#22c1c3');
+const colorOption = chalk.hex('#fdbb2d');
+const HELP = `
+  ${colorCommand('pkg-stats')} <package> - Show version stats
+  ${colorCommand('pkg-stats')} <package-1> <package-2>... - Compare between packages
+
+Options:
+  ${colorOption('--major')}               Group by major version
+  ${colorOption('--minor')}               Group by minor version
+  ${colorOption('--patch')}               Group by patch version
+  ${colorOption('-t, --top')} <number>    Show top <number> most downloaded versions
+  ${colorOption('-a, --all')}             Include all versions in output, even those with minimal downloads
+  ${colorOption('-c, --color')} <scheme>  ${wrapOption(`Choose color scheme from: ${COLOR_SCHEMES.sort().join(', ')}`, 50, 24)}
+
+Examples:
+  ${chalk.dim('# Show stats for react')}
+  ${colorCommand('pkg-stats')} react
+
+  ${chalk.dim('# Compare react, vue, angular and svelte')}
+  ${colorCommand('pkg-stats')} react vue @angular/core svelte
+
+  ${chalk.dim('# Show top 10 major versions of lodash')}
+  ${colorCommand('pkg-stats')} lodash ${colorOption('--major -t 10')}
+`;
+function wrapOption(text, maxLength, indent) {
+    const words = text.split(' ');
+    let result = '';
+    let currentLine = words[0];
+    for (let i = 1; i < words.length; i++) {
+        const nextCurrentLine = currentLine + ' ' + words[i];
+        if (nextCurrentLine.length <= maxLength) {
+            currentLine = nextCurrentLine;
+        }
+        else {
+            result += `\n${currentLine}`;
+            currentLine = words[i];
+        }
+    }
+    if (currentLine) {
+        result += `\n${currentLine}`;
+    }
+    return redent(result.trim(), indent).trim();
+}
+export function showHelp() {
+    console.log(redent(HELP, 2));
+}
 export function parseCliOptions(argv) {
-    program
-        .name('pkg-stats')
-        .description('Show NPM weekly downloads stats for a package')
-        .argument('<package-name>', 'Package name')
-        .option('--major', 'Group by major version')
-        .option('--minor', 'Group by minor version')
-        .option('--patch', 'Group by patch version')
-        .option('-t, --top <number>', 'Show top <number> versions')
-        .option('-c, --color <color>', 'Color scheme: ' + COLOR_SCHEMES.join(', '))
-        .parse(argv);
-    const args = program.args;
-    const options = program.opts();
+    const cli = meow(HELP, {
+        argv: argv.slice(2),
+        autoHelp: true,
+        description: 'Show NPM weekly downloads stats:',
+        importMeta: import.meta,
+        flags: {
+            help: {
+                type: 'boolean',
+                shortFlag: 'h',
+            },
+            major: {
+                type: 'boolean',
+                shortFlag: 'm',
+            },
+            minor: {
+                type: 'boolean',
+            },
+            patch: {
+                type: 'boolean',
+            },
+            top: {
+                shortFlag: 't',
+                type: 'number',
+            },
+            all: {
+                type: 'boolean',
+                shortFlag: 'a',
+            },
+            color: {
+                shortFlag: 'c',
+                type: 'string',
+                choices: COLOR_SCHEMES,
+            },
+        },
+    });
+    if (cli.flags.help) {
+        cli.showHelp();
+    }
+    if (!cli.input.length) {
+        throw new Error('At least one <package-name> is required');
+    }
     return {
-        packageName: args[0],
-        group: options.major ? 'major' : options.minor ? 'minor' : options.patch ? 'patch' : undefined,
-        top: options.top !== undefined ? parseInt(options.top) : undefined,
-        color: options.color && COLOR_SCHEMES.includes(options.color)
-            ? options.color
-            : undefined,
+        packageNames: cli.input,
+        group: cli.flags.major
+            ? 'major'
+            : cli.flags.minor
+                ? 'minor'
+                : cli.flags.patch
+                    ? 'patch'
+                    : undefined,
+        top: cli.flags.top,
+        all: cli.flags.all,
+        color: cli.flags.color,
     };
 }

package/dist/format.js

@@ -0,0 +1,9 @@
+export function formatDownloads(downloads, maxDownloads) {
+    if (maxDownloads > 1000000) {
+        return `${(downloads / 1000000).toFixed(1)}M`;
+    }
+    if (maxDownloads > 1000) {
+        return `${(downloads / 1000).toFixed(1)}K`;
+    }
+    return downloads.toString();
+}

package/dist/mode/compare-packages.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+import { renderChart } from '../chart.js';
+import { getColors } from '../colors.js';
+import { formatDownloads } from '../format.js';
+import { fetchNpmLastWeekDownloads } from '../npm-api.js';
+export async function comparePackages(packageNames, options) {
+    const rawPackages = await Promise.all(packageNames.map((packageName) => fetchPackageData(packageName)));
+    const packagesToDisplay = rawPackages
+        .filter((pkg) => pkg !== undefined)
+        .sort((a, b) => b.downloads - a.downloads);
+    if (packagesToDisplay.length === 0) {
+        console.error(chalk.red('\nNo packages found.\n'));
+        process.exit(1);
+    }
+    console.log(chalk.bold(`\nNPM weekly downloads\n`));
+    const maxDownloads = Math.max(...packagesToDisplay.map((v) => v.downloads));
+    const displayData = packagesToDisplay.map((item) => {
+        return {
+            name: item.packageName,
+            chart: renderChart(item.downloads / maxDownloads),
+            downloads: formatDownloads(item.downloads, maxDownloads),
+        };
+    });
+    const maxNameLength = Math.max(...displayData.map((item) => item.name.length));
+    const maxDownloadsLength = Math.max(...displayData.map((item) => item.downloads.length));
+    const colors = getColors(packagesToDisplay.length, options.color);
+    displayData.forEach((item, i) => {
+        const color = chalk.hex(colors[i]);
+        console.log(`${item.name.padStart(2 + maxNameLength)} ${color(item.chart)} ${color(item.downloads.padStart(maxDownloadsLength))}`);
+    });
+}
+async function fetchPackageData(packageName) {
+    try {
+        const data = await fetchNpmLastWeekDownloads(packageName);
+        if (!Object.keys(data.downloads).length) {
+            console.warn(chalk.yellow(`No data found for package "${packageName}".`));
+            return undefined;
+        }
+        return {
+            packageName,
+            downloads: Object.values(data.downloads).reduce((sum, downloads) => sum + downloads, 0),
+        };
+    }
+    catch (error) {
+        console.warn(chalk.yellow(`Failed to fetch data for package "${packageName}"`, error));
+        return undefined;
+    }
+}

package/dist/mode/package-details.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { renderChart } from '../chart.js';
+import { getColors } from '../colors.js';
+import { formatDownloads } from '../format.js';
+import { fetchNpmLastWeekDownloads } from '../npm-api.js';
+import { filterStats, groupStats } from '../stats.js';
+import { parseVersion, versionCompare } from '../version.js';
+export async function packageDetails(packageName, options) {
+    let data;
+    try {
+        data = await fetchNpmLastWeekDownloads(packageName);
+    }
+    catch (error) {
+        console.error(`Failed to fetch data for package "${packageName}"`, error);
+        return;
+    }
+    if (!Object.keys(data.downloads).length) {
+        console.error(`No data found for package "${packageName}".\n`);
+        process.exit(1);
+    }
+    const npmStats = Object.keys(data.downloads)
+        .map((versionString) => {
+        const version = parseVersion(versionString);
+        return {
+            ...version,
+            downloads: data.downloads[versionString],
+        };
+    })
+        .sort(versionCompare);
+    const { type, stats } = groupStats(npmStats, options.group);
+    const totalDownloads = Object.values(stats).reduce((sum, version) => sum + version.downloads, 0);
+    const statsToDisplay = filterStats(stats, {
+        totalDownloads,
+        all: options.all,
+        top: options.top,
+    });
+    const colors = getColors(statsToDisplay.length, options.color);
+    const primaryColor = chalk.hex(colors[0]);
+    console.log(chalk.bold(`\nNPM weekly downloads for ${primaryColor(packageName)}\n`));
+    console.log(`Total: ${primaryColor(totalDownloads.toLocaleString())} last week\n`);
+    console.log(options.top ? `Top ${options.top} ${type} versions:\n` : `By ${type} version:\n`);
+    const maxDownloads = Math.max(...stats.map((v) => v.downloads));
+    const displayData = statsToDisplay.map((item) => {
+        const versionParts = item.versionString.split('.');
+        return {
+            version: versionParts.length < 3 ? `${item.versionString}.x` : item.versionString,
+            chart: renderChart(item.downloads / maxDownloads),
+            downloads: formatDownloads(item.downloads, maxDownloads),
+        };
+    });
+    const maxVersionLength = Math.max(...displayData.map((item) => item.version.length));
+    const maxDownloadsLength = Math.max(...displayData.map((item) => item.downloads.length));
+    displayData.forEach((item, i) => {
+        const color = chalk.hex(colors[i]);
+        console.log(`${item.version.padStart(2 + maxVersionLength)} ${color(item.chart)} ${color(item.downloads.padStart(maxDownloadsLength))}`);
+    });
+}

package/dist/mode/package-stats.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { renderChart } from '../chart.js';
+import { getColors } from '../colors.js';
+import { formatDownloads } from '../format.js';
+import { fetchNpmLastWeekDownloads } from '../npm-api.js';
+import { filterStats, groupStats } from '../stats.js';
+import { parseVersion, versionCompare } from '../version.js';
+export async function printPackageStats(packageName, options) {
+    let data;
+    try {
+        data = await fetchNpmLastWeekDownloads(packageName);
+    }
+    catch (error) {
+        console.error(`Failed to fetch data for package "${packageName}"`, error);
+        return;
+    }
+    if (!Object.keys(data.downloads).length) {
+        console.error(`No data found for package "${packageName}".\n`);
+        process.exit(1);
+    }
+    const npmStats = Object.keys(data.downloads)
+        .map((versionString) => {
+        const version = parseVersion(versionString);
+        return {
+            ...version,
+            downloads: data.downloads[versionString],
+        };
+    })
+        .sort(versionCompare);
+    const { type, stats } = groupStats(npmStats, options.group);
+    const totalDownloads = Object.values(stats).reduce((sum, version) => sum + version.downloads, 0);
+    const statsToDisplay = filterStats(stats, {
+        totalDownloads,
+        all: options.all,
+        top: options.top,
+    });
+    const colors = getColors(statsToDisplay.length, options.color);
+    const primaryColor = chalk.hex(colors[0]);
+    console.log(chalk.bold(`\nNPM weekly downloads for ${primaryColor(packageName)}\n`));
+    console.log(`Total: ${primaryColor(totalDownloads.toLocaleString())} last week\n`);
+    console.log(options.top ? `Top ${options.top} ${type} versions:\n` : `By ${type} version:\n`);
+    const maxDownloads = Math.max(...stats.map((v) => v.downloads));
+    const displayData = statsToDisplay.map((item) => {
+        const versionParts = item.versionString.split('.');
+        return {
+            version: versionParts.length < 3 ? `${item.versionString}.x` : item.versionString,
+            chart: renderChart(item.downloads / maxDownloads),
+            downloads: formatDownloads(item.downloads, maxDownloads),
+        };
+    });
+    const maxVersionLength = Math.max(...displayData.map((item) => item.version.length));
+    const maxDownloadsLength = Math.max(...displayData.map((item) => item.downloads.length));
+    displayData.forEach((item, i) => {
+        const color = chalk.hex(colors[i]);
+        console.log(`${item.version.padStart(2 + maxVersionLength)} ${color(item.chart)} ${color(item.downloads.padStart(maxDownloadsLength))}`);
+    });
+}

package/dist/mode/single-package.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { renderChart } from '../chart.js';
+import { getColors } from '../colors.js';
+import { formatDownloads } from '../format.js';
+import { fetchNpmLastWeekDownloads } from '../npm-api.js';
+import { filterStats, groupStats } from '../stats.js';
+import { parseVersion, versionCompare } from '../version.js';
+export async function singlePackage(packageName, options) {
+    let data;
+    try {
+        data = await fetchNpmLastWeekDownloads(packageName);
+    }
+    catch (error) {
+        console.error(`Failed to fetch data for package "${packageName}"`, error);
+        return;
+    }
+    if (!Object.keys(data.downloads).length) {
+        console.error(`No data found for package "${packageName}".\n`);
+        process.exit(1);
+    }
+    const npmStats = Object.keys(data.downloads)
+        .map((versionString) => {
+        const version = parseVersion(versionString);
+        return {
+            ...version,
+            downloads: data.downloads[versionString],
+        };
+    })
+        .sort(versionCompare);
+    const { type, stats } = groupStats(npmStats, options.group);
+    const totalDownloads = Object.values(stats).reduce((sum, version) => sum + version.downloads, 0);
+    const statsToDisplay = filterStats(stats, {
+        totalDownloads,
+        all: options.all,
+        top: options.top,
+    });
+    const colors = getColors(statsToDisplay.length, options.color);
+    const primaryColor = chalk.hex(colors[0]);
+    console.log(chalk.bold(`\nNPM weekly downloads for ${primaryColor(packageName)}\n`));
+    console.log(`Total: ${primaryColor(totalDownloads.toLocaleString())} last week\n`);
+    console.log(options.top ? `Top ${options.top} ${type} versions:\n` : `By ${type} version:\n`);
+    const maxDownloads = Math.max(...stats.map((v) => v.downloads));
+    const displayData = statsToDisplay.map((item) => {
+        const versionParts = item.versionString.split('.');
+        return {
+            version: versionParts.length < 3 ? `${item.versionString}.x` : item.versionString,
+            chart: renderChart(item.downloads / maxDownloads),
+            downloads: formatDownloads(item.downloads, maxDownloads),
+        };
+    });
+    const maxVersionLength = Math.max(...displayData.map((item) => item.version.length));
+    const maxDownloadsLength = Math.max(...displayData.map((item) => item.downloads.length));
+    displayData.forEach((item, i) => {
+        const color = chalk.hex(colors[i]);
+        console.log(`${item.version.padStart(2 + maxVersionLength)} ${color(item.chart)} ${color(item.downloads.padStart(maxDownloadsLength))}`);
+    });
+    console.log('');
+}

package/dist/stats.js

@@ -1,23 +1,23 @@
 import { versionCompare } from './version.js';
-export function groupByType(type, stats) {
+export function groupStats(stats, type) {
     if (type === 'major') {
-        return groupByMajor(stats);
+        return { type: 'major', stats: groupByMajor(stats) };
     }
     if (type === 'minor') {
-        return groupByMinor(stats);
+        return { type: 'minor', stats: groupByMinor(stats) };
     }
     if (type === 'patch') {
-        return groupByPatch(stats);
+        return { type: 'patch', stats: groupByPatch(stats) };
     }
     const groupedByMajor = groupByMajor(stats);
-    if (groupedByMajor.length > 1) {
-        return groupedByMajor;
+    if (groupedByMajor.length >= 3) {
+        return { type: 'major', stats: groupedByMajor };
     }
     const groupedByMinor = groupByMinor(stats);
-    if (groupedByMinor.length > 1) {
-        return groupedByMinor;
+    if (groupedByMinor.length >= 3) {
+        return { type: 'minor', stats: groupedByMinor };
     }
-    return groupByPatch(stats);
+    return { type: 'patch', stats: groupByPatch(stats) };
 }
 function groupByMajor(stats) {
     const result = {};
@@ -65,7 +65,17 @@ function groupByPatch(stats) {
     }
     return Object.values(result).sort((a, b) => versionCompare(a.version, b.version));
 }
-export function pickTopStats(stats, top) {
+export function filterStats(stats, options) {
+    if (options.all) {
+        return stats;
+    }
+    if (options.top) {
+        return pickTopStats(stats, options.top);
+    }
+    const downloadThreshold = 0.005 * options.totalDownloads; // 0.5%
+    return stats.filter((stat) => stat.downloads >= downloadThreshold);
+}
+function pickTopStats(stats, top) {
     const sortedStats = stats.sort((a, b) => b.downloads - a.downloads);
     const topStats = sortedStats.slice(0, top);
     return topStats.sort((a, b) => versionCompare(a.version, b.version));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkg-stats",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Beautiful NPM package download stats",
   "license": "MIT",
   "repository": {
@@ -34,18 +34,17 @@
   },
   "dependencies": {
     "chalk": "^5.4.1",
-    "commander": "^13.0.0",
+    "meow": "^13.2.0",
+    "redent": "^4.0.0",
     "tinygradient": "^1.1.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
     "@release-it/conventional-changelog": "^10.0.0",
-    "@types/minimist": "^1.2.5",
     "@types/node": "^22.10.5",
     "eslint": "^9.18.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "globals": "^15.14.0",
-    "redent": "^4.0.0",
     "release-it": "^18.1.1",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.19.1",