Dart 3 (Macros & Native Assets) Migration

[GregoryConrad]

Planned Dart 3 (Macros) Migration

• Update & add docs
• Update & add to README
• Update & add tests
• Add new examples with macros

mimir

• Rename MimirIndex to RawMimirIndex? Maybe we could add a type alias and deprecate one?
• TypedMimirIndex (created in macros): class TypedMimirIndex<T> {…}
  • An adapter around RawMimirIndex that handles JSON conversions
• Macro that defines extension on MimirInstance that has a TypedMimirIndex<ClassName> get classNameIndex for a certain user-defined ClassName
  • Instead of depending on a JSON package, ideally we can just check for the existence of toMap/toJson and fromMap/fromJson in macros placed on ClassName
• Macro that adds static where method(s) on each user-defined class for easier & type-safe queries (supporting String, number, and boolean).
  • E.g., for @mimir class Movie {...}, we could have something like Mimir.and([Movie.whereTitleIsEqualTo('Forrest Gump'), Movie.whereYearIsBetween(2000, 2010)]) or Mimir.and([Mimir.where(titleIsEqualTo: 'Forrest Gump'), Mimir.where(yearIsBetween: (2000, 2010))])
  • Instead of just one where method, which would be nice/concise, I think it would be better to add several functions for each field. Reason being: isBetween requires an and parameter, which cannot be type-safe. Also, multiple methods for each field forces the method use to be checked at compile time instead of runtime (say, if a user specifies both isEqualTo and isGreaterThan inside the same .where())
  • Actually, revisiting this, perhaps we can make the isBetween field a tuple when records/patterns are supported in Dart 3. Although we will still have the issue where you can have multiple things defined in the same where call, perhaps we can add a few where variants: whereOr & whereAnd, which break down their members into Mimir.or and Mimir.and for convenience.
• Macro that adds SortBy generators for each field
  • Proposed API: Movie.sortByAsc.title and Movie.sortByDesc.year, for example, would simply return SortBy.asc('title') and SortBy.desc('year')
• Native Assets instead of custom packaging system in flutter_mimir

Note: there will be no extension methods placed on user-defined classes (i.e. create(), updateWith(), delete()) in plain mimir because there is no way to know the associated instance.
While we could add our own _mimirInstance field to user-defined classes, this approach has numerous issues.

flutter_mimir

• Remove re-export of mimir, and update README with so
  • Not great to re-export right now anyways, but mimir API bindings rely on a particular binary, so flutter_mimir has to enforce this by including a bundled version.
• defaultMimirInstance macro that adds methods to user-defined classes
  • I am inclined to do this as it is super convenient; however, I feel like it might open people up to some anti-patterns (using static members instead of DI)
    • Think we can come to good compromise by stating dangers in documentation
  • Possible because we can use the defaultInstance directly via Mimir.defaultInstance
  • create(), updateWith(…), delete() methods planned
    • create() can probably just call updateWith(...) for its implementation
  • static search(), searchStream(), documents, ... to each class as static as well

[GregoryConrad]

If anyone sees this issue, please feel free to chime in on the proposed changes for Dart 3 above! Would be nice to have some feedback from people using the library.