📦 unified_local_data

A universal, engine-agnostic local database abstraction layer for Flutter.
Swap between Hive, Isar, or any future engine — without changing a single line of your app logic.

Table of Contents

• Overview
• Why unified_local_data?
• Architecture
• Supported Engines
• Installation
• Quick Start
  • Initialize with Hive
  • Initialize with Isar
• Core API Reference
  • Primitives (put / get / delete)
  • Complex Objects (Generic Path)
  • Batch Operations
  • Collection Utilities
  • Reactive Streams
  • Query Builder
  • Transactions
• Native Engine Access
  • Understanding the Two Paths
  • NativeCollectionAccessor API
  • Hive — Native TypeAdapter Flow
  • Isar — Native @collection Flow
  • Isar — Raw Instance Access
  • When to Use Which Path
• Swapping Engines
• Extending with a New Engine
• Error Handling
• Stream Extensions
• Design Patterns
• Folder Structure
• FAQ
• License

Overview

unified_local_data is a production-grade Dart package that provides a single, unified interface for all local database operations in Flutter apps. It decouples your application logic from any specific database engine using the Strategy Pattern, enabling you to switch between Hive CE and Isar Community — or plug in any future engine — with zero refactoring.

The package offers two data access paths:

• Generic Path — Engine-agnostic put/get/putObject API using JSON serialization. Fully portable across all engines.
• Native Path — Direct access to engine-native features like Hive TypeAdapter and Isar @collection with full index, binary speed, and native query support.

Why unified_local_data?

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                        │
├─────────────────────────┬────────────────────────────────────┤
│   Generic Path          │   Native Path                     │
│   (Portable)            │   (Full Engine Power)             │
│                         │                                    │
│   LocalDataSource       │   NativeCollectionAccessor<T>     │
│   put/get/putObject     │   Hive: full TypeAdapter          │
│   via JSON              │   Isar: full @collection          │
└────────────┬────────────┴──────────────┬─────────────────────┘
             │                           │
             ▼                           ▼
┌──────────────────────────────────────────────────────────────┐
│              LocalDataSourceFactory.create()                  │
│          (Singleton · Strategy Selection · Init)             │
└────────────┬──────────────────────────────┬──────────────────┘
             │                              │
             ▼                              ▼
┌────────────────────────────┐  ┌───────────────────────────────┐
│     HiveDataSource         │  │     IsarDataSource            │
│     implements             │  │     implements                │
│     LocalDataSource        │  │     LocalDataSource           │
│                            │  │                               │
│  ┌──────────────────────┐  │  │  ┌─────────────────────────┐  │
│  │ Generic: Box<dynamic>│  │  │  │ Generic: IsarKvEntry    │  │
│  │ Native: Box<T>       │  │  │  │ Native: IsarCollection  │  │
│  │ + TypeAdapter        │  │  │  │ + @collection           │  │
│  └──────────────────────┘  │  │  └─────────────────────────┘  │
└────────────────────────────┘  └──────────────────────��────────┘
             │                              │
             ▼                              ▼
┌──────────────────────────────────────────────────────────────┐
│                    FUTURE ENGINE SLOT                         │
│         DriftDataSource / SqfliteDataSource / etc.           │
│         implements LocalDataSource                           │
└──────────────────────────────────────────────────────────────┘

Supported Engines

Installation

Add the following to your pubspec.yaml:

dependencies:
  unified_local_data:
    path: packages/unified_local_data  # or your git/pub reference

The package bundles both Hive CE and Isar Community internally. You do not need to add them separately.

Quick Start

Initialize with Hive

import 'package:unified_local_data/local_data_source.dart';
import 'package:path_provider/path_provider.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final dir = await getApplicationDocumentsDirectory();

  final db = await LocalDataSourceFactory.create(
    LocalDataSourceConfig.hive(
      directory: dir.path,
      preloadBoxes: ['settings', 'cache'],
    ),
  );

  await db.put<String>('settings', 'language', 'en');
  final language = await db.get<String>('settings', 'language');
}

Initialize with Isar

import 'package:unified_local_data/local_data_source.dart';
import 'package:path_provider/path_provider.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final dir = await getApplicationDocumentsDirectory();

  final db = await LocalDataSourceFactory.create(
    LocalDataSourceConfig.isar(
      directory: dir.path,
      schemas: [],
      maxSizeMiB: 512,
      inspector: true,
    ),
  );

  await db.put<int>('analytics', 'launch_count', 42);
  final count = await db.get<int>('analytics', 'launch_count');
}

