@zgdb/runtime

@ZGDB Homepage

@zgdb/runtime

The @zgdb/runtime package provides the core engine and necessary utilities for databases generated by @zgdb/cli. It offers a flexible, storage-agnostic foundation with built-in support for both synchronous and asynchronous operations, ensuring transactional integrity and type safety.

This package is the powerhouse behind your generated client, handling data serialization, storage abstraction, and transactional logic.

Core Concepts

Store Adapters (StoreAdapter & SyncStoreAdapter)

These interfaces define a standardized contract for how the zgdb client interacts with an underlying key-value storage system. The StoreAdapter is for asynchronous backends, requiring methods like get, set, and transact, while the SyncStoreAdapter provides a synchronous equivalent with get, set, and transactSync. This design makes the runtime storage-agnostic, allowing developers to plug in different storage solutions by creating a class that implements one of these interfaces.

Transactional Clients (TransactionClient & TransactionClientSync)

These type interfaces define the API for performing database operations within a safe, all-or-nothing transaction. The client provides type-safe methods like getNode, createNode, and updateNode that can be used inside a transact or transactSync block. This ensures that a series of mutations to the graph are treated as a single atomic unit, maintaining data consistency and integrity.

Client Factories (createAsyncClient & createSyncClient)

These are the primary factory functions used to initialize a zgdb client instance. They take a storage adapter (either sync or async) and a set of generated helper functions (for serialization and data manipulation) as arguments. The factory then returns a client object equipped with a transact or transactSync method, which serves as the main entry point for executing database operations.

KeyEncoder

The KeyEncoder is a utility class responsible for creating and parsing the hierarchical string keys used to store and retrieve data from the underlying key-value store. It provides static methods to generate specific key formats for nodes (e.g., n:<type>:<id>), edges, and indexes. This structured key scheme is fundamental to how zgdb organizes data and enables efficient data lookups and range scans within the storage layer.

In-Memory Adapters (MapStoreAdapter & MapStoreAdapterSync)

These are concrete, ready-to-use implementations of the store adapter interfaces that use a simple JavaScript Map for in-memory storage. The MapStoreAdapter provides an asynchronous, transactional store by buffering writes and committing them on success. The MapStoreAdapterSync offers a synchronous alternative, ensuring atomicity by creating a cheap backup of the data before a transaction and rolling back to it if an error occurs. These adapters are ideal for testing, development, and applications that require high-speed, non-persistent data management.

Core Data Types (NodeData & Edge)

These interfaces define the primary structures within the graph. NodeData represents a single entity or object in your database, containing a unique id, type, timestamps, user-defined fields, and relationIds to link to other nodes. Edge represents a directed connection between two nodes (from and to), which also has its own id, type, and can contain arbitrary data. These types form the backbone of the graph and are what the generated type-safe clients operate on.