litegraphdb v1.0.1

JavaScript SDK for LiteGraph

LiteGraph is a lightweight graph database with both relational and vector support, built using Sqlite, with support for exporting to GEXF. LiteGraph is intended to be a multi-modal database primarily for providing persistence and retrieval for knowledge and artificial intelligence applications.

Features

• Multi-tenant support with tenant GUID management
• Graph management
• Node and edge operations
• Route finding between nodes
• Search capabilities for graphs, nodes, and edges
• GEXF format export support
• Built-in retry mechanism and error handling
• Comprehensive logging system
• Access key authentication support

Requirements

• Node.js v18.20.4
• npm

Dependencies

• jest - for testing
• msw - for mocking the api
• superagent - for making the api calls
• url - for url parsing
• util - for utility functions
• uuid - for generating unique ids

Installation

Use the command below to install the package.

npm i litegraphdb

Quick Start

import { LiteGraphSdk } from 'litegraphdb';

const sdk = new LiteGraphSdk(
    'https://api.litegraphdb.com',
    'your-tenant-guid',
    'your-access-key'
);
const graphGuid = 'example-graph-guid';

// Create a new graph
sdk.createGraph('graph-guid', 'MyGraph').then((graph) => {
  console.log('Created graph:', graph);
});


const newMultipleNodes = [
    {
        "Name": "Active Directory",
        "Labels": [
            "test"
        ],
        "Tags": {
            "Type": "ActiveDirectory"
        },
        "Data": {
            "Name": "Active Directory"
        }
    },
    {
        "Name": "Website",
        "Labels": [
            "test"
        ],
        "Tags": {
            "Type": "Website"
        },
        "Data": {
            "Name": "Website"
        }
    }
]
//Create multiple Nodes
sdk.createNodes(graphGuid,newMultipleNodes).then((nodes) => {
  console.log('Created Multiple Nodes:', nodes);
});

