Confusing doc / inconsistent implementation

[dotdoom]

After spending some time trying to replace our internal implementation with ObservableList from this package, I decided to summarize my experience here. Indeed, the semantics are slightly different and I might be confusing use cases, but I found a lot of places over the code base where it looks like this package is in the process of refactoring, yet there is very little recent activity.

• documentation suggests using PropertyChangeMixin which does not exist (reverted in Revert PropertyChangeMixin, does not compile in dart2js #14). The only working way I found is:

  class MyNumbers extends ObservableList<int>
      with
          ChangeNotifier<ChangeRecord>,
          // ignore: mixin_inherits_from_not_object
          PropertyChangeNotifier {}

• the above is further reinforced by the lack of a test on observed() / unobserved(), and a test of mixing ChangeNotifier into Observable
• documentation insists that "ObservableList will only emit on ObservableList.changes, instead of on ObservableList.listChanges", yet it does not look even close to that:
  • listChanges is not marked deprecated;
  • list change events (addition/removal) are not delivered to changes;
  • changes interface is not ready to handle both Property change and List change types (for instance, there's no event filtering mechanism). ObservableMap simply reports all events to changes without filtering - is the stream listener supposed to filter with if (event is MapChangeRecord)?
• the code does not give an opportunity to implement observed / unobserved for listChanges (there's a TODO mentioning that), which makes it challenging to implement e.g. self-disposable BLoC with StreamBuilder in Flutter. Not filing a separate issue for it, because in the light of listChanges getting removed (?) this might become invalid.

That's it for now; I'll appreciate feedback on what of the above is valid and needs a fix, or where I misunderstood the intention.

+cc @matanlurey in case they'd be interested in resuming the great work started in #11.

UPD 1: added necessary lint ignore in PropertyChangeNotifier snippet.

[markegli]

The inconsistency between implementation and documentation appears to be due to the planned changes to the ObservableList interface being reverted by 0.21.0. Simplification of the ObservableList interface from 0.18.0 should be reintegrated or documentation should be updated.