Mutastate NPM | npm.io

Description

Mutastate is designed to manage state and send notifications to listeners when state changes.

install

npm install --save mutastate

Api

importables

import Mutastate, {
    withMutastateCreator,
} from 'mutastate';

Mutastate (default import)

The mutastate class, this class is responsible for maintaining state and sending notifications to listeners

import Mutastate from 'mutastate';
const mutastate = new Mutastate();
mutastate.set('foghorn', 'leghorn');
console.log(mutastate.get('foghorn')) // returns leghorn

Functions

getAgent(onChangeFunction)
- Get a new mutastate agent attached to this instance of mutastate
getProxyAgent(onChangeFunction)
- Get a new proxy enabled mutastate agent attached to this instance
listen(key, listener = { callback: () => {}}, alias: null, batch: null, transform: null, defaultValue: undefined })
- listen for changes, notify callback when they occur, defaultValue will directly affect the current data if nothing exists! use batch for easy batch unlistening
unlisten(key, callback)
- Unlisten from a single key with a single known callback function
unlistenBatch(batch, basePath)
- Unlisten from all associated triggers for one given batch which was passed into listen
getForListener(key, listener, keyChange)
- Get data for a given key and listener, this is used by agents to get initial data, and internally to get relevant data upon updating
get(key)
- Get data at a single key, key can be a string with delimiters or an array 'a.b.c0' is equivalent to 'a', 'b', 'c', 0
set(key, value, options)
- Set data.key to value, key can be complex as in get()
delete(key)
- Remove data.key, key can be complex as in get()
assign(key, value)
- Merge value into data.key object, key can be complex as in get()
push(key, value, options)
- Add value to the end of the array at data.key, key can be complex as in get()
pop(key, options)
- Remove final value from the end of the array at data.key, key can be complex as in get()
has(key)
- If the key exists at data.key, return true, otherwise return false, key can be complex as in get()
getEverything()
- return all data for all shards
setEverything(data)
- update all data for all shards
addChangeHook(callback)
- notify callback whenever any data changes, ({ key: [], value: any, meta: { defaultValue: true|undefined, setEverything: true|undefined }}) => {} this is most useful for automated persistence functionality
removeChangeHook(callback)
- stops notifying callback on any data change
replicate({ send, primary, ignore, sendInitial, canSetEverything })
- replicates mutastate to another instance across a network/ipc/rpc

Mutastate Agent

functions

new MutastateAgent(mutastateInstance, callbackFunction) or mutastateInstance.getAgent(callbackFunction)
- Connect to the mutastateInstance and execute callbackFunction when data changes.
listen(key, { alias, transform, initialLoad = true, defaultValue } = {})
- Listen for changes at key in mutastate, then call callbackFunction from the constructor
listenFlat(key, { alias, transform, initialLoad = true, defaultValue } = {})
- Listen for data at key, automatically set alias to the last key section. 'a', 'b', 'c' sets the alias to 'c'
batchListen(childFunction)
- Execute a lambda, during the lambda execution don't send callback information, after the lambda execute the callback
multiListen(listeners, { flat = true } = {})
- Same as listen or listenFlat, but include a { key } in the listener
get(key)
- Get data at key from mutastate
set(key, value)
- Set data at key in mutastate
delete(key)
- Delete data at key in mutastate
assign(baseKey, value)
- Perform an Object.assign() on the object that is at the baseKey in mutastate
push(baseKey, value)
- Push into an array found at baseKey in mutastate
pop(key)
- Remove the last item in an array found at key
has(key)
- Detect if mutastate contains data at this key
assure(key, defaultValue)
- If has fails on this key, use set at that key with defaultValue
getEverything()
- Return all of mutastate
setEverything(data)
- Overwrite all data in mutastate
getAgentData()
- Get current agent data (including aliased data)
pause()
- Pause callback (data will still flow to the agent unless you manually unlisten)
resume()
- Resume callbacks, you may want to manually re-target information found in getAgentData after resuming
resolve(aliasedKey)
- Resolve an alias to the full mutastate path. agent.listen('a.b.c', { alias: 'bobby' }); then agent.resolve('bobby') will return ['a', 'b', 'c']

Use with React

You can use react hooks like so:

import React from 'react';
import { useMutastate } from 'mutastate';

const randomName = () => ['jerry', 'bobby', 'carl'][Math.floor(Math.random() * 3)];

function Assignment(props) {
    [assignment, setAssignment] = useMutastate(['assignment', props.id]);

    const updateAssignment = (data) => {
        return setAssignment({ ...assignment, ...data });
    }

    return (
        <div>
            <div>{assignment.name}</div>
            <div>{assignment.count}</div>
            <div>{JSON.stringify(assignment.list)}</div>
            <button onClick={() => updateAssignment({ count: assignment.count + 1 })}>Add To Count</button>
            <button onClick={() => updateAssignment({ name: randomName() })}>Change Name</button>
            <button onClick={() => updateAssignment({ list: assigment.list.concat(randomName()) })}>Add To List</button>
        </div>
    );
}

If you want to use traditional react class components you can use a higher order component like so:

This example demonstrates how to create a connected react component, this particular component listens for data in the default shard, under the key ['default', 'assignments', props.id]. This means if the data at that key is updated, this component will receive an update including the new data.

It is important to note that the common pattern of incoming props checking for component updating when using mutastate will not function correctly, unless you make a deep copy of your incoming props for comparison yourself. The data passed into your component will be mutated!

Indicating { useProxy: true } will allow you to modify the data directly (only simple data, objects, arrays, strings, numbers, no custom classes or functions) as we do in this example (see assignment.count += 1). The data will not, in fact, be modified; the modification will be captured and converted into function calls to the current mutastate. (the previous assignment.count += 1 becomes mutastate.set('default.assignments[1].count', assignment.count + 1))

Also please note that the function is withMutastateCreator instead of withMutastate, this is to avoid the ambiguity of having a separate repository for react, this is subject to change in a major version far in the future, currently if you want a withMutastate function you can create one by executing: const withMutastate = withMutastateCreator(React, { instance: yourMutastateInstance, useProxy: true });;

import React from 'react';
import { useMutastate } from 'mutastate';

class Assignment extends React.Component {
    constructor(props) {
        super(props);
        props.agent.listen(['default', 'assignments', props.id], { alias: 'assignment', defaultValue: { name: 'john', count: 0, list: [] } });
    }
    render() {
        const { assignment } = this.props.data;

        return (
            <div>
                <div>{assignment.name}</div>
                <div>{assignment.count}</div>
                <div>{JSON.stringify(assignment.list)}</div>
                <button onClick={() => assignment.count += 1}>Add To Count</button>
                <button onClick={() => assignment.name = ['a', 'b', 'c'][Math.floor(Math.random() * 3)]}>Change Name</button>
                <button onClick={() => assignment.list.push('another')}>Add To List</button>
            </div>
        );
    }
}

export default withMutastateCreator(React, { useProxy: true })(Assignment);

Replication

You can replicate mutastate to secondary instances, useful in circumstances where you don't have direct access to the same mutastate instance such as multi-window electron apps

// start replication, the send function will get called whenever any data in our instance changes (but will ignore changes that came from other instances). In this case we use a fake sendIpcMessage function
const receiver = singleton().replicate({ send: data => sendIpcMessage('state-sync', data) });

// this fictitious listenForIpcMessages function shows how you can receive data from an outside source to update your own mutastate
listenForIpcMessages('state-sync', (sender, data) => receiver(data));

The use of useProxy will limit your browser availability due to use of the Proxy es6 feature: