revise-immutable

Expression-based utility to create modified copies of immutable objects.

Set

• Modify properties
• Build and populate objects with an expression
• Array operations (find/delete/insert/append)
• Set values based on existing values

Get

• Get object values using the same expression language

Setup

npm install revise-immutable

Usage

import revise from "revise-immutable";

// Setter
newObject = revise.set(oldObject, "item.collection[$2.selectedIndex].prop", "value");

// Getter 
value = revise.get(object, `path.to[find(${i => i.selected})].color`);

revise.set(<object>, <expression>, <value|valueSetterFunction>, [expression(n), value(n)...])

returns new object where the value at <expression> is modified to <value> without mutating the original object.

• <object> Object to create a revision of
• <expression> Expression describes what to revise relative to <object>
  • Expressions consist of:
    • property specifiers ex: "item.selectedIndex"
    • array specifiers ex: "items[1]" consist of

      • any expression that resolves to an integer in the array

        example: [1] or [(Math.PI * 100)>>0]

      • the remove() special function, which removes an element from the array

        example: "items[remove(1)]"

      • stack variables are defined as $1 to $n (incrementing), where $1 is the array itself, and $n is the root object.

        example: "items[$2.selectedIndex].color"

      • variable functions are available to append() and insert() elements into the array.

• <value> is the value to set at the given path
• <valueSetterFunction> optionally, you can provide a function to set the value. This is useful if the value you are setting is based off of an existing value in the object structure. Note that the stack is passed in as individual arguments to this function.
  example: revise.set(o, "users[0].likes", (likes, index, users) => likes + 1)

revise.get(<object>, <expression>)

• expression is same as above, except that it doesn't support array modification functions insert(), remove(), append().

Advanced Usage

Object Construction

Revise can interpret your expression and build out what isn't there.

revise.set({}, "item.collection[0].description", "Yah!");

// Produces this!
{
    item: {
        collection: [
            {
                description: "Yah!"
            }
        ]
    }
}

Arrays

// insert
// Inserts the value into the array at the specified position
revise.set(o, "gallery.photos[insert($2.selectedPhotoIndex + 1)]", newPhoto);

// append
// Returns the last index in the array plus 1
revise.set(o, "gallery.photos[append()]", newPhoto);

// remove
// Removes the first element that matches the condition
revise.set(o, "gallery.photos[remove($2.selectedPhotoIndex)]");

// find
// Finds the first element that matches the condition
revise.set(o, 
    `gallery.photos[find(${p => p.selected})].description`, 
    newDescription
);

// find or append
// Finds the first element that matches the condition
// If no element is found, returns the last index in the array plus 1
revise.set(o,
    `app.checklist[findOrAppend(i => i.id == ${itemId})])`,
    item => item != null 
        ? {...item, value: value} 
        : {id: itemId, value: value})
)

NOTE : in between [ ]'s, the following "stack variables" are available:

• $1 : reference to the array.
• $2 : reference to parent of array (if exists)
• $<n> : parent of n - 1...

Set Values Dynamically

// Use the existing values to make new ones
revise.set(o, "users[$2.selectedUserIndex].likes", likes => likes + 1);

// The full stack is available
revise.set(o, "a.b.c.d", (d, c, b, a, root) => root.score + c.score)

Batching

Combine multiple expressions together for one result.

const newObject = revise.set(o, 
    "options.preferences.theme", theme
    "options.preferences.editor.font", font
    "user.account.name", name
);

Limitations

• Revise doesn't handle strings with unmatched square brackets in the expression.
  • example revise.set(o, "items[find(i => i.name == ']')]) will cause an error
• Revise only understands property names with ASCII characters A-Z, a-z, _, $, 0-9.
• The find function expects an expression. In some older browsers, arrow functions may not be supported. You may use "function()" syntax instead of the arrow function syntax to remedy this. Another approach that works in some cases is to use string substitution such as a[find(${f => f.})], such that your own transpilation process will substitute the non-arrow function as appropriate. This, however, has the limitation in that it can't read external veriables.