Transparent object mirroring across process boundaries, with change monitoring
Install with npm
npm i --save facsimile
Before you begin:
const Facsimile = require('facsimile');
Create an empty instance of a facsimile node. Hostname is used for data conflict resolution, it may be any value type (string preferably), but types should not be mixed across your network
A monitored object used to manage your state. It can be accessed like any other object
Tells the instance to flush it's state, and request syncronization data from the network
Request exclusive write permissions to an object, promise will not resolve until the lock has been established
NOTE: You must pass an object returned from the Facsimile.state collection
Request exclusive write permissions to an object, promise will return a failure if the lock has already been established.
NOTE: You must pass an object returned from the Facsimile.state collection
Release lock on object, will throw an error if the object is not owned by host node.
NOTE: You must pass an object returned from the Facsimile.state collection
This function must be overloaded as a part of setting up a communications pipeline. For every
call made to this, a similar call to Facsimile.receive
must be made in the same order as they
were dispatched
Receive syncronization data from an external Facsimile instance
A node has redefined the global scope object
Creates a listener that will fire any time all known lazy references have been resolved.
IE: when a .sync()
command has completed.
An instance contained inside of the Facsimile store has changed
NOTE: Property may be undefined if mass object change occured
Facsimile.store.*.on([property:string], cb:function(target:object, property:string, [new:*], [old:*]))
Monitor changes on a reference type in a Facsimile.store
. Can only be attached to
reference types, and will not monitor changes in contained objects.
NOTE: Property may be undefined if mass object change occured
Destroy an event listener created with Facsimile.store.*.on
Facsimile instances do not natively support any signalling between the various modules. You must supply a tunnel between the instances, and all messages sent from one node must be sent to all other nodes in the system.
Caveats:
- Messages sent from a node must be relayed in order.
- How messages are interleaved between multiple nodes does not matter
- Messages are committed in 'Last Written' priority
- If the system cannot determine who wrote last, the host with the highest 'hostname' wins
const Facsimile = require('..');
class Network {
constructor () {
this._nodes = [];
}
add (source) {
this._nodes.push(source);
source.send = (message, payload) => this.send(source, message, payload);
}
send (source, message, payload) {
for (let target of this._nodes) {
if (target === source) continue ;
console.log(source._hostname, message, payload);
target.receive(message, payload);
}
}
}
const network = new Network();
// Create our host network
const a = new Facsimile("host");
network.add(a);
a.store = { elements: [1, 2, 3] };
a.store.elements.on(0, (target, property, new_value) => {
console.log(`Index[0] = ${new_value}`);
});
a.store.elements.on((target, property, new_value) => {
console.log(`Index[${property}] = ${new_value}`);
});
// Create a subnode, and syncronize them
const b = new Facsimile("client");
network.add(b);
b.on('root_changed', () => {
console.log("Root element has changed.");
});
async function arrayFunctions() {
const array = b.store.elements;
console.log("Locking")
await b.lock(array);
console.log("Locked");
console.log("Trying to create a dead lock");
try {
await a.request(a.store.elements);
} catch (e) {
console.log("Intentional error:", e);
}
b.store.elements[0] = 999;
b.store.elements[1] = 888;
b.store.elements.unshift(4);
b.store.elements.sort((a, b) => (a - b));
console.log("Unlocking");
b.release(array);
}
b.on('ready', () => {
console.log("elements =", b.store.elements);
arrayFunctions()
});
b.sync();