@graphora/analytics

Purpose:

• optional graph analysis helpers for visual exploration workflows

Depends on:

• @graphora/core

Public entrypoint:

• @graphora/analytics

Included helpers:

• deterministic degree metrics
• weakly connected components
• breadth-first traversal
• unweighted shortest path
• bounded neighborhood traversal with hop distances and exact parent-edge paths

Use these helpers with public GraphSnapshot values from @graphora/core. Results are plain node IDs or metrics that applications can feed into styling, sizing, highlighting, path tracing, labels, or examples.

Examples:

• examples/vanilla/bounded-traversal/: direction, hop/result limits, path table and Canvas highlights with explicit partial-result explanations

Non-goals:

• renderer, engine, interaction, React, or Graphology dependencies
• weighted shortest paths
• centrality, PageRank, or community detection
• Cytoscape.js-style algorithm breadth
• worker execution or benchmark harnesses

Bounded Neighborhoods

import { traverseNeighborhood, getTraversalPath } from '@graphora/analytics'

const result = traverseNeighborhood(snapshot, 'api', {
  direction: 'out',
  maxDepth: 2,
  maxNodes: 100,
  maxEdgeVisits: 10000
})
const route = getTraversalPath(result, 'database')
Copy

visits are immutable BFS records containing nodeId, depth, parentNodeId and parentEdgeId. Root parent fields are null. Results preserve stored IDs, while root/target lookup normalizes numeric/string aliases. Missing roots yield an empty result; absent path targets return null. Parent-edge selection follows snapshot edge order, including parallel edges.

Defaults are outgoing traversal, two hops, 1000 nodes including the root, and 10000 inspected adjacency entries. in finds predecessors; both combines orientations. Undirected edges are bidirectional in every mode, as in existing analytics, unlike core's endpoint-oriented collection selectors. Self-loops count as one work entry and never rediscover nodes. Invalid limits/direction throw GraphError with INVALID_GRAPH.

Always inspect truncated / limitReasons (depth, nodes, edges). Exact-fit complete results are distinguished from actual depth/node omissions and work exhaustion. Work-limited output is not certified as a complete traversal even if it already contains every reachable node. The helper is iterative and stores a parent forest; paths are reconstructed on demand, not eagerly for every visit. Building adjacency still requires O(V + E) time and space over the entire supplied snapshot. Limits apply to result size and the subsequent walk, not elapsed time.

The caller chooses source or visible topology and recomputes when that snapshot changes. graphVersion is diagnostic, not an engine view freshness token. No source mutations or automatic subscriptions occur. Read the analytics guide for limits and integration details.