const searchNodes = async () => {
  // Graph object to update

  const searchRequest = {
    GraphGUID: '00900db5-c9b7-4631-b250-c9e635a9036e',
    Ordering: 'CreatedDescending',
    Expr: {
      Left: 'Hello',
      Operator: 'Equals',
      Right: 'World',
    },
  };

sdk.searchNodes(searchRequest).then((response) => {
  console.log('Search response:', response);
})

API Endpoints Reference

Tenant Operations

User Operations

Authorization Operations

Credential Operations

Label Operations

Tag Operations

Vector Operations

Graph Operations

Node Operations

Edges Operations

Route Operations

Batch Operations

Core Components

Base Models

• TenantMetaData: Represents a tenant in the system
• Graph: Represents a graph container
• Node: Represents a node in a graph
• Edge: Represents a connection between nodes
• RouteRequest: Used for finding routes between nodes
• RouteResult: Contains route finding results
• ExistenceRequest: Used for checking the existence

API Resource Operations

Graphs

const { LiteGraphSdk } = require('litegraphdb');

const api = new LiteGraphSdk(
    'https://api.litegraphdb.com',
    'your-tenant-guid',
    'your-access-key'
);

// Create a graph
api.createGraph('graph-guid', 'New Graph')
    .then(graph => console.log(graph))
    .catch(err => console.error(err));

// Retrieve a graph
api.readGraph('graph-guid')
    .then(graph => console.log(graph))
    .catch(err => console.error(err));

// Retrieve all graphs for tenant
api.readGraphs()
    .then(graphs => console.log(graphs))
    .catch(err => console.error(err));

// Update a graph
const graphUpdate = { Name: 'Updated Graph' };
api.updateGraph('graph-guid', graphUpdate)
    .then(graph => console.log(graph))
    .catch(err => console.error(err));

// Delete a graph
api.deleteGraph('graph-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Export to GEXF
api.exportGraphToGexf('graph-guid')
    .then(gexfData => console.log(gexfData))
    .catch(err => console.error(err));

// Check if Graph Exists
api.graphExists('graph-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Search graphs in tenant
const searchRequest = {
    Ordering: 'CreatedDescending',
    Expr: {
        Left: 'Name',
        Operator: 'Equals',
        Right: 'My Graph'
    }
};
api.searchGraphs(searchRequest)
    .then(graphResults => console.log(graphResults))
    .catch(err => console.error(err));

Nodes

// Create Multiple Nodes
const newMultipleNodes = [
    {
        Name: 'Active Directory',
        Data: { Name: 'Active Directory' }
    },
    {
        Name: 'Website',
        Data: { Name: 'Website' }
    }
];
api.createNodes('graph-guid', newMultipleNodes)
    .then(nodes => console.log(nodes))
    .catch(err => console.error(err));

// Create a single node
const nodeData = {
    Name: 'New Node',
    Data: { type: 'service' }
};
api.createNode('graph-guid', nodeData)
    .then(node => console.log(node))
    .catch(err => console.error(err));

// Retrieve a node
api.readNode('graph-guid', 'node-guid')
    .then(node => console.log(node))
    .catch(err => console.error(err));

// Retrieve all nodes in a graph
api.readNodes('graph-guid')
    .then(nodes => console.log(nodes))
    .catch(err => console.error(err));

// Update a node
const nodeUpdate = { Name: 'Updated Node' };
api.updateNode('graph-guid', 'node-guid', nodeUpdate)
    .then(node => console.log(node))
    .catch(err => console.error(err));

// Delete a node
api.deleteNode('graph-guid', 'node-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Delete multiple nodes
api.deleteMultipleNodes('graph-guid', ['node-guid-1', 'node-guid-2'])
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Check if Node Exists
api.nodeExists('graph-guid', 'node-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Delete all nodes within a graph
api.deleteNodes('graph-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

const searchReq = {
  "Ordering": "CreatedDescending",
  "Labels": [
    "test"
  ],
  "Tags": { },
  "Expr": { }
};
// Search a node
api.searchNodes('graph-guid', searchReq)
    .then(nodes => console.log(nodes))
    .catch(err => console.error(err));

Edges

// Create Multiple Edges
const newMultipleEdges = [
    {
        Name: 'Connection 1',
        From: 'node-guid-1',
        To: 'node-guid-2',
        Cost: 1
    },
    {
        Name: 'Connection 2',
        From: 'node-guid-2',
        To: 'node-guid-3',
        Cost: 1
    }
];
api.createEdges('graph-guid', newMultipleEdges)
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Create a single edge
const edgeData = {
    Name: 'Direct Connection',
    From: 'node-guid-1',
    To: 'node-guid-2',
    Cost: 1
};
api.createEdge(edgeData)
    .then(edge => console.log(edge))
    .catch(err => console.error(err));

// Retrieve an edge
api.readEdge('graph-guid', 'edge-guid')
    .then(edge => console.log(edge))
    .catch(err => console.error(err));

// Update an edge
const edgeUpdate = { Name: 'Updated Connection', Cost: 2 };
api.updateEdge('graph-guid', 'edge-guid', edgeUpdate)
    .then(edge => console.log(edge))
    .catch(err => console.error(err));

// Delete an edge
api.deleteEdge('graph-guid', 'edge-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Delete multiple edges
api.deleteMultipleEdges('graph-guid', ['edge-guid-1', 'edge-guid-2'])
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Check if Edge Exists
api.edgeExists('graph-guid', 'edge-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

const searchRequest = {
    GraphGUID: '01010101-0101-0101-0101-010101010101',
    Ordering: 'CreatedDescending',
    Expr: {
      Left: 'Hello',
      Operator: 'Equals',
      Right: 'World',
    },
  };
// Search edges
api.searchEdges('graph-guid', searchRequest)
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Read all edges in a graph
api.readEdges('graph-guid')
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Delete all edges
api.deleteEdges('graph-guid')
    .then(console.log('All edges deleted'))
    .catch(err => console.error(err));

Vector Operations

// Retrieve all vectors
api.readAllVectors()
    .then(vectors => console.log(vectors))
    .catch(err => console.error(err));

// Retrieve a specific vector
api.readVector('vector-guid')
    .then(vector => console.log(vector))
    .catch(err => console.error(err));

// Check if a vector exists
api.existsVector('vector-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Create a new vector
const newVector = {
    GraphGUID: 'graph-guid',
    Domain: 'Test Domain',
    SearchType: 'Exact',
    Labels: ['label1', 'label2']
};
api.createVector(newVector)
    .then(vector => console.log(vector))
    .catch(err => console.error(err));

// Update a vector
const vectorUpdate = {
    Domain: 'Updated Domain',
    SearchType: 'Updated Exact',
    Labels: ['updated-label1', 'updated-label2']
};
api.updateVector( vectorUpdate,'vector-guid')
    .then(updatedVector => console.log(updatedVector))
    .catch(err => console.error(err));

// Delete a vector
api.deleteVector('vector-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Search vectors
const searchRequest = {
    GraphGUID: '00000000-0000-0000-0000-000000000000',
    Domain: 'Search Domain',
    SearchType: 'Contains',
    Labels: ['search-label1', 'search-label2']
};
api.searchVectors(searchRequest)
    .then(searchResults => console.log(searchResults))
    .catch(err => console.error(err));

Route and Traversal

// Find Routes
const routeRequest = {
    Graph: 'graph-guid',
    From: 'node-guid',
    To: 'node-guid',
    NodeFilter: {
        Ordering: 'CreatedDescending',
        Expr: { Left: 'Hello', Operator: 'GreaterThan', Right: 'World' }
    }
};
api.getRoutes('graph-guid', routeRequest)
    .then(routes => console.log(routes))
    .catch(err => console.error(err));

// Get Edges From
api.getEdgesFromNode('graph-guid', 'node-guid')
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Get Edges To
api.getEdgesToNode('graph-guid', 'node-guid')
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Get Edges Between
api.getEdgesBetween('graph-guid', 'node-guid-1', 'node-guid-2')
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Get All Node Edges
api.getAllNodeEdges('graph-guid', 'node-guid')
    .then(edges => console.log(edges))
    .catch(err => console.error(err));

// Get Children Node
api.getChildrenFromNode('graph-guid', 'node-guid')
    .then(nodes => console.log(nodes))
    .catch(err => console.error(err));

// Get Parent  Node
api.getParentsFromNode('graph-guid', 'node-guid')
    .then(nodes => console.log(nodes))
    .catch(err => console.error(err));

// Get Node Neighbors
api.getNodeNeighbors('graph-guid', 'node-guid')
    .then(neighbors => console.log(neighbors))
    .catch(err => console.error(err));

Tenant Operations

// Retrieve all tenants
api.readTenants()
    .then(tenants => console.log(tenants))
    .catch(err => console.error(err));

// Retrieve a specific tenant
api.readTenant('tenant-guid')
    .then(tenant => console.log(tenant))
    .catch(err => console.error(err));

// Create a new tenant
const newTenant = {
    Name: 'Another Tenant',
    Active: true
};
api.createTenant(newTenant)
    .then(tenant => console.log(tenant))
    .catch(err => console.error(err));

// Check if a tenant exists
api.tenantExists('tenant-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Update a tenant
const tenantUpdate = {
    Name: 'Updated Tenant',
    Active: true
};
api.updateTenant('tenant-guid', tenantUpdate)
    .then(updatedTenant => console.log(updatedTenant))
    .catch(err => console.error(err));

// Delete a tenant
api.deleteTenant('tenant-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

// Force delete a tenant
api.tenantDeleteForce('tenant-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

User Operations

// Retrieve all users
api.readAllUsers()
    .then(users => console.log(users))
    .catch(err => console.error(err));

// Retrieve a specific user
api.readUser('user-guid')
    .then(user => console.log(user))
    .catch(err => console.error(err));

// Create a new user
const newUser = {
    FirstName: 'Another',
    LastName: 'User',
    Email: 'another@user.com',
    Password: 'password',
    Active: true
};
api.createUser(newUser)
    .then(user => console.log(user))
    .catch(err => console.error(err));

// Check if a user exists
api.existsUser('user-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Update a user
const userUpdate = {
    FirstName: 'Again Updated',
    LastName: 'User',
    Email: 'anotherbbb@user.com',
    Password: 'password',
    Active: true
};
api.updateUser('user-guid', userUpdate)
    .then(user => console.log(user))
    .catch(err => console.error(err));

// Delete a user
api.deleteUser('user-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

Credential Operations

// Retrieve all credentials
api.readAllCredentials()
    .then(credentials => console.log(credentials))
    .catch(err => console.error(err));

// Retrieve a specific credential
api.readCredential('credential-guid')
    .then(credential => console.log(credential))
    .catch(err => console.error(err));

// Create a new credential
const newCredential = {
    UserGUID: 'user-guid',
    Name: 'New Credential',
    BearerToken: 'foobar',
    Active: true
};
api.createCredential(newCredential)
    .then(credential => console.log(credential))
    .catch(err => console.error(err));

// Check if a credential exists
api.existsCredential('credential-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Update a credential
const credentialUpdate = {
    UserGUID: 'user-guid',
    Name: 'Updated Credential',
    BearerToken: 'default',
    Active: true
};
api.updateCredential(credentialUpdate, 'credential-guid')
    .then(updatedCredential => console.log(updatedCredential))
    .catch(err => console.error(err));

// Delete a credential
api.deleteCredential('credential-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

Tag Operations

// Retrieve all tags
api.readAllTags()
    .then(tags => console.log(tags))
    .catch(err => console.error(err));

// Retrieve a specific tag
api.readTag('tag-guid')
    .then(tag => console.log(tag))
    .catch(err => console.error(err));

// Check if a tag exists
api.existsTag('tag-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Create a new tag
const newTag = {
    GraphGUID: 'graph-guid',
    NodeGUID: 'node-guid',
    EdgeGUID: 'edge-guid',
    Key: 'test-key',
    Value: 'test-value'
};
api.createTag(newTag)
    .then(tag => console.log(tag))
    .catch(err => console.error(err));

// Update a tag
const tagUpdate = {
    Key: 'updated-key',
    Value: 'updated-value'
};
api.updateTag(tagUpdate, 'tag-guid')
    .then(updatedTag => console.log(updatedTag))
    .catch(err => console.error(err));

// Delete a tag
api.deleteTag('tag-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

Label Operations

// Retrieve all labels
api.readAllLabels()
    .then(labels => console.log(labels))
    .catch(err => console.error(err));

// Retrieve a specific label
api.readLabel('label-guid')
    .then(label => console.log(label))
    .catch(err => console.error(err));

// Check if a label exists
api.existsLabel('label-guid')
    .then(exists => console.log(exists))
    .catch(err => console.error(err));

// Create a new label
const newLabel = {
    GraphGUID: 'graph-guid',
    NodeGUID: 'node-guid',
    Label: 'test-label',
    CreatedUtc: '2025-01-16T07:23:26.752372Z',
    LastUpdateUtc: '2025-01-16T07:23:26.752417Z'
};
api.createLabel(newLabel)
    .then(label => console.log(label))
    .catch(err => console.error(err));

// Update a label
const labelUpdate = {
    Key: 'updated-label',
    Value: 'updated-value',
    CreatedUtc: '2024-12-27T18:12:38.653402Z',
    LastUpdateUtc: '2024-12-27T18:12:38.653402Z'
};
api.updateLabel(labelUpdate, 'label-guid')
    .then(updatedLabel => console.log(updatedLabel))
    .catch(err => console.error(err));

// Delete a label
api.deleteLabel('label-guid')
    .then(response => console.log(response))
    .catch(err => console.error(err));

Authentication

// Generate an authentication token
const email = 'user@example.com';
const password = 'securepassword';
const tenantId = 'tenant-guid';
api.generateToken(email, password, tenantId)
    .then(token => console.log(token))
    .catch(err => console.error(err));

// Fetch details about an authentication token
const authToken = 'token';
api.getTokenDetails(authToken)
    .then(tokenDetails => console.log(tokenDetails))
    .catch(err => console.error(err));

Batch Operation

// Execute a batch existence request
const existenceRequest = {
    "Nodes": [
        "node-guid-1",
        "node-guid-2",
        "node-guid-3"
    ],
    "Edges": [
        "edge-guid-1",
        "edge-guid-2",
        "edge-guid-3"
    ],
    "EdgesBetween": [
        { "From": "node-guid-1", "To": "node-guid-2" },
        { "From": "node-guid-3", "To": "node-guid-4" },
        { "From": "node-guid-5", "To": "node-guid-6" }
    ]
}
api.batchExistence('graph-guid',existenceRequest )
    .then(existenceResults => console.log(existenceResults))
    .catch(err => console.error(err));

Development

Linking the project locally (for development and testing)

To use the library locally without publishing to a remote npm registry, first install the dependencies with the command:

npm install

Next, link it globally in local system's npm with the following command:

npm link

To use the link you just defined in your project, switch to the directory you want to use your litegraphdb from, and run:

npm link litegraphdb

Finally, you need to build the sdk, use command:

npm run build

You can then import the SDK with either import or require based on the ES Module (esm) or CommonJS (cjs) project, as shown below:

import { LiteGraphSdk } from 'litegraphdb';
//or
var { LiteGraphSdk } = require('litegraphdb');

Setting up Pre-commit Hooks

The pre-commit hooks will run automatically on git commit. They help maintain:

• Code formatting (using ruff)
• Import sorting
• Code quality checks
• And other project-specific checks

Running Tests

The project uses jest for running tests in isolated environments. Make sure you have jest installed, which should automatically be there if you have installed dependencies via npm i command:

# Run only the tests
npm run test

# Run tests with coverage report
npm run test:coverage

Documentation

Docs can be generated by running the following command:

npm run build:docs

and view the docs in the docs/docs.md file.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details

Feedback and Issues

Have feedback or found an issue? Please file an issue in our GitHub repository.

Version History

Please refer to CHANGELOG.md for a detailed version history.