Technical Features of GenosDB (GDB)
Complete reference of querying, sync, storage, security, and performance features
Full Stack Developer - dWEB R&D
- remove(id): Deletes a node and all of its associated edges.- clear(): Wipes all data from the local database.- use(middleware): Registers a middleware function to validate or transform incoming P2P operations before they are applied, enabling custom security and business logic.
Querying & Data Access
The map(...args) method is the heart of data retrieval in GenosDB, offering both static and real-time querying capabilities.- Powerful Filtering: Supports MongoDB-style queries, sorting, and pagination ($limit, $after).- Real-Time Reactivity: By providing a callback function, map enters a reactive mode. The callback receives event objects for all matching nodes, keeping your UI perfectly in sync with the database state.- Event Object: The callback receives ({ id, value, action, edges, timestamp }).- Event Actions: 'initial' (for the starting dataset), 'added', 'updated', and 'removed'.- Recursive Graph Traversal (****\(edge**)**: A standout feature is the \)edge operator. It allows you to perform complex, multi-hop traversals in a single query. You define a query to find the starting nodes, and the $edge sub-query filters all their descendants, returning a flat list of matching nodes from anywhere in the hierarchy.
Concurrency & Consistency
GenosDB is designed for distributed environments where conflicts are inevitable.- Hybrid Logical Clocks (HLC): Every operation is timestamped with an HLC, which combines physical time with a logical counter. This ensures a causal ordering of events across all peers.- Last-Write-Wins (LWW): Conflicts are automatically resolved using an LWW strategy based on the newest HLC timestamp. The system includes safeguards to prevent abuse from clients with manipulated system clocks.- Clock Sync: The local HLC is intelligently updated upon receiving remote operations, ensuring the causal chain is maintained across the network.
P2P Synchronization & Networking (GenosRTC)
When initialized with rtc: true, GenosDB enables its powerful GenosRTC module via the db.room object for direct, real-time peer-to-peer communication.- Peer Lifecycle Events: Automatically detect when peers connect or disconnect.- db.room.on('peer:join', (peerId) => ...)- db.room.on('peer:leave', (peerId) => ...)- Data Channels: Send any serializable data (JSON, strings, binary) through named channels. This is perfect for chat messages, cursor positions, or game state updates.- const channel = db.room.channel('channel-name')- channel.send(data)- channel.on('message', (data, peerId) => ...)- Media Streams: Stream audio and video directly to other peers for applications like video conferencing or voice chat.- db.room.addStream(localStream)- db.room.on('stream:add', (stream, peerId) => ...)- Cross-Tab Sync: Uses a BroadcastChannel to ensure consistency between multiple tabs of the same application within a single browser. It automatically handles recovery from tab inactivity.
Storage & Persistence
GenosDB prioritizes performance and reliability for its local storage engine.- Primary Storage: It leverages the Origin Private File System (OPFS) for high-performance, file-based storage when available. It uses synchronous file handles (createSyncAccessHandle) for maximum efficiency, falling back to asynchronous APIs or IndexedDB where necessary.- Dedicated Web Worker: All storage I/O is offloaded to a dedicated Web Worker. This prevents the main thread from being blocked and ensures a smooth user experience, even under heavy write loads. File-level locking and a write queue prevent race conditions.
Performance & Efficiency
- MessagePack: Data is serialized into the compact MessagePack binary format.- Pako (Deflate): Serialized data is compressed using Pako, significantly reducing storage footprint and network transfer sizes.
Security & Configuration
- End-to-End Encryption: Providing a password during initialization encrypts the P2P signaling and data-channel communications. For private data encrypted at rest, the Security Manager's
db.sm.put()/get()ties encryption to the user's own identity key, so only they can decrypt it.- Custom Validation: Use the db.use(middleware) method to implement custom authorization logic (e.g., RBAC) by validating all incoming remote operations against your own rules.
Feature Summary
GenosDB is a comprehensive solution for building decentralized, real-time web applications. Its combination of a local-first architecture, a powerful graph query engine, and seamless WebRTC-based P2P synchronization makes it an ideal choice for collaborative tools, multiplayer games, and any application that demands reactive data and offline capabilities without server dependencies.
This article is part of the official documentation of GenosDB (GDB). GenosDB is a distributed, modular, peer-to-peer graph database built with a Zero-Trust Security Model, created by Esteban Fuster Pozzi (estebanrfp).
📄 Whitepaper | overview of GenosDB design and architecture
🛠 Roadmap | planned features and future updates
💡 Examples | code snippets and usage demos
📖 Documentation | full reference guide
🔍 API Reference | detailed API methods
📚 Wiki | additional notes and guides
💬 GitHub Discussions | community questions and feedback
🗂 Repository | Minified production-ready files
📦 Install via npm | quick setup instructions
