Statorgfc (wip) ·

a library for state management of JavaScript apps, with built-in support for React Components

Used for state management of a JavaScript application when any of the following are true

• the same piece of application state needs to be mapped to multiple container components
• there are global components that can be accessed from anywhere
• too many props are being passed through multiple hierarchies of components

If you can maintain the state of a component within the component itself you should not use statorgfc.

Statorgfc has

• Predictable global state: State management occurs in one location -- a variable named store.
• Intuitive API: Similar to React's, with no boilerplate necessary
• Typesafe changes: Values can only be replaced with data of the same type
• Immutable data... or not: You choose if you want to work with immutable data structures by setting a single boolean
• No Dependencies: Written in plain JavaScript. No dependencies.
• Efficient: If a value isn't changed during an update to the store, listeners aren't notified

Install

yarn add statorgfc

Simple Example

import {store} from 'statorgfc'

store.initialize({count: 0})

store.get('count')  // 0
store.set({count: store.get('count') + 1}) // changed value to 1
store.get('count') // 1

Subscribe a function to changes

import {store} from 'statorgfc'

store.initialize({count: 0})

store.subscribe( () => console.log(store.get()) )  // call anytime something changes, and log entire store
store.set({count: store.get('count') + 1})  // prints {count: 1}
store.set({count: store.get('count')})  // no callbacks triggered, because the value didn't actually change

Connecting React Component's State to Global Store

import {store} from 'statorgfc'
import React from 'react'

// keys cannot be added after initialization.
// Type of value of each key cannot be changed after initialization.
store.initialize({
    numSheep: 10,
    numWolves: 2,
    numChickens: 90
  })

// Create a normal component
class SheepWatcher extends React.Component {
  constructor(){
      super()
      // connect global store to the state of this component
      store.connectComponentState(this, ['numSheep', 'numWolves'])  // this.setState will be called when 'numSheep' or 'numWolves' changes
  }
  render(){
    return <div>
      <h1>Sheep Watcher</h1>
      Current sheep status: {this.state.numSheep > this.state.numWolves ? 'all good' : 'watch out sheep!'}
    </div>
  }
}

// somewhere else in a component far, far away...
store.set({numSheep: store.get('numSheep') + 1})  // triggers a call to setState in sheepWatcher, which updates that component
store.set({numChickens: 100})  // doesn't trigger a call to setState in sheepWatcher
// because sheepWatcher isn't connected to the numChickens key

See which components listen to which keys

let watchers = store.getKeySubscribers()
console.log(watchers)
// {
//   "numSheep": ["SheepWatcher"],
//   "numWolves": ["SheepWatcher"]
// }

If a key in the store is not being acted upon by anything, that is useful to know too. You can probably remove that key from the global store and simply store it statically somewhere else.

let no_watchers = store.getUnwatchedKeys()
console.log(no_watchers)
// ["numChickens"]

See more examples.

Real World Use Cases

• gdbgui: frontend to a C/C++ debugger written as a single page JavaScript app with many disparate components that need to update frequently and efficiently. It is 5749 lines of JavaScript across 41 files and dozens of components and JavaScript functions.

License

MIT

Author

[email protected]