[pkg:observe] Add support for explicit change notification, even on dirty-checked objects

pkg/observe/lib/src/observable.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of observe;
 
 /**
  * Use `@observable` to make a field automatically observable.
  */
 const Object observable = const _ObservableAnnotation();
 
 /**
  * Interface representing an observable object. This is used by data in
  * model-view architectures to notify interested parties of [changes].
  *
  * This object does not require any specific technique to implement
- * observability. However if you implement change notification yourself, you
- * should also implement [ChangeNotifier], so [dirtyCheck] knows to skip the
- * object.
+ * observability. If you mixin [ObservableMixin], [dirtyCheck] will know to
+ * check for changes on the object. You may also implement change notification
+ * yourself, by calling [notifyChange].
  *
  * You can use [ObservableBase] or [ObservableMixin] to implement this.
  */
 abstract class Observable {
   /**
    * The stream of change records to this object. Records will be delivered
    * asynchronously.
    *
    * [deliverChanges] can be called to force synchronous delivery.
    */
@@ skipping 10 matching lines @@
   // The rationale for that, and for async delivery in general, is the principal
   // that you shouldn't run code (observers) when it doesn't expect to be run.
   // If you do that, you risk violating invariants that the code assumes.
   //
   // For this reason, we need to match the ES Harmony version. The way we can do
   // this in Dart is to add a method on StreamSubscription (possibly by
   // subclassing Stream* types) that immediately delivers records for only
   // that subscription. Alternatively, we could consider using something other
   // than Stream to deliver the multicast change records, and provide an
   // Observable->Stream adapter.
+  //
+  // Also: we should be delivering changes to the observer (subscription) based
+  // on the birth order of the observer. This is for compatibility with ES
+  // Harmony as well as predictability for app developers.
   bool deliverChanges();
 
   /**
+   * Notify observers of a change.
+   *
+   * For most objects [ObservableMixin.notifyPropertyChange] is more
+   * convenient, but collections sometimes deliver other types of changes such
+   * as a [ListChangeRecord].
+   */
+  void notifyChange(ChangeRecord record);
+
+  /**
    * Performs dirty checking of objects that inherit from [ObservableMixin].
    * This scans all observed objects using mirrors and determines if any fields
    * have changed. If they have, it delivers the changes for the object.
    */
   static void dirtyCheck() => dirtyCheckObservables();
 }
 
 /**
  * Base class implementing [Observable].
  *
  * When a field, property, or indexable item is changed, the change record
  * will be sent to [changes].
  */
 typedef ObservableBase = Object with ObservableMixin;
 
 /**
  * Mixin for implementing [Observable] objects.
  *
  * When a field, property, or indexable item is changed, the change record
  * will be sent to [changes].
  */
 abstract class ObservableMixin implements Observable {
   StreamController _changes;
   InstanceMirror _mirror;
 
   Map<Symbol, Object> _values;
+  List<ChangeRecord> _records;
 
   Stream<List<ChangeRecord>> get changes {
     if (_changes == null) {
       _changes = new StreamController.broadcast(sync: true,
           onListen: _observed, onCancel: _unobserved);
     }
     return _changes.stream;
   }
 
   /**
@@ skipping 36 matching lines @@
     // This will happen automatically at the next call to dirtyCheck.
     if (_values != null) {
       _mirror = null;
       _values = null;
     }
   }
 
   bool deliverChanges() {
     if (_values == null || !hasObservers) return false;
 
-    List changes = null;
+    // Start with an manually notified records (computed properties, etc),

[Siggi Cherem (dart-lang), 2013/07/26 15:53:14]

an manually => a list of manually?

[Jennifer Messerly, 2013/07/26 18:14:43]

fixed. not sure what "an" was doing there.

+    // then scan all fields for additional changes.
+    List records = _records;
+    _records = null;
+
     _values.forEach((name, oldValue) {
       var newValue = _mirror.getField(name).reflectee;
       if (!identical(oldValue, newValue)) {
-        if (changes == null) changes = <PropertyChangeRecord>[];
-        changes.add(new PropertyChangeRecord(name));
+        if (records == null) records = [];
+        records.add(new PropertyChangeRecord(name));
         _values[name] = newValue;
       }
     });
 
-    if (changes == null) return false;
+    if (records == null) return false;
 
-    // TODO(jmesserly): make "changes" immutable
-    _changes.add(changes);
+    _changes.add(new UnmodifiableListView<ChangeRecord>(records));
     return true;
   }
+
+  /**
+   * Notify that the field [name] of this object has been changed.
+   *
+   * The [oldValue] and [newValue] are also recorded. If the two values are
+   * identical, no change will be recorded.
+   *
+   * For convenience this returns [newValue].
+   */
+  notifyPropertyChange(Symbol field, Object oldValue, Object newValue)
+      => _notifyPropertyChange(this, field, oldValue, newValue);
+
+  /**
+   * Notify a change manually. This is *not* required for fields, but can be
+   * used for computed properties. *Note*: unlike [ChangeNotifierMixin] this
+   * will not schedule [deliverChanges]; use [Observable.dirtyCheck] instead.
+   */
+  void notifyChange(ChangeRecord record) {
+    if (!hasObservers) return;
+
+    if (_records == null) _records = [];
+    _records.add(record);
+  }
 }
 
+// TODO(jmesserly): remove the instance method and make this top-level method
+// public instead?
+_notifyPropertyChange(Observable obj, Symbol field, Object oldValue,
+    Object newValue) {
+
+  // TODO(jmesserly): should this be == instead of identical, to prevent
+  // spurious loops?
+  if (obj.hasObservers && !identical(oldValue, newValue)) {
+    obj.notifyChange(new PropertyChangeRecord(field));
+  }
+  return newValue;
+}
+
+
 /**
  * The type of the `@observable` annotation.
  *
  * Library private because you should be able to use the [observable] field
  * to get the one and only instance. We could make it public though, if anyone
  * needs it for some reason.
  */
 class _ObservableAnnotation {
   const _ObservableAnnotation();
 }