Set Method Overiew

New updates are merged into AutoImmutable instance data by default.

So only supply the exact changes to be merged (i.e. do not spread changing properties into the current properties as is commonly done in pure functional development).

An optional onUpdateComplete callback may be provided as a second argument.

And to overwrite/delete a slice of the AutoImmutable instance data, use any combinations of the tag commands.

Example:

import AutoImmutable from 'auto-immutable';

// Given the following immutable data:
const protectedData = {
    a: { b: [ { x: 7, y: 8, z: 9 } ] },
    j: 10
};

const aImmutable = new AutoImmutable( protectedData );

const consumer = aImmutable.connect();

consumer.set({
    a: {
        b: { 0: { y: 73 } },
        d: 80
    },
    j: 23
}, changes => console.log( changes ))
// updates AutoImmutable instance data to: {
//    a: {
//        b: [ { x: 7, y: 73, z: 9 } ],
//        d: 80
//    },
//    j: 23
// };
// the second argument is invoked immediately following the update

Indexing

Traditionally, AutoImmutable instance data properties of the Array type are updated by a new array replacement. This overwrites the current property.

Hence the need for indexing. Indexing provides a mechanism for updating array properties at specific indexes using an indexed change object property.

The store also recognizes and resolves negative indexes when present in the indexed change object. See additional tip below.

Example:

import AutoImmutable from 'auto-immutable';

// Given the following array bearing immutable data:
const protectedData = {
    a: { b: [ { x: 7, y: 8, z: 9 } ] },
    j: 10
};

const aImmutable = new AutoImmutable( protectedData );

const consumer = aImmutable.connect();

// The following will override the existing array.
consumer.set({ a: { b: [ { y: 30 }, 22 ] } });
// updates the AutoImmutable instance data to: {
//     a: { b: [ { y: 30 }, 22 ] },
//     j: 10
// };

// The followinng will update the existing array at indexes.
consumer.set({ a: { b: { 0: { y: 30 }, 1: 22 } } });
// updates the AutoImmutable instance data to: {
//     a: { b: [ { x: 7, y: 30, z: 9 }, 22 ] },
//     j: 10
// };

// The followinng will update the existing array at indexes.
consumer.set({ a: { b: { '-1': { y: 30 }, 1: 22 } } });
// updates the AutoImmutable instance data to: {
//     a: { b: [ { x: 7, y: 30, z: 9 }, 22 ] },
//     j: 10
// };

Tip:

Negative indexing pointing at an out-of-bounds index is ignored.

Batched Updates

Auto Immutable JS provides a means for updating data as a transaction of several change payloads.

The list of change payloads are applied sequentially from index 0 to the final index.

This capability is especially applicable when update operation using tag commands depends on previous outcomes.

import AutoImmutable from 'auto-immutable';

// Given the following immutable data:
const protectedData = {
    a: { b: [ { x: 7, y: 8, z: 9 } ] },
    j: 10
};

const aImmutable = new AutoImmutable( protectedData );

const consumer = aImmutable.connect();

consumer.set([
    {
        a: { b: { 1: 22 },
        c: 40
    },
    {
        a: { b: { 0: { v: 8, w: 560, y: 110, z: 120 } } }
    },
]);
// updates the AutoImmutable instance data to: {
//     a: { b: [ { v: 8, w: 560, x: 7, y: 110, z: 120 }, 22 ] },
//     c: 40,
//     j: 10
// };