README
Domes
What's a dome?
A dome is an object that wraps another object, and proxies reads and mutations to it. Those mutations are kept in a diff-log that can be extracted, so that it can be synchronized to other domes. This way two domes can remain identical. Imagine for example that you want to read a JSON object from your database and keep it synchronized in a browser. You can instantiate domes both in Node and the browser, and exchange diff-logs to keep them synchronized.
You can also listen for events on changes on values, so you can update UI or do other operations based on particular data being mutated.
Benefits over other solutions
- Domes do not inject hidden meta data into your objects.
- Designed for crazy performance.
- No more object-chaining errors (
Cannot read property 'foo' of undefined
). - Simple API and simple design, easy to maintain.
- Ability to snapshot and rollback the data to a previous state.
Installation
npm install domes --save
Example usage
var dome = require('domes');
var myObject = { hello: 'world' };
var d = dome(myObject);
d.set('hello.world.foo.bar', { a: { whole: { new: 'world' } } });
d.get('hello.world.foo.bar.a.whole.new'); // returns 'world'
d.set('list', []);
d.push('list', 'item1', 'item2');
API reference
Glossary
- dome: wraps your object or array
- target: the object or array being wrapped
- path: a string that describes the path to a sub-property or index into an array (eg:
'foo.bar[2].foobar'
) - diff: a list of changes that have been applied to the target
- child: a dome that wraps a sub-object/array of an already wrapped target
Properties
dome.target
This is the object or array you wrapped in the dome.
Reading
bool dome.has(string path)
Returns true
if the property at the given path exists, false
otherwise.
mixed dome.get(string path[, mixed fallback])
Returns the value at the given path, or if it doesn't exist the given fallback value. If no value is found and no
fallback value is passed, undefined
will be returned.
Mutating
All types
mixed dome.set(string path, mixed value)
Sets the property at the given path to the given value, and returns this new value.
mixed dome.del(string path)
Deletes the property at the given path, and returns the previous value.
Numbers
number dome.inc(string path[, number amount])
Increments the number property at the given path by the given amount or by 1 if no amount is passed, then returns the new value.
number dome.dec(string path[, number amount])
Decrements the number property at the given path by the given amount or by 1 if no amount is passed, then returns the new value.
Objects and Arrays
array|object dome.clear(string path)
Empties all properties or elements from the object or array at the given path, then returns the object or array reference.
Strings and Arrays
array|string dome.append(string path[, mixed arg1[, mixed arg2[, ...]]])
Appends the given arguments to the array or string at the given path, then returns the new value.
Arrays
array dome.fill(string path, mixed value[, number start[, number end]])
Fills the array at the given path with the given value. You may provide start and end positions for fill to take place. More information at MDN. The full array is returned.
number dome.push(string path[, mixed arg1[, mixed arg2[, ...]]])
Pushes all given values to the end of the array at the given path, then returns the new array length. More information at MDN.
mixed dome.pop(string path)
Pops a value from the end of the array at the given path, then returns it. More information at MDN.
mixed dome.shift(string path)
Removes a value from the beginning of the array at the given path, then returns it. More information at MDN.
mixed dome.unshift(string path[, mixed arg1[, mixed arg2[, ...]]])
Adds all given values to the beginning of the array at the given path, then returns the new length of the array. More information at MDN.
array dome.splice(string path, number start, number deleteCount, [, mixed arg1[, mixed arg2[, ...]]])
Removes deleteCount
items from the array at the given path, starting at index start
. It then inserts all given
values at that position. An array containing all deleted elements is returned (which will be empty if deleteCount
was
0
).
More information at MDN.
array dome.reverse(string path)
Reverses the array at the given path in place, then returns the array. More information at MDN.
array dome.sort(string path)
Sorts the array at the given path in place, then returns the array. At this time, a compare function cannot be provided. More information at MDN.
Synchronization
array dome.extractDiff()
Returns the current diff, and resets the dome's internal diff.
array dome.peekDiff()
Returns the current diff, but does not remove it from the dome. This can be useful when debugging, but should generally not be needed.
bool dome.hasDiff()
Returns true if changes have been made to the target since instantiation or last dome.extractDiff()
.
dome.applyDiff(array diff[, bool silent])
Applies a diff structure to the dome, making all the changes and emitting all events that go with it. If silent
is
true
, events will not be emitted.
Snapshots
dome.snapshot()
Makes a snapshot of the current target and diff. If you ever want to undo changes made, you will be able to roll back to this point in time. You can make as many snapshots as you like, you are not limited to 1.
dome.rollback()
Rolls back to the last snapshot. You can call this method as often as you have called snapshot()
.
Events
"change": string path, mixed newValue, mixed oldValue, object operationData
The value at the given path has changed, and its value has changed from oldValue
to newValue
. The operationData
object has the properties string op
(the operation name, eg: "set"
) and mixed result
(the return value of the
operation).
"change:path": mixed newValue, mixed oldValue, object operationData
Here, path
in "change:path"
is the actual path that changed. This allows you to listen for changes at very specific
locations. The arguments you receive are the same as with the change
event.
"snapshot"
A snapshot was made.
"rollback"
A rollback occurred.
"diff": string opName, string path, array args
A diff entry was added because of a mutation. The operation is described by opName
, the path on which it happened by
path
and the arguments passed to the operation are in the args
array.
Client domes
Dome dome.wrap(string path)
This creates a dome from a path on an existing dome. They will remain connected, so any changes that you make on the child dome will automatically be added to the diff in the parent dome. The child will also keep its own diff state. Changes made on the child dome will also be emitted as change events on the parent.
Other
dome.destroy()
Removes all data and diff references from the dome, as well as all event listeners.
object|array dome.toJSON()
Returns the target object or array so that serializing the dome to JSON is the same as serializing its target to JSON.