Data Model & Lifecycle

This guide explains how the Graph, Vertex, and Edge classes structure their data, which properties are derived, and when to recompute metadata via infer().

GraphProperties

When instantiating new Graph(props, comparator), you can pass the following optional fields:

Property	Type	Default	Notes
uuid	string	crypto.randomUUID()	Acts as the canonical identifier when serializing.
title	string	'new graph'	Convenience label for UIs.
vertices	Set<IVertex<T>>	new Set()	Pre-populate the graph; remember to call infer() afterwards.
edges	Set<IEdge<T>>	new Set()	When seeding edges manually ensure the source/target vertices exist in the set.
directed	boolean	false	Derived by isDirected(); mirrors whether any edge is marked directed.
mixed	boolean	false	True when both directed and undirected edges are present.
connected	boolean	false	Updated by isConnected().
connectedComponentsCount	number	0	Populated by connectedComponents().
strongConnectedComponentsCount	number	0	Populated by strongConnectedComponents().
cycleCount	number	0	Updated by inferCycles().
hasCycles	boolean	false	Updated by checkForCycles().
hasNegativeCycles	boolean	false	Updated by checkForNegativeCycles().

VertexProperties

Vertices encapsulate metadata attached to each node:

Property	Type	Default
uuid	string	crypto.randomUUID()
title	string	'new vertex'
point	Point	undefined
incomingEdges	Set<IEdge<T>>	new Set()
outgoingEdges	Set<IEdge<T>>	new Set()
type	string	undefined
data	T	undefined

Helper methods such as deg(), indeg(), outdeg(), getNeighbours(), and getEdgeTo() reflect these sets and stay in sync as edges are added/removed.

EdgeProperties

Edges capture relationships between two vertices:

Property	Type	Default
uuid	string	crypto.randomUUID()
title	string	'new edge'
from / to	IVertex<T>	required
directed	boolean	true
weight	number	0
type	string	undefined
data	Record<string, any>	undefined

Calling graph.createEdge(a, b, title, directed, weight) ensures edge instances automatically register with the involved vertices. If you instantiate new Edge({ from: a, to: b }) directly, remember to call graph.addEdge(edge) so graph-level events fire.

Lifecycle & infer()

• The constructor invokes infer() once to initialize derived flags (directed, mixed, hasCycles, etc.).
• After bulk mutations (batch edge inserts, manual vertex manipulation) call graph.infer() to recompute isDirected() and checkForCycles().
• Methods like isConnected() and connectedComponents() recompute their respective caches on demand; store the return value if you need the result later.

When to call what

Scenario	Recommended call
Added/removed many vertices or edges manually	graph.infer()
Need to know density classification	graph.density() followed by isDense(threshold)
Need connectivity metadata	graph.connectedComponents(); the method updates connectedComponentsCount.
Detect negative cycles after weight changes	graph.checkForNegativeCycles()

Remember that undirected edges are stored internally as two directed edges (forward + reverse). Keep this in mind when interpreting size() or iterating over graph.edges.