That's it. The rest of your code uses the same LocalDataSource API regardless of which engine is active.

Core API Reference

All methods are available on the LocalDataSource interface returned by LocalDataSourceFactory.create().

Primitives

Store and retrieve simple Dart types (String, int, double, bool, List, Map).

await db.put<String>('settings', 'theme', 'dark');

final theme = await db.get<String>('settings', 'theme');

await db.delete('settings', 'theme');

await db.deleteAll('settings', ['theme', 'locale']);

await db.clear('settings');

await db.drop(collection: 'settings');

await db.drop();

clear vs drop: clear empties a collection but keeps it available for reuse. drop removes the collection itself — on Hive it deletes the box file from disk, on Isar it deletes every entry belonging to that collection. Calling drop() with no argument wipes the entire database.

Complex Objects (Generic Path)

Use DataModelAdapter<T> to serialize/deserialize any custom Dart object. This path stores objects as JSON strings, making it fully portable across all engines.

Tip: If your model class already implements toJson/fromJson, you can optionally have it implement the DataModel<T> interface as a marker contract:

abstract interface class DataModel<T> {
  JsonMap toJson();
  T fromJson(JsonMap json);
}

The adapter (DataModelAdapter<T>) is what the API actually uses; DataModel<T> is an optional structural contract you can adopt for consistency.

Step 1 — Define your model:

class User {
  final String id;
  final String name;
  final String email;

  const User({required this.id, required this.name, required this.email});

  factory User.fromJson(Map<String, dynamic> json) => User(
        id: json['id'] as String,
        name: json['name'] as String,
        email: json['email'] as String,
      );

  Map<String, dynamic> toJson() => {'id': id, 'name': name, 'email': email};
}

Step 2 — Create an adapter:

final userAdapter = DataModelAdapter<User>(
  fromJson: User.fromJson,
  toJson: (user) => user.toJson(),
);

Step 3 — Store and retrieve:

final user = User(id: '1', name: 'Yasin', email: 'yasin@example.com');

await db.putObject<User>('users', 'user_1', user, userAdapter);

final retrieved = await db.getObject<User>('users', 'user_1', userAdapter);

final allUsers = await db.getAllObjects<User>('users', userAdapter);

Batch Operations

Write multiple entries in a single call for better performance.

await db.putAll<String>('settings', {
  'theme': 'dark',
  'language': 'en',
  'font_size': '16',
});

await db.putAllObjects<User>('users', {
  'user_1': User(id: '1', name: 'Yasin', email: 'yasin@example.com'),
  'user_2': User(id: '2', name: 'Ali', email: 'ali@example.com'),
}, userAdapter);

Collection Utilities

final keys = await db.getAllKeys('users');

final exists = await db.containsKey('users', 'user_1');

final total = await db.count('users');

final allValues = await db.getAll<String>('settings');

Reactive Streams

Subscribe to real-time changes on keys, collections, or object collections.

db.watch<String>('settings', 'theme').listen((value) {
  print('Theme changed to: $value');
});

db.watchObject<User>('users', 'user_1', userAdapter).listen((user) {
  print('User changed: ${user?.name}');
});

db.watchAll<String>('settings').listen((values) {
  print('Settings updated: $values');
});

db.watchAllObjects<User>('users', userAdapter).listen((users) {
  print('Users updated: ${users.length}');
});

All streams emit the current value immediately upon subscription, then emit on every subsequent change.

Query Builder

Build fluent, chainable queries with filtering, sorting, pagination, and reactive watching.

final activeUsers = await db
    .query<User>('users', userAdapter)
    .where((user) => user.name.startsWith('Y'))
    .sortBy((a, b) => a.name.compareTo(b.name))
    .limit(20)
    .offset(0)
    .findAll();

final firstMatch = await db
    .query<User>('users', userAdapter)
    .where((user) => user.email.contains('@example.com'))
    .findFirst();

final total = await db
    .query<User>('users', userAdapter)
    .where((user) => user.id.isNotEmpty)
    .count();

db.query<User>('users', userAdapter)
    .where((user) => user.name.contains('Yasin'))
    .sortBy((a, b) => a.name.compareTo(b.name))
    .limit(10)
    .watch()
    .listen((users) {
  print('Matching users: ${users.length}');
});

Transactions

Wrap multiple operations in a transaction for atomicity.

