IsonGraph 1.0.0

<p align="center"> <img src="../assets/github_logo_stretched.png" alt="ISONGraph Logo"> </p>

ison-graph-cs

ISONGraph - A token-efficient property graph store with ISON persistence for C# / .NET 8.

Features

• Property Graph Model: Nodes and edges with string properties
• O(1) Lookups: Fast node access by (type, id)
• Multi-Hop Traversal: 1-hop, N-hop, and range queries
• Path Finding: BFS shortest path and iterative all-paths DFS
• ISONQL Query Language: Declarative graph queries
• Schema Validation: Type-safe graph constraints (Graphantic)
• Deterministic Visualization: Seeded force layout with bit-identical cross-language geometry, SVG and interactive HTML rendering
• Fluent API: Chainable traversal and query builders
• ISON Persistence: Token-efficient serialization (ISON and ISONL)
• Zero Dependencies: Pure .NET base class library

Installation

dotnet add package IsonGraph

Or build from source:

dotnet build -c Release
dotnet test

Quick Start

using IsonGraph;

// Create a graph
var graph = new ISONGraph("social");

// Add nodes
graph.AddNode("person", "1", new() { ["name"] = "Alice", ["age"] = "30" });
graph.AddNode("person", "2", new() { ["name"] = "Bob", ["age"] = "25" });
graph.AddNode("person", "3", new() { ["name"] = "Charlie", ["age"] = "35" });
graph.AddNode("company", "100", new() { ["name"] = "TechCorp" });

// Add edges
graph.AddEdge("KNOWS", new("person", "1"), new("person", "2"), new() { ["since"] = "2020" });
graph.AddEdge("KNOWS", new("person", "2"), new("person", "3"), new() { ["since"] = "2021" });
graph.AddEdge("WORKS_AT", new("person", "1"), new("company", "100"), new() { ["role"] = "Engineer" });

// Query neighbors
List<NodeRef> friends = graph.Neighbors(new("person", "1"), "KNOWS");

// Multi-hop traversal
List<NodeRef> fof = graph.MultiHop(new("person", "1"), "KNOWS", 2);

// Shortest path
Path? path = graph.ShortestPath(new("person", "1"), new("person", "3"), "KNOWS");
if (path is not null)
    Console.WriteLine($"Path length: {path.Length}");

// Serialize
string ison = graph.ToIson();
graph.Save("social.ison");
var loaded = ISONGraph.Load("social.ison");

API Reference

ISONGraph

var graph = new ISONGraph("name");                  // Directed graph
var graph = new ISONGraph("name", directed: false); // Undirected graph

Node Operations

Edge Operations

Traversal

Path Finding

Graph Analysis

Serialization

Types

public readonly record struct NodeRef(string Type, string Id);

// Properties are string dictionaries
Dictionary<string, string> props;

public enum Direction { Out, In, Both }

Fluent Traversal

var companies = graph.Start(new("person", "1"))
    .Hop("KNOWS")
    .Hop("WORKS_AT")
    .Filter(n => n.Properties.GetValueOrDefault("industry") == "Tech")
    .Collect();

ISONQL Query Language

ISONQL is a declarative query language for ISONGraph, providing SQL-like queries for property graphs.

Basic Usage

using IsonGraph;

var graph = new ISONGraph("social");
graph.AddNode("person", "alice", new() { ["name"] = "Alice", ["age"] = "30", ["city"] = "NYC" });
graph.AddNode("person", "bob", new() { ["name"] = "Bob", ["age"] = "25", ["city"] = "LA" });
graph.AddEdge("KNOWS", new("person", "alice"), new("person", "bob"), new() { ["since"] = "2020" });

var engine = new QueryEngine(graph);

QueryResult result = engine.Execute("NODES person WHERE age > 25");
Console.WriteLine($"Found {result.Count} people");

Supported Query Types

-- NODES: select and filter nodes
NODES person
NODES person WHERE age > 25 AND city = NYC
NODES person WHERE city = LA OR city = Chicago
NODES person ORDER BY age DESC LIMIT 10 OFFSET 5
NODES person WHERE city = NYC RETURN name, age
NODES person(city="NYC")

-- EDGES: select and filter edges
EDGES KNOWS WHERE since > 2020 LIMIT 10

-- TRAVERSE: graph traversal
TRAVERSE person:alice -> KNOWS -> person
TRAVERSE person:bob <- KNOWS <- person
TRAVERSE person:alice -> KNOWS -> person MAX 3

-- PATH: shortest path
PATH person:alice TO person:bob VIA KNOWS MAX 5

-- COUNT and aggregations
COUNT person WHERE age > 20
SUM person.salary WHERE city = NYC
AVG person.age
MIN person.age
MAX person.age

