work in progress: observable implementation using detailed change records

lib/watcher.dart

Index: lib/watcher.dart
diff --git a/lib/watcher.dart b/lib/watcher.dart
index 937184291d0c4ec1c674af1ed31b4651452b6b98..ccba0dd184e3cc5788f7d5148a488ea30ed9f6f5 100644
--- a/lib/watcher.dart
+++ b/lib/watcher.dart
@@ -47,6 +47,20 @@
 library watcher;
 
 import 'dart:async';
+import 'observe.dart';
+
+/**
+ * True to use the [observe] library instead of watchers.
+ *
+ * Observers require the [observable] annotation on objects and for collection
+ * types to be observable, such as [ObservableList]. But in return they offer
+ * better performance and more precise change tracking. [dispatch] is not
+ * required with observers, and changes to observable objects are always
+ * detected.
+ *
+ * Currently this flag is experimental, but it may be the default in the future.
+ */
+bool useObservers = false;
 
 /**
  * Watch for changes in [target].  The [callback] function will be called when
@@ -76,7 +90,10 @@ import 'dart:async';
  *   This is syntactic sugar for using the getter portion of a [Handle].
  *         watch(handle, ...)  // equivalent to `watch(handle._getter, ...)`
  */
-WatcherDisposer watch(var target, ValueWatcher callback, [String debugName]) {
+ChangeUnobserver watch(target, ExpressionObserver callback,
+      [String debugName]) {
+  if (useObservers) return observe(target, callback);
+
   if (callback == null) return () {}; // no use in passing null as a callback.
   if (_watchers == null) _watchers = [];
   Function exp;
@@ -109,35 +126,17 @@ WatcherDisposer watch(var target, ValueWatcher callback, [String debugName]) {
  * passed to [callback] will have `null` as the old value, and the current
  * evaluation of [exp] as the new value.
  */
-WatcherDisposer watchAndInvoke(exp, callback, [debugName]) {
+ChangeUnobserver watchAndInvoke(exp, callback, [debugName]) {
   var res = watch(exp, callback, debugName);
   // TODO(jmesserly): this should be "is Getter" once dart2js bug is fixed.
   if (exp is Function) {
-    callback(new WatchEvent(null, exp()));
+    callback(new ExpressionChange(null, exp()));
   } else {
-    callback(new WatchEvent(null, exp));
+    callback(new ExpressionChange(null, exp));
   }
   return res;
 }
 
-/** Callback fired when an expression changes. */
-typedef void ValueWatcher(WatchEvent e);
-
-/** A function that unregisters a watcher. */
-typedef void WatcherDisposer();
-
-/** Event passed to [ValueMatcher] showing what changed. */
-class WatchEvent {
-
-  /** Previous value seen on the watched expression. */
-  final oldValue;
-
-  /** New value seen on the watched expression. */
-  final newValue;
-
-  WatchEvent(this.oldValue, this.newValue);
-}
-
 /** Internal set of active watchers. */
 List<_Watcher> _watchers;
 
@@ -154,7 +153,7 @@ class _Watcher {
   final Getter _getter;
 
   /** Callback to invoke when the value changes. */
-  final ValueWatcher _callback;
+  final ExpressionObserver _callback;
 
   /** Last value observed on the matched expression. */
   var _lastValue;
@@ -171,7 +170,7 @@ class _Watcher {
     if (_compare(currentValue)) {
       var oldValue = _lastValue;
       _update(currentValue);
-      _callback(new WatchEvent(oldValue, currentValue));
+      _callback(new ExpressionChange(oldValue, currentValue));
       return true;
     }
     return false;
@@ -287,13 +286,13 @@ class Handle<T> {
   }
 }
 
-/** 
+/**
  * A watcher for list objects. It stores as the last value a shallow copy of the
  * list as it was when we last detected any changes.
  */
 class _ListWatcher<T> extends _Watcher {
 
-  _ListWatcher(getter, ValueWatcher callback, String debugName)
+  _ListWatcher(getter, ExpressionObserver callback, String debugName)
       : super(getter, callback, debugName) {
     _update(_safeRead());
   }