work_db #

A lightweight, cross-platform local database for Dart and Flutter. Simple key-value storage organized in collections, with support for Desktop, Web, and Mobile platforms.

Features #

• ✅ Cross-platform: Works on Windows, macOS, Linux, Web, iOS, and Android
• ✅ Simple API: Easy-to-use CRUD operations
• ✅ Collections: Organize data in named collections
• ✅ Batch operations: Create, retrieve, and update multiple items at once
• ✅ Type-safe: Full Dart type safety with generics
• ✅ No dependencies: Minimal footprint (only path package for IO)
• ✅ Well tested: 99 tests across all implementations

Installation #

dependencies:
  work_db: ^1.0.0

Quick Start #

import 'package:work_db/work_db.dart';

void main() async {
  // Create a database instance
  final db = WorkDbFactory.forIo(dataPath: './data');
  
  // Create an item
  await db.create(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Doe', 'email': 'john@example.com'},
  ));
  
  // Retrieve the item
  final user = await db.retrieve(ItemId(id: 'user-1', collection: 'users'));
  print(user?.item['name']); // John Doe
  
  // Update the item
  await db.update(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Doe', 'email': 'john.updated@example.com'},
  ));
  
  // Delete the item
  await db.delete(ItemId(id: 'user-1', collection: 'users'));
}

Platform-Specific Setup #

Desktop (Windows, macOS, Linux) & Server #

import 'package:work_db/work_db.dart';

final db = WorkDbFactory.forIo(dataPath: './my_app_data');

Web #

import 'package:work_db/work_db.dart';

// Uses localStorage under the hood
final db = WorkDbFactory.forWeb();

Flutter Mobile (iOS, Android) #

import 'package:work_db/work_db.dart';
import 'package:path_provider/path_provider.dart';

Future<IWorkDb> createDatabase() async {
  final dir = await getApplicationDocumentsDirectory();
  return WorkDbFactory.forIo(dataPath: dir.path);
}

Testing #

import 'package:work_db/work_db.dart';

// In-memory storage, perfect for unit tests
final db = WorkDbFactory.forMemory();

API Reference #

Factory Methods #

Database Operations #

Examples #

Batch Operations #

// Create multiple items at once
await db.createMultiple([
  ItemWithId(id: 'user-1', collection: 'users', item: {'name': 'Alice'}),
  ItemWithId(id: 'user-2', collection: 'users', item: {'name': 'Bob'}),
  ItemWithId(id: 'user-3', collection: 'users', item: {'name': 'Charlie'}),
]);

// Retrieve multiple items
final users = await db.retrieveMultiple([
  ItemId(id: 'user-1', collection: 'users'),
  ItemId(id: 'user-2', collection: 'users'),
]);

Upsert (Create or Update) #

// Creates if not exists, updates if exists
await db.createOrUpdate(ItemWithId(
  id: 'settings',
  collection: 'config',
  item: {'theme': 'dark', 'language': 'en'},
));

Collection Management #

// List all collections
final collections = await db.getCollections();
print(collections); // ['users', 'config', 'posts']

// List items in a collection
final userIds = await db.getItemsInCollection('users');
print(userIds); // ['user-1', 'user-2', 'user-3']

// Delete entire collection
await db.deleteCollection('cache');

// Clear everything
await db.clearDatabase();

Nested Data #

await db.create(ItemWithId(
  id: 'post-1',
  collection: 'posts',
  item: {
    'title': 'Hello World',
    'content': 'This is my first post',
    'author': {
      'name': 'John',
      'email': 'john@example.com',
    },
    'tags': ['dart', 'flutter', 'database'],
    'metadata': {
      'views': 0,
      'likes': 0,
      'published': true,
    },
  },
));

Storage Format #

Data is stored as JSON files in a simple directory structure:

<dataPath>/
└── WorkDB/
    ├── users/
    │   ├── user-1    (JSON file)
    │   └── user-2    (JSON file)
    └── posts/
        └── post-1    (JSON file)

Error Handling #

try {
  await db.create(ItemWithId(
    id: 'duplicate',
    collection: 'test',
    item: {'data': 'value'},
  ));
  
  // This will throw - item already exists
  await db.create(ItemWithId(
    id: 'duplicate',
    collection: 'test',
    item: {'data': 'new value'},
  ));
} catch (e) {
  print('Error: $e');
}

// Use createOrUpdate to avoid exceptions
await db.createOrUpdate(ItemWithId(
  id: 'safe',
  collection: 'test',
  item: {'data': 'value'},
));

Testing Your Code #

import 'package:test/test.dart';
import 'package:work_db/work_db.dart';

void main() {
  late IWorkDb db;

  setUp(() {
    // Fresh in-memory database for each test
    db = WorkDbFactory.createMemory();
  });

  test('should store and retrieve data', () async {
    await db.create(ItemWithId(
      id: 'test-1',
      collection: 'test',
      item: {'value': 42},
    ));

    final result = await db.retrieve(ItemId(id: 'test-1', collection: 'test'));
    expect(result?.item['value'], equals(42));
  });
}

License #

MIT License - see LICENSE for details.

Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.