Nanananananananana.. Pat Man!

    immutable-state-controller
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    Immutable State Controller

    npm version Node CI

    A small library to work with immutable state without a lot of boilerplate, but with a lot of type-safety using TypeScript.

    immutable-state-controller 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 immutable-state-controller

    Example

    import { controllerWithInitialValue } from 'immutable-state-controller'
    
    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.

    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.

    Property / Method Description
    value The value in the controller.
    setValue(newValue: T) Set the value in the controller.

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

    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:

    Method Description
    get(index: number) Returns a sub-controller for the value at the given index.
    set(index: number, newValue) Set the value at the given index.
    map(callback) Map over the values. The callback receives a controller for each value as its first argument and an index as its second.
    find(predicate) Returns the first value in the controller that matches the predicate. The predicate signature is (value: T, index: number, array: T[]) => boolean. The find method returns a Controller for the found value, or undefined if not found.
    findIndex(predicate) Returns the index of the first value in the controller that matches the predicate. The predicate signature is (value: T, index: number, array: T[]) => boolean.

    Object controllers

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

    Method Description
    get(prop: string) Return a sub-controller for the value of the given property.
    set(prop: string, newValue) Set the value of the given property.
    get(prop: string, index: number) Returns a sub-controller for the value at the given index of the array in the given property.
    map(prop: string, callback) Map over the values in the given array-valued property. The callback receives a controller for each value as its first argument and an index as its second.
    find(prop: string, predicate) Returns the first value in the given array-valued property that matches the predicate. The predicate signature is (value: T, index: number, array: T[]) => boolean. The find method returns a Controller for the found value, or undefined if not found.
    findIndex(prop: string, predicate) Returns the index of the first value in the given array-values property that matches the predicate. The predicate signature is (value: T, index: number, array: T[]) => boolean.

    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()

    Keywords

    Install

    npm i immutable-state-controller

    DownloadsWeekly Downloads

    0

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    83.8 kB

    Total Files

    37

    Last publish

    Collaborators

    • karlvr