work in progress: observable implementation using detailed change records

lib/observe/expression.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 for observing changes to expressions. */
+library web_ui.observe.expression;
+
+import 'package:web_ui/observe.dart';
+import 'package:web_ui/src/utils.dart' show setImmediate;
+import 'package:web_ui/src/observe/impl.dart' as impl;
+
+// TODO(jmesserly): notifyRead/notifyWrite are only used by people
+// implementating advanced observable functionality. The need to be public, but
+// ideally they would not be in the top level "observe" library.
+
+// TODO(jmesserly): ExpressionObserver, ObservableExpression, ExpressionChange
+// types need work. They're a bit long and I don't like the disconnect between
+// observing expressions and observing objects for changes.
+
+/** Callback fired when an expression changes. */
+typedef void ExpressionObserver(ExpressionChange e);
+
+/** A function that computes a value. */
+typedef Object ObservableExpression();
+
+/**
+ * A notification of a change to an [ObservableExpression] that is passed to a
+ * [ExpressionObserver].
+ */
+class ExpressionChange {
+
+  /** Previous value seen on the watched expression. */
+  final oldValue;
+
+  /** New value seen on the watched expression. */
+  final newValue;
+
+  ExpressionChange(this.oldValue, this.newValue);
+
+  // Note: these two methods are here mainly to make testing easier.
+  bool operator ==(other) {
+    return other is ExpressionChange && oldValue == other.oldValue &&
+        newValue == other.newValue;
+  }
+
+  String toString() => 'change from $oldValue to $newValue';
+}
+
+/**
+ * Observes the [expression] and delivers asynchronous notifications of changes
+ * to the [callback].
+ *
+ * The expression is considered to have changed if the values no longer compare
+ * equal via the equality operator.
+ *
+ * Returns a function that can be used to stop observation.
+ * Calling this makes it possible for the garbage collector to reclaim memory
+ * associated with the observation and prevents further calls to [callback].
+ *
+ * Because notifications are delivered asynchronously and batched, only a single
+ * notification is provided for all changes that were made prior to running
+ * callback. Intermediate values of the expression are not saved. Instead,
+ * [ExpressionChange.oldValue] represents the value before any changes, and
+ * [ExpressionChange.newValue] represents the current value of [expression]
+ * at the time that [callback] is called.
+ *
+ * You can force a synchronous change delivery at any time by calling
+ * [deliverChangesSync]. Calling this method if there are no changes has no
+ * effect. If changes are delivered by deliverChangesSync, they will not be
+ * delivered again asynchronously, unless the value is changed again.
+ *
+ * Any errors thrown by [expression] and [callback] will be caught and sent to
+ * [onObserveUnhandledError].
+ */
+ChangeUnobserver observe(expression, ExpressionObserver callback) {
+
+  if (expression is Observable) {
+    Observable obs = expression;
+    return obs.observe((_) {
+      callback(new ExpressionChange(obs, obs));
+    });
+  }
+  var obs = new impl.ExpressionObserverImpl(expression, callback);
+  obs.observe();
+  return obs.unobserve;
+}