install-purescript
Version:
Install PureScript to a given directory
281 lines (211 loc) • 9.54 kB
Markdown
# install-purescript
[](https://www.npmjs.com/package/install-purescript)
[](https://travis-ci.com/shinnn/install-purescript)
[](https://codecov.io/gh/shinnn/install-purescript)
Install [PureScript](https://github.com/purescript/purescript) to a given directory
```javascript
cconst {execFile} = require('child_process');
const installPurescript = require('install-purescript');
installPurescript({version: '0.13.0'}).subscribe({
next(event) {
if (event.id === 'search-cache' && event.found) {
console.log('✓ Found a cache.');
return;
}
if (event.id === 'restore-cache:complete') {
console.log('✓ Cached binary restored.');
return;
}
if (event.id === 'check-binary:complete') {
console.log('✓ Binary works correctly.');
return;
}
}
complete() {
execFile('./purs', ['--version'], (err, stdout) => {
stdout.toString(); //=> '0.13.0\n'
});
}
});
```
## Installation
[Use](https://docs.npmjs.com/cli/install) [npm](https://docs.npmjs.com/about-npm/).
```
npm install install-purescript
```
## API
```javascript
const installPurescript = require('install-purescript');
```
### installPurescript([*options*])
*options*: `Object`
Return: [`Observable`](https://github.com/tc39/proposal-observable#observable) ([Kevin Smith's implementation](https://github.com/zenparsing/zen-observable))
When the `Observable` is [subscribe](https://tc39.github.io/proposal-observable/#observable-prototype-subscribe)d,
1. it searches [the standard cache directory](https://github.com/shinnn/app-cache-dir) for an already cached PureScript binary, and restores the cache if available
3. if a cached binary is not available, it downloads a prebuilt binary from the [PureScript release page](https://github.com/purescript/purescript/releases)
4. if a prebuilt binary is not available, it downloads [the PureScript source code](https://github.com/purescript/purescript) and [builds](https://github.com/purescript/purescript/blob/master/INSTALL.md#compiling-from-source) a binary form it
5. Cache the downloaded or built binary to the [npm cache directory](https://docs.npmjs.com/files/folders#cache)
while successively sending [events](#events) to its [`Observer`](https://github.com/tc39/proposal-observable#observer).
#### Events
Every event object has `id` property with one of these values:
[group1]: #head-headfail-headcomplete-download-binary-download-binaryfail-download-binarycomplete-check-stack-check-stackcomplete-download-source-download-sourcecomplete
[group2]: #setup-setupcomplete-build-buildcomplete
* [`search-cache`](#search-cache)
* [`restore-cache`](#restore-cache)
* [`restore-cache:fail`](#restore-cachefail)
* [`restore-cache:complete`](#restore-cachecomplete)
* [`check-binary`](#check-binary)
* [`check-binary:fail`](#check-binaryfail)
* [`check-binary:complete`](#check-binarycomplete)
* [`head`][group1]
* [`head:fail`][group1]
* [`head:complete`][group1]
* [`download-binary`][group1]
* [`download-binary:fail`][group1]
* [`download-binary:complete`][group1]
* [`check-stack`][group1]
* [`check-stack:complete`][group1]
* [`download-source`][group1]
* [`download-source:complete`][group1]
* [`setup`][group2]
* [`setup:complete`][group2]
* [`build`][group2]
* [`build:complete`][group2]
* [`write-cache`](#write-cache)
* [`write-cache:fail`](#write-cachefail)
* [`write-cache:complete`](#write-cachecomplete)
```
|
search-cache -- x -+- head ------------ x -+- check-stack ----- x -+
| | | | | |
o | o | o |
| | | | | |
restore-cache - x -+ download-binary - x -+ download-source - x -+
| | | | | |
o | o | o |
| | | | | |
check-binary -- x -+ check-binary ---- x -+ setup ----------- x -+
| | | |
o | o |
| | | |
| | build ----------- x -+
| | | |
| o o |
| | | |
******************* ***************** ***************** ^^^^^^^
Restored a Downloaded a Built a binary Error
binary from cache prebuilt binary from the source ^^^^^^^
******************* ***************** *****************
| |
write-cache write-cache
```
##### `search-cache`
Fires when it checks if a `tgz` archive of the required PureScript binary exists in the cache directory.
```javascript
{
id: 'search-cache',
path: <string>, // path to the cache file
found: <boolean> // whether a cache is found or not
}
```
##### `restore-cache`
Fires when it starts to extract a binary from the cached `tgz` archive.
```javascript
{
id: 'restore-cache'
}
```
##### `restore-cache:fail`
Fires when it fails to restore the binary from cache.
```javascript
{
id: 'restore-cache:fail',
error: <Error>
}
```
##### `restore-cache:complete`
Fires when the cached binary is successfully restored.
```javascript
{
id: 'restore-cache:complete'
}
```
##### `check-binary`
Fires when it starts to verify the cached or downloaded binary works correctly, by running `purs --version`.
```javascript
{
id: 'check-binary'
}
```
##### `check-binary:fail`
Fires when the cached or downloaded binary doesn't work correctly.
```javascript
{
id: 'check-binary:fail',
error: <Error>
}
```
##### `check-binary:complete`
Fires when it verifies the cached or downloaded binary works correctly.
```javascript
{
id: 'check-binary:complete'
}
```
##### [`head`](https://github.com/shinnn/download-or-build-purescript#head) [`head:fail`](https://github.com/shinnn/download-or-build-purescript#headfail) [`head:complete`](https://github.com/shinnn/download-or-build-purescript#headcomplete) [`download-binary`](https://github.com/shinnn/download-or-build-purescript#download-binary) [`download-binary:fail`](https://github.com/shinnn/download-or-build-purescript#download-binaryfail) [`download-binary:complete`](https://github.com/shinnn/download-or-build-purescript#download-binarycomplete) [`check-stack`](https://github.com/shinnn/download-or-build-purescript#check-stack) [`check-stack:complete`](https://github.com/shinnn/download-or-build-purescript#check-stackcomplete) [`download-source`](https://github.com/shinnn/download-or-build-purescript#download-source) [`download-source:complete`](https://github.com/shinnn/download-or-build-purescript#download-sourcecomplete)
Inherited from [`download-or-build-purescript`](https://github.com/shinnn/download-or-build-purescript#events).
##### [`setup`](https://github.com/shinnn/build-purescript#setup) [`setup:complete`](https://github.com/shinnn/build-purescript#setupcomplete) [`build`](https://github.com/shinnn/build-purescript#build) [`build:complete`](https://github.com/shinnn/build-purescript#buildcomplete)
Inherited from [`build-purescript`](https://github.com/shinnn/build-purescript#events).
##### `write-cache`
Fires when it starts to create a cache. The cache is compressed with [Brotli](https://github.com/google/brotli).
```javascript
{
id: 'write-cache',
originalSize: <integer> // the size of the binary before compression in bytes
}
```
##### `write-cache:fail`
Fires when it fails to create the cache.
```javascript
{
id: 'write-cache:fail',
error: <Error>
}
```
##### `write-cache:complete`
Fires when the cache is successfully created.
```javascript
{
id: 'write-cache:complete'
}
```
#### Errors
Every error passed to the `Observer` has `id` property that indicates which step the error occurred at.
```javascript
// When the `stack` command is not installed
installPurescript('.').subscribe({
error(err) {
err.message; //=> '`stack` command is not found in your PATH ...'
err.id; //=> 'check-stack'
}
});
// When your machine lose the internet connection while downloading the source
installPurescript('.').subscribe({
error(err) {
err.message; //=> 'socket hang up'
err.id; //=> 'download-source'
}
});
```
#### Options
Options are directly passed to [`download-or-build-purescript`](https://github.com/shinnn/download-or-build-purescript#options).
Additionally, you can use the following:
##### forceReinstall
Type: `boolean`
Default: `false`
Force reinstalling a binary even if an appropriate cache already exists.
## Related projects
* [install-purescript-cli](https://github.com/shinnn/install-purescript-cli) — CLI for this module
* [download-or-build-purescript](https://github.com/shinnn/download-or-build-purescript) — Almost the same as this module, but has no cache feature
## License
[ISC License](./LICENSE) © 2017 - 2019 Watanabe Shinnosuke