install-purescript

Install PureScript to a given directory

cconst {execFile} = require('child_process');
const installPurescript = require('install-purescript');

installPurescript('./dest', {version: '0.11.6'}).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('./dest/purs', ['--version'], (err, stdout) => {
      stdout.toString(); //=> '0.11.6\n'
    });
  }
});

Installation

Use npm.

npm install install-purescript

API

const installPurescript = require('install-purescript');

installPurescript(dir [, options])

path: string (a directory path where the PureScript binary will be installed)
options: Object
Return: Observable (zenparsing's implementation)

When the Observable is subscribed,

1. it searches the standard cache directory for an already cached PureScript binary, and restores the cache if available
2. if a cached binary is not available, it downloads a prebuilt binary from the PureScript release page
3. if a prebuilt binary is not available, it downloads the PureScript source code and builds a binary form it
4. Cache the downloaded or built binary to the standard cache directory

while successively sending events to its Observer.

Events

Every event object has id property with one of these values:

• search-cache
• restore-cache
• restore-cache:fail
• restore-cache:complete
• check-binary
• check-binary:fail
• check-binary:complete
• head
• head:fail
• head:complete
• download-binary
• download-binary:fail
• download-binary:complete
• check-stack
• check-stack:complete
• download-source
• download-source:complete
• setup
• setup:complete
• build
• build:complete
• write-cache
• write-cache:fail
• write-cache:complete

 |
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.

{
  id: 'search-cache',
  path: <string>, // path to the .tgz file
  found: <boolean>, // whether a cache is found or not
  warning: <string | null>
}

If the cache directory has too many contents, warning property will become a message to recommend removing unused caches to free disk usage:

The cache directory ~/.cache/purescript has 6 contents, most of whom would be currently unused:

* v0.11.1-darwin-x64.tgz
* v0.11.2-darwin-x64.tgz
* v0.11.3-darwin-x64.tgz
* v0.11.4-darwin-x64.tgz

and 2 more

You can free disk usage by deleting obsolete caches or simply removing the cache directory itself.

restore-cache

Fires many times while extracting the a binary from the cached tgz archive.

bytes and header properties are derived from tar-to-file's progress object.

{
  id: 'restore-cache',
  bytes: <number>,
  header: <Object>
}

restore-cache:fail

Fires when it fails to restore the binary from cache.

{
  id: 'restore-cache:fail',
  error: <Error>
}

restore-cache:complete

Fires when the cached binary is successfully restored.

{
  id: 'restore-cache:complete'
}

check-binary

Fires when it starts to verify the cached or downloaded binary works correctly, by running purs --version.

{
  id: 'check-binary'
}

check-binary:fail

Fires when the cached or downloaded binary doesn't work correctly.

{
  id: 'check-binary:fail',
  error: <Error>
}

check-binary:complete

Fires when it verifies the cached or downloaded binary works correctly.

{
  id: 'check-binary:complete'
}

head head:fail head:complete download-binary download-binary:fail download-binary:complete check-stack check-stack:complete download-source download-source:complete

Inherited from download-or-build-purescript.

setup setup:complete build build:complete

Inherited from build-purescript.

write-cache

Fires many times while archiving a downloaded or built binary as a cache.

bytes and header properties are derived from file-to-tar's progress object.

{
  id: 'write-cache',
  bytes: <number>,
  header: <Object>
}

write-cache:fail

Fires when it fails to create the cache.

{
  id: 'write-cache:fail',
  error: <Error>
}

write-cache:complete

Fires when the cache is successfully created.

{
  id: 'write-cache:complete'
}

Errors

Every error passed to the Observer has id property that indicates which step the error occurred at.

// 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'
  }
});

onComplete value

Type: Object

Unlike the current draft spec of Observable, zen-observable allows an Observable to send value to the complete fallback and this library follows its behavior.

path property is a path of the installed binary.

cachePath property is a path of the created cache archive, or null when no cache is created.

installPurescript('/my/dir').subscribe({
  complete(paths) {
    paths.path; //=> '/my/dir/purs'
    paths.cachePath; //=> '/Users/shinnn/.cache/purescript/npm/v0.11.6-darwin-x64.tgz'
  }
});

Options

Options are directly passed to download-or-build-purescript.

Additionally, you can use the following:

cacheDir

Type: string or boolean
Default: require('path').join(require('app-cache-dir')('purescript'), 'npm')

A path of the directory which caches are restored from and written to. By default,

• ~/.cache/purescript/npm on POSIX
• C:\\Users\\${username}\\AppData\Local\purescript\cache\npm on Windows

If this option is false, install-purescript doesn't restore a cache whether or not it exists, and doesn't write a cache after installation.

forceReinstall

Type: boolean
Default: false

Force reinstalling a binary even if an appropriate cache already exists. When cacheDir option is false, this option cannot be enabled.

Related projects

• install-purescript-cli — CLI for this module
• download-or-build-purescript — Almost the same as this module, but has no cache feature

License

Copyright (c) 2017 Shinnosuke Watanabe

Licensed under the MIT License.