Most state management libraries don't clone your state for you.
Most don't optionally deep clone your state. Most don't offer an entire messaging system either. Most don't come as a 3kb package. This one does.

• To manage state with a simple pub/sub pattern
• To improve upon the pub/sub with unidirectional data flow
• For State to return a new state (pure function)
• Message filtering can be applied without a switch statement (you create your own event $type)
• To allow for manipulation of deeply nested state properties through use of strings {'my[index]deeply.nests.state': 'new value'} (we're sending this to substate to not mutate the state, but make a new copy (Flux-y)!
• Maintain a small size

• Flow
• Terms
  • store
  • emit
  • on
  • off
  • payload
• How it Works
  • The Steps
• Demo
• Installation
• Development Mode
• Instantiation
• Options
• State Methods
• Event Methods
• State Events
• Custom Events
• Usage with React
• Updates to Come
• Pull Requests

The store is the substate instance. It has methods and state storage. It basically handles all your changes for you and acts as a mediator between different parts of your application. It's really a simple pub/sub pattern with data in it. That's all.

store - "I'll handle this!"
  ___________________
 |                   |
 | message queues    |
 | application state |
 |___________________|

A method that shoots a $type and payload to the store. This method tells the store: "Hey store. I need you to send this message $type out. And here's a payload of data to send with it!"

store.emit($type, payload);

A method that listens for the above $type and fires a callback function that gets passed the emit methods payload "Hello store. When you send out a message of this $type, please fire this callbackFunction and pass it your payload! Thanks!"

store.on($type, callbackFunction);

A method that stops a certain callbackFunction on a specific $type "Howdy store. When you send out a message of this $type, you don't need to fire this callbackFunction. Please remove the function from your queue."

store.off($type, callbackFunction);

An object of data. You can put any data in there that you want. The idea is that you would put your updated state object in there. The store will save your old state and emit your make updates to your new state according to this object. When triggering a state change with UPDATE_STATE you have the option of passing 2 fields into your payload

• $type - this is a String value of a message $type that the store will emit. So if you pass it $type: "SAY_HI", the store will emit store.emit("SAY_HI", data) and any callbacks that have been registered with store.on("SAY_HI", callback) will be fired in registration order.
• $deep - this is a boolean that, when set to true will deep clone your state object. In the guts of the store we use Object.assign, which does not deep clone the state object. But the store has a special trick that can deep clone for you. So that means you don't have to normalize your state. You can have it as nested and complicated as you want. This is a huge plus for people who want their state to reflect their complex dataset.

1. (if using modules)

//store.js
import substate from "substate";

export const store = new substate({
  state: {
    todos: [],
  },
});

// MyComponent.js
import { store } from "./store.js";

2. Components will register one or more methods to rerender themselves using your instance (see instantiation) using myInstance.on('STATE_UPDATED', rerender) per method You can register to a custom event as well

// MyComponent.js

// default state event
store.on("STATE_UPDATED", rerenderFunction);

// custom state event
store.on("HEIGHT_CHANGE", rerenderFunction);

3. Components take UI event ("click", "focus", etc) and pass it off to a Handler/Reducer

// MyComponent.js
element.addEventListener("click", clickHandler);

4. The Handler/Reducer figures out what should change in the state (it does not update the state directly). It also figures out if/what $type should be sent to the Pub/Sub module

// MyComponent.js

clickHandler = () => {
  // define which fields should be updated and to what values
  // you can use string notation because of the underlying technology in substate!

  const newState = {
    name: "Pablo",
    "height.inches": 62,
    "height.centimeters": 157.48,
  };

  store.emit("UPDATE_STATE", newState);
};

A couple notes: If you want a deep clone pass in $deep: true into the state on emit. OR defaultDeep: true in the options.

const newState = {
  ...newValues,
  $deep: true,
};

If you want to emit a custom event, you can pass in a $type If you want a deep clone pass in $deep: true into the state on emit. OR defaultDeep: true in the options.

const newState = {
  ...newValues,
  $type: "HEIGHT_CHANGE",
};

https://codesandbox.io/s/substate-example-6qfbx

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

ES2015 Version

// ES Module
import substate from "substate";

// Node
const substate = require("substate");

// Dev Version
// ES Module
import substate from "substate/dist/index.dev.js";

// Node
const substate = require("substate/dist/index.dev.js");

ES5 Version

// ES Module
import substate from "substate/dist/index.es5.js";

// Node
const substate = require("substate/dist/index.es5.js");

// Dev Version
// ES Module
import substate from "substate/dist/index.es5.dev.js";

// Node
const substate = require("substate/dist/index.es5.dev.js");

Running the *.dev.js versions of substate will output a warning that you are using the developer mode.
This will use console.debug to display:

• What data changed
• What action type caused this change
• Where was this action fired from

substate is a class so you call it like so

myFile.js

import { substate } from 'substate';

Then you instantiate it as such

export const myInstance = new substate({options});

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

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

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

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

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

• better dev instructions and console warnings/errors
• typescript support
• seemless compatibility with react, infernojs, preactjs, stenciljs
• demos demos demos
• better documentation