/**
42 | * @module graph-crdt.Graph
43 | */
44 |
45 | import Emitter from 'eventemitter3';
46 | import Node from '../Node';
47 |
48 | const nodes = Symbol('graph node container');
49 |
50 | /**
51 | * Container and interface for groups of nodes.
52 | *
53 | * @class Graph
54 | */
55 | export default class Graph extends Emitter {
56 |
57 | /**
58 | * Instantiates a graph without needing `new`.
59 | *
60 | * @returns {Graph} - A graph instance.
61 | */
62 | static create () {
63 | return new Graph();
64 | }
65 |
66 | /**
67 | * Imports a format compliant graph into a new one. It expects
68 | * nested nodes to use the node metadata format. Useful for
69 | * sending and importing graphs over the network.
70 | *
71 | * @param {Object} object - The raw graph object.
72 | * @returns {Graph} - A new graph instance that consumes
73 | * the imported data.
74 | */
75 | static source (object) {
76 |
77 | // Create a new graph
78 | const graph = Graph.create();
79 |
80 | // For each node...
81 | Object.keys(object).forEach((key) => {
82 |
83 | let node = object[key];
84 |
85 | // Make sure it's a node.
86 | if (!(node instanceof Node)) {
87 | node = Node.source(node);
88 | }
89 |
90 | // Get it's unique ID.
91 | const { uid } = node.meta();
92 |
93 | // Add it to the new graph.
94 | graph[nodes][uid] = node;
95 | });
96 |
97 | return graph;
98 | }
99 |
100 | constructor () {
101 | super();
102 |
103 | this[nodes] = {};
104 | }
105 |
106 | /**
107 | * Return the unmodified value of a node lookup.
108 | *
109 | * @param {String} key - The name/uid of the node.
110 | * @returns {Node|null} - The node if found, otherwise `null`.
111 | */
112 | value (key) {
113 | return this[nodes][key] || null;
114 | }
115 |
116 | new () {
117 | return new Graph();
118 | }
119 |
120 | /**
121 | * Replays all the changes in the graph as though they occurred
122 | * after the events in the target graph.
123 | * @param {Graph} target - Preceding state.
124 | * @return {Graph} - A new graph containing the rebased nodes.
125 | */
126 | rebase (target) {
127 | const rebased = this.new();
128 |
129 | rebased.merge(target);
130 | rebased.merge(this);
131 |
132 | for (const [id] of this) {
133 | const existing = target.value(id);
134 |
135 | if (existing) {
136 | rebased[nodes][id] = this.value(id).rebase(existing);
137 | }
138 | }
139 |
140 | return rebased;
141 | }
142 |
143 | /**
144 | * Figures out what fields are common to both graphs.
145 | * @param {Graph} target - Any other graph.
146 | * @return {Graph} - The shared properties between both graphs.
147 | */
148 | overlap (target) {
149 | const shared = this.new();
150 |
151 | for (const [key] of this) {
152 | if (this.value(key) && target.value(key)) {
153 |
154 | // Calculate the node overlap.
155 | const nodeSource = this.value(key);
156 | const nodeTarget = target.value(key);
157 | const overlap = nodeSource.overlap(nodeTarget);
158 |
159 | // Merge it into the new graph.
160 | shared.merge({ [key]: overlap });
161 | }
162 | }
163 |
164 | return shared;
165 | }
166 |
167 | /**
168 | * Merge one graph with another (graph union operation).
169 | *
170 | * @param {Object} graph - The graph to merge with.
171 | * Items must be enumerable, and cannot be inherited from prototypes.
172 | * @returns {Graph} - The `this` context.
173 | */
174 | merge (graph) {
175 |
176 | /** Ensure it's a graph. */
177 | if (!(graph instanceof Graph)) {
178 | graph = Graph.source(graph);
179 | }
180 |
181 | const changes = {
182 | update: this.new(),
183 | history: this.new(),
184 | };
185 |
186 | for (const [uid, node] of graph) {
187 | let target = this.value(uid);
188 |
189 | if (!target) {
190 | target = this[nodes][uid] = node.new();
191 | }
192 |
193 | const { update, history } = target.merge(node);
194 |
195 | changes.update[nodes][uid] = update;
196 | changes.history[nodes][uid] = history;
197 | }
198 |
199 | this.emit('update', changes.update);
200 | this.emit('history', changes.history);
201 |
202 | return changes;
203 | }
204 |
205 | /**
206 | * Iterates over every node in the graph.
207 | * @return {Array} - Every yielded value is a key/value pair.
208 | */
209 | * [Symbol.iterator] () {
210 | const object = this[nodes];
211 |
212 | for (const key in object) {
213 | if (object.hasOwnProperty(key)) {
214 | const value = this.value(key);
215 | yield [key, value];
216 | }
217 | }
218 | }
219 |
220 | /* Coercion interfaces */
221 |
222 | /**
223 | * Used to serialize a graph (JSON.stringify calls this method).
224 | *
225 | * @private
226 | * @returns {Object} - The hidden collection of nodes.
227 | */
228 | toJSON () {
229 | return this[nodes];
230 | }
231 |
232 | }
233 | Distributed Graph Engine
52 |54 |graph-crdt is a work in progress with frequent breaking changes.
53 |
Designed for serializing arbitrary data structures, making offline edits, and seamlessly merging changes back in. All data is observable and event driven.
55 |What for?
This graph library aims to ease the complexity of synchronizing complex and interconnected state between peers, without assuming centralized authority.
56 |How does it work?
Truly offline systems cannot rely on any form of collaboration. They must (at some point) assume the editor is in complete isolation, such as a smartphone that lost cell service, or a server who's network is unreachable.
57 |You have a few options:
58 |-
59 |
Block writes
61 |
60 | Probably the worst experience, block all writes until the network heals. This is essentially the same as losing socket connection to your database (Rethink, Neo4j, Redis, MySQL, etc.)
62 | Defer the updates
64 |
63 | You allow writes on the offline machine, wait for the network to heal, then publish them. If not handled perfectly, you're susceptible to merge hell on an active production environment.
65 | Use a CRDT
67 |
66 | CRDTs (Convergent Replicated Data Types) are similar to the option above, but come with additional guarantees: regardless of the order which updates are received in, every machine will arrive at the exact same result every time, and if implemented correctly, make merge conflicts impossible*.
68 |
70 | *graph-crdt uses Lamport time to track state mutation and resolves concurrent edit conflicts using a deterministic sorting algorithm.
71 |
This library opts for the latter, implementing a delta graph CvRDT. However, as great as they may seem, there are some cons (some specific to this library):
73 |-
74 |
You need more data.
76 |
75 | Merges need a state integer on each field.
77 | There is no "true" delete.
79 |
78 | You can remove the value, but some metadata has to stay around.
80 | It only plays nice with other CRDTs.
82 |
81 | To merge two states, both must have the CRDT metadata (though this library allows you to upgrade nearly any data).
83 |
Features
-
85 |
- Commutative, idempotent, conflict-resolved
Nodeunions.
86 | - Delta emission on
NodeandGraphunions.
87 | - Time travel (track and selectively apply deltas). 88 |
Documentation
All the API docs can be found here.
90 |Roadmap
-
91 |
- Node field tombstones. 92 |
- Graph member tombstones. 93 |
- Custom conflict resolvers. 94 |
- A new data structure (this one is a surprise). 95 |
Disclaimer
Although I have working experience with decentralized systems (at GunDB), I'm still a n00b. This library is my best understanding of CvRDTs and how they operate. I'm open to most suggestions.