await db.transaction(() async {
  await db.put<String>('settings', 'theme', 'dark');
  await db.put<String>('settings', 'language', 'en');
  await db.putObject<User>('users', 'user_1', newUser, userAdapter);
});

Hive: Operations are executed sequentially (Hive has no native transaction support).

Isar: Operations are wrapped in a native writeTxn for true ACID compliance.

Native Engine Access

Understanding the Two Paths

The package provides two distinct ways to store complex objects:

┌──────────────────────────────────────────────────────────────────────┐
│                        DECISION FLOWCHART                            │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Need to swap engines freely across projects?                        │
│  ├─ YES → Use Generic Path                                          │
│  │        db.putObject / db.getObject                                │
│  │        Uses DataModelAdapter<T> + JSON serialization              │
│  │        ✅ Works on ALL engines without changes                    │
│  │        ⚠️ No engine-native indexes or binary speed                │
│  │                                                                   │
│  └─ NO → Engine is fixed for this project?                           │
│     ├─ YES → Use Native Path                                         │
│     │        db.native<T>('collection')                              │
│     │        ✅ Full Hive TypeAdapter support                        │
│     │        ✅ Full Isar @collection + indexes                     │
│     │        ✅ Binary speed, zero JSON overhead                    │
│     │        ⚠️ Models are engine-specific                           │
│     │                                                                │
│     └─ Need Isar's full .filter().sortBy() generated DSL?           │
│        └─ Cast to IsarDataSource, use rawInstance                    │
│           ✅ Complete Isar native query power                       │
│           ❌ Completely tied to Isar                                │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

NativeCollectionAccessor API

The NativeCollectionAccessor<T> interface provides a unified API for working with engine-native models:

Hive — Native TypeAdapter Flow

Use Hive's native TypeAdapter for maximum binary serialization speed.

Step 1 — Define your Hive model:

import 'package:hive_ce/hive_ce.dart';

part 'user_entity.g.dart';

@HiveType(typeId: 1)
class UserEntity extends HiveObject {
  @HiveField(0)
  final String id;

  @HiveField(1)
  final String name;

  @HiveField(2)
  final String email;

  @HiveField(3)
  final DateTime createdAt;

  UserEntity({
    required this.id,
    required this.name,
    required this.email,
    required this.createdAt,
  });
}

Step 2 — Run code generation:

dart run build_runner build --delete-conflicting-outputs

Step 3 — Register adapter, open typed box, and use:

import 'package:hive_ce/hive_ce.dart';
import 'package:unified_local_data/local_data_source.dart';
import 'package:path_provider/path_provider.dart';

import 'models/user_entity.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final dir = await getApplicationDocumentsDirectory();

  Hive.registerAdapter(UserEntityAdapter());

  final db = await LocalDataSourceFactory.create(
    LocalDataSourceConfig.hive(directory: dir.path),
  );

  final hiveDb = db as HiveDataSource;
  await hiveDb.openTypedBox<UserEntity>('users');

  final users = db.native<UserEntity>('users');

  await users.put(UserEntity(
    id: '1',
    name: 'Yasin',
    email: 'yasin@example.com',
    createdAt: DateTime.now(),
  ));

  await users.putAll([
    UserEntity(
      id: '2',
      name: 'Ali',
      email: 'ali@example.com',
      createdAt: DateTime.now(),
    ),
  ]);

  // NOTE: HiveNativeAccessor.putAll() uses box.addAll() — items are appended
  // with auto-incremented integer keys. For keyed upsert, call put() individually.

  final allUsers = await users.getAll();

  final yasin = await users.getById('1');

  users.watchAll().listen((userList) {
    print('Users changed: ${userList.length}');
  });

  final filtered = await users
      .query()
      .where((u) => u.name.startsWith('Y'))
      .sortBy((a, b) => a.createdAt.compareTo(b.createdAt))
      .limit(10)
      .findAll();
}

Isar — Native @collection Flow

Use Isar's native @collection annotation for full index and schema support.

Step 1 — Define your Isar model:

import 'package:isar_community/isar_community.dart';

part 'product_entity.g.dart';

@collection
class ProductEntity {
  Id id = Isar.autoIncrement;

  @Index()
  late String title;

  late double price;

  @Index(composite: [CompositeIndex('price')])
  late String category;

  late DateTime createdAt;
}

@embedded
class Address {
  late String street;
  late String city;
  late String zipCode;
}

