# @rimbu/graph > Immutable Graph data structures for TypeScript Latest version **2.0.11** (published 2026-01-20) · MIT license · 0 weekly downloads ## Install ```sh npm install @rimbu/graph pnpm add @rimbu/graph yarn add @rimbu/graph bun add @rimbu/graph ``` ## Health **Score 70/100 (B)** — status: stable. Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.0.11 | | Published | 2026-01-20 | | First published | 2021-06-06 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 7 | | Unpacked size | 834.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 144 | | Author | Arvid Nicolaas | | Maintainers | vitoke | | Keywords | graph, edge, directed, undirected, vertex, vertices, weighted, nodes, traverse, immutable, collection, rimbu, typescript | ## Links - npm: https://www.npmjs.com/package/@rimbu/graph - Repository: https://github.com/rimbu-org/rimbu - Homepage: https://rimbu.org - Issues: https://github.com/rimbu-org/rimbu/issues - Funding: https://github.com/sponsors/vitoke - npm.io page: https://npm.io/package/@rimbu/graph ## Dependencies (7) - [tslib](https://npm.io/package/tslib.md) ^2.8.1 - [@rimbu/base](https://npm.io/package/@rimbu/base.md) ^2.0.7 - [@rimbu/common](https://npm.io/package/@rimbu/common.md) ^2.0.7 - [@rimbu/hashed](https://npm.io/package/@rimbu/hashed.md) ^2.1.10 - [@rimbu/sorted](https://npm.io/package/@rimbu/sorted.md) ^2.1.10 - [@rimbu/stream](https://npm.io/package/@rimbu/stream.md) ^3.0.3 - [@rimbu/collection-types](https://npm.io/package/@rimbu/collection-types.md) ^2.1.10 ## Alternatives - [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads - [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads - [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads - [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads - [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads ## Recent versions - 2.0.11 (latest) — 2026-01-20 - 2.0.8 — 2026-01-15 - 2.0.7 — 2025-11-28 - 2.0.6 — 2025-11-25 - 2.0.5 — 2025-11-23 - 2.0.4 — 2025-05-16 - 2.0.3 — 2024-06-28 - 2.0.2 — 2024-03-05 - 2.0.1 — 2024-02-14 - 2.0.0 — 2024-01-26 - 1.1.1 — 2023-12-09 - 1.1.0 — 2023-07-29 - 1.0.0 — 2023-07-03 - 1.0.0-alpha.2 — 2023-07-02 - 1.0.0-alpha.1 — 2023-07-02 - … 67 more at https://npm.io/package/@rimbu/graph/versions ## README

Rimbu Logo

