work_db 1.3.0

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

work_db

A lightweight, cross-platform local database for Dart and Flutter with optional thread-safe locking. Simple key-value storage organized in collections, supporting Desktop, Web, Mobile platforms, and concurrent access scenarios.

Features

• Cross-platform: Windows, macOS, Linux, Web, iOS, Android
• Simple API: CRUD operations, batch, upsert
• Collections: Organize data in named collections
• Batch operations: Create, retrieve, update multiple items
• Type-safe: Full Dart type safety
• Thread-Safe Locking (New in 1.1.0): File-based locking with stale lock detection
  • ClientWorkDbLock for concurrent access protection
  • Automatic lock expiration (5000ms timeout)
  • Stale lock cleanup with configurable timeout
  • Lock information tracking (timestamp, user)
• Flexible Architecture: Choose ClientWorkDb (lightweight) or ClientWorkDbLock (thread-safe)
• Factory Pattern: Polymorphic factory with dedicated input types for each implementation
• Minimal dependencies: Only path for IO operations
• Synchronous API (New in 1.2.0): Full *Sync counterparts for all operations via IWorkDbSync
  • createSync, updateSync, retrieveSync, deleteSync, and all other operations available synchronously
  • ClientWorkDbLockSync for thread-safe synchronous operations
• Record Limit per Collection (New in 1.3.0): Optional maxRecordsPerCollection with automatic eviction of oldest records
• Well tested: 397 tests across all implementations + locking tests + full sync test coverage

Installation

dependencies:
  work_db: ^1.3.0

Quick Start

import 'package:work_db/work_db.dart';

void main() async {
  // Create a factory
  final factory = WorkDbFactory();

  // Create a database instance for desktop/server
  final db = factory.create(IoWorkDbFactoryInput(dataPath: './data'));

  // Create an item
  await db.create(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Doe', 'email': '[e-mail]'},
  ));

  // 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': '[e-mail]'},
  ));

  // Delete the item
  await db.delete(ItemId(id: 'user-1', collection: 'users'));
}

Thread-Safe Operations with Locking (New in 1.1.0)

For concurrent access across multiple clients or isolates, use ClientWorkDbLock for automatic lock management:

import 'package:work_db/work_db.dart';

void main() async {
  // Create a locked database instance for thread-safe operations
  final db = ClientWorkDbLock(IoWorkDb('./data'));

  // All operations are protected by file locks
  await db.create(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Doe'},
  ));

  // Locks are automatically acquired and released
  await db.update(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Smith'},
  ));
}

Locking Features

• Automatic Lock Management: Locks are acquired at operation start and released after completion
• Stale Lock Cleanup: Expired locks are automatically detected and cleaned up
• Lock Expiration: Locks expire after 5000ms if not explicitly released
• Configurable Timeout: Use ClientWorkDbLock.withWaitingMs() for stale lock detection with custom timeout

// Enable stale lock detection with 300ms timeout
final db = ClientWorkDbLock.withWaitingMs(
  IoWorkDb('./data'),
  waitingMs: 300,
);

Choosing Between Implementations

Use Case	Implementation	Benefits
Single-threaded app	ClientWorkDb	Minimal overhead, simpler code
Concurrent access	ClientWorkDbLock	Thread-safe, automatic lock management
Sync single-threaded	ClientWorkDb (sync API)	No async overhead, blocking calls
Sync concurrent access	ClientWorkDbLockSync	Thread-safe sync operations
Testing	In-memory backend with ClientWorkDb or ClientWorkDbLock	No file I/O, isolated state

Synchronous API (New in 1.2.0)

All database operations are available as synchronous methods. ClientWorkDb implements IWorkDbSync directly — no wrapper needed:

import 'package:work_db/work_db.dart';

void main() {
  final db = ClientWorkDb(IoWorkDb('./data'));

  // Synchronous create
  db.createSync(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Doe'},
  ));

  // Synchronous retrieve
  final user = db.retrieveSync(ItemId(id: 'user-1', collection: 'users'));
  print(user?.item['name']); // John Doe

  // Synchronous update
  db.updateSync(ItemWithId(
    id: 'user-1',
    collection: 'users',
    item: {'name': 'John Smith'},
  ));

  // Synchronous delete
  db.deleteSync(ItemId(id: 'user-1', collection: 'users'));
}

Thread-Safe Synchronous Operations

For concurrent synchronous access, use ClientWorkDbLockSync:

import 'package:work_db/work_db.dart';

