Usage Guide

This section will guide you through the basic usage of QuantumCacheDB for Dart and Flutter projects, including common operations like storing, retrieving, updating, and deleting data.

Setting Up the Database

Before performing any operations, you need to initialize the QuantumCacheDB database. Here’s how you can do that:

Dart Project

import 'package:quantum_cache_db/quantum_cache_db.dart';

void main() {
  final db = QuantumCacheDB();
  db.init(); // Initialize the database
}

Flutter Project

import 'package:flutter/material.dart';
import 'package:quantum_cache_db/quantum_cache_db.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('QuantumCacheDB Example')),
        body: Center(
          child: ElevatedButton(
            onPressed: () {
              final db = QuantumCacheDB();
              db.init(); // Initialize the database
            },
            child: Text('Initialize QuantumCacheDB'),
          ),
        ),
      ),
    );
  }
}

Once the database is initialized, you can perform various operations such as storing, retrieving, updating, and deleting data.

Basic Operations

1. Storing Data

You can store data in QuantumCacheDB using the set method. The data is saved as key-value pairs.

Example: Storing Data

// Storing a simple key-value pair
db.set('user_1', {'name': 'John Doe', 'age': 30});

// Storing a more complex object
db.set('product_1', {
  'id': 101,
  'name': 'Laptop',
  'price': 1500,
});

2. Retrieving Data

To retrieve data from QuantumCacheDB, use the get method. It will return the data stored under the specified key.

Example: Retrieving Data

// Retrieving a value by key
var user = db.get('user_1');
print(user); // Output: {'name': 'John Doe', 'age': 30}

// Retrieving a more complex object
var product = db.get('product_1');
print(product); // Output: {'id': 101, 'name': 'Laptop', 'price': 1500}

3. Updating Data

Updating data is similar to storing new data. You can simply use the set method with the same key, and the existing data will be overwritten with the new value.

Example: Updating Data

// Updating a user's age
var updatedUser = {'name': 'John Doe', 'age': 31};
db.set('user_1', updatedUser);

// Updating a product price
var updatedProduct = {
  'id': 101,
  'name': 'Laptop',
  'price': 1400, // New price
};
db.set('product_1', updatedProduct);

4. Deleting Data

To delete a record from the database, use the delete method with the key you wish to remove.

Example: Deleting Data

// Deleting a record by key
db.delete('user_1');

// Deleting a more complex object
db.delete('product_1');

5. Checking if Data Exists

You can check whether a key exists in the database by using the containsKey method.

Example: Checking for Existence

bool userExists = db.containsKey('user_1');
print(userExists); // Output: true or false

bool productExists = db.containsKey('product_1');
print(productExists); // Output: true or false

Advanced Usage

Using Collections

If you are working with a collection of data, you can store each item in the collection under a specific key and retrieve it as needed.

// Storing a collection
List<Map<String, dynamic>> users = [
  {'name': 'John Doe', 'age': 30},
  {'name': 'Jane Smith', 'age': 25},
];

for (int i = 0; i < users.length; i++) {
  db.set('user_${i + 1}', users[i]);
}

// Retrieving a collection
for (int i = 0; i < users.length; i++) {
  var user = db.get('user_${i + 1}');
  print(user);
}

Using Reactive Streams

For real-time updates, you can use QuantumCacheDB's reactive data model with streams. This allows you to listen for changes to a key and update your UI or application logic accordingly.

Example: Using Streams

Stream<Map<String, dynamic>> userStream = db.watch('user_1');
userStream.listen((user) {
  print('User data updated: $user');
});

This stream will emit updates every time the data for the user_1 key is changed.

Conclusion

Now that you've learned the basic operations of QuantumCacheDB, you can efficiently store, retrieve, update, and delete data within your application. In addition, you can also utilize streams to build reactive applications where data changes are reflected in real-time.

For more advanced features, check out the following documentation pages or visit the QuantumCacheDB GitHub repository for community discussions, feature requests, and contributions.