work in progress: observable implementation using detailed change records

lib/watcher.dart

 // Copyright (c) 2012, 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.
 
 /**
  * A library to observe changes on Dart objects.
  *
  * Similar to the principle of watchers in AngularJS, this library provides the
  * mechanisms to observe and react to changes that happen in an application's
  * data model.
@@ skipping 29 matching lines @@
  * You can watch several kinds of expressions, including lists. See [watch] for
  * more details.
  *
  * A common design pattern for MVC applications is to call [dispatch] at the end
  * of each event loop (e.g. after each UI event is fired). Our view library does
  * this automatically.
  */
 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
  * [dispatch] is called and the value represented by [target] had changed.  The
  * returned function can be used to unregister this watcher.
  *
  * There are several values you can use for [target]:
  *
  *   * A [Getter] function.
  *   Use this to watch expressions as they change. For instance, to watch
  *   whether `a.b.c` changes, wrap it in a getter and call [watch] as follows:
  *         watch(() => a.b.c, ...)
  *   These targets are tracked to check for equality. If calling `target()`
  *   returns the same result, then the [callback] will not be invoked. In the
  *   special case whe the getter returns a [List], we will treat the value in a
  *   special way, similar to passing [List] directly as [target].
  *   **Important**: this library assumes that [Getter] is a read-only function
  *   and that it will consistently return the same value if called multiple
  *   times in a row.
  *
  *   * A [List].
  *   Use this to watch whether a list object changes. For instance, to detect
  *   if an element is added or changed in a list can call [watch] as follows:
  *         watch(list, ...)
  *
  *   * A [Handle].
  *   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;
   bool isList = false;
   if (target is Handle) {
     exp = (target as Handle)._getter;
   } else if (target is Function) {
     exp = target;
     try {
       isList = (target() is List);
@@ skipping 12 matching lines @@
       : new _Watcher(exp, callback, debugName);
   _watchers.add(watcher);
   return () => _unregister(watcher);
 }
 
 /**
  * Add a watcher for [exp] and immediatly invoke [callback]. The watch event
  * 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;
 
 /**
  * An internal representation of a watcher. Contains the expression it watches,
  * the last value seen for it, and a callback to invoke when a change is
  * detected.
  */
 class _Watcher {
   /** Name used to debug. */
   final String debugName;
 
   /** Function that retrieves the value being watched. */
   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;
 
   _Watcher(this._getter, this._callback, this.debugName) {
     _lastValue = _getter();
   }
 
   String toString() => debugName == null ? '<unnamed>' : debugName;
 
   /** Detect if any changes occurred and if so invoke [_callback]. */
   bool compareAndNotify() {
     var currentValue = _safeRead();
     if (_compare(currentValue)) {
       var oldValue = _lastValue;
       _update(currentValue);
-      _callback(new WatchEvent(oldValue, currentValue));
+      _callback(new ExpressionChange(oldValue, currentValue));
       return true;
     }
     return false;
   }
 
   bool get _hasChanged => _compare(_safeRead());
 
   void _updateAndNotify() {
     var currentValue = _safeRead();
     var oldValue = _lastValue;
@@ skipping 95 matching lines @@
 
   void set value(T value) {
     if (_setter != null) {
       _setter(value);
     } else {
       throw new Exception('Sorry - this handle has no setter.');
     }
   }
 }
 
-/** 
+/**
  * 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());
   }
 
   bool _compare(List<T> currentValue) {
     if (_lastValue.length != currentValue.length) return true;
 
     for (int i = 0 ; i < _lastValue.length; i++) {
       if (_lastValue[i] != currentValue[i]) return true;
     }
     return false;
   }
 
   void _update(currentValue) {
     _lastValue = new List<T>.from(currentValue);
   }
 }