@fohlen/github-release-downloader

github-release-downloader

A tiny Promise-compliant wrapper around requests to download release assets from GitHub. I use mocha, eslint and Travis for code quality. Also jsdoc-to-markdown is a great help in creating this README.

Get started

To get started, simply install this module via (if you plan using it without progress or command line):

npm i @fohlen/github-release-downloader --save --no-optional

Once that's done you can simply require the downloader in your code

const releaseDownloader = require('@fohlen/github-release-downloader');

releaseDownloader.downloadByPlatformArch('inexorgame/inexor-core').then((downloaded) => {
    console.log(`Hooray! It downloaded my archive at ${downloaed}!`)
}).catch((err) => {
    console.error('omighosh, seems like this platform is not supported')
})

Command line

You can also use this package as a small command-line wrapper to download stuff from GitHub.

npm i @fohlen/github-release-downloader -g

Then go ahead and enjoy the command line,

github-release-downloader --help

Use progress for download progress

You can also pass an optional callback to the downloadAsset function. Given you use progress that would look like

const releaseDownloader = require('github-release-downloader');
const progress = require('progress');

releaseDownloader.getVersion('inexorgame/inexor-core').then((release) => {
    releaseDownloader.getAssetByPlatformArch(release).then((asset) => {
        let progressBar = new ProgressBar(':bar:', { total: asset.size })
        
        releaseDownloader.downloadAsset(asset.url, asset.name, (chunk) => {
            progressBar.tick((asset.size - chunk))
        }).then((downloaded) => {
            console.log(`Successfully downloaded file to ${downloaded}`)
        })
    })
})

Improvement ideas

There's surely plenty room for improvement, and I appreciate pull requests. I think that support for authentication is indeed most needed right now, because the api limit can be rather harsh.

#API

Functions

getReleaseList(repo) ⇒ Promise.<Object>

Retrieves versions and their associated assets

getReleaseByVersion(repo, range) ⇒ Promise.<Object>

Retrieves the assets of a specific release or tries to match a release using the semver

getAssetByPlatformArch(release, platform, arch) ⇒ Promise.<Object>

Tries to match an asset of a release for specific platform and arch. Using platform="", arch="" behaves like a wildcard.

downloadAsset(url, name, dir, [progress]) ⇒ Promise.<string>

Downloads a release asset from GitHub. Calls the progress callback with the chunk length progressively. You can get the file size via @see getAssetByPlatformArch

downloadAssetByPlatformArch(repo, range, dir, platform, arch) ⇒ Promise.<string>

Tries to download given release by range for specified platform and arch. If the architecture+platform cannot be matched the promise will be rejected.

getReleaseList(repo) ⇒ Promise.<Object>

Retrieves versions and their associated assets

Kind: global function
See: https://developer.github.com/v3/repos/releases/#list-releases-for-a-repository

Param	Type	Description
repo	string	the name of the GitHub name+repo, e.g fohlen/github-release-downloader

getReleaseByVersion(repo, range) ⇒ Promise.<Object>

Retrieves the assets of a specific release or tries to match a release using the semver

Kind: global function
See: https://developer.github.com/v3/repos/releases/#get-a-single-release

Param	Type	Default	Description
repo	string		the name of the GitHub name+repo, e.g fohlen/github-release-downloader
range	string	"latest"	[range=latest] - semver range

getAssetByPlatformArch(release, platform, arch) ⇒ Promise.<Object>

Tries to match an asset of a release for specific platform and arch. Using platform="", arch="" behaves like a wildcard.

Kind: global function

Param	Type	Description
release	Object	a GitHub release object
platform	string	[platform=os.platform()] - one of the supported platforms of os.platform
arch	string	[arch=os.arch()] - one of the supported architectures of os.arch

downloadAsset(url, name, dir, [progress]) ⇒ Promise.<string>

Downloads a release asset from GitHub. Calls the progress callback with the chunk length progressively. You can get the file size via @see getAssetByPlatformArch

Kind: global function
Returns: Promise.<string> - - the path of the downloaded file

Param	Type	Default	Description
url	string
name	string
dir	string		[directory=process.cwd()] - an optional download path
[progress]	function		an optional callback to hook into with asset download

downloadAssetByPlatformArch(repo, range, dir, platform, arch) ⇒ Promise.<string>

Tries to download given release by range for specified platform and arch. If the architecture+platform cannot be matched the promise will be rejected.

Kind: global function
Returns: Promise.<string> - - the path of the downloaded file

Param	Type	Default	Description
repo	string		the name of the GitHub name+repo, e.g fohlen/github-release-downloader
range	string	"latest"	[range=latest] - semver range
dir	string		[directory=process.cwd()] - an optional download path
platform	string		[platform=os.platform()] - one of the supported platforms of os.platform
arch	string		[arch=os.arch()] - one of the supported architectures of os.arch