gitdb-client 1.0.3

Official Rust client for GitDB - GitHub-backed NoSQL database
# GitDB Rust Client


Official Rust client for GitDB - GitHub-backed NoSQL database.

## Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
gitdb-client = "1.0.0"
```

## Quick Start


```rust
use gitdb_client::GitDBClient;
use std::collections::HashMap;
use serde_json::json;

#[tokio::main]

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client
    let client = GitDBClient::new(
        "your-github-token",
        "your-github-username", 
        "your-repo-name"
    );
    
    // Check server health
    client.health().await?;
    
    // Create a collection
    client.create_collection("users").await?;
    
    // Insert a document
    let mut user = HashMap::new();
    user.insert("name".to_string(), json!("John Doe"));
    user.insert("email".to_string(), json!("john@example.com"));
    user.insert("age".to_string(), json!(30));
    
    let id = client.insert("users", &user).await?;
    println!("Inserted user with ID: {}", id);
    
    // Find documents
    let mut query = HashMap::new();
    query.insert("age".to_string(), json!({ "$gte": 25 }));
    
    let users = client.find("users", &query).await?;
    println!("Found {} users", users.len());
    
    // Update a document
    let mut update = HashMap::new();
    update.insert("age".to_string(), json!(31));
    
    client.update("users", &id, &update).await?;
    println!("Updated user");
    
    // Delete a document
    client.delete("users", &id).await?;
    println!("Deleted user");
    
    Ok(())
}
```

## Features


- **Zero-cost abstractions** - High performance with minimal overhead
-**Memory safety** - Rust's ownership system prevents common bugs
-**Async/await support** - Non-blocking operations with tokio
-**Type safety** - Strong typing throughout the API
-**Error handling** - Comprehensive error handling with anyhow
-**CRUD operations** - Create, Read, Update, Delete documents
-**Query support** - MongoDB-style query operators
-**GraphQL integration** - Native GraphQL query support
-**Batch operations** - Insert, update, delete multiple documents
-**Collection management** - Create, list, delete collections

## API Reference


### Client Creation


```rust
// Basic client
let client = GitDBClient::new(token, owner, repo);

// Client with custom URL
let client = GitDBClient::with_url(token, owner, repo, "http://localhost:7896");
```

### Health Check


```rust
// Check if server is healthy
client.health().await?;
```

### Collection Management


```rust
// Create a collection
client.create_collection("users").await?;

// List all collections
let collections = client.list_collections().await?;
for collection in collections {
    println!("Collection: {} ({} documents)", collection.name, collection.count);
}

// Delete a collection
client.delete_collection("users").await?;
```

### Document Operations


#### Insert


```rust
let mut document = HashMap::new();
document.insert("name".to_string(), json!("Alice"));
document.insert("age".to_string(), json!(25));

let id = client.insert("users", &document).await?;
```

#### Find


```rust
// Find all documents
let all_users = client.find("users", &HashMap::new()).await?;

// Find with query
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$gte": 30 }));
let older_users = client.find("users", &query).await?;

// Find one document
let user = client.find_one("users", &query).await?;

// Find by ID
let user = client.find_by_id("users", "document-id").await?;
```

#### Update


```rust
let mut update = HashMap::new();
update.insert("age".to_string(), json!(26));
update.insert("last_updated".to_string(), json!("2024-01-01"));

client.update("users", "document-id", &update).await?;
```

#### Delete


```rust
// Delete by ID
client.delete("users", "document-id").await?;

// Delete multiple documents
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$lt": 18 }));
let deleted_count = client.delete_many("users", &query).await?;
```

### Batch Operations


```rust
// Insert multiple documents
let mut documents = Vec::new();
for i in 1..=5 {
    let mut doc = HashMap::new();
    doc.insert("name".to_string(), json!(format!("User {}", i)));
    doc.insert("age".to_string(), json!(20 + i));
    documents.push(doc);
}

for doc in documents {
    client.insert("users", &doc).await?;
}

// Update multiple documents
let mut query = HashMap::new();
query.insert("age".to_string(), json!({ "$gte": 25 }));

let mut update = HashMap::new();
update.insert("category".to_string(), json!("senior"));

let updated_count = client.update_many("users", &query, &update).await?;
```

### GraphQL Queries


```rust
// Simple GraphQL query
let query = r#"
    query {
        users {
            id
            name
            age
        }
    }
"#;

let response = client.graphql_simple(query).await?;
if let Some(data) = response.data {
    println!("GraphQL result: {}", data);
}

// GraphQL query with variables
let query = r#"
    query GetUser($id: String!) {
        user(id: $id) {
            id
            name
            age
        }
    }
"#;

let mut variables = HashMap::new();
variables.insert("id".to_string(), json!("user-id"));

let response = client.graphql(query, Some(variables)).await?;
```

### Query Operators


The Rust client supports MongoDB-style query operators:

```rust
let mut query = HashMap::new();

// Equal
query.insert("age".to_string(), json!(30));

// Greater than
query.insert("age".to_string(), json!({ "$gt": 25 }));

// Greater than or equal
query.insert("age".to_string(), json!({ "$gte": 25 }));

// Less than
query.insert("age".to_string(), json!({ "$lt": 50 }));

// Less than or equal
query.insert("age".to_string(), json!({ "$lte": 50 }));

// Not equal
query.insert("age".to_string(), json!({ "$ne": 30 }));

// In array
query.insert("category".to_string(), json!({ "$in": ["admin", "user"] }));

// Not in array
query.insert("category".to_string(), json!({ "$nin": ["admin"] }));

// Regular expression
query.insert("name".to_string(), json!({ "$regex": "john", "$options": "i" }));
```

## Error Handling


The client uses `anyhow::Result` for error handling:

```rust
use anyhow::Result;

async fn example() -> Result<()> {
    let client = GitDBClient::new("token", "owner", "repo");
    
    match client.health().await {
        Ok(()) => println!("Server is healthy"),
        Err(e) => eprintln!("Health check failed: {}", e),
    }
    
    Ok(())
}
```

## Configuration


### Environment Variables


You can configure the client using environment variables:

```bash
export GITDB_TOKEN="your-github-token"
export GITDB_OWNER="your-github-username"
export GITDB_REPO="your-repo-name"
export GITDB_SERVER_URL="http://localhost:7896"
```

### Custom HTTP Client


The client uses `reqwest` with a 30-second timeout by default. You can customize this:

```rust
let client = GitDBClient::with_url(token, owner, repo, base_url);
client.set_base_url("http://custom-server:7896");
```

## Testing


Run the tests:

```bash
cargo test
```

## Examples


See the `examples/` directory for more detailed examples:

- Basic usage
- Advanced queries
- GraphQL operations
- Error handling
- Batch operations

## Dependencies


- `reqwest` - HTTP client
- `tokio` - Async runtime
- `serde` - Serialization/deserialization
- `serde_json` - JSON handling
- `anyhow` - Error handling

## License


MIT License - see LICENSE file for details.

## Authors


- AFOT Team <team@afot.com>
- karthikeyanV2K <karthikeyan@afot.com>

## Repository


https://github.com/karthikeyanV2K/GitDB