graphology

Graphology provides a single, robust Graph object for representing directed, undirected, or mixed graphs in JavaScript and TypeScript, with optional support for self-loops and parallel (multi) edges — all through one unified API rather than separate classes with divergent interfaces. It ships as a specification with a reference implementation, so alternative implementations (WASM-backed, immutable, etc.) can be built against the same contract and remain interchangeable.

Beyond the core data structure, the graphology ecosystem includes a standard library of graph-theory algorithms and utilities — traversals, shortest paths, generators, metrics, community detection (Louvain, Leiden), layouts (force, ForceAtlas2, noverlap), and serialization to formats like GEXF and GraphML. Graphs emit a rich set of events on every mutation, which is what lets rendering libraries like sigma.js use graphology as a live data backend for interactive network visualizations.

What You Get

• A single Graph class (plus DirectedGraph, UndirectedGraph, MultiGraph, and combinations) covering every common graph topology without switching APIs
• A large standard library of algorithms — traversal, shortest-path, community detection (Louvain, Leiden), metrics, generators, and layouts (force, ForceAtlas2, noverlap)
• An EventEmitter-based graph that fires node/edge add, drop, and attribute-update events, ideal for driving live visualizations
• Serialization/deserialization to and from GEXF, GraphML, and plain JSON, plus import/export helpers for interop with other tools
• First-class TypeScript type declarations via the graphology-types peer dependency

Common Use Cases

• Modeling and querying network/graph data (social graphs, dependency graphs, knowledge graphs) in a browser or Node.js app
• Powering the data layer behind interactive graph visualizations, most notably as the backend for sigma.js
• Running graph-theory algorithms (shortest paths, centrality, community detection) over application data without hand-rolling graph traversal code
• Building custom graph analysis or visualization tools that need a stable, well-specified graph data structure as a foundation

Under The Hood

Architecture

The reference implementation centers on a single Graph class (src/graphology/src/graph.js, ~3000 lines) that composes behavior from focused modules rather than encoding every graph variant as a subclass: attributes/nodes.js and attributes/edges.js attach attribute-access methods, iteration/edges.js, iteration/neighbors.js, and iteration/adjacency.js attach iteration/traversal methods, and serialization.js handles import/export. Graph ‘flavors’ (DirectedGraph, UndirectedGraph, MultiGraph, and their combinations in src/graphology/src/index.js) are thin subclasses that just pin constructor options (type, multi) on the same underlying Graph, so a change to core storage or attribute handling propagates to every flavor automatically. Internally, node and edge records are plain data objects (data.js: MixedNodeData, DirectedNodeData, UndirectedNodeData, EdgeData) indexed in maps for O(1) lookup, and the class extends Node’s EventEmitter so every mutation (addNode, dropEdge, attribute updates) can broadcast an event — this is the seam that lets external renderers like sigma.js treat the graph as a live, observable data source rather than a static structure.

Tech Stack

graphology is authored in ES2015+ JavaScript with optional TypeScript typings distributed via the graphology-types peer dependency, compiled through Babel (@babel/preset-env plus loose-mode class/destructuring/spread transforms) and bundled with Rollup into CommonJS, ESM, and minified UMD builds for browser <script> tag usage. The repo is a Lerna-managed monorepo (lerna.json, "packages": ["src/*"]) with independent versioning, housing the core graphology package alongside dozens of companion packages under src/ — traversal, shortest-path, metrics, generators, layout algorithms (force, ForceAtlas2, noverlap), community detection (Louvain, Leiden), and format converters (GEXF, GraphML, SVG, canvas rendering) — all built against the same graphology-types contract.

Code Quality

Tests are written with Mocha and Chai (chai-roughly-v2 for approximate-equality assertions on numeric/graph output) and run via @babel/register against the test.js entry point covering attributes, events, instantiation, iteration, mutation, properties, read access, and serialization in dedicated spec files. A parallel test-types.ts file is type-checked with tsc under strict null checks as its own CI step, giving the library an explicit contract test for its TypeScript surface, not just its runtime behavior. Linting uses the maintainer’s shared @yomguithereal/eslint-config plus prettier, and GitHub Actions (tests.yml) runs install, lint, and test across five Node.js versions (12 through 20) on every push and pull request, giving good confidence in backward compatibility across the Node LTS range.

What Makes It Unique

Rather than shipping one opinionated graph class, graphology is explicitly framed as a specification with a reference implementation — the same documented contract (traversal semantics, attribute methods, event names) is meant to be reusable across alternative implementations, which is unusual discipline for a JavaScript data-structure library. Its event-emitting design is also a deliberate architectural bet: most graph libraries are static value objects, but graphology’s events are what make it viable as the live backend for an interactive WebGL renderer (sigma.js), and the surrounding standard library of algorithms and layouts extends that same event-driven graph rather than operating on a disconnected copy of the data.