quark-state

Simple state manager based on Singleton design pattern.

This package is part of quark framework but it can be used independently.

Installation

npm install quark-state --save

Usage

Basic

Initialize a container and set/get a prop.

import State from 'quark-state'

const initialUserState = {
  'name': 'John Doe',
  'age': 36,
  'location': {
    'latitude': 34.564756,
    'longitude': 32.804872
  }
}

// Initialize a container
State.initContainer('USER', initialUserState)

// Get a prop from a container
const name = State.get('USER.name') // = 'John Doe'

// Set a prop on a container
State.set('USER.age', 40)

Container

Init a container

import State from 'quark-state'

const initialContainerState = {}
State.initContainer('CONTAINER', initialContainerState)

Destroy a container

import State from 'quark-state'

State.destroyContainer('CONTAINER')

Clear

Clear the State by destroying all containers

import State from 'quark-state'

const initialContainerState = {}
State.initContainer('CONTAINER', initialContainerState)

State.clear()

Set

Set a (deep) prop

import State from 'quark-state'

const initialContainerState = {
  'deep': {
    'prop': true
  }
}
State.initContainer('CONTAINER', initialContainerState)

State.set('CONTAINER.deep.prop', false)

Set an object prop (merge)

import State from 'quark-state'

const initialContainerState = {
  'deep': {
    'prop': {
      'integer': 10,
      'boolean': true
    }
  }
}
State.initContainer('CONTAINER', initialContainerState)

// By default, it will merge the two objects
State.set('CONTAINER.deep.prop', {
  'integer': 20,
  'string': 'foo'
})

Set an object prop (overwrite)

import State from 'quark-state'

const initialContainerState = {
  'deep': {
    'prop': {
      'integer': 10,
      'boolean': true
    }
  }
}
State.initContainer('CONTAINER', initialContainerState)

// If you set the third argument to true, it will overwrite the prop value
State.set('CONTAINER.deep.prop', { 'integer': 20 }, true)

Get

import State from 'quark-state'

const initialContainerState = {
  'boolean': true
}
State.initContainer('CONTAINER', initialContainerState)

State.get('CONTAINER.boolean') // = true

Has

Check if the given query exists (container or prop)

import State from 'quark-state'

const initialContainerState = {
  'string': 'foo'
}
State.initContainer('CONTAINER', initialContainerState)

State.has('CONTAINER') // = true
State.has('CONTAINER.foo') // = true
State.has('CONTAINER.doesNotExist') // = false

On change

Add

When a prop is modified, call a callback with old and new values

import State from 'quark-state'

const initialContainerState = {
  'string': 'foo',
  'deep': {
    'prop': true
  }
}
State.initContainer('CONTAINER', initialContainerState)

// When a prop is modified, callback is called
State.onChange('CONTAINER.string', (oldVal, newVal) => { }) // oldVal = 'foo', newVal = 'bar'
State.set('CONTAINER.string', 'bar')

// When a deep prop is modified, it also triggers parent callback
State.onChange('CONTAINER', (oldVal, newVal) => { }) // oldVal = true, newVal = false
State.set('CONTAINER.deep.prop', false)

Remove

import State from 'quark-state'

const initialContainerState = {
  'string': 'foo',
  'deep': {
    'prop': true
  }
}
State.initContainer('CONTAINER', initialContainerState)

const callback = (oldVal, newVal) => { } // Won't be trigger

State.onChange('CONTAINER.string', callback)
State.removeChangeCallback('CONTAINER.string', callback)

State.set('CONTAINER.string', 'bar')

API

See https://fm-ph.github.io/quark-state/

Build

To build the sources with babel in ./lib directory :

npm run build

Documentation

To generate the JSDoc :

npm run docs

To generate the documentation and deploy on gh-pages branch :

npm run docs:deploy

Testing

To run the tests, first clone the repository and install its dependencies :

git clone https://github.com/fm_ph/quark-state.git
cd quark-state
npm install

Then, run the tests :

npm test

To watch (test-driven development) :

npm run test:watch

For coverage :

npm run test:coverage