Initial version

.gitignore

@@ -0,0 +1,34 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.packages
+build/
+
+.fvm/
+.flutter-plugins-dependencies
+.flutter-plugins

.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: 4d9e56e694b656610ab87fcf2efbcd226e0ed8cf
+  channel: unknown
+
+project_type: package

CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+* Initial release.

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 indexed_entity_store authors
+
+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.

README.md

@@ -0,0 +1,76 @@
+## Indexed Entity Store
+
+`IndexedEntityStore` is a new approach to persistent data management for Flutter applications.
+
+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.get(99); // returns TODO with ID 99, if any
+
+// 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.query((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: (t) => { 'done': t?.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

analysis_options.yaml

@@ -0,0 +1,4 @@
+include: package:flutter_lints/flutter.yaml
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

lib/indexed_entity_store.dart

@@ -0,0 +1,3 @@
+export './src/index_entity_store.dart';
+export './src/indexed_entity_connector.dart';
+export './src/indexed_entity_database.dart';

lib/src/index_column.dart

@@ -0,0 +1,17 @@
+part of 'index_entity_store.dart';
+
+class IndexColumn {
+  IndexColumn({
+    required String entity,
+    required String field,
+  })  : _entity = entity,
+        _field = field;
+
+  final String _entity;
+
+  final String _field;
+
+  Query equals(dynamic value) {
+    return _EqualQuery(_entity, _field, value);
+  }
+}

lib/src/index_columns.dart

@@ -0,0 +1,19 @@
+part of 'index_entity_store.dart';
+
+class IndexColumns {
+  IndexColumns(
+    Map<String, IndexColumn> indexColumns,
+  ) : _indexColumns = Map.unmodifiable(indexColumns);
+
+  final Map<String, IndexColumn> _indexColumns;
+
+  IndexColumn operator [](String columnName) {
+    final col = _indexColumns[columnName];
+
+    if (col == null) {
+      throw Exception('"$col" is not a known index column');
+    }
+
+    return col;
+  }
+}

lib/src/index_entity_store.dart

