falcor-json-graph

falcor-json-graph is a small JavaScript library from Netflix that provides factory functions for constructing JSON Graph values. It is a companion utility to Falcor, Netflix's data-fetching framework, and it encodes the primitive value types that make up the format:format:falcor-json-graph. Rather than defining a new wire protocol, the package exists to build the "sentinel" objects that Falcor's model exchanges, so applications and servers can emit well-formed JSON Graph without hand-writing the tagged object literals.

JSON Graph itself addresses a structural mismatch: plain JSON models trees, but application data is usually a graph, so serializing it naively duplicates entities and risks stale, inconsistent copies. JSON Graph keeps each entity at a single canonical "identity path" and replaces every other occurrence with a reference. The library's factory functions produce exactly these tagged values: ref(path) yields { $type: "ref", value: [...] } (a symbolic-link-like pointer used to deduplicate and to model graph edges), atom(value) yields { $type: "atom", value } to box an object or array so the model treats it as an opaque, retrieved-in-entirety leaf, and undefinedAtom, error, pathValue, and pathInvalidation cover missing values, error propagation, path-value pairs, and cache invalidation respectively. Clients then read the graph through paths such as ['todos', 0, 'name'], and the model transparently follows refs during traversal.

In the graph-data and format-conversion landscape, falcor-json-graph occupies a niche distinct from analysis-oriented toolkits like tool:networkx, tool:igraph, or tool:graph-tool and from property-graph databases such as tool:neo4j. It is not a graph-algorithm engine; it is a serialization vocabulary for reference-linked, path-addressable JSON, closer in spirit to node-link JSON conventions like format:networkx-node-link or format:pg-json, but oriented toward incremental client-server data fetching rather than whole-graph interchange.

Its strengths are simplicity, tiny footprint, and a clean model for deduplicating linked data over REST-like APIs. The limitations are equally clear: it is only meaningful inside the Falcor ecosystem, which Netflix has largely stopped actively developing in favor of GraphQL; keys must be strings or integers and access is strictly path-based; the graph is rooted and directed via refs rather than a symmetric edge model; and the package alone does no fetching, caching, or algorithmic work.