Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fohlen/github-release-downloader

Download release assets from GitHub is no nightmare no more
https://github.com/fohlen/github-release-downloader

Last synced: about 1 month ago
JSON representation

Download release assets from GitHub is no nightmare no more

Awesome Lists containing this project

README 

        
github-release-downloader

-------------------------



[![Build Status](https://travis-ci.org/Fohlen/github-release-downloader.svg?branch=master)](https://travis-ci.org/Fohlen/github-release-downloader)



A tiny Promise-compliant wrapper around [requests](https://github.com/request/request) to download release assets from [GitHub](https://github.com).

I use [mocha](https://mochajs.org/), [eslint](https://eslint.org/) and [Travis](https://travis-ci.org/) for code quality. Also [jsdoc-to-markdown](https://www.npmjs.com/package/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](https://github.com/visionmedia/node-progress#readme) 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](https://developer.github.com/v3/rate_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](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](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 |