GitHub Release Stats

Description

GitHub Release Stats is a JavaScript library written in TypeScript for fetching the GitHub release download count and other statistics.

It can be used in several ways:

• Command-line tool
• Module (Node.js or browser)

This library also supports the GitHub API pagination out of the box.

Usage

Using as a command-line tool

Installation

npm i -g github-release-stats

Now you can run ghstats in your command line interpreter.

Syntax

ghstats [owner] [repo] [tag] [options]
ghstats [owner/repo] [tag] [options]

Parameters

| Parameter | Description | | --------- | ----------------------------------------------------------------------- | | owner | Repository owner. If not present, you will be prompted for the input. | | repo | Repository name. If not present, you will be prompted for the input. | | tag | Release tag name. If not present, prints the total number of downloads. |

Options

| Option | Description | ---------------- | ---------------------------------------------------- | | -d, --detail | Print detailed statistics for each release | | -q, --quiet | Print only resulting numbers and errors (quiet mode) | | -l, --latest | Print statistics for the latest release | | -h, --help | Print help message |

Environment Variables

| Environment Variable | Description | | -------------------- | ------------------------------------------------------ | | GITHUB_TOKEN | GitHub personal access token. Read more |

Examples

ghstats atom atom            # Print download count for all releases.
ghstats atom/atom            # Print download count for all releases (alt. syntax).
ghstats atom atom -q         # Quiet mode (print only numerical result or errors).
ghstats atom atom -d         # Print detailed description for each release.
ghstats atom atom -l         # Print download count for the latest release.
ghstats atom atom -l -q      # Print download count for the latest release (quiet mode).
ghstats atom atom -l -d      # Print detailed description for the latest release.
ghstats atom atom v1.0.0     # Print download count for the the "v1.0.0" release.
ghstats atom atom v1.0.0 -q  # Print download count for the the "v1.0.0" release (quiet mode).
ghstats atom atom v1.0.0 -d  # Print detailed description for the "v1.0.0" release.
ghstats                      # Get repository owner and name from the user input.
ghstats -h                   # Print help message.

Using as a Module

You can use this library in both Node.js and browser environments. In the latter case, you can use bundlers such as Webpack and Parcel.

Installation

npm i github-release-stats

Constructor

GithubStats(repoOwner: string, repoName: string, token?: string)

| Parameter | Description | Required | | ----------- | ------------------------------------------------------ | -------- | | repoOwner | Repository owner | Yes | | repoName | Repository name | Yes | | token | GitHub personal access token. Read more | No |

Methods

| Method | Description | Returns | | ---------------------------------- | ------------------------------------------------------------------------- | -------------------------- | | getAllReleases() | Fetch all releases | Promise<GithubRelease[]> | | getLatestRelease() | Fetch the latest release | Promise<GithubRelease> | | getRelease(tag: string) | Fetch a single release by the specified tag | Promise<GithubRelease> | | getTotalDownloads() | Fetch the total number of release downloads for the whole repo | Promise<number> | | getLatestReleaseDownloads() | Fetch the number of downloads for the latest release | Promise<number> | | getReleaseDownloads(tag: string) | Fetch the number of downloads for a single release by the specified tag | Promise<number> |

Example of a GithubRelease object: https://api.github.com/repos/atom/atom/releases/latest

Example

// ES Module:
import { GithubStats } from 'github-release-stats';

// CommonJS Module:
const { GithubStats } = require('github-release-stats');

const gh = new GithubStats('atom', 'atom');

gh.getTotalDownloads().then(count => {
  console.log('Total downloads: ' + count);
}).catch(error => {
  console.error(error.message);
});

API Limits

By default, GitHub API allows you to make up to 60 requests per hour. You can increase this limit by specifying your personal access token which can be created here.

• Store your token in the GITHUB_TOKEN environment variable (works in CLI and Node.js environment)
• Pass your token to the GithubStats constructor (works in Node.js and browser environments)

License

MIT License

You are free to use, modify, distribute (including commercial purposes) as long as you credit the original author and include the license text.