state-update-builder

state-update-builder

A javascript utility to navigate, update and then generate versionable copies of plain js objects

Why You Should Use It

This small lib is useful in the following scenarios:

• navigate through objects subtree and retrieve data
• shallow copy objects
• object versioning:
  • you have to change data or structure of a shallow copy without affecting the original
  • grant immutable objects using plain objects

Install

  npm install --save state-update-builder 

Basic Usage (ES6 syntax)

You can simply navigate and update create a copy of an object

import StateUpdateBuilder from 'state-update-builder'

let obj = {a:{ b:1},c:{ d:3}};

let builder = new StateUpdateBuilder(obj);

//set param b of a to 2
builder.traverseNode('a').set('b', 2);

let objNextState = builder.execute();

console.log(obj == objNextState) //returns false

console.log(obj.a == objNextState.a) //returns false

console.log(obj.c == objNextState.c) //returns true because only the "a" subtree is changed 

PROPS

Name	Description
origin	current SUB subtree node. You should consider it as readonly prop
current	current SUB updated node. You should consider it as readonly prop

API

API to navigate object

Name	Description	Return
traverseNode(label:string)	navigate to "label" subtree. "label" prop must be an object	a new StateUpdateBuilder (linked to caller SUB) positioned on "label" subtree
traverseList(label:string, lambda:function)	navigate from current subtree to "label" array than into the first element of "lambda" that matches lambda condition	a new StateUpdateBuilder (linked to caller SUB) positioned on matched "label" element subtree
checkSubtree(label:string, lambda:function)	check if "label" subtree exists in the currentNode. If "label" is an array you can use "lambda" parameter to check array item like traverseList. If "label" is a node, you can use "lambda" to perform an extra check of its content	bool

API to update object subtree

Name	Description	Return
set(label:string, value:any)	set "value" to "label" (original object wont be affected)	current SUB
setNode(node:any)	replace current subtree with "node" (original object wont be affected)	current SUB
merge(label:string, value)	merge "value" with "label" (original object wont be affected)	current SUB
mergeNode(node:object)	merge current subtree with "node" (original object wont be affected)	current SUB
removeNode(label:string [, lambda:function])	remove "label" subtree (original object wont be affected). If "label" is an array and you you can pass lambda to select the element you want to remove (without lambda the whole array will be removed)	current SUB
push(label:string, array:Array)	add "array" elements into "label" array (original object wont be affected)	current SUB
unshift(label:string, array:Array)	remove "array" elments from "label" array (original object wont be affected)	current SUB
splice(label:string, start:number, deleteCount:number, item1:any, item2:any, ...)	call splice fn on "label" array	current SUB
apply(label:string, fn:function)	calls "fn" passing the value of "label" then update "label" with the function result	current SUB

API to manage Current State

Name	Description	Return
checkNodeUpdated()	check if node related to current SUB has been modified	bool
checkError()	check if current SUB is in error	bool
resetError()	remove error status to current SUB and to related ancestors	void

Note: the traverse functions returns a new StateUpdateBuilder linked to the caller SUB with a parent-child relationship. When a SUB generates an exception, an error status will be set and propagated to every parent SUB.

Generate object

Name	Description	Return
execute()	generates the new object version	bool

TODO

• add more examples
• use a.b.c syntax in labels to navigate and update model at the same time