API

This document summarizes the primary entry points exposed by @avensio/graph, explains how to configure the Graph constructor, and links to detailed guides for the surrounding concepts.

Graph constructor & comparator

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

const comparator = (v1: Vertex, v2: Vertex) =>
  v1.uuid === v2.uuid ? 0 : v1.outdeg() < v2.outdeg() ? -1 : 1

const graph = new Graph<unknown>(
  { title: 'custom graph' } satisfies GraphProperties<unknown>,
  comparator
)

• props (GraphProperties<T>): see the data model guide for the full list and defaults.
• comparator: mandatory for algorithms that rely on ordering (DFS, topological sorting, k shortest paths). The comparator must return -1 | 0 | 1 (aka Ordering).

To build domain-specific graphs, extend AGraph and inject your vertex/edge classes:

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

class ConceptVertex extends Vertex<{ id: string }> {
  kind = 'concept'
}

class ConceptEdge extends Edge<{ weight: number }> {}

interface ConceptEvents extends GraphEvents<{ id: string }> {
  'concept:activated': [ConceptVertex]
}

class ConceptGraph extends AGraph<{ id: string }, ConceptVertex, ConceptEdge, ConceptEvents> {
  constructor(props = {}, comparator = (a, b) => a.uuid === b.uuid ? 0 : 1) {
    super(props, comparator, ConceptVertex, ConceptEdge)
  }
}

See the customization guide for a complete walkthrough.

Graph properties (selected)

Method	Returns	Notes
density()	number	Ratio of actual to possible edges; configurable threshold via isDense/isSparse.
order()	number	Count of vertices.
size()	number	Count of edges (undirected edges created with directed=false are stored twice).
isDirected() / isMixed()	boolean	Mixed graphs contain both directed and undirected edges; calling isDirected updates cached flags.
isConnected() / isStronglyConnected()	boolean	Uses DFS to test reachability; strongly connected graphs must be directed.
isTree() / isForest()	boolean	Based on connectedness + acyclicity heuristics.
isDense(threshold?) / isSparse(threshold?)	boolean	Threshold defaults to 0.5.

The data model page documents every property, the lifecycle of infer(), and when to recompute derived values.

Algorithms (high level)

The Graph implements the following algorithms; the deep dive in algorithms covers complexity, prerequisites, and example outputs.

• depthFirstSearch(startVertex, stack?)
• breadthFirstSearch(startVertex)
• shortestPath(from, to) – Moore–Bellman–Ford variant
• kShortestPaths(from, to, k) – Yen-style simple paths
• minimalSpanningTree() – Kruskal/minimum branching
• topologicalSorting() and parallelTopologicalSorting()
• connectedComponents() and strongConnectedComponents()
• checkForCycles() / checkForNegativeCycles() / inferCycles()

Utility helpers

Method	Description
createEdge(from, to, title?, directed?, weight?)	Instantiates an Edge, adds it to both vertices, and inserts it into the graph (undirected edges store a reverse edge).
addEdge(edge) / removeEdge(edge)	Adds/removes an existing edge instance and emits the corresponding graph events.
createVertex(title?, point?, data?)	Creates a vertex of the configured type but does not automatically add it to the graph.
addVertex(vertex) / removeVertex(vertex)	Adds/removes vertices and emits vertex:* events.
c(from, to)	Returns the weight (cost) between two vertices or Infinity if no edge exists.

Serialization & events

• graph.render(format = 'json') / graph.fromFormat(format, data) – see serialization
• graph.registerSerializer(format, serializer) – plug in custom (de-)serializers.
• graph.on('vertex:added', handler) – subscribe to lifecycle hooks described in events.