Skip to content

README.md

Latest commit

 

History

History
143 lines (106 loc) · 3.49 KB

README.md

File metadata and controls

143 lines (106 loc) · 3.49 KB

Nuclear - WASM CRDT Database

A high-performance, WASM-based embedded NoSQL database with GraphQL query language support and CRDT-based synchronization for distributed systems.

Features

  • WASM Compatible: Runs natively in browsers and WASI-compatible runtimes
  • GraphQL API: Full support for queries, mutations, and subscriptions
  • CRDT Synchronization: Conflict-free replicated data types with Last-Writer-Wins (LWW) strategy
  • Real-time Sync: WebSocket-based real-time data synchronization
  • Offline-First: Works offline with automatic conflict resolution when syncing
  • Flat Data Design: Optimized for flattened data with efficient relation queries
  • Zero Configuration: Simple builder pattern for quick setup

Quick Start

Prerequisites

  • Rust 1.70+
  • wasm-pack (for WASM targets)

Add to Your Project

[dependencies]
nuclear = "0.1.0"

Basic Usage

use nuclear::Database;
use nuclear::storage::WasiStorage;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let storage = WasiStorage::new("./data");
    let db = Database::builder(storage)
        .node_id("node1".to_string())
        .build()
        .await?;
    
    // Create data with GraphQL mutation
    db.mutation(r#"
        mutation {
            create_user(input: {name: "Alice", email: "alice@example.com"}) {
                id
                name
            }
        }
    "#).await?;
    
    // Query data with GraphQL
    let result = db.query("query { users { id name email } }").await?;
    println!("{:?}", result);
    
    // Subscribe to real-time updates
    let mut stream = db.subscribe("subscription { user_updated { id name } }").await?;
    
    Ok(())
}

Architecture

Core Layers

  1. CRDT Engine (src/core/)

    • LWW Register: Last-Writer-Wins value containers
    • LWW Map: Key-value store with CRDT semantics
    • Vector Clock: Logical time tracking for causality

  2. Storage Layer (src/storage/)

    • Trait-based abstraction for storage backends
    • WasiStorage: WASI file system implementation
    • Pluggable design for browser/localStorage

  3. GraphQL Layer (src/graphql/)

    • Schema definition with queries, mutations, subscriptions
    • Scalars for custom types
    • Integration with CRDT data model

  4. Sync Engine (src/sync/)

    • SyncMessage: Wire format for synchronization
    • ConflictResolver: LWW-based conflict resolution

  5. API Layer (src/api/)

    • Database: Main interface for all operations
    • DatabaseBuilder: Fluent builder for configuration

Data Flow

User Query → GraphQL Parser → CRDT Engine → Storage → Response
                    ↓
              Sync Engine → Network → Other Nodes

Building

Native Build

cargo build --release

WASM Build

wasm-pack build --target web

Run Examples

cargo run --example basic_usage

Testing

cargo test
cargo test --test integration_test

Project Structure

nuclear/
├── src/
│   ├── api/           # Public API (Database, Builder)
│   ├── core/          # CRDT implementations
│   ├── graphql/      # GraphQL schema and execution
│   ├── storage/      # Storage abstractions
│   └── sync/         # Synchronization protocol
├── examples/          # Usage examples
├── tests/            # Integration tests
└── Cargo.toml        # Project manifest

License

MIT License - see LICENSE file for details.