FlowDB

A lightweight, reactive local database package for Flutter and Dart that provides simple key-value storage with optional encryption, background processing, and reactive state management.

Features

  • πŸ—„οΈ Simple Key-Value Storage: Store and retrieve data using simple key-value pairs
  • 🌐 Cross-Platform: Works on both mobile (file-based) and web (localStorage)
  • πŸ”’ Optional Encryption: Secure your data with built-in encryption support
  • ⚑ Background Processing: Optional background worker for non-blocking operations
  • πŸ”„ Reactive State Management: Built-in reactive state with FlowState and FlowBuilder
  • πŸ“ Nested Keys: Support for nested data structures using dot notation (e.g., user.profile.name)
  • πŸ“Š File Size Tracking: Monitor your database file size

Getting started

Installation

Add flowdb to your pubspec.yaml:

dependencies:
  flowdb: ^0.0.1

Then run:

flutter pub get

Import

import 'package:flowdb/flowdb.dart';

Usage

Basic Setup

Create a FlowDB instance:

final db = FlowDB(
  fileName: "data.json",        // Database file name (optional)
  dir: "data",                  // Directory path (mobile and desktop only) (optional)
  encrypted: true,              // Enable encryption (optional)
  secretKey: "your-secret-key", // Encryption key (optional)
  useBG: false,                 // Use background worker (optional)
  useState: true,               // Enable reactive state (optional)
);

Basic Operations

Set and Get Values

// Set a value
await db.set("username", "john_doe");
await db.set("age", 25);

await db.setFrom("username", (username) => username.toUppercase());

// Get a value
String? username = await db.get("username");
int? age = await db.get("age");

Nested Keys

FlowDB supports nested keys using dot notation:

// Set nested values
await db.set("user.profile.name", "John Doe");
await db.set("user.profile.email", "john@example.com");
await db.set("user.settings.theme", "dark");

// Get nested values
String? name = await db.get("user.profile.name");
String? email = await db.get("user.profile.email");

Check and Delete

// Check if a key exists
bool exists = await db.has("username");

// Delete a key
await db.delete("username");

// Clear all data
await db.clear();

Read and Write Entire Database

// Write entire database
await db.write({
  "user": {
    "name": "John",
    "age": 25
  }
});

// Read entire database
Map<String, dynamic>? allData = await db.read();

Reactive State Management

FlowDB provides reactive state management for building responsive UIs.

Setup Reactive State

// Initialize with database value
final counterState = await db.addListenerAndUseDB("counter", 0);

// Or initialize with a default value
final counterState = db.addListener("counter", 0);

Use in Flutter Widgets

import 'package:flowdb/flowdb.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return FlowBuilder<int>(
      flow: db.states['counter']!,
      builder: (data) {
        return Text('Counter: $data');
      },
    );
  }
}

Update Reactive State

// Update the value - this will automatically update the UI
await db.set("counter", 10);

// Or update the state directly
db.states['counter']?.update(10);

Complete Example

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

// Initialize database
final db = FlowDB(
  useState: true,
  dir: "data",
  fileName: "data.json",
  encrypted: true,
  secretKey: "my-secret-key",
);

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'FlowDB Demo',
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    super.initState();
    // Initialize reactive state from database
    db.addListenerAndUseDB("counter", 0);
  }

  void _incrementCounter() async {
    final current = await db.get("counter") ?? 0;
    await db.set("counter", current + 1);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('FlowDB Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text('You have pushed the button this many times:'),
            FlowBuilder<int>(
              flow: db.states['counter']!,
              builder: (data) {
                return Text(
                  '$data',
                  style: Theme.of(context).textTheme.headlineMedium,
                );
              },
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

File Size Information

// Get file size in bytes
int size = await db.fileSize;

// Get formatted file size (B, KB, MB, GB)
String formattedSize = await db.fileSizeFormatted;
print("Database size: $formattedSize");

Synchronous Version

For synchronous operations, use FlowDBSync:

final dbSync = FlowDBSync(
  name: "data.json",
  dir: "data",
  encrypted: true,
  secretKey: "my-secret-key",
);

// Synchronous operations
dbSync.set("key", "value");
dynamic value = dbSync.get("key");
dbSync.delete("key");

Configuration Options

Parameter Type Default Description
fileName String? Auto-generated Database file name
dir String? "./" Directory path (mobile only)
isWeb bool? Auto-detected Force web mode
encrypted bool? false Enable encryption
secretKey String? Default key Encryption secret key
useBG bool? false Use background worker
useState bool? false Enable reactive state

Additional information

FlowDB is a simple yet powerful local database solution for Flutter applications. It's perfect for storing user preferences, app settings, cached data, and more.

For issues, feature requests, or contributions, please visit the package repository.

Libraries

flowdb