🗃️ Offline First Core

High-performance LMDB-based local storage library optimized for FFI integration with Flutter and cross-platform applications.

✨ Features

• 🚀 LMDB-powered - Battle-tested database engine used by Bitcoin Core and OpenLDAP
• 📱 Flutter-ready - Hot restart compatible FFI interface
• ⚡ High performance - Zero-copy reads and ACID transactions
• 🔄 Cross-platform - Works on iOS, Android, Windows, macOS, and Linux
• 📦 Simple API - Only 9 functions to learn

🚀 Quick Start

Flutter Integration

import 'dart:ffi';
import 'dart:convert';

// 1. Load the native library
final dylib = DynamicLibrary.open('liboffline_first_core.so');

// 2. Define FFI functions
typedef CreateDbNative = Pointer Function(Pointer<Utf8>);
typedef CreateDb = Pointer Function(Pointer<Utf8>);
final createDb = dylib.lookupFunction<CreateDbNative, CreateDb>('create_db');

// 3. Use the database
final dbPointer = createDb("my_app_database".toNativeUtf8());

final jsonData = jsonEncode({
  "id": "user_123",
  "hash": "content_hash",
  "data": {"name": "John Doe", "email": "john@example.com"}
});

final result = pushData(dbPointer, jsonData.toNativeUtf8());

Rust Direct Usage

use offline_first_core::{AppDbState, LocalDbModel};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize database
    let db = AppDbState::init("my_database".to_string())?;

    // Create and store data
    let user = LocalDbModel {
        id: "user_123".to_string(),
        hash: "content_hash".to_string(),
        data: json!({"name": "John Doe", "email": "john@example.com"}),
    };

    db.push(user)?;

    // Retrieve data
    let user = db.get_by_id("user_123")?.unwrap();
    println!("User: {}", user.data["name"]);

    Ok(())
}

📚 API Reference

Core Functions

Data Model

pub struct LocalDbModel {
    pub id: String,      // Unique identifier (cannot be empty)
    pub hash: String,    // Content hash for versioning
    pub data: JsonValue, // Your JSON data
}

🎯 Usage Examples

1. User Preferences

use offline_first_core::{AppDbState, LocalDbModel};
use serde_json::json;

fn save_preferences() -> Result<(), Box<dyn std::error::Error>> {
    let db = AppDbState::init("user_settings".to_string())?;
    
    let preferences = LocalDbModel {
        id: "app_preferences".to_string(),
        hash: "v1.0".to_string(),
        data: json!({
            "theme": "dark",
            "language": "en",
            "notifications": true
        }),
    };
    
    db.push(preferences)?;
    Ok(())
}

2. Shopping Cart

fn add_to_cart(product_id: &str, quantity: i32) -> Result<(), Box<dyn std::error::Error>> {
    let db = AppDbState::init("shopping_cart".to_string())?;
    
    let item = LocalDbModel {
        id: product_id.to_string(),
        hash: format!("cart_{}", chrono::Utc::now().timestamp()),
        data: json!({
            "product_id": product_id,
            "quantity": quantity,
            "price": 29.99
        }),
    };
    
    db.push(item)?;
    Ok(())
}

3. Offline Cache

fn cache_article(article_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
    let db = AppDbState::init("article_cache".to_string())?;
    
    let article = LocalDbModel {
        id: article_id.to_string(),
        hash: format!("article_{}", md5::compute(content)),
        data: json!({
            "title": "Article Title",
            "content": content,
            "cached_at": chrono::Utc::now().to_rfc3339()
        }),
    };
    
    db.push(article)?;
    Ok(())
}

🔧 Advanced Usage

Error Handling

use offline_first_core::{AppDbState, AppResponse};

match db.push(model) {
    Ok(_) => println!("✅ Success"),
    Err(AppResponse::DatabaseError(msg)) => eprintln!("💾 Database error: {}", msg),
    Err(AppResponse::SerializationError(msg)) => eprintln!("📝 JSON error: {}", msg),
    Err(AppResponse::NotFound(msg)) => eprintln!("🔍 Not found: {}", msg),
    Err(other) => eprintln!("🔥 Other error: {}", other),
}

Batch Operations

fn bulk_insert(records: Vec<LocalDbModel>) -> Result<usize, Box<dyn std::error::Error>> {
    let db = AppDbState::init("bulk_data".to_string())?;
    let mut success_count = 0;
    
    for model in records {
        if db.push(model).is_ok() {
            success_count += 1;
        }
    }
    
    Ok(success_count)
}

