@avensio/graph

Documentation · GitHub

@avensio/graph is a TypeScript-first graph toolkit with strongly typed vertices, edges, traversal helpers, and classic graph algorithms that run identically in Node.js and modern browsers. It depends only on two lightweight sibling packages (@avensio/shared for data structures and @avensio/event-emitter for events), so installs stay fast and predictable.

Features

• Directed, undirected, and mixed graphs with density, connectivity, and cycle analytics
• Moore–Bellman–Ford based shortest path, parallel topological sorting, k shortest paths, MST, and component detection
• Extensible vertex/edge classes, comparator injection, and custom event payloads via AGraph
• Serialization hooks plus GraphView/JSONGraphView helpers for persisting or visualizing graph state
• Vertex emitters and a ready-to-use TextEmitter for generating custom reports from graph nodes

Installation

# with pnpm
pnpm add @avensio/graph

# or npm
npm install @avensio/graph

# or yarn
yarn add @avensio/graph

Browser (IIFE or ESM)

<script src="https://unpkg.com/@avensio/graph@1.0.0/dist/graph.iife.js"></script>
<script>
  const { Graph, Vertex, Edge } = graph
  const a = new Vertex({ title: 'A' })
  const b = new Vertex({ title: 'B' })
  const instance = new Graph()
  instance.addVertex(a)
  instance.addVertex(b)
  instance.addEdge(new Edge({ from: a, to: b }))
  console.debug(instance.shortestPath(a, b))
</script>

<script type="module">
  import { Graph, Vertex, Edge } from 'https://unpkg.com/@avensio/graph@latest/dist/graph.es.js'
  const g = new Graph()
  // ...
</script>

Node / Bundlers

import { Graph, Vertex, Edge } from '@avensio/graph'

const graph = new Graph()
const a = graph.createVertex('A')
const b = graph.createVertex('B')
graph.addVertex(a)
graph.addVertex(b)
graph.createEdge(a, b, 'A -> B')

Documentation

The complete online documentation covers the data model, serializers, events, customization, and graph algorithms. Its sources live in the docs/ folder and can be served locally via pnpm run docs:dev.

Matrix Layer

The library includes an optional adjacency- and incidence-matrix layer for workloads where indexed matrix access is preferable to set traversal. Benchmark representative data before enabling it. See docs/matrix-layer.md.

Development & Scripts

• pnpm test – run the Vitest suite with coverage
• pnpm lint – lint and auto-fix the TypeScript sources
• pnpm build – produce ESM, CJS, and IIFE bundles and regenerate declarations
• pnpm docs:dev / pnpm docs:build – develop or build the VitePress docs
• pnpm release – run tests, build artifacts, and generate the changelog

Contributions welcome! Please add/adjust tests that cover new graph behaviors and keep documentation in sync with feature changes.