Empire State

A small package to work with mutable state without a lot of boilerplate, immutability when you want it, and type-safety using TypeScript.

empire-state lets you view and mutate state using a Controller, while also providing access to immutable copies of state using Snapshots.

Each Controller or Snapshot provides a method to change the state. All changes are immediately visible in the Controller, but a Snapshot never changes.

Installation

npm install empire-state

Example

import { controllerWithInitialValue } from 'empire-state'

const controller = controllerWithInitialValue({
	a: 'Hello world',
	b: 42,
	c: {
		d: 'Nested okay',
		e: ['A', 'B', 'C', 'D'],
	},
})

controller.get('a').setValue('Bye bye')

const immutableValue = controller.snapshot('c')

Snapshots

A Snapshot is an immutable snapshot of the state from a controller.

You can obtain snapshots from the Controller of either the whole state, or of parts of the state. Any changes you make via the Controller will be reflected immediately in the controller's value, but the Snapshot never changes as it is immutable — ensuring that you retain a consistent, immutable view of the state.

const aSnapshot = controller.snapshot('a') // Snapshot<string>
// aSnapshot.value === 'Hello world'

aSnapshot.change('Bye bye')
// controller.value.a === 'Bye bye'
// aSnapshot.value === 'Hello world'

Snapshots can be created for any type, including objects:

const cSnapshot = controller.snapshot('c') // Snapshot<{ d: string, e: string[] }>
// cSnapshot.value.d === 'Nested okay'

cSnapshot.change({
	d: 'Changed',
	e: ['E'],
})

// controller.value.c.d === 'Changed'
// cSnapshot.value.d === 'Nested okay'

You can also create controllers for nested objects in order to access further nested snapshots:

const eSnapshot = controller.get('c').snapshot('e') // Snapshot<string[]>

// eSnapshot.value == ['E']

eSnapshot.change(['F', 'G'])
// controller.value.c.e == ['F', 'G']

This pattern is powerful when sharing state between multiple pieces of code while wanting to ensure an immutable and consistent view of that state; creating and sharing a new snapshot of the state when appropriate.

Changing values

You can change the value in a Controller either by using a Snapshot, as above, or by using the setValue or set methods on the Controller. The setValue method sets the entire value of the Controller. The set method can identify a nested value in the Controller and change that.

You can also obtain a function that changes a value in the Controller when the function is called. Use onChange(...) to obtain a function that changes the specific value in the Controller when it is called. Use onToggle(...) to obtain a function that toggles a boolean value when called.

Nested controllers

You can obtain a controller for a nested value. Any changes to the nested controller are also reflected in the parent controller.

const cController = controller.get('c')
cController.setValue({
	d: 'Gone',
	e: [],
})

Array Controllers also support map and find to access nested controllers:

const eController = controller.get('e')
eController.map((controller: Controller<string>, index: number, array: string[]) => controller.value.toLowerCase()) == ['a', 'b', 'c', 'd']

const ecController = eController.find((value: string, index: number, array: string[]) => value === 'C')
ecController.setValue('c')

Controller reference

A Controller manages a value. It is a generic type, where its type represents the type of value it contains.

Some examples of controllers:

• Controller<string> for a controller that simply contains a string value
• Controller<Person> for a controller that contains an object
• Controller<Person[]> for a controller that contains an array

Accessing the value

You can get the value from the controller using the value property, and set it using the setValue method.

Note that the value in the controller is live, ie. it is independent of React’s render cycle.

You can also obtain functions to change the value for the controller, or for a property in the controller:

Nested values

When the controller contains an array or an object, you can create sub-controllers to access specific parts of the controller. Changes in sub-controllers are immediately reflected in the parent controller.

Array controllers

When a controller contains an array value, these methods are applicable:

Object controllers

When a controller contains an object value, these methods are applicable:

Listening for changes

You can add change listeners to a controller. The change listener will be called when the value in the controller is changed.

controller.addChangeListener(function(newValue: T) {

})

Listeners can also be removed:

controller.removeChangeListener(listenerFunc)

Listeners can be added with a "tag" and then removed all at once:

controller.addChangeListener(listenerFunc, 'myTag')
controller.removeAllChangeListeners('myTag')

Or all change listeners can be removed:

controller.removeAllChangeListeners()

Transforming Controllers

Sometimes controllers don't contain exactly the right type of value that you need, so you can transform a controller using a pair of functions to map between two different types.

First create a ControllerTransformer<T, X>, which is an object containing to and from functions. Then pass that object to the controller's transform(ControllerTransformer<T, X>) method to obtain a transformed controller.

ControllerTransformers should be statically initialised and reused as the controller memoizes the transformed controllers.

Some build in transforming functions are included: