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

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 |