Step 2 — Run code generation:

dart run build_runner build --delete-conflicting-outputs

Step 3 — Pass schemas at init and use:

import 'package:unified_local_data/local_data_source.dart';
import 'package:path_provider/path_provider.dart';

import 'models/product_entity.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final dir = await getApplicationDocumentsDirectory();

  final db = await LocalDataSourceFactory.create(
    LocalDataSourceConfig.isar(
      directory: dir.path,
      schemas: [ProductEntitySchema],
    ),
  );

  final products = db.native<ProductEntity>('products');

  await products.put(
    ProductEntity()
      ..title = 'Flutter Widget'
      ..price = 29.99
      ..category = 'Development'
      ..createdAt = DateTime.now(),
  );

  await products.putAll([
    ProductEntity()
      ..title = 'Dart Package'
      ..price = 9.99
      ..category = 'Development'
      ..createdAt = DateTime.now(),
    ProductEntity()
      ..title = 'UI Kit'
      ..price = 49.99
      ..category = 'Design'
      ..createdAt = DateTime.now(),
  ]);

  final allProducts = await products.getAll();

  final product = await products.getById(1);

  products.watchAll().listen((productList) {
    print('Products changed: ${productList.length}');
  });

  final expensive = await products
      .query()
      .where((p) => p.price > 20.0)
      .sortBy((a, b) => b.price.compareTo(a.price))
      .limit(5)
      .findAll();
}

Isar — Raw Instance Access

When you need Isar's full native query DSL — generated .filter(), .sortBy(), composite index queries — access the raw Isar instance directly:

import 'package:isar_community/isar_community.dart';
import 'package:unified_local_data/local_data_source.dart';

import 'models/product_entity.dart';

Future<void> advancedIsarQuery(LocalDataSource db) async {
  final isarDb = db as IsarDataSource;
  final isar = isarDb.rawInstance;

  final results = await isar.productEntitys
      .filter()
      .categoryEqualTo('Development')
      .and()
      .priceGreaterThan(10.0)
      .sortByPriceDesc()
      .limit(20)
      .findAll();

  isar.productEntitys
      .filter()
      .priceGreaterThan(50)
      .watch(fireImmediately: true)
      .listen((premiumProducts) {
    print('Premium products: ${premiumProducts.length}');
  });
}

⚠️ Warning: Using rawInstance ties your code directly to Isar. This should be limited to repository implementations where you have consciously chosen Isar as the engine.

When to Use Which Path

Swapping Engines

The entire point of this package — swap your database with one config change:

// Using Hive
final db = await LocalDataSourceFactory.create(
  LocalDataSourceConfig.hive(directory: dir.path),
);

// Switch to Isar — no other code changes needed (for Generic Path)
final db = await LocalDataSourceFactory.create(
  LocalDataSourceConfig.isar(directory: dir.path, schemas: []),
);

Swap at runtime:

// reset() calls dispose() on the current instance, then clears it
await LocalDataSourceFactory.reset();

await LocalDataSourceFactory.create(
  LocalDataSourceConfig.isar(directory: dir.path, schemas: []),
);

final db = LocalDataSourceFactory.instance;

You can also dispose a specific instance directly:

await db.dispose(); // closes the DB and frees all resources

Note: create() automatically disposes any existing instance before creating the new one, so you don't need to call reset() first when simply switching configs.

Code using the Generic Path (put/get/putObject) swaps seamlessly. Code using the Native Path (db.native<T>()) requires engine-specific models and may need adjustment when switching engines.

Extending with a New Engine

Adding a new database engine (e.g., Drift, Sqflite) requires zero changes to the core abstraction. This is the Open/Closed Principle in action.

Step 1 — Add the engine enum value:

enum DatabaseEngine { hive, isar, drift }

Step 2 — Create engine-specific config:

final class DriftDataSourceConfig extends LocalDataSourceConfig {
  final String databaseName;

  const DriftDataSourceConfig({
    required super.directory,
    required this.databaseName,
  }) : super(engine: DatabaseEngine.drift);
}

Step 3 — Implement the interface:

final class DriftDataSource implements LocalDataSource {
  final DriftDataSourceConfig config;

  DriftDataSource({required this.config});

  @override
  Future<void> init() async { /* Drift initialization */ }

  @override
  Future<void> put<T>(String collection, String key, T value) async { /* ... */ }

  @override
  NativeCollectionAccessor<T> native<T>(String collection) { /* ... */ }

