SubState

The Problem

State management with Redux is really nice. But it requires switch statements and works poorly with deeply nested states. I also find the terminology very confusing.

Purpose

• To manage state with a simple PubSub pattern
• For State to return the whole state or just a chunk of state (just what you need).
• Message filtering can be applied without a switch statement (you create your own event types)
• To allow for manipulation of deeply nested state properties through use of strings
• Maintain a small size. Currently it's 6kb minified, <2kb gzipped!

note: anything marked | no docs | means I haven't documented it yet.

Contents

1. Demos
2. Installation
3. Instantiation
4. Options
5. Initialization
6. State Methods
7. Event Methods
8. State Events
9. Custom Events
10. Updates to Come

Demos

• Demo showing State object changing. The module can be observed in the console
• Demo with React and VanillaJS
• new demos forth-coming with React, Vanilla JS, jQuery

Installation

• npm install substate --save
• copy and paste from index.js into a <script> or external js file

Instantiation

SubState is a class so you call it like so

import SubState from 'substate';

Then you instantiate it as such

var s = new SubState();

Options

Substate accepts an options object as an optional parameter. These are the possible options

Option	Desc	Default
name	name of the instance	'SubStateInstance'
currentState	index of state to start on	0
stateStorage	array of all the states	[ ]
saveOnChange	save state to localStorage on change	null
pullFromLocal	pull currentState from localStorage on initialization	null
state	object containing the initial state	null

Initialization

to initialize the class call

instance.init()

State Methods

• @param optional method parameter
• @param* required method parameter

Method	Desc	Returns
getState	get a state @param* - index of state needed	state
getcurrentState	get the current state	current state object
getProp	get a prop from current state @param* - string path to prop	property you request
changeState	change the version of the state @param* - {requestedState: index of state, action: (optional name of event to emit)}	emits action parameter event or 'STATE_CHANGED' event with the new current state
saveState	save stateStorage array to localStorage. Will use instance param of name	emits 'STATE_SAVED'
removeSavedState	removed state from LocalStorage	emits 'STATE_REMOVED_SAVED_STATE'
resetState	resets the stateStorage array to an empty array	emits 'STATE_RESET'

Event Methods

• @param optional method parameter
• @param* required method parameter
• @param[num] order of method parameter

Method	Desc
on	@param1* STRING of event name to listen to. @param2* FUNC handler to execute when this event you listen to happens
off	@param1* STRING of event name to remove handler from. @param2* FUNC to remove from the execution queue
emit	@param1* STRING event name @param2 object of data to pass into your handler event from 'on' method

State Events

Event	Desc	Returns
'UPDATE_STATE'	updates the entire state with the object passed in	updated state
'UPDATE_CHUNK'	updates part of a state, this does not iterate over the entire state object	the data passed in
'CHANGE_STATE'	fires changeState method above requires same @params	emits 'STATE_CHANGED'

Custom Events

note: the object of data that is passed, cannot have a key called 'type'

Method	Event	Custom Event	Next
emit	'UPDATE_CHUNK' or 'UPDATE_STATE'	@param2 is an object: {type: 'MY_CUSTOM_EVENT'}	Will update/change state. The type property will then be emitted so you can listen to it like SubStateInstance.on('MY_CUSTOM_EVENT', func)

To clear this ^ up :

Basically to utilitze a custom event, you still need to use UPDATE_STATE/UPDATE_CHUNK but the data object needs a type with an event name you want the State to emit when updated

Updates to come

1. Documentation on Custom Events
2. Example Code for all Events and Custom Events
3. documentation on special array methods for state
4. change 'action' nomenclature to 'event'
5. Add in comments and console.logs and remove them with UglifyJS
6. Have only production version with dev version not published to npm