[![npm version](https://badge.fury.io/js/@rimbu%2Fgraph.svg)](https://www.npmjs.com/package/@rimbu/graph) ![License](https://img.shields.io/github/license/rimbu-org/rimbu) ![Types Included](https://img.shields.io/badge/TypeScript-ready-blue) ![Node](https://img.shields.io/badge/Node-18+-6DA55F?logo=node.js&logoColor=white) ![Bun](https://img.shields.io/badge/Bun-%23000000.svg) ![ESM + CJS](https://img.shields.io/badge/modules-ESM%20%2B%20CJS-informational)
# `@rimbu/graph` **Fast, immutable graph data structures for TypeScript & JavaScript.** `@rimbu/graph` provides a rich family of **directed** and **undirected** graph implementations, with optional **edge values**, and both **hashed** and **sorted** internal representations. All graphs are **immutable & persistent**, giving you predictable behaviour and structural sharing while still feeling ergonomic to use. Use it whenever you need to model **networks, dependencies, state machines, hierarchical links, or arbitrary relationships** between entities. --- ## Table of Contents 1. [Why `@rimbu/graph`?](#why-rimbu-graph) 2. [Feature Highlights](#feature-highlights) 3. [Quick Start](#quick-start) 4. [Core Concepts & Types](#core-concepts--types) 5. [Directed vs Undirected Graphs](#directed-vs-undirected-graphs) 6. [Valued Graphs](#valued-graphs) 7. [Traversal Helpers (`Traverse`)](#traversal-helpers-traverse) 8. [Performance Notes](#performance-notes) 9. [Installation](#installation) 10. [FAQ](#faq) 11. [Ecosystem & Integration](#ecosystem--integration) 12. [Contributing](#contributing) 13. [License](#license) --- ## Why `@rimbu/graph`? Graphs are everywhere: - **Domain models** – users ↔ groups, services ↔ dependencies, resources ↔ references. - **Algorithms** – path finding, reachability, connectivity, topological ordering. - **Config & state** – workflows, finite state machines, dependency graphs. `@rimbu/graph` focuses on: - **Clear semantics** – separate types for **directed** (`ArrowGraph`) and **undirected** (`EdgeGraph`) graphs. - **Valued edges** – attach weights, metadata, or labels via valued graphs (e.g. `ArrowValuedGraphHashed`). - **Immutable operations** – updates always return new instances, sharing structure internally. - **Strong typing** – generics for node and value types, plus non‑empty refinements. - **Consistent API** – graph families share common operations and higher‑kinded `Context` / `Builder` types. --- ## Feature Highlights - **Directed & undirected graphs** – choose between arrow (directed) and edge (undirected) graphs. - **Valued edges** – store extra data per connection (weights, labels, costs, metadata). - **Hashed & sorted variants** – pick between hashed (`*Hashed`) or sorted (`*Sorted`) internal collections. - **Immutable & persistent** – safe sharing across components, snapshots, and undo/redo flows. - **Context & builders** – use `Context` and `Builder` types for efficient, batched updates. - **Traversal utilities** – breadth‑first and depth‑first traversal helpers via the exported `Traverse` namespace. Try Rimbu (including `@rimbu/graph`) live in the browser using the [Rimbu Sandbox on CodeSandbox](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts). --- ## Quick Start ### Basic undirected graph ```ts import { EdgeGraphHashed } from '@rimbu/graph'; // Create from node/connection tuples const g = EdgeGraphHashed.of( [1, 2], [2, 3], [3, 4], [5] // isolated node ); g.hasNode(2); // true g.hasConnection(1, 2); // true // Get all connections from a node as a nested map const neighbors = g.getConnectionsFrom(2); console.log(neighbors.toArray()); // e.g. [[1], [3]] // Iterate graph elements as a stream g.stream().toArray(); // => [[1, 2], [2, 3], [3, 4], [5]] ``` ### Basic directed graph ```ts import { ArrowGraphHashed } from '@rimbu/graph'; const g = ArrowGraphHashed.of([1, 2], [2, 3], [3, 1]); g.hasConnection(1, 2); // true g.hasConnection(2, 1); // false g.getConnectionsFrom(1).toArray(); // => [[2]] ``` ### Valued graph (weighted edges) ```ts import { ArrowValuedGraphHashed } from '@rimbu/graph'; // [from, to, weight] const wg = ArrowValuedGraphHashed.of([1, 2, 5], [2, 3, 3]); wg.getValue(1, 2); // 5 wg.stream().toArray(); // => [[1, 2, 5], [2, 3, 3]] ``` --- ## Core Concepts & Types The main public surface of `@rimbu/graph` is exported from `src/main/index.mts`. ### Common graph interfaces | Name | Description | | ----------------------- | ---------------------------------------------------------------------------------------- | | `Graph` | Type‑invariant immutable graph interface. | | `Graph.NonEmpty` | Non‑empty refinement of `Graph` with a non‑empty `stream` of graph elements. | | `Graph.Context` | Factory/context for creating `Graph` instances and builders for an upper node type `UN`. | | `VariantGraph` | Type‑variant graph interface with covariant node type. | | `VariantGraph.NonEmpty` | Non‑empty refinement of `VariantGraph` with a non‑empty stream of graph elements. | ### Directed (arrow) graphs | Name | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | `ArrowGraph` | Type‑invariant **directed** graph. | | `ArrowGraph.NonEmpty` | Non‑empty directed graph; `stream()` yields either `[N]` (isolated node) or `[from, to]` connections. | | `ArrowGraph.Context` | Context for `ArrowGraph` instances (generic over an upper node type `UN`). | | `ArrowGraph.Builder` | Mutable builder for efficiently constructing or mutating an `ArrowGraph` before freezing it. | | `ArrowGraphHashed` | Directed graph whose connections are internally stored in hashed collections. | | `ArrowGraphSorted` | Directed graph whose connections are internally stored in sorted collections. | Each of the hashed/sorted variants has its own `NonEmpty`, `Builder`, and `Context` types, such as: - `ArrowGraphHashed.NonEmpty` - `ArrowGraphHashed.Context` - `ArrowGraphSorted.NonEmpty` - `ArrowGraphSorted.Context` ### Undirected (edge) graphs | Name | Description | | ----------------------- | ------------------------------------------------------------------------------- | | `EdgeGraph` | Type‑invariant **undirected** graph. | | `EdgeGraph.NonEmpty` | Non‑empty undirected graph; `stream()` yields `[N]` or `[N, N]` graph elements. | | `EdgeGraph.Context` | Context for `EdgeGraph` instances. | | `EdgeGraph.Builder` | Mutable builder for `EdgeGraph`. | | `EdgeGraphHashed` | Undirected graph backed by hashed collections. | | `EdgeGraphSorted` | Undirected graph backed by sorted collections. | Again, hashed/sorted variants include corresponding `NonEmpty`, `Builder`, and `Context` types. --- ## Directed vs Undirected Graphs - **Arrow graphs** (`ArrowGraph*`) represent **directed** edges. A connection `[1, 2]` means “an edge from `1` to `2`”, but not necessarily from `2` to `1`. - **Edge graphs** (`EdgeGraph*`) represent **undirected** edges. A connection `[1, 2]` is symmetric: `hasConnection(1, 2)` and `hasConnection(2, 1)` both hold. All graph variants share core APIs, such as: ```ts g.hasNode(node); g.hasConnection(node1, node2); g.getConnectionsFrom(node); // returns a map / set of neighbors g.stream(); // stream of graph elements ``` Use `*Hashed` variants when you care about fast hashed lookups, and `*Sorted` variants when you want deterministic, ordered traversal. --- ## Valued Graphs Valued graphs let you store an extra value per edge (weight, label, capacity, etc.). ### Generic valued interfaces | Name | Description | | ----------------------------- | ------------------------------------------------------------------------------ | | `ValuedGraph` | Type‑invariant graph where each connection has a value of type `V`. | | `ValuedGraph.NonEmpty` | Non‑empty valued graph; `stream()` yields `ValuedGraphElement` elements. | | `VariantValuedGraph` | Type‑variant valued graph. | | `VariantValuedGraph.NonEmpty` | Non‑empty variant valued graph. | ### Concrete valued graph families | Name | Description | | ------------------------------ | --------------------------------------------------------- | | `ArrowValuedGraph` | Directed valued graph interface. | | `ArrowValuedGraphHashed` | Directed valued graph backed by `HashMap` structures. | | `ArrowValuedGraphSorted` | Directed valued graph backed by `SortedMap` structures. | | `EdgeValuedGraph` | Undirected valued graph interface. | | `EdgeValuedGraphHashed` | Undirected valued graph backed by `HashMap` structures. | | `EdgeValuedGraphSorted` | Undirected valued graph backed by `SortedMap` structures. | Each of these has matching `NonEmpty`, `Builder`, and `Context` types, and exposes a `stream()` that yields **graph elements**: - Isolated node: `[node]` - Valued connection: `[from, to, value]` ```ts import { EdgeValuedGraphHashed } from '@rimbu/graph'; const g = EdgeValuedGraphHashed.of([1, 2, 'a'], [2, 3, 'b']); g.getValue(1, 2); // 'a' g.stream().toArray(); // => [[1, 2, 'a'], [2, 3, 'b']] ``` --- ## Traversal Helpers (`Traverse`) The main index exports a `Traverse` namespace that groups traversal utilities: ```ts import { Traverse, EdgeGraphHashed } from '@rimbu/graph'; const g = EdgeGraphHashed.of([1, 2], [2, 3], [1, 3], [3, 4]); // Breadth‑first traversal const bfs = Traverse.traverseBreadthFirstHashed(g, 1); console.log(bfs.toArray()); // => [[1, 2], [1, 3], [2, 3], [3, 4]] // Depth‑first traversal const dfs = Traverse.traverseDepthFirstHashed(g, 1); console.log(dfs.toArray()); // => [[1, 2], [2, 3], [1, 3], [3, 4]] ``` Available helpers include: - `traverseBreadthFirstCustom` - `traverseBreadthFirstHashed` - `traverseBreadthFirstSorted` - `traverseDepthFirstCustom` - `traverseDepthFirstHashed` - `traverseDepthFirstSorted` All of them work with any non‑empty `VariantGraphBase`‑compatible graph from this package. --- ## Performance Notes - Graphs in Rimbu are built on **persistent data structures** – updates are typically \\(O(\log n)\\) and share most of their structure. - Hashed vs sorted variants differ mainly in the underlying maps/sets (`HashMap` / `HashSet` vs `SortedMap` / `SortedSet`). - Many operations accept generic `StreamSource` inputs (from `@rimbu/stream`), allowing efficient construction and transformation from arrays, iterables, or streams. For more details, see the main Rimbu documentation at [rimbu.org](https://rimbu.org). --- ## Installation ### Node / Bun / npm / Yarn ```sh npm install @rimbu/graph # or yarn add @rimbu/graph # or bun add @rimbu/graph # or deno add npm:@rimbu/graph ``` Then: ```ts import { EdgeGraphHashed } from '@rimbu/graph/mod.ts'; ``` ### Browser / ESM `@rimbu/graph` ships both **ESM** and **CJS** builds. Use it with any modern bundler (Vite, Webpack, esbuild, Bun, etc.) or directly in Node ESM projects. --- ## FAQ **Q: What is the difference between `Graph`, `ArrowGraph`, and `EdgeGraph`?** `Graph` and `VariantGraph` are general graph interfaces, while `ArrowGraph*` and `EdgeGraph*` are concrete families for directed and undirected graphs, respectively, with hashed/sorted variants and context/builder support. **Q: When should I use valued graphs?** Whenever edges carry additional information (weights, labels, capacities, timestamps, etc.), use `ArrowValuedGraph*` or `EdgeValuedGraph*` to keep that data close to the topology. **Q: Are these graphs mutable?** No. All operations return new graph instances; existing ones remain unchanged and can be freely shared. **Q: Can I build graphs incrementally?** Yes. Use the `Builder` types (e.g. `ArrowGraphHashed.Builder`, `EdgeValuedGraphSorted.Builder`) exposed via their `Context` or via helpers like `toBuilder()`. --- ## Ecosystem & Integration - Part of the broader **Rimbu** collection ecosystem – interoperates with `@rimbu/hashed`, `@rimbu/sorted`, `@rimbu/collection-types`, and `@rimbu/stream`. - Well‑suited for domain modelling, compilers/interpreters, schedulers, routing, and more. - Works seamlessly with Rimbu streams and other collections for building rich, immutable data models. Explore more at the [Rimbu Graph docs](https://rimbu.org/docs/collections/graph) and the [Graph API reference](https://rimbu.org/api/rimbu/graph). --- ## Contributing We welcome contributions! See the [Contributing guide](https://github.com/rimbu-org/rimbu/blob/main/CONTRIBUTING.md) for details. Contributors _Made with [contributors-img](https://contrib.rocks)._ --- ## License MIT © Rimbu contributors. See [LICENSE](./LICENSE) for details. --- _Source: https://npm.io/package/@rimbu/graph · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._