Implement Model-Driven-Views spec for Dart

pkg/mdv_observe/lib/mdv_observe.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.
+
+/**
+ * *Warning*: this library is experimental, and APIs are subject to change.
+ *
+ * This library is used to observe changes to [Observable] types. It also
+ * has helpers to implement [Observable] objects.
+ *
+ * For example:
+ *
+ *     class Monster extends Object with ObservableMixin {
+ *       static const _HEALTH = const Symbol('health');
+ *
+ *       int _health = 100;
+ *       get health => _health;
+ *       set health(value) {
+ *         _health = notifyChange(_HEALTH, _health, value);
+ *       }
+ *
+ *       void damage(int amount) {
+ *         print('$this takes $amount damage!');
+ *         health -= amount;
+ *       }
+ *
+ *       toString() => 'Monster with $health hit points';
+ *
+ *       // These methods are temporary until dart2js supports mirrors.
+ *       getValueWorkaround(key) {
+ *         if (key == _HEALTH) return health;
+ *         return null;
+ *       }
+ *       setValueWorkaround(key, val) {
+ *         if (key == _HEALTH) health = val;
+ *       }
+ *     }
+ *
+ *     main() {
+ *       var obj = new Monster();
+ *       obj.changes.listen((records) {
+ *         print('Changes to $obj were: $records');
+ *       });
+ *       // Schedules asynchronous delivery of these changes
+ *       obj.damage(10);
+ *       obj.damage(20);
+ *       print('done!');
+ *     }
+ */
+library mdv_observe;
+
+import 'dart:collection';
+
+// Import and reexport the observe implementation library. It contains the types
+// that are required to implement Model-Driven-Views in dart:html.
+// NOTE: always use package:mdv_observe (this package) in your code!
+// DO NOT import mdv_observe_impl; it may break unpredictably.
+import 'dart:mdv_observe_impl';
+export 'dart:mdv_observe_impl';
+
+part 'src/observable_box.dart';
+part 'src/observable_list.dart';
+part 'src/observable_map.dart';
+
+
+/**
+ * Converts the [Iterable] or [Map] to an [ObservableList] or [ObservableMap],
+ * respectively. This is a convenience function to make it easier to convert
+ * literals into the corresponding observable collection type.
+ *
+ * If [value] is not one of those collection types, or is already [Observable],
+ * it will be returned unmodified.
+ *
+ * If [value] is a [Map], the resulting value will use the appropriate kind of
+ * backing map: either [HashMap], [LinkedHashMap], or [SplayTreeMap].
+ *
+ * By default this performs a deep conversion, but you can set [deep] to false
+ * for a shallow conversion. This does not handle circular data structures.
+ */
+// TODO(jmesserly): ObservableSet?
+toObservable(value, {bool deep: true}) =>
+    deep ? _toObservableDeep(value) : _toObservableShallow(value);
+
+_toObservableShallow(value) {
+  if (value is Observable) return value;
+  if (value is Map) return new ObservableMap.from(value);
+  if (value is Iterable) return new ObservableList.from(value);
+  return value;
+}
+
+_toObservableDeep(value) {
+  if (value is Observable) return value;
+  if (value is Map) {
+    var result = new ObservableMap._createFromType(value);
+    value.forEach((k, v) {
+      result[_toObservableDeep(k)] = _toObservableDeep(v);
+    });
+    return result;
+  }
+  if (value is Iterable) {
+    return new ObservableList.from(value.map(_toObservableDeep));
+  }
+  return value;
+}