From f3910ebd1ebee1f78fed9abe59f81f88e71fa52d Mon Sep 17 00:00:00 2001 From: Timm Preetz Date: Wed, 23 Oct 2024 17:01:47 +0200 Subject: [PATCH] Expand documentation, move example to proper location --- README.md | 74 ++++----------------------------- example/example.md | 69 ++++++++++++++++++++++++++++++ lib/src/index_column.dart | 6 ++- lib/src/index_columns.dart | 3 +- lib/src/index_entity_store.dart | 20 +++++++-- 5 files changed, 99 insertions(+), 73 deletions(-) create mode 100644 example/example.md diff --git a/README.md b/README.md index 2b99882..253c2c8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ ## Indexed Entity Store -`IndexedEntityStore` is a new approach to persistent data management for Flutter applications. +`IndexedEntityStore` offers fast, *synchronous* persistent data storage for Flutter applications. + +* 💨 Fast: Optimized for both data access and development speed. + * Use hot-reload instead of code generation and writing manual schema migrations. + * All queries use indices, so data access is always instantaneous. +* ⚡️ Reactive: Every read from the store is reactive by default, so your application can update whenever the underlying data changes. +* 📖 Simple: Offers a handful of easy-to-use APIs, and strives for a straightforward implementation of only a few hundred lines of codes. It's first and foremost goal is developer productivity while developing[^1]. Most applications a few thousand or less entities of each types, and if access to these is done via indexed queries, there is no need to make even the simplest data update `async`. Furthermore no manual mapping from entity to "rows" is needed. Just use `toJson`/`fromJson` methods which likely already exists on the typed[^2]. @@ -8,72 +14,6 @@ The library itself is developed in the [Berkeley style](https://www.cs.princeton Because this library uses SQLite synchronously in the same thread, one can easily mix SQL and Dart code with virtually no overhead, which wouldn't be advisable in an `async` database setup (not least due to the added complexity that stuff could've chagned between statement). This means the developer can write simpler, more reusable queries and keep complex logic in Dart[^3]. -### Example - -Let's see how this would look for a simple TODO list application. - -```dart -class Todo { - final int id; - final String text; - final bool done; - - Todo({ required this.id, required this.text, required this.done }); - - // These would very likely be created by [json_serializable](https://pub.dev/packages/json_serializable) or [freezed](https://pub.dev/packages/freezed) already for your models - Map toJSON() { - return { - 'id': id, - 'text': text, - 'done': done, - }; - } - - static Todo fromJSON(Map json) { - return Todo( - id: json['id'], - text: json['text'], - done: json['done'], - ); - } -} - -``` - -```dart -final db = IndexedEntityDabase.open('/tmp/appdata.sqlite3'); // in practice put into app dir - -final todos = db.entityStore(todoConnector); - -final someTodo /* Todo? */ = todos.getOnce(99); // returns TODO with ID 99, if any -// Alternatively use `todos.get(99)` to get a subscription (`ValueListenable`) to the item, getting notified of every update - -// While using the String columns here is not super nice, this works without code gen and will throw if using a non-indexed column -final openTodos /* List */ = todos.queryOnce((cols) => cols['done'].equals(false)); - -todos.insert( - Todo(id: 99, text: 'Publish new version', done: false), -); -``` - -The above code omitted the defintion of `todoConnector`. This is the tiny piece of configuration that tells the library how to map between its storage and the entity's type. For a Todo task it might look like this: - - -```dart -final todoConnector = IndexedEntityConnector( - entityKey: 'todo', - getPrimaryKey: (t) => t.id, - getIndices: (index) { - index((t) => t.done, as: 'done'); - }, - serialize: (t) => jsonEncode(t.toJSON()), - deserialize: (s) => _FooEntity.fromJSON( - jsonDecode(s) as Map, - ), -); -``` - - [^1]: This means there is no code generation, manual migrations for schema updates, and other roadblocks. Hat tip to [Blackbird](https://github.com/marcoarment/Blackbird) to bringing this into focus. [^2]: Or Protobuf, if you want to be strictly backwards compatible by default. [^3]: https://www.sqlite.org/np1queryprob.html diff --git a/example/example.md b/example/example.md new file mode 100644 index 0000000..69f446e --- /dev/null +++ b/example/example.md @@ -0,0 +1,69 @@ +### Example + +Let's see how this would look for a simple TODO list application. + +```dart +class Todo { + final int id; + final String text; + final bool done; + + Todo({ required this.id, required this.text, required this.done }); + + // These would very likely be created by [json_serializable](https://pub.dev/packages/json_serializable) or [freezed](https://pub.dev/packages/freezed) already for your models + Map toJSON() { + return { + 'id': id, + 'text': text, + 'done': done, + }; + } + + static Todo fromJSON(Map json) { + return Todo( + id: json['id'], + text: json['text'], + done: json['done'], + ); + } +} +``` + +```dart +final db = IndexedEntityDabase.open('/tmp/appdata.sqlite3'); // in practice put into app dir + +final todos = db.entityStore(todoConnector); + +// While using the String columns here is not super nice, this works without code gen and will throw if using a non-indexed column +final openTodos = todos.query((cols) => cols['done'].equals(false)); + +print(openTodos.value); // prints an empty list on first run as no TODOs are yet added to the database + +todos.insert( + Todo(id: 1, text: 'Publish new version', done: false), +); + +print(openTodos.value); // now prints a list containing the newly added TODO +// `openTodos` was actually updated right after the insert, and one could e.g. `addListener` to connect side-effects on every change + +openTodos.dispose(); // unsubscribe when no loger interested in updates +``` + +The above code omitted the defintion of `todoConnector`. This is the tiny piece of configuration that tells the library how to map between its storage and the entity's type. For a Todo task it might look like this: + + +```dart +final todoConnector = IndexedEntityConnector( + entityKey: 'todo', + getPrimaryKey: (t) => t.id, + getIndices: (index) { + index((t) => t.done, as: 'done'); + }, + serialize: (t) => jsonEncode(t.toJSON()), + deserialize: (s) => _FooEntity.fromJSON( + jsonDecode(s) as Map, + ), +); +``` + +The benefit of using the connector instead of a base class interface that would need to be implemented by every storage model, is that you can store arbitrary classes, even those you might not control. \ No newline at end of file diff --git a/lib/src/index_column.dart b/lib/src/index_column.dart index 81264c1..b3b4eff 100644 --- a/lib/src/index_column.dart +++ b/lib/src/index_column.dart @@ -1,7 +1,11 @@ part of 'index_entity_store.dart'; +/// An indexed column of an [IndexedEntityStore] +/// +/// This provides an interface to indexed fields, which are the only queries that can be executed on a store +/// (so that we never end up in a full table scan to look for a result). class IndexColumn { - IndexColumn({ + IndexColumn._({ required String entity, required String field, required I Function(T e) getIndexValue, diff --git a/lib/src/index_columns.dart b/lib/src/index_columns.dart index ac7540e..5bf321c 100644 --- a/lib/src/index_columns.dart +++ b/lib/src/index_columns.dart @@ -1,7 +1,8 @@ part of 'index_entity_store.dart'; +/// The collection of indexed columns for a given [IndexedEntityStore] class IndexColumns { - IndexColumns( + IndexColumns._( Map indexColumns, ) : _indexColumns = Map.unmodifiable(indexColumns); diff --git a/lib/src/index_entity_store.dart b/lib/src/index_entity_store.dart index 675c0a8..2bfb1fa 100644 --- a/lib/src/index_entity_store.dart +++ b/lib/src/index_entity_store.dart @@ -20,11 +20,11 @@ class IndexedEntityStore { this._connector, ) { { - final collector = IndexCollector(_connector.entityKey); + final collector = IndexCollector._(_connector.entityKey); _connector.getIndices(collector); - _indexColumns = IndexColumns({ + _indexColumns = IndexColumns._({ for (final col in collector._indices) col._field: col, }); } @@ -250,6 +250,10 @@ class IndexedEntityStore { ); } + /// Insert or updates the given entity in the database. + /// + /// In case an entity with the same primary already exists in the database, it will be updated. + // TODO(tp): We might want to rename this to `upsert` going forward to make it clear that this will overwrite and not error when the entry already exits (alternatively maybe `persist`, `write`, or `set`). void insert(T e) { _database.execute('BEGIN'); assert(_database.autocommit == false); @@ -285,14 +289,17 @@ class IndexedEntityStore { } } + /// Deletes a single entity by its primary key void delete(K key) { deleteMany({key}); } + /// Deletes a single entity void deleteEntity(T entity) { delete(_connector.getPrimaryKey(entity)); } + /// Deletes many entities void deleteEntities(Iterable entities) { deleteMany( { @@ -301,6 +308,7 @@ class IndexedEntityStore { ); } + /// Deletes many entities by their primary key void deleteMany(Set keys) { for (final key in keys) { _database.execute( @@ -379,16 +387,19 @@ class IndexedEntityStore { } } +// NOTE(tp): This is implemented as a `class` with `call` such that we can +// correctly capture the index type `I` and forward that to `IndexColumn` class IndexCollector { - IndexCollector(this._entityKey); + IndexCollector._(this._entityKey); final String _entityKey; final _indices = >[]; + /// Adds a new index defined by the mapping [index] and stores it in [as] void call(I Function(T e) index, {required String as}) { _indices.add( - IndexColumn( + IndexColumn._( entity: _entityKey, field: as, getIndexValue: index, @@ -397,4 +408,5 @@ class IndexCollector { } } +/// Specifies how the result should be sorted typedef OrderByClause = (String column, SortOrder direction);