Expand documentation, move example to proper location

README.md

@@ -1,79 +1,19 @@
 ## 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].
 
 The library itself is developed in the [Berkeley style](https://www.cs.princeton.edu/courses/archive/fall13/cos518/papers/worse-is-better.pdf), meaning that the goal is to make it practially nice to use and also keep the implementation straighforward and small. While this might prevent some nice-to-have features in the best case, it also prevents the worst case meaning that development is slowing down as the code is too entrenched or abandoned and can not be easily migrated.
 
 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<String, dynamic> toJSON() {
-    return {
-        'id': id,
-        'text': text,
-        'done': done,
-    };
-  }
-
-  static Todo fromJSON(Map<String, dynamic> 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<Todo?>`) 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<Todo?> */ = 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<Todo, int /* key type */, String /* DB type */>(
-  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<String, dynamic>,
-  ),
-);
-```
-
-
 [^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

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<String, dynamic> toJSON() {
+    return {
+        'id': id,
+        'text': text,
+        'done': done,
+    };
+  }
+
+  static Todo fromJSON(Map<String, dynamic> 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<Todo, int /* key type */, String /* DB type */>(
+  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<String, dynamic>,
+  ),
+);
+```
+
+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.

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<T /* entity type */, I /* index type */ > {
-  IndexColumn({
+  IndexColumn._({
     required String entity,
     required String field,
     required I Function(T e) getIndexValue,

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<String, IndexColumn> indexColumns,
   ) : _indexColumns = Map.unmodifiable(indexColumns);
 

lib/src/index_entity_store.dart

@@ -20,11 +20,11 @@ class IndexedEntityStore<T, K> {
     this._connector,
   ) {
     {
-      final collector = IndexCollector<T>(_connector.entityKey);
+      final collector = IndexCollector<T>._(_connector.entityKey);
 
       _connector.getIndices(collector);
 
-      _indexColumns = IndexColumns({
+      _indexColumns = IndexColumns._({
         for (final col in collector._indices) col._field: col,
       });
     }
@@ -250,6 +250,10 @@ class IndexedEntityStore<T, K> {
     );
   }
 
+  /// 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<T, K> {
     }
   }
 
+  /// 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<T> entities) {
     deleteMany(
       {
@@ -301,6 +308,7 @@ class IndexedEntityStore<T, K> {
     );
   }
 
+  /// Deletes many entities by their primary key
   void deleteMany(Set<K> keys) {
     for (final key in keys) {
       _database.execute(
@@ -379,16 +387,19 @@ class IndexedEntityStore<T, K> {
   }
 }
 
+// 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<T> {
-  IndexCollector(this._entityKey);
+  IndexCollector._(this._entityKey);
 
   final String _entityKey;
 
   final _indices = <IndexColumn<T, dynamic>>[];
 
+  /// Adds a new index defined by the mapping [index] and stores it in [as]
   void call<I>(I Function(T e) index, {required String as}) {
     _indices.add(
-      IndexColumn<T, I>(
+      IndexColumn<T, I>._(
         entity: _entityKey,
         field: as,
         getIndexValue: index,
@@ -397,4 +408,5 @@ class IndexCollector<T> {
   }
 }
 
+/// Specifies how the result should be sorted
 typedef OrderByClause = (String column, SortOrder direction);