Query Operators

AND binds tighter than OR: a AND b OR c evaluates as (a AND b) OR c.

Fluent Query Builder

var result = engine.Match("person")
    .Where("age", ">", 25)
    .Where("city", "=", "NYC")
    .OrderBy("age", "DESC")
    .Limit(10)
    .Execute();

long count = engine.Match("person").Where("city", "=", "NYC").Count();

var edges = engine.MatchEdges("KNOWS")
    .Where("since", ">", 2020)
    .Limit(10)
    .Execute();

Unknown operator strings in Where() throw ArgumentException instead of silently matching everything.

Schema Validation (Graphantic)

using IsonGraph;

var person = new NodeType("person")
    .Id(new IntField())
    .Field("name", new StringField().Required().Max(100))
    .Field("age", new IntField().Min(0).Max(150))
    .Field("email", new StringField().Email())
    .Field("status", new StringField().Enum("active", "inactive").Default("active"));

var company = new NodeType("company")
    .Id(new IntField())
    .Field("name", new StringField().Required());

var knows = new EdgeType("KNOWS")
    .FromNode(person)
    .ToNode(person)
    .NoSelfLoop()
    .Unique();

var worksAt = new EdgeType("WORKS_AT")
    .FromNode(person)
    .ToNode(company)
    .Cardinality(Cardinality.ManyToOne);

var reportsTo = new EdgeType("REPORTS_TO")
    .FromNode(person)
    .ToNode(person)
    .Acyclic()                      // per-relationship-type DAG check
    .Field("since", new IntField().Required());

var schema = new GraphSchema("social")
    .NodeTypes(person, company)
    .EdgeTypes(knows, worksAt, reportsTo)
    .NoOrphans();

ValidationResult result = schema.Validate(graph);
if (!result.Valid)
{
    foreach (var error in result.Errors)
        Console.WriteLine($"[{error.Location}] {error.Code}: {error.Message}");
}

Field validators: StringField (Required, Min, Max, Pattern, Email, Enum, Default), IntField, FloatField, BoolField, and RefField (To). Declared defaults are written into missing properties during validation. Edge constraints: NoSelfLoop, Unique, Acyclic (checked per relationship type), Bidirectional, and Cardinality (OneToOne, OneToMany, ManyToOne, ManyToMany). Graph constraints: Connected, NoOrphans, MaxDepth, and custom Constraint callbacks.

Visualization

Deterministic force-directed layout plus SVG and self-contained interactive HTML rendering. The PRNG is a portable 32-bit LCG, so the same graph, size, and seed produce bit-identical coordinates across every ISONGraph language port.

using IsonGraph;

var layout = Viz.ComputeLayout(graph, width: 900, height: 600, seed: 42);

string svg = Viz.RenderSvg(graph, layout, title: "My Graph");
string html = Viz.RenderHtml(graph, layout);   // hover tooltips, zoom, pan

Viz.Save(graph, "graph.svg");
Viz.Save(graph, "graph.html");

// Radius-aware collision pass: keep node centers >= (rA + rB) * spacing apart
var radii = graph.Nodes().ToDictionary(n => n.Ref, _ => 24.0);
var spaced = Viz.ComputeLayout(graph, radii: radii, spacing: 1.2);

Exception Handling

try
{
    graph.AddNode("person", "1");
    graph.AddNode("person", "1");  // throws DuplicateNodeError
}
catch (DuplicateNodeError e)
{
    Console.Error.WriteLine($"Duplicate node: {e.Message}");
}

try
{
    var node = graph.GetNode("person", "999");  // throws NodeNotFoundError
}
catch (NodeNotFoundError e)
{
    Console.Error.WriteLine($"Node not found: {e.Message}");
}

// AddNode("bad:type", ...) throws ArgumentException (':' is reserved)
// FromIson / FromIsonl throw GraphError on malformed input - never a silent skip

ISON Format

ISONGraph uses a token-efficient serialization format:

nodes.person
id name age
1 Alice 30
2 Bob 25

edges.KNOWS
source target since
:person:1 :person:2 2020

ISONL (Line-Oriented Format)

For streaming/appending:

nodes.person|id name|1 Alice
nodes.person|id name age|2 Bob 25
edges.KNOWS|source target since|:person:1 :person:2 2020

Values containing a space, |, ", a newline, or the empty string are double-quoted with \", \n, and \\ escapes; round-trips are lossless.

Requirements

• .NET 8.0 SDK or later
• No external dependencies (base class library only)

Running Tests

dotnet test

License

MIT License - see LICENSE for details.

Author

Mahesh Vaikri

• Website: graph.ison.dev
• Documentation: graph.ison.dev/docs.html
• GitHub: @maheshvaikri-code