graphology

library0.26.0jsnpmunverified

Graphology is a comprehensive JavaScript library providing a robust and multipurpose Graph object. It implements a unified specification for various graph types, including directed, undirected, multi, and mixed graphs, making it a versatile tool for network analysis and graph theory applications. The library focuses on performance and memory efficiency, particularly when handling complex multigraph structures. The current stable version is 0.26.0, which introduced explicit ESM support and removed some internal dependencies. Releases are made periodically, incorporating performance enhancements, new features like additional degree methods, and refinements to its internal architecture. It distinguishes itself by offering a well-defined and consistent API for graph manipulation.

data

npm install graphology

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHOLOGY

graphology

datajavascriptv0.26.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Graph

✓ import Graph from 'graphology';

✗ const Graph = require('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)

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

✗ import { DirectedGraph } from 'graphology';

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.

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')}`);

Debug

Known issues

breakingGraphology 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.

affects: >=0.26.0

breakingThe 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.

affects: >=0.24.0

breakingAs 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.

affects: >=0.26.0

gotchaInternal 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.

affects: >=0.24.0

Errors

Common errors & fixes

TypeError: Graph is not a constructor

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.

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.

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.

Upgrade

Version history

0.26.0latest on npm

Audit

Dependencies

graphology-typesrequiredProvides TypeScript type definitions for graphology. This is a peer dependency, so it must be installed alongside graphology if TypeScript is used.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/graphology/graphology ↗

packagehttps://www.npmjs.com/package/graphology ↗

homepagehttps://graphology.github.io ↗