  // ... implement all other methods
}

Step 4 — Register in the factory (one line):

final LocalDataSource dataSource = switch (config) {
  HiveDataSourceConfig() => HiveDataSource(config: config),
  IsarDataSourceConfig() => IsarDataSource(config: config),
  DriftDataSourceConfig() => DriftDataSource(config: config),
};

That's it. No existing code changes. Pure Open/Closed Principle.

Error Handling

The package uses a sealed exception hierarchy for exhaustive, compile-time checked error handling:

try {
  final value = await db.get<String>('settings', 'theme');
} on DataSourceNotInitializedException {
  // Database not initialized — call init() first
} on DataSourceReadException catch (e) {
  print('Read error: ${e.message}, cause: ${e.cause}');
} on DataSourceWriteException catch (e) {
  print('Write error: ${e.message}, cause: ${e.cause}');
} on DataNotFoundException catch (e) {
  // Requested data does not exist
} on UnsupportedOperationException catch (e) {
  // Operation not supported by current engine
} on LocalDataSourceException catch (e) {
  // Catch-all for any data source error
}

Stream Extensions

The package includes utility extensions for working with reactive streams:

import 'package:unified_local_data/local_data_source.dart';

db.watchAll<String>('settings')
    .debounceTime(Duration(milliseconds: 300))
    .listen((values) {
  print('Debounced update: $values');
});

db.watch<String>('settings', 'theme')
    .distinctUntilChanged()
    .listen((value) {
  print('Theme actually changed to: $value');
});

Design Patterns

Folder Structure

local_data_source/
├── pubspec.yaml
├── lib/
│   ├── local_data_source.dart                     # Public barrel export
│   └── src/
│       ├── core/
│       │   ├── local_data_source.dart             # Base abstract interface
│       │   ├── local_data_source_config.dart      # Unified configuration (abstract)
│       │   ├── local_data_source_factory.dart     # Factory entry point
│       │   ├── data_model.dart                    # DataModel<T> interface + DataModelAdapter<T>
│       │   ├── native_collection_accessor.dart    # Native engine access interface
│       │   ├── query_builder.dart                 # Abstract + in-memory query builder
│       │   ├── exceptions.dart                    # Sealed exception hierarchy
│       │   └── typedefs.dart                      # Shared type aliases
│       ├── engines/
│       │   ├── hive/
│       │   │   ├── hive_data_source.dart          # Hive implementation
│       │   │   ├── hive_native_accessor.dart      # Hive TypeAdapter accessor
│       │   │   └── hive_config.dart               # Hive-specific configuration
│       │   └── isar/
│       │       ├── isar_data_source.dart          # Isar implementation
│       │       ├── isar_native_accessor.dart      # Isar @collection accessor
│       │       ├── isar_config.dart               # Isar-specific configuration
│       │       ├── isar_kv_entry.dart             # Internal @collection for KV ops
│       │       └── isar_kv_entry.g.dart           # Generated Isar schema (build_runner)
│       └── extensions/
│           └── stream_extensions.dart             # Reactive stream utilities
└── test/
    └── local_data_source_test.dart

FAQ

Hive.registerAdapter(UserEntityAdapter());
final hiveDb = db as HiveDataSource;
await hiveDb.openTypedBox<UserEntity>('users');

LocalDataSourceConfig.isar(
  directory: dir.path,
  schemas: [ProductEntitySchema, OrderEntitySchema],
)

// Generic: app settings (portable)
await db.put<String>('settings', 'theme', 'dark');

// Native: domain entities (engine-optimized)
final products = db.native<ProductEntity>('products');
await products.put(myProduct);

// Isar
final isarDb = db as IsarDataSource;
final isar = isarDb.rawInstance;

// Hive — access typed boxes directly
final hiveDb = db as HiveDataSource;
final box = await hiveDb.openTypedBox<UserEntity>('users');

LocalDataSourceConfig.hive(
  directory: dir.path,
  encryption: HiveEncryptionConfig(key: mySecureKey),
);

// Dispose directly on the instance
await db.dispose();

// Or via the factory (also clears the singleton)
await LocalDataSourceFactory.reset();

try {
  await db.transaction(() async { /* ... */ });
} on UnsupportedOperationException {
  // Fallback: execute operations without transaction
}

License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with ❤️ for the Flutter community
One interface. Any engine. Zero rewrites.
_{Generic when you need portability. Native when you need power.}