void main() {
  final db = ClientWorkDbLockSync(IoWorkDb('./data'));

  // Sync operations are protected by file locks
  db.createSync(ItemWithId(
    id: 'doc-1',
    collection: 'documents',
    item: {'title': 'Hello'},
  ));

  // With stale lock detection
  final dbWithTimeout = ClientWorkDbLockSync.withWaitingMs(
    IoWorkDb('./data'),
    waitingMs: 300,
  );
}

ClientWorkDbLockSync also inherits all async operations from ClientWorkDbLock, so you can mix sync and async calls on the same instance.

Record Limit per Collection (New in 1.3.0)

Set an optional maximum number of records per collection. When the limit is exceeded, the oldest records are automatically evicted:

// Keep max 10 log entries per collection
final db = ClientWorkDb(
  IoWorkDb('./data'),
  maxRecordsPerCollection: 10,
);

Works with all backends and factory methods:

// Via factory
final db = factory.create(MemoryWorkDbFactoryInput(
  maxRecordsPerCollection: 100,
));

// Via convenience class
final db = WorkDb.memory(maxRecordsPerCollection: 3);

// With locking
final db = ClientWorkDbLock(
  IoWorkDb('./data'),
  maxRecordsPerCollection: 50,
);

Eviction is triggered on create, createMultiple, createOrUpdate, and createOrUpdateMultiple (and their sync variants). Items are sorted by creation timestamp and the oldest are removed when the limit is exceeded.

Platform-Specific Setup

Desktop (Windows, macOS, Linux) & Server

import 'package:work_db/work_db.dart';

final factory = WorkDbFactory();
final db = factory.create(IoWorkDbFactoryInput(dataPath: './my_app_data'));

Web

import 'package:work_db/work_db.dart';

final factory = WorkDbFactory();
final db = factory.create(WebWorkDbFactoryInput());

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();
  final factory = WorkDbFactory();
  return factory.create(IoWorkDbFactoryInput(dataPath: dir.path));
}

Testing

import 'package:work_db/work_db.dart';

final factory = WorkDbFactory();
final db = factory.create(MemoryWorkDbFactoryInput());

API Reference

Factory Methods

Method	Description
WorkDbFactory().create(IoWorkDbFactoryInput)	File system storage (Desktop/Server)
WorkDbFactory().create(WebWorkDbFactoryInput)	localStorage storage (Web)
WorkDbFactory().create(MemoryWorkDbFactoryInput)	In-memory storage (Testing)

Each call to create() returns a new independent instance. You can create multiple databases with different paths:

final db1 = factory.create(IoWorkDbFactoryInput(dataPath: './data1'));
final db2 = factory.create(IoWorkDbFactoryInput(dataPath: './data2'));
// db1 and db2 are completely independent

Database Operations

All operations are available in both async (Future<T>) and sync (T) variants.

Async Method	Sync Method	Description
create(ItemWithId)	createSync(ItemWithId)	Create a new item (throws if exists)
createMultiple(List<ItemWithId>)	createMultipleSync(List<ItemWithId>)	Create multiple items
update(ItemWithId)	updateSync(ItemWithId)	Update existing item (throws if not exists)
createOrUpdate(ItemWithId)	createOrUpdateSync(ItemWithId)	Create or update (upsert)
createOrUpdateMultiple(List<ItemWithId>)	createOrUpdateMultipleSync(List<ItemWithId>)	Batch upsert
retrieve(ItemId)	retrieveSync(ItemId)	Get item or null
retrieveMultiple(List<ItemId>)	retrieveMultipleSync(List<ItemId>)	Get multiple items
delete(ItemId)	deleteSync(ItemId)	Delete item (throws if not exists)
deleteCollection(String)	deleteCollectionSync(String)	Delete entire collection
clearDatabase()	clearDatabaseSync()	Delete all data
getItemsInCollection(String)	getItemsInCollectionSync(String)	List item IDs in collection
getCollections()	getCollectionsSync()	List all collection names

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': '[e-mail]',
    },
    '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

import 'package:work_db/work_db.dart';

try {
  await db.create(ItemWithId(
    id: 'duplicate',
    collection: 'test',
    item: {'data': 'value'},
  ));

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

// 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;
  late WorkDbFactory factory;

  setUp(() {
    factory = WorkDbFactory();
    db = factory.createNew(MemoryWorkDbFactoryInput());
  });

  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

LGPL v3 License - see LICENSE for details.

Contributing

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