incremental-installer

v1.1.0

Published

2 years ago

A module that helps create scripts that install non-npm dependencies for a project. Allows for smoothly and incremental adding dependencies during development

Downloads

0High
0Medium
0Low

fresheneesz

installer install package dependencies

`incremental-installer`

A module that helps create scripts that install non-npm dependencies for a project. Allows for smoothly and incrementally adding dependencies during development.

During development, multiple engineers on a project will need to add dependencies and configuration for the project - things like database schema changes, version upgrades, and additions to the technology stack. This library helps you create scripts that can be run quickly on every pull from the repository to ensure all the correct configuration is in place. The installers created with this will be idempotent - meaning you can run them multiple times without duplicate installation happening. The installer will only install pieces that have not yet been installed.

This way, engineers can easily be sure they have the correct setup, automatically.

What is it good for?

absolutely nothing!
Wait actually, its good for creating installers for one-time dependencies of a project (databases, caching systems, encryption packages, etc),
installers for automatically setting up and configuring development environments (git, nano, adding package repositories, configuring test users or test data, etc), for example installing on vagrant virtual machines,
or setting up shared environments (creating users, creating directory structures, setting up groups and permissions, etc)

Example

var install = require('incremental-installer')
var run = install.run
var Future = install.Future

install('install.state', [
        function(args) { // runs first, only if the state is 0
            run('yum install -y nano')
        },
        function(args) { // runs second, only if the state is less than 1
			run('yum install -y locate')
        },
        {  install: function(args) { // runs third, only if the 'check' function returns true
              run('yum install -y git')
           },
           check: function(args) { // checks to see if the install function of this object should be run
              if(isGitInstalled()) {
                  return Future(false)
              } else {
                  return Future(false)
              }
           }
        }
    ]
).done() // ensures that any error from the returned future are thrown

Requirements

Just requires node.js to be installed

Install

npm install incremental-installer

#Usage

Steps

Write the installer - Create a node.js script that uses 'incremental-installer' with a single element inside 'installFunctions' containing anything that fulfils your current needs.
Update the installer - When you need to add more to the installation, add another function to the end of the installFunctions list.

Running the installer will skip over the already-ran functions and only run the new one(s)

Node API

var install = require('incremental-installer')

install(stateFileInfo, installFunctions) - runs install-functions that have not yet run on. Returns a future that resolves when the last function in installFunctions finishes and resolves.

stateFilePath - can be either:
- The (string) full path to the state-file location.
- An object with the properties:
  - curState - a number representing the current state
  - writeState(state) - a function that writes the state to some kind of storage
installFunctions - A list of tasks to run in order.
- Each element (task) in the array can either be:
  - A function. In this case, the function is run if state >= the number of function-tasks that preceded it (ie if you have 2 function-tasks, then 1 object-task, then another 2 function-tasks, the task with index 1 will be run if the state is 1 or less and the task with index 3 will be run if the state is 2 or less).
    - In maintaining this installer script, it is important that the order of function-tasks remains the same. If the order is changed, the next time the installer is run on a partially installed machine, already-ran functions may run, and necessary functions may not run.
    - If a function returns a future (see async-future), the next function will wait until that future resolves before running the next function.
    - It is not safe to insert a new function-tasks anywhere but at the end of the list. This is because the installation state of the machine is recorded as the number of functions run. If new function-tasks
  - An object. The object's check function will be run on every install (regardless of state), and if it returns Future(true)the install function will be run.
    - It is safe to insert a new object-task in the middle of an installation procedure, because this task doesn't change the 'state' of the installation.
    - The object should have the following properties:
      - check() - A function that returns Future(true) (see async-future) if the install function of the object should be run.
      - install() - A function.
        If the function returns a future (see async-future), the next function will wait until that future resolves before running the next function.

makeInstaller.run(command, printToConsole, options) - runs a system command, displays the output on the console, and returns when the command is done. Throws an exception if the command returns an exit code other than 0.

command - a string of the command to run
printToConsole - (Optional- default true) If true, output is displayed to the console. If false, its not.
options - has only one option at the moment: unref, which causes the current process to not wait for the child process to finish before exiting

makeInstaller.Future - a reference to async-future for convenience (e.g. to use in options.scripts[n].check above)

Recommendations

Fibers/future

I recommend using node-fibers for concurrency. This library uses async-future because requiring multiple versions of node-fibers isn't safe (causes bugs).