js-immutable

    0.0.7 • Public • Published

    Motivation 🐬🐬

    Consider the scenario where you have to set a new value to "temporary" field without mutating original state.

    const state = {
      detail: {
        age: 30,
        friends: ['Roshan'],
        personal: {
          address: {
            permanent: 'Kathmandu',
            temporary: 'Pokhara'
          },
          spouse: 'Nancy'
        }
      }
    }          

    Javascript way of setting a new value without modifying original state would be something like this:

    // For my brain, this is too much to wrap around just to change a single field.
    // There must be some better way. 
    const newState = {
      ...state,
      detail: {
        ...state.detail,
        personal: {
          ...state.detail.personal,
          address: {
            ...state.detail.personal.address,
            temporary: 'New Random Location' // here is the actual change
          }
        }
      }
    } 
     
    Look at all the repetition! This is not only annoying, but also provides a large surface area for bugs.

    Problems with the above code:

    📌 Need to keep track of whole state tree just to perform such small modification.

    📌 Need to make sure that state tree is not mutated while returning new state.

    📌 Need to make sure structure of state tree is not changed while returning new state. Specially it becomes nightmare in real world application where you don't know which action modified the entire redux state.

    📌 If structure of original state tree is modified, then every action reducer must be re-written. i.e Your reducer has an dependency on structure of redux state.

    JS Immutable in Action

    // Add as a dependency
    npm install js-immutable --save
    import reduce from 'js-immutable';
    // create a address reducer by passing a selector
     
    const addressReducer = reduce({
      detail: {
        personal: {
          address: {
            temporary: '#',
          }
        }
      }
    })
    // No mutation fear
    // State Structure is maintained
    // No dependency to the state structure while returning new state
     
    const newState = addressReducer(state)
      .set('New Random Location')
      .apply();

    A more complex scenario where we need to append new friend to the friends list and set new value to permanent address.

     
    const complexReducer = reduce({
      detail: {
        friends: '#friends', // selector
        personal: {
          address: {
            permanent: '#permanent' // selector 
          }
        }
      }
    });
     
    // Clean and elegant 
    const newState = complexReducer(state)
      .of('#friends') // using friends selector and appending
      .append('John')
      .of('#permanent') // using permanent selector and setting
      .set('New Value')
      .apply();
     
    // or you can simply pipe it through predicate
     
    const newState = complexReducer(state)
        .of('#friends')
        .pipe(friends => friends.concat('John'))
        .of('#permanent')
        .pipe(value => value.toUpperCase())
        .apply();

    Note

    ###### '#' is the default selector. You don't need to use "of("some selector")' when you use '#' as a selector.

    ### Benefits 📌 Structural Sharing out of Box. Performant! 📌 Your code is independent of the state tree and it's structure.

    📌 You don't have to worry about mutation. Js-Immutable handles it for you.

    📌 You only have to make changes to selector if structure of redux state tree is modified. Your reducer will never be touched in the case of state tree modification.

    📌 It looks functional, clean, simple and easy to follow. It just makes life of your co-worker easier.

    More on JS-Immutable

    Selector

    Selector are plain object that helps to select the fields on the state tree. Default selector value is '#'. The selector value must start with '#'. If your selector has multiple fields to select, Make sure they start with '#' and are unique.

    // Example of Selector
     
    const selector = {
      person: {
        friends: '#' // default
      }
    }
    // Example of using the above selector
     
    const friendsReducer = reduce(selector);
     
    const newState = friendsReducer(state)
      .append('My new friend') // no need of "of('#')" since it is the default one.
      .apply();
    // Example of multiple selector
     
    const nextSelector = {
      name: '#name', // named selector (unique)
      detail: {
        address: '#address' // named selector (unique)
      }
    }
     
    // Example of using the above selector
     
    const multipleReducer = reduce(nextSelector);
     
    const newState = multipleReducer(state)
        .of('#name')
        .set('New Name')
        .of('#address')
        .merge({temporary: 'Pokhara'})
        .apply();

    Available Methods

    💧 set(value: any)

    💧 append(value: any)

    💧 merge({key: value})

    💧 extend([]: any)

    💧 delete(key: any)

    💧 pipe(predicate: function)

    Utility Method

    💧 Of(selectorName: any)

    Helps to select the specific target so that it apply transformation to that target in the object.

    // if we have a multiple targets in a single selector
    const selector = {
      task: {
        done: '#done',
        taskDetail: '#taskDetail'
      }
    }
    const taskReducer = reduce(selector)
     
    const newState = taskReducer
        .of('#done')
        .set(true)
        .of('#taskDetail')
        .set('some new Detail')
        .apply();

    Note:

    If you think I have missed methods that is crucially important, then please send a Pull Request.

    License

    Copyright © 2015-2016 Robus, LLC. This source code is licensed under the MIT license found in the [LICENSE.txt] The documentation to the project is licensed under the CC BY-SA 4.0 license.


    Made with ♥ by Robus Gauli ([@robusgauli]

    Keywords

    none

    Install

    npm i js-immutable

    DownloadsWeekly Downloads

    2

    Version

    0.0.7

    License

    MIT

    Unpacked Size

    77.9 kB

    Total Files

    15

    Last publish

    Collaborators

    • robusgauli