Lightweight In-Memory Graph Database

Common errors

• TypeError: Graph is not a constructor

  cause Attempting to import the Graph class incorrectly, often using a default import or CommonJS `require()` pattern instead of a named import for an ESM-style module.
  fix Ensure you are using a named import: `import { Graph } from 'simple-graphdb';` in an ES module environment or with appropriate transpilation.

• Error: Node with ID 'xyz123' not found.

  cause Attempting to access, modify, or traverse from a node ID that does not exist in the current graph instance.
  fix Verify the node ID exists using `graph.hasNode(id)` before attempting operations, or ensure that the ID is correctly obtained from a previously added node or a deserialized graph.

• Cannot find module 'simple-graphdb'

  cause Node.js (or bundler) cannot resolve the package, often due to an ES module/CommonJS mismatch or incorrect `tsconfig.json`/`package.json` configuration.
  fix Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`, targetting `esnext` in `tsconfig.json`), or verify that your bundler (Webpack, Rollup, etc.) is correctly configured to handle ES Modules. If using CommonJS, ensure you're using `const { Graph } = require('simple-graphdb');` (though this might not work if the package is strictly ESM).

Warnings

• gotcha simple-graphdb is an in-memory database. All data is lost when the application process terminates unless explicitly serialized and deserialized by the user. There are no built-in persistence mechanisms.
  Fix: Implement custom serialization (e.g., to JSON) and deserialization logic to save and load graph state. For example: `const data = graph.toJSON(); // Save data... const loadedGraph = Graph.fromJSON(data);` (Check API for exact serialization methods).
• gotcha Performance may degrade significantly with very large graphs (tens of thousands of nodes/edges or more) due to its in-memory nature and single-threaded JavaScript execution. It is not designed for petabyte-scale graph data.
  Fix: For very large datasets or complex analytical queries, consider migrating to a dedicated, persistent graph database (e.g., Neo4j, Apache TinkerPop, JanusGraph) or optimizing your graph structure and queries.
• gotcha Node and edge IDs are internally generated strings. While unique within a single graph instance, they are not guaranteed to be stable across application restarts or different graph instances unless you manage them explicitly during serialization/deserialization.
  Fix: When serializing and deserializing, ensure that the ID mapping is preserved, or design your application to handle potentially new IDs upon reload, identifying nodes by their unique properties if IDs are not stable.
• gotcha The library does not provide built-in concurrency control or transaction management. If multiple asynchronous operations modify the same graph instance concurrently, data corruption or unexpected behavior may occur.
  Fix: Ensure all graph modifications are synchronized or performed in a single-threaded context. If using in a multi-threaded (e.g., Worker threads) or highly concurrent async environment, implement your own locking or queueing mechanism for graph access.

Install

• npm install simple-graphdb npm
• yarn add simple-graphdb yarn
• pnpm add simple-graphdb pnpm

Imports

• Graph
  wrong:

  const Graph = require('simple-graphdb');

  correct:

  import { Graph } from 'simple-graphdb';

  The primary class for creating and interacting with a graph. Use named import for ESM environments.
• Node

  import { Node } from 'simple-graphdb';

  Type definition for a graph node. Primarily used for TypeScript type hinting.
• Edge

  import { Edge } from 'simple-graphdb';

  Type definition for a graph edge/relationship. Primarily used for TypeScript type hinting.

Quickstart

This quickstart demonstrates how to initialize a graph, add nodes and edges with properties, and perform basic traversal and querying operations to find related data.

import { Graph } from 'simple-graphdb';

// Create a new graph instance
const graph = new Graph();

// Add nodes with types and properties
const userNode = graph.addNode('User', { name: 'Alice', email: 'alice@example.com' });
const productNode = graph.addNode('Product', { name: 'Laptop', price: 1200 });
const orderNode = graph.addNode('Order', { orderId: 'ORD001', date: new Date() });

// Add directed edges to represent relationships
graph.addEdge(userNode.id, orderNode.id, 'PLACED');
graph.addEdge(orderNode.id, productNode.id, 'CONTAINS', { quantity: 1 });

// Query the graph
const aliceOrders = graph.getChildren(userNode.id, { edgeType: 'PLACED' });
console.log('Alice\'s orders:', aliceOrders.map(node => node.properties));

const orderProducts = graph.getChildren(orderNode.id, { edgeType: 'CONTAINS' });
console.log('Products in Order ORD001:', orderProducts.map(node => node.properties));

// Find a path between Alice and the Laptop product
const path = graph.traverse(userNode.id, productNode.id, { method: 'bfs' });
if (path) {
  console.log('Path from Alice to Laptop:', path);
} else {
  console.log('No path found from Alice to Laptop.');
}