init

Author: patoi

.travis.yml

@@ -0,0 +1,5 @@
+language: node_js
+node_js:
+  - "6"
+  - "8"
+  - "10"

README.md

@@ -1,2 +1,59 @@
 # node-appstate
-Application state handler
+
+[![TravisCI Build Status](https://travis-ci.org/vanioinformatika/node-appstate.svg?branch=master)](https://travis-ci.org/vanioinformatika/node-appstate)
+
+Application state handler without dependency
+
+Initializaion without callback (logger):
+
+```javascript
+const appState = require('./appState')()
+```
+
+Initialization with a simple logger:
+
+```javascript
+const appState = require('./appState')((appState, newAppState) => {
+  console.log(`App state has changed from ${appState} to ${newAppState}`)
+})
+```
+
+You have two variables:
+
+* appState: application state
+
+* newAppState: new application state
+
+You can use any logger library, for example pino.
+
+```javascript
+let logger = require('pino')()
+const appState = require('./appState')((appState, newAppState) => {
+  logger.warn(`App state has changed from ${appState} to ${newAppState}`)
+})
+```
+
+Changing application state.
+
+```javascript
+const appState = require('./appState')()
+appState.init()
+appState.running()
+appState.error()
+appState.stopped()
+```
+
+**Application state values: INIT, ERROR, RUNNING, STOPPED**
+
+## Best practice
+
+Using state:
+
+* RUNNING - application is running
+* STOPPED - application is running, but programmatically stopped
+* ERROR - application is running, but has a critical error (e.g.: DB connection error): app doesn't serves requests
+* INIT - application is starting, initialization: starting phase (app doesn't handle request)
+
+Use a /health endpoint for load-balancers, and set to UP, if ```appState.get() === 'RUNNING'```, else DOWN.
+
+You can change anytime the application state, for example under initialization process: persistent DB connection error => appState.error()

appState.js

@@ -0,0 +1,47 @@
+// RUNNING - application is running
+// STOPPED - application is running, but programmatically stopped
+// ERROR - application is running, but has a critical error (e.g.: DB connection error): app doesn't serves requests
+// INIT - application is starting, initialization: starting phase (app doesn't handle request)
+
+// start state
+var appState = 'INIT'
+
+/**
+ * Callback has two params: cb(appState, newAppState)
+ * - appState: application state actually
+ * - newAppState: new application state
+ * Tipical use case is when cb contains a logger function.
+ */
+module.exports = (cb) => {
+  /**
+   * Set application state to new state and loging it,
+   * if state has changed.
+   * @param String newAppState
+   */
+  function changeAppState (newAppState) {
+    if (appState !== newAppState) {
+      if (cb) cb(appState, newAppState)
+      appState = newAppState
+    }
+  }
+
+  // changing appState
+  function init () {
+    changeAppState('INIT')
+  }
+  function running () {
+    changeAppState('RUNNING')
+  }
+  function error () {
+    changeAppState('ERROR')
+  }
+  function stopped () {
+    changeAppState('STOPPED')
+  }
+
+  // reading appState
+  function get () {
+    return appState
+  }
+  return {init, running, error, stopped, get}
+}

appState.spec.js

@@ -0,0 +1,68 @@
+/* eslint-env mocha */
+const should = require('should') // eslint-disable-line
+const sinon = require('sinon')
+const shouldSinon = require('should-sinon') // eslint-disable-line
+
+describe('appState', () => {
+  it('handling undefined logger callback function', () => {
+    const appState = require('./appState')()
+    appState.get().should.equal('INIT')
+    appState.running()
+    appState.get().should.equal('RUNNING')
+  })
+
+  it('handling logger callback function, logging changes', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.init()
+    loggerCB.should.be.calledOnce()
+    // appState hasn't changed: called one
+    appState.init()
+    loggerCB.should.be.calledOnce()
+  })
+
+  it('changed: logged', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.running()
+    loggerCB.should.be.calledOnce()
+    appState.stopped()
+    loggerCB.should.be.calledTwice()
+  })
+
+  it('is logging', () => {
+    sinon.spy(console, 'log')
+    const logger = {
+      info (appState, newAppState) { console.log(`App state has changed from ${appState} to ${newAppState}`) }
+    }
+    const appState = require('./appState')(logger.info)
+    appState.init()
+    console.log.should.be.calledOnce()
+    console.log.should.be.calledWith('App state has changed from STOPPED to INIT')
+    console.log.restore()
+  })
+
+  it('is INIT', () => {
+    const appState = require('./appState')()
+    appState.init()
+    appState.get().should.be.equal('INIT')
+  })
+
+  it('is RUNNING', () => {
+    const appState = require('./appState')()
+    appState.running()
+    appState.get().should.be.equal('RUNNING')
+  })
+
+  it('is STOPPED', () => {
+    const appState = require('./appState')()
+    appState.stopped()
+    appState.get().should.be.equal('STOPPED')
+  })
+
+  it('is ERROR', () => {
+    const appState = require('./appState')()
+    appState.error()
+    appState.get().should.be.equal('ERROR')
+  })
+})