@@ -0,0 +1,136 @@
+import 'package:flutter/foundation.dart';
+import 'package:indexed_entity_store/indexed_entity_store.dart';
+import 'package:sqlite3/sqlite3.dart';
+
+part 'index_column.dart';
+part 'index_columns.dart';
+part 'query.dart';
+
+class IndexedEntityStore<T, K> {
+  IndexedEntityStore(this._database, this._connector) {
+    _ensureIndexIsUpToDate();
+  }
+
+  final Database _database;
+
+  final IndexedEntityConnector<T, K, dynamic> _connector;
+
+  String get _entityKey => _connector.entityKey;
+
+  T? get(K key) {
+    final res = _database.select(
+      'SELECT value FROM `entity` WHERE `type` = ? AND `key` = ?',
+      [_entityKey, key],
+    );
+
+    if (res.isEmpty) {
+      return null;
+    }
+
+    return _connector.deserialize(res.single['value']);
+  }
+
+  List<T> getAll() {
+    final res = _database.select(
+      'SELECT * FROM `entity` WHERE `type` = ?',
+      [_entityKey],
+    );
+
+    return res.map((e) => _connector.deserialize(e['value'])).toList();
+  }
+
+  List<T> query(QueryBuilder q) {
+    final columns = _connector.getIndices(null).keys.toList();
+
+    final indexColumns = IndexColumns(
+      {
+        for (final column in columns)
+          column: IndexColumn(
+            entity: _entityKey,
+            field: column,
+          ),
+      },
+    );
+
+    final (w, s) = q(indexColumns)._entityKeysQuery();
+
+    final query =
+        'SELECT value FROM `entity` WHERE `type` = ? AND `key` IN ( $w )';
+    final values = [_entityKey, ...s];
+
+    final res = _database.select(query, values);
+
+    return res.map((e) => _connector.deserialize(e['value'])).toList();
+  }
+
+  void insert(T e) {
+    _database.execute('BEGIN');
+    assert(_database.autocommit == false);
+
+    _database.execute(
+      'REPLACE INTO `entity` (`type`, `key`, `value`) VALUES (?, ?, ?)',
+      [_entityKey, _connector.getPrimaryKey(e), _connector.serialize(e)],
+    );
+
+    _updateIndexInternal(e);
+
+    _database.execute('COMMIT');
+  }
+
+  void _updateIndexInternal(T e) {
+    _database.execute(
+      'DELETE FROM `index` WHERE `type` = ? AND `entity` = ?',
+      [_entityKey, _connector.getPrimaryKey(e)],
+    );
+
+    for (final MapEntry(:key, :value) in _connector.getIndices(e).entries) {
+      _database.execute(
+        'INSERT INTO `index` (`type`, `entity`, `field`, `value`) VALUES (?, ?, ?, ?)',
+        [_entityKey, _connector.getPrimaryKey(e), key, value],
+      );
+    }
+  }
+
+  void delete(Set<K> keys) {
+    for (final key in keys) {
+      _database.execute(
+        'DELETE FROM `entity` WHERE `type` = ? AND `key` = ?',
+        [_entityKey, key],
+      );
+    }
+  }
+
+  void _ensureIndexIsUpToDate() {
+    final currentlyIndexedFields = _database
+        .select(
+          'SELECT DISTINCT `field` FROM `index` WHERE `type` = ?',
+          [this._entityKey],
+        )
+        .map((r) => r['field'] as String)
+        .toSet();
+
+    final currentEntityIndexedFields = _connector.getIndices(null).keys.toSet();
+
+    final missingFields =
+        currentEntityIndexedFields.difference(currentlyIndexedFields);
+
+    if (currentEntityIndexedFields.length != currentlyIndexedFields.length ||
+        missingFields.isNotEmpty) {
+      debugPrint(
+        'Need to update index as fields where changed or added',
+      );
+
+      _database.execute('BEGIN');
+
+      final entities = getAll();
+
+      for (final e in entities) {
+        _updateIndexInternal(e);
+      }
+
+      _database.execute('COMMIT');
+
+      debugPrint('Updated indices for ${entities.length} entities');
+    }
+  }
+}

lib/src/indexed_entity_connector.dart

@@ -0,0 +1,63 @@
+abstract class IndexedEntityConnector<T /* entity */, K /* primary key */,
+    S /* storage format */ > {
+  factory IndexedEntityConnector({
+    required String entityKey,
+    required K Function(T) getPrimaryKey,
+    required Map<String, dynamic> Function(T?) getIndices,
+    required S Function(T) serialize,
+    required T Function(S) deserialize,
+  }) {
+    return _IndexedEntityConnector(
+      entityKey,
+      getPrimaryKey,
+      getIndices,
+      serialize,
+      deserialize,
+    );
+  }
+
+  String get entityKey;
+
+  K getPrimaryKey(T e);
+
+  Map<String, dynamic> getIndices(T? e);
+
+  /// String or bytes
+  S serialize(T e);
+
+  T deserialize(S s);
+}
+
+class _IndexedEntityConnector<T, K, S>
+    implements IndexedEntityConnector<T, K, S> {
+  _IndexedEntityConnector(
+    this.entityKey,
+    this._getPrimaryKey,
+    this._getIndices,
+    this._serialize,
+    this._deserialize,
+  );
+
+  @override
+  final String entityKey;
+
+  final K Function(T) _getPrimaryKey;
+
+  final Map<String, dynamic> Function(T? e) _getIndices;
+
+  final S Function(T) _serialize;
+
+  final T Function(S) _deserialize;
+
+  @override
+  K getPrimaryKey(T e) => _getPrimaryKey(e);
+
+  @override
+  S serialize(T e) => _serialize(e);
+
+  @override
+  T deserialize(S s) => _deserialize(s);
+
+  @override
+  Map<String, dynamic> getIndices(T? e) => _getIndices(e);
+}