Skip to content

TypeScript SDK & HTTP Interface

API & SDK Reference

Detailed specifications for classes, methods, query pipelines, wire protocols, and REST endpoints.

Embedded Engine

Core TypeScript API

VaagaiGraph.open(options: GraphOpenOptions): Promise<VaagaiGraph>

Factory method to initialize and open a graph instance with pluggable storage and replay active WAL records. 

const graph = await VaagaiGraph.open({
  storage: new FileSystemStorage('./data/graph'),
  snapshotKey: 'graph.json',
  persistenceMode: 'wal', // 'wal' | 'segmented' | 'snapshot'
  autoPersist: true,
});

graph.upsertNode(node: Node): Node

Inserts or updates a node. O(1) in-memory write with synchronous WAL append. 

graph.upsertNode({ id: 'u1', labels: ['User'], props: { name: 'Alice', age: 30 } });

graph.upsertEdge(edge: Edge): Edge

Creates or updates a directed edge with optional weight and properties. 

graph.upsertEdge({ id: 'e1', from: 'u1', to: 'u2', type: 'KNOWS', weight: 1.0 });

graph.query(): TraversalBuilder

Starts a fluent Gremlin-style traversal query pipeline. 

const names = graph.query().nodes().hasId('u1').out('KNOWS').values('name');

graph.match(label?: string): FuzzyMatchQuery

Starts a fluent multi-condition Dynamic Match Threshold query. Pass any custom threshold percentage (e.g. 25%, 50%, 75%, 90% or decimal 0.50). Returns ranked candidate nodes in < 10ms. 

const candidates = graph.match('Candidate')
  .threshold(50) // Dynamic threshold: pass ANY percentage (25, 50, 75, 90...)
  .whereProp('role', 'Engineer', { weight: 1 })
  .whereProp('city', 'Chennai', { weight: 1 })
  .wherePropRange('experienceYears', 4, 10, { weight: 1 })
  .whereEdge('WORKS_AT', { targetLabel: 'VaagaTech', weight: 2 })
  .execute();

Analytics Engine

Built-in Graph Algorithms

GraphAlgorithms.shortestPathBfs(graph, fromId, toId)

Breadth-First Search unweighted shortest path. Returns array of node IDs or null if unreachable.

GraphAlgorithms.shortestPathDijkstra(graph, fromId, toId)

Dijkstra weighted shortest path utilizing edge weights.

GraphAlgorithms.connectedComponents(graph)

Calculates all weakly connected components in the graph for fraud ring and community detection.

GraphAlgorithms.degreeCentrality(graph)

Calculates in/out/total degree centrality metrics for all nodes in O(V) time.

REST Interface

HTTP Endpoints (Port 4000)

GET /health

Health check & node/edge counts.

GET /metrics

Process uptime and memory consumption stats for Prometheus scraping.

POST /nodes

Upsert node: { "id": "u1", "labels": ["User"], "props": {} }

POST /edges

Upsert edge: { "id": "e1", "from": "u1", "to": "u2", "type": "KNOWS" }

POST /query/match

Dynamic Match Threshold Query: Distributed scatter-gather across EKS cluster shards. Evaluates weighted criteria and filters candidates by custom threshold (e.g. 25%, 50%, 75%, 90%). 

{
  "label": "Candidate",
  "threshold": 50,
  "props": { "role": "Architect", "city": "Chennai" },
  "ranges": { "experienceYears": { "min": 5 } },
  "connections": [{ "type": "WORKS_AT", "targetLabel": "VaagaTech", "weight": 2 }]
}
POST /nodes/batch

Fault-tolerant batch ingestion. Corrupted items are safely captured in dead-letter quarantine, while valid records proceed and replicate.

Networking Layer

Multi-Protocol Transports (SDK & Wire)

new VaagaGraphClient(options: VaagaGraphClientOptions)

Connect using HTTP (4000), Binary TCP (4001, default dual protocol), Unix Domain Socket (UDS), or WebSockets (WS): 

import { VaagaGraphClient } from '@vaagatech/vaaga-graph-sdk';

// 1. High-Performance Binary TCP Wire Protocol (Port 4001, sub-2ms latency)
const clientTcp = new VaagaGraphClient({
  protocol: 'tcp',
  tcpHost: '127.0.0.1',
  tcpPort: 4001,
});

// 2. HTTP/REST Gateway (Port 4000, default)
const clientHttp = new VaagaGraphClient({
  protocol: 'http',
  endpoints: ['http://127.0.0.1:4000'],
});

// Identical fluent API across all protocols:
await clientTcp.connect();
const matches = await clientTcp.query().match({
  label: 'Developer',
  threshold: 50, // Dynamic 50% match threshold
  props: { city: 'Chennai', skill: 'TypeScript' },
});