abstractdb

A flexible, lightweight, and hierarchical document database abstraction layer for Dart and Flutter. It provides an intuitive API for collection-based operations, query filtering, sorting, custom indexing, reactivity, and replication with pluggable persistence providers (such as Sembast, Supabase, or in-memory storage).

Features

• Document-Based Collections: Store and retrieve JSON-compatible documents in collections.
• Pluggable Persistence: Use the built-in SembastPersistence for encrypted local file storage, or implement your own PersistenceProvider (e.g., custom SQLite/SQL backends).
• Reactive Data Streams: Subscribe to data changes at both the Collection level and the Cursor query level. Integration with standard Dart ValueNotifier and signals.
• Custom Indexing: Optimize queries using UniqueEqualityIndex, NonUniqueEqualityIndex, and TextIndexer.
• Flexible Queries: Rich filtering DSL (eq, neq, gt, gte, lt, lte, contains, etc.) combined with sorting, pagination, and limits.
• Data Replication: Seamlessly synchronize local collections with remote backends like Supabase using realtime channels.

Getting started

Add the package to your pubspec.yaml dependencies:

dependencies:
  abstractdb: ^1.0.0

To run with Sembast local persistence, add sembast dependency if you need additional configurations:

dependencies:
  sembast: ^3.8.7

Usage

Below is a quick example of initializing AbstractDb, creating a collection with a unique index, saving records, querying them, and closing the connection.

import 'package:abstractdb/abstractdb.dart';

void main() async {
  // 1. Initialize AbstractDb with our collections. By default, it operates in-memory.
  final db = AbstractDb(
    name: 'sample_db',
    collections: [
      Collection(
        name: 'users',
        indexes: [
          UniqueEqualityIndex(name: 'username_idx', fields: ['username']),
        ],
      ),
    ],
  );

  await db.ensureInitialized;
  print('Database "${db.name}" initialized successfully.');

  // 2. Retrieve the collection
  final usersCollection = db.collection('users')!;

  // 3. Save documents
  final doc1 = Document<String>({
    'username': 'alice',
    'role': 'Admin',
    'age': 30,
  });
  final doc2 = Document<String>({
    'username': 'bob', 
    'role': 'User', 
    'age': 25,
  });

  await usersCollection.save(doc1);
  await usersCollection.save(doc2);

  // 4. Query using filters and sorting
  final query = Query('role'.eq('User'), sort: [('age', true)], limit: 1);
  final cursor = await usersCollection.find(query);
  final results = await cursor.exec();
  
  print('Found users: $results');

  // 5. Cleanup and dispose database
  await db.dispose();
}

Check the example/ folder for a more comprehensive walkthrough including exception handling and index verification.

Additional information

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the repository at https://github.com/jessicamr/abstractdb if you find bugs or want to request new features.

License

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