Hot Restart (Flutter)

class DatabaseManager {
  static Pointer? _dbPointer;
  
  static void initDatabase() {
    _dbPointer = createDb("my_app_db".toNativeUtf8());
  }
  
  static void closeDatabase() {
    if (_dbPointer != null) {
      closeDatabase(_dbPointer!);
      _dbPointer = null;
    }
  }
}

🛠️ Setup

Installation

Add to your Cargo.toml:

[dependencies]
offline_first_core = "0.3.0"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

For FFI projects:

[lib]
name = "my_storage_lib"
crate-type = ["staticlib", "cdylib"]

Building

# Debug build
cargo build

# Release build
cargo build --release

# Cross-platform builds
cargo build --target aarch64-apple-ios --release        # iOS
cargo build --target aarch64-linux-android --release    # Android
cargo build --target x86_64-pc-windows-msvc --release   # Windows

⚠️ Important Notes

LMDB Limitations

// ❌ Empty IDs not supported
let invalid = LocalDbModel {
    id: "".to_string(), // Will fail!
    // ...
};

// ✅ Always use non-empty IDs
let valid = LocalDbModel {
    id: "user_123".to_string(), // Good!
    // ...
};

Memory Safety (FFI)

// ✅ Always check null pointers
void* db = create_db("my_db");
if (db == NULL) {
    // Handle error
    return;
}

// ✅ Free returned strings
const char* result = get_by_id(db, "user_1");
if (result != NULL) {
    // Use result...
    free((void*)result); // Important!
}

Performance Tips

// ✅ DO: Reuse connections
let db = AppDbState::init("my_db".to_string())?;
for i in 0..1000 {
    db.push(create_model(i))?; // Efficient
}

// ❌ DON'T: Create new connections
for i in 0..1000 {
    let db = AppDbState::init("my_db".to_string())?; // Slow!
    db.push(create_model(i))?;
}

🧪 Testing

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_basic_crud() {
        let db = AppDbState::init("test_db".to_string()).unwrap();
        
        let model = LocalDbModel {
            id: "test_1".to_string(),
            hash: "test_hash".to_string(),
            data: json!({"name": "Test User"}),
        };
        
        // Insert
        assert!(db.push(model).is_ok());
        
        // Read
        let retrieved = db.get_by_id("test_1").unwrap();
        assert!(retrieved.is_some());
        
        // Update
        let mut updated = retrieved.unwrap();
        updated.data["name"] = json!("Updated User");
        assert!(db.update(updated).is_ok());
        
        // Delete
        assert!(db.delete_by_id("test_1").unwrap());
    }
}

📦 Integration Examples

Flutter Plugin

// pubspec.yaml
dependencies:
  ffi: ^2.0.0

// lib/database.dart
import 'dart:ffi';
import 'dart:io';

class NativeDatabase {
  late DynamicLibrary _lib;
  
  NativeDatabase() {
    if (Platform.isAndroid) {
      _lib = DynamicLibrary.open('liboffline_first_core.so');
    } else if (Platform.isIOS) {
      _lib = DynamicLibrary.process();
    }
  }
  
  // Define your FFI functions here...
}

React Native

// Install react-native-ffi
npm install react-native-ffi

// Use the library
import { NativeModules } from 'react-native';
const { OfflineFirstCore } = NativeModules;

async function saveData(id, data) {
  const result = await OfflineFirstCore.pushData(id, JSON.stringify(data));
  return JSON.parse(result);
}

📋 Changelog

v0.3.0 - LMDB Migration

• ✨ Migrated from redb to LMDB
• ✨ Added close_database() function
• 🐛 Fixed Flutter hot restart issues
• 🔧 Improved error handling
• 📚 Added comprehensive test suite (60+ tests)

v0.2.0 - Feature Expansion

• ✨ Added clear_all_records() and reset_database()
• 🔧 Improved error handling
• 🛡️ Enhanced FFI safety

v0.1.0 - Initial Release

• ✨ Basic CRUD operations
• 🔌 FFI interface for cross-platform integration

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• LMDB team for the robust database engine
• redb project for inspiration
• Rust community for excellent FFI tools

Made with ❤️ for developers who need reliable offline storage

⭐ Star on GitHub • 📦 View on Crates.io • 📖 Read the Docs