@semiont/graph

Graph database abstraction with Neo4j, Neptune, JanusGraph, and in-memory implementations.

Installation

npm install @semiont/graph

Then install the peer dependency for your chosen graph database:

# For Neo4j
npm install neo4j-driver

# For Neptune or JanusGraph
npm install gremlin

# For Neptune with AWS SDK
npm install @aws-sdk/client-neptune

# MemoryGraph has no dependencies

Architecture Context

Infrastructure Ownership: In production applications, graph database instances are created and managed by @semiont/make-meaning's startMakeMeaning() function, which serves as the single orchestration point for all infrastructure components (EventStore, GraphDB, RepStore, InferenceClient, JobQueue, Workers).

The examples below show direct usage for testing, CLI tools, or standalone applications. For backend integration, see @semiont/make-meaning.

Quick Start

import { getGraphDatabase } from '@semiont/graph';
import type { EnvironmentConfig } from '@semiont/core';

const envConfig: EnvironmentConfig = {
  services: {
    graph: {
      type: 'neo4j',
      uri: 'bolt://localhost:7687',
      username: 'neo4j',
      password: 'password',
      database: 'neo4j'
    }
  }
};

const graph = await getGraphDatabase(envConfig);
await graph.connect();

// Create a document
const document = await graph.createDocument({
  id: 'doc-123',
  name: 'My Document',
  format: 'text/plain',
  entityTypes: ['Person', 'Organization'],
  archived: false,
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
});

// Create an annotation
const annotation = await graph.createAnnotation({
  id: 'anno-456',
  target: { source: 'doc-123' },
  body: [{ value: 'Important note' }],
  creator: 'user-123',
  created: new Date().toISOString()
});

// Query relationships
const annotations = await graph.getAnnotationsForDocument('doc-123');

Features

• 🔌 Multiple Providers - Neo4j, AWS Neptune, JanusGraph, In-memory
• 🎯 Unified Interface - Same API across all providers
• 📊 W3C Compliant - Full Web Annotation Data Model support
• 🔄 Event-Driven Updates - Sync from Event Store projections
• 🚀 Optional Projection - Graph is optional, core features work without it
• 🔍 Rich Queries - Cross-document relationships and entity searches

Documentation

• API Reference - Complete API documentation
• Architecture - System design and principles
• Eventual Consistency - Order-independent projections and race condition handling
• Provider Guide - Provider-specific details

Examples

• Basic Example - Simple graph operations
• Multi-Provider - Switching between providers

Supported Implementations

Neo4j

Native graph database with Cypher query language.

const envConfig = {
  services: {
    graph: {
      type: 'neo4j',
      uri: 'bolt://localhost:7687',
      username: 'neo4j',
      password: 'password',
      database: 'neo4j'
    }
  }
};

AWS Neptune

Managed graph database supporting Gremlin.

const envConfig = {
  services: {
    graph: {
      type: 'neptune',
      endpoint: 'wss://your-cluster.neptune.amazonaws.com:8182/gremlin',
      port: 8182,
      region: 'us-east-1'
    }
  }
};

JanusGraph

Open-source distributed graph database.

const envConfig = {
  services: {
    graph: {
      type: 'janusgraph',
      host: 'localhost',
      port: 8182,
      storage: 'cassandra',
      index: 'elasticsearch'
    }
  }
};

MemoryGraph

In-memory implementation for development and testing.

const envConfig = {
  services: {
    graph: {
      type: 'memory'
    }
  }
};

API Overview

Core Operations

// Document operations
await graph.createDocument(document);
await graph.getDocument(id);
await graph.updateDocument(id, updates);
await graph.deleteDocument(id);

// Annotation operations
await graph.createAnnotation(annotation);
await graph.getAnnotation(id);
await graph.updateAnnotation(id, updates);
await graph.deleteAnnotation(id);

// Query operations
await graph.getAnnotationsForDocument(documentId);
await graph.findDocumentsByEntityTypes(['Person']);
await graph.findAnnotationsByTarget(targetId);

// Tag collections
await graph.getEntityTypes();
await graph.addEntityType('NewType');

Graph as Optional Projection

The graph database is designed as an optional read-only projection:

Works WITHOUT Graph

✅ Viewing resources and annotations ✅ Creating/updating/deleting annotations ✅ Single-document workflows ✅ Real-time SSE updates

Requires Graph

❌ Cross-document relationship queries ❌ Entity-based search across resources ❌ Graph visualization ❌ Network analysis

See Architecture Documentation for details.

Performance

| Provider | Setup | Speed | Scalability | Persistence | |----------|-------|-------|-------------|-------------| | Neo4j | Medium | Fast | High | Yes | | Neptune | Complex | Medium | Very High | Yes | | JanusGraph | Complex | Medium | Very High | Yes | | Memory | None | Very Fast | Low | No |

Development

# Install dependencies
npm install

# Build package
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

License

Apache-2.0