Graphology: JavaScript Graph Library

Common errors

• TypeError: Graph is not a constructor

  cause Attempting to use `require('graphology')` to import the `Graph` class in an environment that enforces ESM-style imports, or when the package's `package.json` entry points prioritize ESM.
  fix Change the import statement to `import Graph from 'graphology';` for ESM compatibility. If using TypeScript, ensure your `tsconfig.json`'s `module` option is set correctly (e.g., `"ESNext"` or `"NodeNext"`).

• TS2307: Cannot find module 'graphology' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the type definitions for `graphology`.
  fix Install the peer dependency `graphology-types`: `npm install --save-dev graphology-types` or `yarn add -D graphology-types`. Ensure `tsconfig.json` includes `node_modules/@types` in `typeRoots` or that type declaration files are correctly resolved.

• Error: The given graph is not multi.

  cause Attempting to add multiple edges between the same two nodes in a non-multi graph, or other multi-graph specific operations on a simple graph.
  fix When creating the graph, explicitly set the `multi` option to `true`: `new Graph({ multi: true });` if you intend to allow multiple edges between the same nodes.

Warnings

• breaking Graphology v0.26.0 introduced explicit ESM support. Projects using CommonJS `require()` might encounter module resolution errors or unexpected behavior, especially in modern Node.js environments or bundlers. The library primarily targets ESM.
  Fix: Migrate your import statements to ESM syntax (e.g., `import Graph from 'graphology';`). Ensure your `package.json` has `"type": "module"` if you are running in Node.js ESM mode, or configure your bundler appropriately.
• breaking The undocumented methods `#.upgradeToMixed` and `#.upgradeToMulti` were removed in v0.24.0. Code relying on these internal methods will break.
  Fix: If you were using these methods, refactor your graph manipulation logic to explicitly create new graphs with the desired `type` and `multi` options, and copy nodes/edges as needed, or adjust your graph creation strategy.
• breaking As of v0.26.0, `graphology` no longer shims `Array.from`. This means that environments lacking native `Array.from` support (e.g., very old browsers or Node.js versions) will require a polyfill if `graphology`'s internal operations depend on it.
  Fix: Ensure your target environment supports `Array.from`, or include a polyfill (e.g., `core-js`) if targeting older platforms that do not provide this method natively.
• gotcha Internal refactoring of edge & neighbor iteration schemes and index handling in v0.24.0 might lead to subtle behavioral changes or performance differences, especially in complex use cases involving self-loops or multigraphs, although no direct API breaks were documented.
  Fix: Thoroughly test existing graph manipulation and traversal logic when upgrading to v0.24.0 or newer to ensure consistent behavior.

Install

• npm install graphology npm
• yarn add graphology yarn
• pnpm add graphology pnpm

Imports

• Graph
  wrong:

  const Graph = require('graphology');

  correct:

  import Graph from 'graphology';

  Since v0.26.0, graphology fully supports ESM. While CommonJS `require` might still work in some setups, `import` is the recommended and more robust approach. Graph is typically imported as a default export.
• Graph type

  import type Graph from 'graphology';

  For TypeScript projects, you can import the `Graph` type directly using `import type` to avoid bundling issues and ensure type safety.
• Specific graph factory (e.g., DirectedGraph)
  wrong:

  import { DirectedGraph } from 'graphology';

  correct:

  import Graph from 'graphology'; const directedGraph = new Graph({ type: 'directed' });

  Unlike some graph libraries, `graphology` typically uses a single `Graph` class and configuration options (e.g., `type: 'directed'`) to create specific graph instances, rather than separate named exports for each graph type.

Quickstart

This quickstart demonstrates how to create a directed graph, add nodes and edges with custom attributes, and perform basic operations like counting elements and iterating over nodes and edges.

import Graph from 'graphology';

interface NodeAttributes {
  label: string;
}

interface EdgeAttributes {
  weight: number;
}

// Create a new directed graph
const graph = new Graph<NodeAttributes, EdgeAttributes, any>({
  type: 'directed',
  multi: false
});

// Add nodes with attributes
graph.addNode('A', { label: 'Node A' });
graph.addNode('B', { label: 'Node B' });
graph.addNode('C', { label: 'Node C' });

// Add edges with attributes
graph.addEdge('A', 'B', { weight: 1 });
graph.addEdge('B', 'C', { weight: 2 });
graph.addEdge('C', 'A', { weight: 3 });

// Check graph properties
console.log(`Number of nodes: ${graph.order}`);
console.log(`Number of edges: ${graph.size}`);

// Iterate over nodes and their attributes
console.log('Nodes:');
graph.forEachNode((node, attributes) => {
  console.log(`- ${node} (Label: ${attributes.label})`);
});

// Iterate over edges and their attributes
console.log('Edges:');
graph.forEachEdge((edge, attributes, source, target) => {
  console.log(`- ${source} -> ${target} (Weight: ${attributes.weight})`);
});

// Get neighbors of a node
const neighborsOfB = graph.neighbors('B');
console.log(`Neighbors of B: ${neighborsOfB.join(', ')}`);

// Check if node exists
console.log(`Does node 'D' exist? ${graph.hasNode('D')}`);