├── .analysis_options ├── .gitignore ├── .test_config ├── AUTHORS ├── CHANGELOG.md ├── LICENSE ├── PATENTS ├── README.md ├── codereview.settings ├── lib ├── html.dart ├── mirrors_used.dart ├── observe.dart ├── src │ ├── auto_observable.dart │ ├── bind_property.dart │ ├── bindable.dart │ ├── dirty_check.dart │ ├── list_path_observer.dart │ ├── messages.dart │ ├── metadata.dart │ ├── observable_box.dart │ ├── observer_transform.dart │ └── path_observer.dart └── transformer.dart ├── pubspec.yaml └── test ├── list_change_test.dart ├── list_path_observer_test.dart ├── observe_test.dart ├── observe_test_utils.dart ├── path_observer_test.dart ├── transformer_test.dart └── unique_message_test.dart /.analysis_options: -------------------------------------------------------------------------------- 1 | analyzer: 2 | strong-mode: true 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Don’t commit the following directories created by pub. 2 | .pub 3 | build/ 4 | packages 5 | .packages 6 | 7 | # Or the files created by dart2js. 8 | *.dart.js 9 | *.dart.precompiled.js 10 | *.js_ 11 | *.js.deps 12 | *.js.map 13 | *.sw? 14 | .idea/ 15 | .pub/ 16 | 17 | # Include when developing application packages. 18 | pubspec.lock 19 | -------------------------------------------------------------------------------- /.test_config: -------------------------------------------------------------------------------- 1 | { 2 | "test_package": { 3 | "barback": true 4 | } 5 | } 6 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | # Names should be added to this file with this pattern: 2 | # 3 | # For individuals: 4 | # Name 5 | # 6 | # For organizations: 7 | # Organization 8 | # 9 | Google Inc. <*@google.com> 10 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | #### 0.15.2 2 | 3 | * Update to use strong-mode clean Zone API. 4 | 5 | #### 0.15.1 6 | 7 | * Update to use new analyzer API 8 | 9 | #### 0.15.0 10 | 11 | * update to use package:observable 0.17.0 12 | * cleanup and format 13 | 14 | #### 0.14.0 15 | 16 | * Update to be built on top of `package:observable`. Contains the following 17 | breaking changes: 18 | - `Observable` now lives in `package:observable` and behaves like the old 19 | `ChangeNotifier` did (except that it's now the base class) - with subclasses 20 | manually notifying listeners of changes via `notifyPropertyChange()`. 21 | - `ChangeNotifier` has been removed. 22 | - `ObservableList` has been moved to `package:observable`. 23 | - `ObservableMap` has been moved to `package:observable`. 24 | - `toObservable()` has been moved to `package:observable`. 25 | - `Observable` (the one with dirty checking) in `package:observe` has been 26 | renamed `AutoObservable` 27 | 28 | #### 0.13.5 29 | 30 | * Fixed strong mode errors and warnings 31 | 32 | #### 0.13.4 33 | 34 | * Fixed strong mode errors and warnings 35 | 36 | #### 0.13.3+1 37 | 38 | * Add support for code_transformers `0.4.x`. 39 | 40 | #### 0.13.3 41 | 42 | * Update to the `test` package. 43 | 44 | #### 0.13.2 45 | 46 | * Update to analyzer '^0.27.0'. 47 | 48 | #### 0.13.1+3 49 | 50 | * Sorting an already sorted list will no longer yield new change notifications. 51 | 52 | #### 0.13.1+2 53 | 54 | * Update to analyzer '<0.27.0' 55 | 56 | #### 0.13.1+1 57 | 58 | * Update to logging `<0.12.0`. 59 | 60 | #### 0.13.1 61 | 62 | * Update to analyzer `<0.26.0`. 63 | 64 | #### 0.13.0+2 65 | * Fixed `close` in `PathObserver` so it doesn't leak observers. 66 | * Ported the benchmarks from 67 | [observe-js](https://github.com/Polymer/observe-js/tree/master/benchmark). 68 | 69 | #### 0.13.0+1 70 | * Widen the constraint on analyzer. 71 | 72 | #### 0.13.0 73 | * Don't output log files by default in release mode, and provide option to 74 | turn them off entirely. 75 | * Changed the api for the ObserveTransformer to use named arguments. 76 | 77 | #### 0.12.2+1 78 | * Cleanup some method signatures. 79 | 80 | #### 0.12.2 81 | * Updated to match release 0.5.1 82 | [observe-js#d530515](https://github.com/Polymer/observe-js/commit/d530515). 83 | 84 | #### 0.12.1+1 85 | * Expand stack_trace version constraint. 86 | 87 | #### 0.12.1 88 | * Upgraded error messages to have a unique and stable identifier. 89 | 90 | #### 0.12.0 91 | * Old transform.dart file removed. If you weren't use it it, this change is 92 | backwards compatible with version 0.11.0. 93 | 94 | #### 0.11.0+5 95 | * Widen the constraint on analyzer. 96 | 97 | #### 0.11.0+4 98 | * Raise the lower bound on the source_maps constraint to exclude incompatible 99 | versions. 100 | 101 | #### 0.11.0+3 102 | * Widen the constraint on source_maps. 103 | 104 | #### 0.11.0+2 105 | * Widen the constraint on barback. 106 | 107 | #### 0.11.0+1 108 | * Switch from `source_maps`' `Span` class to `source_span`'s `SourceSpan` 109 | class. 110 | 111 | #### 0.11.0 112 | * Updated to match [observe-js#e212e74][e212e74] (release 0.3.4), which also 113 | matches [observe-js#fa70c37][fa70c37] (release 0.4.2). 114 | * ListPathObserver has been deprecated (it was deleted a while ago in 115 | observe-js). We plan to delete it in a future release. You may copy the code 116 | if you still need it. 117 | * PropertyPath now uses an expression syntax including indexers. For example, 118 | you can write `a.b["m"]` instead of `a.b.m`. 119 | * **breaking change**: PropertyPath no longer allows numbers as fields, you 120 | need to use indexers instead. For example, you now need to write `a[3].d` 121 | instead of `a.3.d`. 122 | * **breaking change**: PathObserver.value= no longer discards changes (this is 123 | in combination with a change in template_binding and polymer to improve 124 | interop with JS custom elements). 125 | 126 | #### 0.10.0+3 127 | * minor changes to documentation, deprecated `discardListChages` in favor of 128 | `discardListChanges` (the former had a typo). 129 | 130 | #### 0.10.0 131 | * package:observe no longer declares @MirrorsUsed. The package uses mirrors 132 | for development time, but assumes frameworks (like polymer) and apps that 133 | use it directly will either generate code that replaces the use of mirrors, 134 | or add the @MirrorsUsed declaration themselves. For convinience, you can 135 | import 'package:observe/mirrors_used.dart', and that will add a @MirrorsUsed 136 | annotation that preserves properties and classes labeled with @reflectable 137 | and properties labeled with @observable. 138 | * Updated to match [observe-js#0152d54][0152d54] 139 | 140 | [fa70c37]: https://github.com/Polymer/observe-js/blob/fa70c37099026225876f7c7a26bdee7c48129f1c/src/observe.js 141 | [0152d54]: https://github.com/Polymer/observe-js/blob/0152d542350239563d0f2cad39d22d3254bd6c2a/src/observe.js 142 | [e212e74]: https://github.com/Polymer/observe-js/blob/e212e7473962067c099a3d1859595c2f8baa36d7/src/observe.js 143 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2013, the Dart project authors. All rights reserved. 2 | Redistribution and use in source and binary forms, with or without 3 | modification, are permitted provided that the following conditions are 4 | met: 5 | 6 | * Redistributions of source code must retain the above copyright 7 | notice, this list of conditions and the following disclaimer. 8 | * Redistributions in binary form must reproduce the above 9 | copyright notice, this list of conditions and the following 10 | disclaimer in the documentation and/or other materials provided 11 | with the distribution. 12 | * Neither the name of Google Inc. nor the names of its 13 | contributors may be used to endorse or promote products derived 14 | from this software without specific prior written permission. 15 | 16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 18 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 19 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 20 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 21 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 22 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 26 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 | -------------------------------------------------------------------------------- /PATENTS: -------------------------------------------------------------------------------- 1 | Additional IP Rights Grant (Patents) 2 | 3 | "This implementation" means the copyrightable works distributed by 4 | Google as part of the Dart Project. 5 | 6 | Google hereby grants to you a perpetual, worldwide, non-exclusive, 7 | no-charge, royalty-free, irrevocable (except as stated in this 8 | section) patent license to make, have made, use, offer to sell, sell, 9 | import, transfer, and otherwise run, modify and propagate the contents 10 | of this implementation of Dart, where such license applies only to 11 | those patent claims, both currently owned by Google and acquired in 12 | the future, licensable by Google that are necessarily infringed by 13 | this implementation of Dart. This grant does not include claims that 14 | would be infringed only as a consequence of further modification of 15 | this implementation. If you or your agent or exclusive licensee 16 | institute or order or agree to the institution of patent litigation 17 | against any entity (including a cross-claim or counterclaim in a 18 | lawsuit) alleging that this implementation of Dart or any code 19 | incorporated within this implementation of Dart constitutes direct or 20 | contributory patent infringement, or inducement of patent 21 | infringement, then any patent rights granted to you under this License 22 | for this implementation of Dart shall terminate as of the date such 23 | litigation is filed. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # observe 2 | 3 | Support for marking objects as observable, and getting notifications when those 4 | objects are mutated. 5 | 6 | This library is used to observe changes to [AutoObservable][] types. It also 7 | has helpers to make implementing and using [Observable][] objects easy. 8 | 9 | You can provide an observable object in two ways. The simplest way is to 10 | use dirty checking to discover changes automatically: 11 | 12 | ```dart 13 | import 'package:observe/observe.dart'; 14 | import 'package:observe/mirrors_used.dart'; // for smaller code 15 | 16 | class Monster extends Unit with AutoObservable { 17 | @observable int health = 100; 18 | 19 | void damage(int amount) { 20 | print('$this takes $amount damage!'); 21 | health -= amount; 22 | } 23 | 24 | toString() => 'Monster with $health hit points'; 25 | } 26 | 27 | main() { 28 | var obj = new Monster(); 29 | obj.changes.listen((records) { 30 | print('Changes to $obj were: $records'); 31 | }); 32 | // No changes are delivered until we check for them 33 | obj.damage(10); 34 | obj.damage(20); 35 | print('dirty checking!'); 36 | Observable.dirtyCheck(); 37 | print('done!'); 38 | } 39 | ``` 40 | 41 | **Note**: by default this package uses mirrors to access getters and setters 42 | marked with `@reflectable`. Dart2js disables tree-shaking if there are any 43 | uses of mirrors, unless you declare how mirrors are used (via the 44 | [MirrorsUsed](https://api.dartlang.org/apidocs/channels/stable/#dart-mirrors.MirrorsUsed) 45 | annotation). 46 | 47 | As of version 0.10.0, this package doesn't declare `@MirrorsUsed`. This is 48 | because we intend to use mirrors for development time, but assume that 49 | frameworks and apps that use this pacakge will either generate code that 50 | replaces the use of mirrors, or add the `@MirrorsUsed` declaration 51 | themselves. For convenience, you can import 52 | `package:observe/mirrors_used.dart` as shown on the first example above. 53 | That will add a `@MirrorsUsed` annotation that preserves properties and 54 | classes labeled with `@reflectable` and properties labeled with 55 | `@observable`. 56 | 57 | If you are using the `package:observe/mirrors_used.dart` import, you can 58 | also make use of `@reflectable` on your own classes and dart2js will 59 | preserve all of its members for reflection. 60 | 61 | [Tools](https://www.dartlang.org/polymer-dart/) exist to convert the first 62 | form into the second form automatically, to get the best of both worlds. 63 | 64 | [AutoObservable]: http://www.dartdocs.org/documentation/observe/latest/index.html#observe/observe.AutoObservable 65 | [AutoObservable.dirtyCheck]: http://www.dartdocs.org/documentation/observe/latest/index.html#observe/observe.AutoObservable@id_dirtyCheck 66 | -------------------------------------------------------------------------------- /codereview.settings: -------------------------------------------------------------------------------- 1 | CODE_REVIEW_SERVER: http://codereview.chromium.org/ 2 | VIEW_VC: https://github.com/dart-lang/observe/commit/ 3 | CC_LIST: reviews@dartlang.org 4 | -------------------------------------------------------------------------------- /lib/html.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | // TODO(jmesserly): can we handle this more elegantly? 6 | // In general, it seems like we want a convenient way to take a Stream plus a 7 | // getter and convert this into an AutoObservable. 8 | 9 | /// Helpers for exposing dart:html as observable data. 10 | @Deprecated('Parts of Observe used to support Polymer will move out of library') 11 | library observe.html; 12 | 13 | import 'dart:html'; 14 | 15 | import 'package:observable/observable.dart'; 16 | 17 | import 'observe.dart'; 18 | 19 | /// An observable version of [window.location.hash]. 20 | final ObservableLocationHash windowLocation = new ObservableLocationHash._(); 21 | 22 | class ObservableLocationHash extends PropertyChangeNotifier { 23 | Object _currentHash; 24 | 25 | ObservableLocationHash._() { 26 | // listen on changes to #hash in the URL 27 | // Note: listen on both popState and hashChange, because IE9 doesn't support 28 | // history API. See http://dartbug.com/5483 29 | // TODO(jmesserly): only listen to these if someone is listening to our 30 | // changes. 31 | window.onHashChange.listen(_notifyHashChange); 32 | window.onPopState.listen(_notifyHashChange); 33 | 34 | _currentHash = hash; 35 | } 36 | 37 | @reflectable 38 | String get hash => window.location.hash; 39 | 40 | /// Pushes a new URL state, similar to the affect of clicking a link. 41 | /// Has no effect if the [value] already equals [window.location.hash]. 42 | @reflectable 43 | void set hash(String value) { 44 | if (value == hash) return; 45 | 46 | window.history.pushState(null, '', value); 47 | _notifyHashChange(null); 48 | } 49 | 50 | void _notifyHashChange(Event _) { 51 | var oldValue = _currentHash; 52 | _currentHash = hash; 53 | notifyPropertyChange(#hash, oldValue, _currentHash); 54 | } 55 | } 56 | 57 | /// *Deprecated* use [CssClassSet.toggle] instead. 58 | /// 59 | /// Add or remove CSS class [className] based on the [value]. 60 | @deprecated 61 | void updateCssClass(Element element, String className, bool value) { 62 | if (value == true) { 63 | element.classes.add(className); 64 | } else { 65 | element.classes.remove(className); 66 | } 67 | } 68 | 69 | /// *Deprecated* use `class="{{ binding }}"` in your HTML instead. It will also 70 | /// work on a ``. 71 | /// 72 | /// Bind a CSS class to the observable [object] and property [path]. 73 | @deprecated 74 | PathObserver bindCssClass( 75 | Element element, String className, AutoObservable object, String path) { 76 | callback(value) { 77 | updateCssClass(element, className, value); 78 | } 79 | 80 | var obs = new PathObserver(object, path); 81 | callback(obs.open(callback)); 82 | return obs; 83 | } 84 | -------------------------------------------------------------------------------- /lib/mirrors_used.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | /// An empty library that declares what needs to be retained with [MirrorsUsed] 6 | /// if you were to use observables together with mirrors. By default this is not 7 | /// included because frameworks using this package also use code generation to 8 | /// avoid using mirrors at deploy time. 9 | @Deprecated('Parts of Observe used to support Polymer will move out of library') 10 | library observe.mirrors_used; 11 | 12 | // Note: ObservableProperty is in this list only for the unusual use case of 13 | // invoking dart2js without running this package's transformers. The 14 | // transformer in `lib/transformer.dart` will replace @observable with the 15 | // @reflectable annotation. 16 | @MirrorsUsed( 17 | metaTargets: const [Reflectable, ObservableProperty], 18 | override: 'smoke.mirrors') 19 | import 'dart:mirrors' show MirrorsUsed; 20 | import 'package:observe/observe.dart' show Reflectable, ObservableProperty; 21 | -------------------------------------------------------------------------------- /lib/observe.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe; 6 | 7 | // This library contains code ported from observe-js: 8 | // https://github.com/Polymer/observe-js/blob/0152d542350239563d0f2cad39d22d3254bd6c2a/src/observe.js 9 | // We port what is needed for data bindings. Most of the functionality is 10 | // ported, except where differences are needed for Dart's AutoObservable type. 11 | 12 | export 'package:observable/observable.dart'; 13 | export 'src/auto_observable.dart'; 14 | export 'src/bindable.dart'; 15 | export 'src/bind_property.dart'; 16 | export 'src/list_path_observer.dart'; 17 | export 'src/metadata.dart'; 18 | export 'src/observable_box.dart'; 19 | export 'src/observer_transform.dart'; 20 | export 'src/path_observer.dart' hide getSegmentsOfPropertyPathForTesting; 21 | -------------------------------------------------------------------------------- /lib/src/auto_observable.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.auto_observable; 6 | 7 | import 'dart:async'; 8 | import 'dart:collection'; 9 | 10 | import 'package:observable/observable.dart'; 11 | import 'package:smoke/smoke.dart' as smoke; 12 | 13 | import 'dirty_check.dart' show dirtyCheckObservables, registerObservable; 14 | import 'metadata.dart' show ObservableProperty; 15 | 16 | abstract class AutoObservable implements ChangeNotifier { 17 | /// Performs dirty checking of objects that inherit from [AutoObservable]. 18 | /// This scans all observed objects using mirrors and determines if any fields 19 | /// have changed. If they have, it delivers the changes for the object. 20 | static void dirtyCheck() => dirtyCheckObservables(); 21 | 22 | StreamController> _changes; 23 | 24 | Map _values; 25 | List _records; 26 | 27 | /// The stream of change records to this object. Records will be delivered 28 | /// asynchronously. 29 | /// 30 | /// [deliverChanges] can be called to force synchronous delivery. 31 | @override 32 | Stream> get changes { 33 | if (_changes == null) { 34 | _changes = new StreamController.broadcast( 35 | sync: true, onListen: observed, onCancel: unobserved); 36 | } 37 | return _changes.stream; 38 | } 39 | 40 | /// True if this object has any observers, and should call 41 | /// [notifyChange] for changes. 42 | @override 43 | bool get hasObservers => _changes != null && _changes.hasListener; 44 | 45 | @override 46 | void observed() { 47 | // Register this object for dirty checking purposes. 48 | registerObservable(this); 49 | 50 | var values = new Map(); 51 | 52 | // Note: we scan for @observable regardless of whether the base type 53 | // actually includes this mixin. While perhaps too inclusive, it lets us 54 | // avoid complex logic that walks "with" and "implements" clauses. 55 | var queryOptions = new smoke.QueryOptions( 56 | includeInherited: true, 57 | includeProperties: false, 58 | withAnnotations: const [ObservableProperty]); 59 | for (var decl in smoke.query(this.runtimeType, queryOptions)) { 60 | var name = decl.name; 61 | // Note: since this is a field, getting the value shouldn't execute 62 | // user code, so we don't need to worry about errors. 63 | values[name] = smoke.read(this, name); 64 | } 65 | 66 | _values = values; 67 | } 68 | 69 | /// Release data associated with observation. 70 | @override 71 | void unobserved() { 72 | // Note: we don't need to explicitly unregister from the dirty check list. 73 | // This will happen automatically at the next call to dirtyCheck. 74 | if (_values != null) { 75 | _values = null; 76 | } 77 | } 78 | 79 | /// Synchronously deliver pending [changes]. Returns true if any records were 80 | /// delivered, otherwise false. 81 | // TODO(jmesserly): this is a bit different from the ES Harmony version, which 82 | // allows delivery of changes to a particular observer: 83 | // http://wiki.ecmascript.org/doku.php?id=harmony:observe#object.deliverchangerecords 84 | // 85 | // The rationale for that, and for async delivery in general, is the principal 86 | // that you shouldn't run code (observers) when it doesn't expect to be run. 87 | // If you do that, you risk violating invariants that the code assumes. 88 | // 89 | // For this reason, we need to match the ES Harmony version. The way we can do 90 | // this in Dart is to add a method on StreamSubscription (possibly by 91 | // subclassing Stream* types) that immediately delivers records for only 92 | // that subscription. Alternatively, we could consider using something other 93 | // than Stream to deliver the multicast change records, and provide an 94 | // Observable->Stream adapter. 95 | // 96 | // Also: we should be delivering changes to the observer (subscription) based 97 | // on the birth order of the observer. This is for compatibility with ES 98 | // Harmony as well as predictability for app developers. 99 | @override 100 | bool deliverChanges() { 101 | if (_values == null || !hasObservers) return false; 102 | 103 | // Start with manually notified records (computed properties, etc), 104 | // then scan all fields for additional changes. 105 | var records = _records; 106 | _records = null; 107 | 108 | _values.forEach((name, oldValue) { 109 | var newValue = smoke.read(this, name); 110 | if (oldValue != newValue) { 111 | if (records == null) records = []; 112 | records.add(new PropertyChangeRecord(this, name, oldValue, newValue)); 113 | _values[name] = newValue; 114 | } 115 | }); 116 | 117 | if (records == null) return false; 118 | 119 | _changes.add(new UnmodifiableListView(records)); 120 | return true; 121 | } 122 | 123 | /// Notify that the field [name] of this object has been changed. 124 | /// 125 | /// The [oldValue] and [newValue] are also recorded. If the two values are 126 | /// equal, no change will be recorded. 127 | /// 128 | /// For convenience this returns [newValue]. 129 | @override 130 | /*=T*/ notifyPropertyChange/**/( 131 | Symbol field, /*=T*/ oldValue, /*=T*/ newValue) { 132 | if (hasObservers && oldValue != newValue) { 133 | notifyChange(new PropertyChangeRecord(this, field, oldValue, newValue)); 134 | } 135 | return newValue; 136 | } 137 | 138 | /// Notify observers of a change. 139 | /// 140 | /// For most objects [AutoObservable.notifyPropertyChange] is more 141 | /// convenient, but collections sometimes deliver other types of changes 142 | /// such as a [ListChangeRecord]. 143 | /// 144 | /// Notes: 145 | /// - This is *not* required for fields if you mixin or extend 146 | /// [AutoObservable], but you can use it for computed properties. 147 | /// - Unlike [Observable] this will not schedule [deliverChanges]; use 148 | /// [AutoObservable.dirtyCheck] instead. 149 | @override 150 | void notifyChange([ChangeRecord record]) { 151 | if (record == null || !hasObservers) return; 152 | if (_records == null) _records = []; 153 | _records.add(record); 154 | } 155 | } 156 | -------------------------------------------------------------------------------- /lib/src/bind_property.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.bind_property; 6 | 7 | import 'dart:async'; 8 | import 'package:observable/observable.dart' as obs; 9 | 10 | /// Forwards an observable property from one object to another. For example: 11 | /// 12 | /// class MyModel extends AutoObservable { 13 | /// StreamSubscription _sub; 14 | /// MyOtherModel _otherModel; 15 | /// 16 | /// MyModel() { 17 | /// ... 18 | /// _sub = onPropertyChange(_otherModel, #value, 19 | /// () => notifyPropertyChange(#prop, oldValue, newValue); 20 | /// } 21 | /// 22 | /// String get prop => _otherModel.value; 23 | /// set prop(String value) { _otherModel.value = value; } 24 | /// } 25 | /// 26 | /// See also [notifyPropertyChange]. 27 | // TODO(jmesserly): make this an instance method? 28 | StreamSubscription onPropertyChange( 29 | obs.Observable source, Symbol sourceName, void callback()) { 30 | return source.changes.listen((records) { 31 | for (var record in records) { 32 | if (record is obs.PropertyChangeRecord && record.name == sourceName) { 33 | callback(); 34 | break; 35 | } 36 | } 37 | }); 38 | } 39 | -------------------------------------------------------------------------------- /lib/src/bindable.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.bindable; 6 | 7 | /// An object that can be data bound. 8 | // Normally this is used with 'package:template_binding'. 9 | // TODO(jmesserly): Node.bind polyfill calls this "observable" 10 | abstract class Bindable { 11 | // Dart note: changed setValue to be "set value" and discardChanges() to 12 | // be "get value". 13 | 14 | /// Initiates observation and returns the initial value. 15 | /// The callback will be called with the updated [value]. 16 | /// 17 | /// Some subtypes may chose to provide additional arguments, such as 18 | /// [PathObserver] providing the old value as the second argument. 19 | /// However, they must support callbacks with as few as 0 or 1 argument. 20 | /// This can be implemented by performing an "is" type test on the callback. 21 | open(callback); 22 | 23 | /// Stops future notifications and frees the reference to the callback passed 24 | /// to [open], so its memory can be collected even if this Bindable is alive. 25 | void close(); 26 | 27 | /// Gets the current value of the bindings. 28 | /// Note: once the value of a [Bindable] is fetched, the callback passed to 29 | /// [open] should not be called again with this new value. 30 | /// In other words, any pending change notifications must be discarded. 31 | // TODO(jmesserly): I don't like a getter with side effects. Should we just 32 | // rename the getter/setter pair to discardChanges/setValue like they are in 33 | // JavaScript? 34 | get value; 35 | 36 | /// This can be implemented for two-way bindings. By default does nothing. 37 | set value(newValue) {} 38 | 39 | /// Deliver changes. Typically this will perform dirty-checking, if any is 40 | /// needed. 41 | void deliver() {} 42 | } 43 | -------------------------------------------------------------------------------- /lib/src/dirty_check.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | /// *Warning*: this library is **internal**, and APIs are subject to change. 6 | /// 7 | /// Tracks observable objects for dirty checking and testing purposes. 8 | /// 9 | /// It can collect all observed objects, which can be used to trigger 10 | /// predictable delivery of all pending changes in a test, including objects 11 | /// allocated internally to another library, such as those in 12 | /// `package:template_binding`. 13 | library observe.src.dirty_check; 14 | 15 | import 'dart:async'; 16 | 17 | import 'package:func/func.dart'; 18 | import 'package:logging/logging.dart'; 19 | import 'package:observable/observable.dart' as obs show Observable; 20 | 21 | import 'auto_observable.dart' show AutoObservable; 22 | 23 | /// The number of active observables in the system. 24 | int get allObservablesCount => _allObservablesCount; 25 | 26 | int _allObservablesCount = 0; 27 | 28 | List _allObservables = null; 29 | 30 | bool _delivering = false; 31 | 32 | void registerObservable(obs.Observable obj) { 33 | if (_allObservables == null) _allObservables = []; 34 | _allObservables.add(obj); 35 | _allObservablesCount++; 36 | } 37 | 38 | /// Synchronously deliver all change records for known observables. 39 | /// 40 | /// This will execute [AutoObservable.deliverChanges] on objects that inherit from 41 | /// [AutoObservable]. 42 | // Note: this is called performMicrotaskCheckpoint in change_summary.js. 43 | void dirtyCheckObservables() { 44 | if (_delivering) return; 45 | if (_allObservables == null) return; 46 | 47 | _delivering = true; 48 | 49 | int cycles = 0; 50 | bool anyChanged = false; 51 | List debugLoop = null; 52 | do { 53 | cycles++; 54 | if (cycles == MAX_DIRTY_CHECK_CYCLES) { 55 | debugLoop = []; 56 | } 57 | 58 | var toCheck = _allObservables; 59 | _allObservables = []; 60 | anyChanged = false; 61 | 62 | for (int i = 0; i < toCheck.length; i++) { 63 | final observer = toCheck[i]; 64 | if (observer.hasObservers) { 65 | if (observer.deliverChanges()) { 66 | anyChanged = true; 67 | if (debugLoop != null) debugLoop.add([i, observer]); 68 | } 69 | _allObservables.add(observer); 70 | } 71 | } 72 | } while (cycles < MAX_DIRTY_CHECK_CYCLES && anyChanged); 73 | 74 | if (debugLoop != null && anyChanged) { 75 | _logger.warning('Possible loop in AutoObservable.dirtyCheck, stopped ' 76 | 'checking.'); 77 | for (final info in debugLoop) { 78 | _logger.warning('In last iteration AutoObservable changed at index ' 79 | '${info[0]}, object: ${info[1]}.'); 80 | } 81 | } 82 | 83 | _allObservablesCount = _allObservables.length; 84 | _delivering = false; 85 | } 86 | 87 | const MAX_DIRTY_CHECK_CYCLES = 1000; 88 | 89 | /// Log for messages produced at runtime by this library. Logging can be 90 | /// configured by accessing Logger.root from the logging library. 91 | final Logger _logger = new Logger('AutoObservable.dirtyCheck'); 92 | 93 | /// Creates a [ZoneSpecification] to set up automatic dirty checking after each 94 | /// batch of async operations. This ensures that change notifications are always 95 | /// delivered. Typically used via [dirtyCheckZone]. 96 | ZoneSpecification dirtyCheckZoneSpec() { 97 | bool pending = false; 98 | 99 | enqueueDirtyCheck(ZoneDelegate parent, Zone zone) { 100 | // Only schedule one dirty check per microtask. 101 | if (pending) return; 102 | 103 | pending = true; 104 | parent.scheduleMicrotask(zone, () { 105 | pending = false; 106 | AutoObservable.dirtyCheck(); 107 | }); 108 | } 109 | 110 | ZoneCallback wrapCallback( 111 | Zone self, ZoneDelegate parent, Zone zone, R f()) { 112 | // TODO(jmesserly): why does this happen? 113 | if (f == null) return f; 114 | return () { 115 | enqueueDirtyCheck(parent, zone); 116 | return f(); 117 | }; 118 | } 119 | 120 | ZoneUnaryCallback wrapUnaryCallback( 121 | Zone self, ZoneDelegate parent, Zone zone, R f(T x)) { 122 | // TODO(jmesserly): why does this happen? 123 | if (f == null) return f; 124 | return (x) { 125 | enqueueDirtyCheck(parent, zone); 126 | return f(x); 127 | }; 128 | } 129 | 130 | return new ZoneSpecification( 131 | registerCallback: wrapCallback, registerUnaryCallback: wrapUnaryCallback); 132 | } 133 | 134 | /// Forks a [Zone] off the current one that does dirty-checking automatically 135 | /// after each batch of async operations. Equivalent to: 136 | /// 137 | /// Zone.current.fork(specification: dirtyCheckZoneSpec()); 138 | Zone dirtyCheckZone() => Zone.current.fork(specification: dirtyCheckZoneSpec()); 139 | -------------------------------------------------------------------------------- /lib/src/list_path_observer.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.list_path_observer; 6 | 7 | import 'dart:async'; 8 | import 'package:observable/observable.dart'; 9 | import 'package:observe/observe.dart'; 10 | 11 | // Inspired by ArrayReduction at: 12 | // https://raw.github.com/rafaelw/ChangeSummary/master/util/array_reduction.js 13 | // The main difference is we support anything on the rich Dart Iterable API. 14 | 15 | /// Observes a path starting from each item in the list. 16 | @deprecated 17 | class ListPathObserver extends PropertyChangeNotifier { 18 | final ObservableList list; 19 | final String _itemPath; 20 | final List _observers = []; 21 | StreamSubscription _sub; 22 | bool _scheduled = false; 23 | Iterable

_value; 24 | 25 | ListPathObserver(this.list, String path) : _itemPath = path { 26 | // TODO(jmesserly): delay observation until we are observed. 27 | _sub = list.listChanges.listen((records) { 28 | for (var record in records) { 29 | _observeItems(record.addedCount - record.removed.length); 30 | } 31 | _scheduleReduce(null); 32 | }); 33 | 34 | _observeItems(list.length); 35 | _reduce(); 36 | } 37 | 38 | @reflectable 39 | Iterable

get value => _value; 40 | 41 | void dispose() { 42 | if (_sub != null) _sub.cancel(); 43 | _observers.forEach((o) => o.close()); 44 | _observers.clear(); 45 | } 46 | 47 | void _reduce() { 48 | _scheduled = false; 49 | var newValue = _observers.map((o) => o.value as P); 50 | _value = notifyPropertyChange(#value, _value, newValue); 51 | } 52 | 53 | void _scheduleReduce(_) { 54 | if (_scheduled) return; 55 | _scheduled = true; 56 | scheduleMicrotask(_reduce); 57 | } 58 | 59 | void _observeItems(int lengthAdjust) { 60 | if (lengthAdjust > 0) { 61 | for (int i = 0; i < lengthAdjust; i++) { 62 | int len = _observers.length; 63 | var pathObs = new PathObserver(list, '[$len].$_itemPath'); 64 | pathObs.open(_scheduleReduce); 65 | _observers.add(pathObs); 66 | } 67 | } else if (lengthAdjust < 0) { 68 | for (int i = 0; i < -lengthAdjust; i++) { 69 | _observers.removeLast().close(); 70 | } 71 | } 72 | } 73 | } 74 | -------------------------------------------------------------------------------- /lib/src/messages.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | /// Contains all warning messages produced by the observe transformer. 6 | library observe.src.messages; 7 | 8 | import 'package:code_transformers/messages/messages.dart'; 9 | 10 | const NO_OBSERVABLE_ON_LIBRARY = const MessageTemplate( 11 | const MessageId('observe', 1), 12 | '@observable on a library no longer has any effect. ' 13 | 'Instead, annotate individual fields as @observable.', 14 | '`@observable` not supported on libraries', 15 | _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE); 16 | 17 | const NO_OBSERVABLE_ON_TOP_LEVEL = const MessageTemplate( 18 | const MessageId('observe', 2), 19 | 'Top-level fields can no longer be observable. ' 20 | 'Observable fields must be in observable objects.', 21 | '`@observable` not supported on top-level fields', 22 | _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE); 23 | 24 | const NO_OBSERVABLE_ON_CLASS = const MessageTemplate( 25 | const MessageId('observe', 3), 26 | '@observable on a class no longer has any effect. ' 27 | 'Instead, annotate individual fields as @observable.', 28 | '`@observable` not supported on classes', 29 | _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE); 30 | 31 | const NO_OBSERVABLE_ON_STATIC_FIELD = const MessageTemplate( 32 | const MessageId('observe', 4), 33 | 'Static fields can no longer be observable. ' 34 | 'Observable fields must be in observable objects.', 35 | '`@observable` not supported on static fields', 36 | _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE); 37 | 38 | const REQUIRE_OBSERVABLE_INTERFACE = const MessageTemplate( 39 | const MessageId('observe', 5), 40 | 'Observable fields must be in observable objects. ' 41 | 'Change this class to extend, mix in, or implement AutoObservable.', 42 | '`@observable` field not in an `AutoObservable` class', 43 | _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE); 44 | 45 | const String _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE = ''' 46 | Only instance fields on `Observable` classes can be observable, 47 | and you must explicitly annotate each observable field as `@observable`. 48 | 49 | Support for using the `@observable` annotation in libraries, classes, and 50 | elsewhere is deprecated. 51 | '''; 52 | -------------------------------------------------------------------------------- /lib/src/metadata.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.metadata; 6 | 7 | /// Use `@observable` to make a field automatically observable, or to indicate 8 | /// that a property is observable. This only works on classes that extend or 9 | /// mix in `AutoObservable`. 10 | const ObservableProperty observable = const ObservableProperty(); 11 | 12 | /// An annotation that is used to make a property observable. 13 | /// Normally this is used via the [observable] constant, for example: 14 | /// 15 | /// class Monster extends AutoObservable { 16 | /// @observable int health; 17 | /// } 18 | /// 19 | // TODO(sigmund): re-add this to the documentation when it's really true: 20 | // If needed, you can subclass this to create another annotation that will 21 | // also be treated as observable. 22 | // Note: observable properties imply reflectable. 23 | class ObservableProperty { 24 | const ObservableProperty(); 25 | } 26 | 27 | /// This can be used to retain any properties that you wish to access with 28 | /// Dart's mirror system. If you import `package:observe/mirrors_used.dart`, all 29 | /// classes or members annotated with `@reflectable` wil be preserved by dart2js 30 | /// during compilation. This is necessary to make the member visible to 31 | /// `PathObserver`, or similar systems, once the code is deployed, if you are 32 | /// not doing a different kind of code-generation for your app. If you are using 33 | /// polymer, you most likely don't need to use this annotation anymore. 34 | const Reflectable reflectable = const Reflectable(); 35 | 36 | /// An annotation that is used to make a type or member reflectable. This makes 37 | /// it available to `PathObserver` at runtime. For example: 38 | /// 39 | /// @reflectable 40 | /// class Monster extends AutoObservable { 41 | /// int _health; 42 | /// int get health => _health; 43 | /// ... 44 | /// } 45 | /// ... 46 | /// // This will work even if the code has been tree-shaken/minified: 47 | /// final monster = new Monster(); 48 | /// new PathObserver(monster, 'health').changes.listen(...); 49 | class Reflectable { 50 | const Reflectable(); 51 | } 52 | -------------------------------------------------------------------------------- /lib/src/observable_box.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.observable_box; 6 | 7 | import 'package:observable/observable.dart'; 8 | import 'package:observe/observe.dart'; 9 | 10 | // TODO(jmesserly): should the property name be configurable? 11 | // That would be more convenient. 12 | /// An observable box that holds a value. Use this if you want to store a single 13 | /// value. For other cases, it is better to use [AutoObservableList], 14 | /// [AutoObservableMap], or a custom [AutoObservable] implementation based on 15 | /// [AutoObservable]. The property name for changes is "value". 16 | class ObservableBox extends PropertyChangeNotifier { 17 | T _value; 18 | 19 | ObservableBox([T initialValue]) : _value = initialValue; 20 | 21 | @reflectable 22 | T get value => _value; 23 | 24 | @reflectable 25 | void set value(T newValue) { 26 | _value = notifyPropertyChange(#value, _value, newValue); 27 | } 28 | 29 | String toString() => '#<$runtimeType value: $value>'; 30 | } 31 | -------------------------------------------------------------------------------- /lib/src/observer_transform.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.observer_transform; 6 | 7 | import 'package:observe/observe.dart'; 8 | 9 | /// ObserverTransform is used to dynamically transform observed value(s). 10 | /// 11 | /// var obj = new ObservableBox(10); 12 | /// var observer = new PathObserver(obj, 'value'); 13 | /// var transform = new ObserverTransform(observer, 14 | /// (x) => x * 2, setValue: (x) => x ~/ 2); 15 | /// 16 | /// // Open returns the current value of 20. 17 | /// transform.open((newValue) => print('new: $newValue')); 18 | /// 19 | /// obj.value = 20; // prints 'new: 40' async 20 | /// new Future(() { 21 | /// transform.value = 4; // obj.value will be 2 22 | /// }); 23 | /// 24 | /// ObserverTransform can also be used to reduce a set of observed values to a 25 | /// single value: 26 | /// 27 | /// var obj = new AutoObservableMap.from({'a': 1, 'b': 2, 'c': 3}); 28 | /// var observer = new CompoundObserver() 29 | /// ..addPath(obj, 'a') 30 | /// ..addPath(obj, 'b') 31 | /// ..addPath(obj, 'c'); 32 | /// 33 | /// var transform = new ObserverTransform(observer, 34 | /// (values) => values.fold(0, (x, y) => x + y)); 35 | /// 36 | /// // Open returns the current value of 6. 37 | /// transform.open((newValue) => print('new: $newValue')); 38 | /// 39 | /// obj['a'] = 2; 40 | /// obj['c'] = 10; // will print 'new 14' asynchronously 41 | /// 42 | class ObserverTransform extends Bindable { 43 | Bindable _bindable; 44 | Function _getTransformer, _setTransformer; 45 | Function _notifyCallback; 46 | var _value; 47 | 48 | ObserverTransform(Bindable bindable, computeValue(value), {setValue(value)}) 49 | : _bindable = bindable, 50 | _getTransformer = computeValue, 51 | _setTransformer = setValue; 52 | 53 | open(callback) { 54 | _notifyCallback = callback; 55 | _value = _getTransformer(_bindable.open(_observedCallback)); 56 | return _value; 57 | } 58 | 59 | _observedCallback(newValue) { 60 | final value = _getTransformer(newValue); 61 | if (value == _value) return null; 62 | _value = value; 63 | return _notifyCallback(value); 64 | } 65 | 66 | void close() { 67 | if (_bindable != null) _bindable.close(); 68 | _bindable = null; 69 | _getTransformer = null; 70 | _setTransformer = null; 71 | _notifyCallback = null; 72 | _value = null; 73 | } 74 | 75 | get value => _value = _getTransformer(_bindable.value); 76 | 77 | set value(newValue) { 78 | if (_setTransformer != null) { 79 | newValue = _setTransformer(newValue); 80 | } 81 | _bindable.value = newValue; 82 | } 83 | 84 | deliver() => _bindable.deliver(); 85 | } 86 | -------------------------------------------------------------------------------- /lib/src/path_observer.dart: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file 2 | // for details. All rights reserved. Use of this source code is governed by a 3 | // BSD-style license that can be found in the LICENSE file. 4 | 5 | library observe.src.path_observer; 6 | 7 | import 'dart:async'; 8 | import 'dart:collection'; 9 | import 'dart:math' show min; 10 | 11 | import 'package:logging/logging.dart' show Logger, Level; 12 | import 'package:observable/observable.dart'; 13 | import 'package:observe/observe.dart'; 14 | import 'package:smoke/smoke.dart' as smoke; 15 | 16 | import 'package:utf/utf.dart' show stringToCodepoints; 17 | 18 | /// A data-bound path starting from a view-model or model object, for example 19 | /// `foo.bar.baz`. 20 | /// 21 | /// When [open] is called, this will observe changes to the object and any 22 | /// intermediate object along the path, and send updated values accordingly. 23 | /// When [close] is called it will stop observing the objects. 24 | /// 25 | /// This class is used to implement `Node.bind` and similar functionality in 26 | /// the [template_binding](pub.dartlang.org/packages/template_binding) package. 27 | class PathObserver extends _Observer implements Bindable { 28 | PropertyPath _path; 29 | Object _object; 30 | _ObservedSet _directObserver; 31 | 32 | /// Observes [path] on [object] for changes. This returns an object 33 | /// that can be used to get the changes and get/set the value at this path. 34 | /// 35 | /// The path can be a [PropertyPath], or a [String] used to construct it. 36 | /// 37 | /// See [open] and [value]. 38 | PathObserver(Object object, [path]) 39 | : _object = object, 40 | _path = new PropertyPath(path); 41 | 42 | PropertyPath get path => _path; 43 | 44 | /// Sets the value at this path. 45 | void set value(newValue) { 46 | if (_path != null) _path.setValueFrom(_object, newValue); 47 | } 48 | 49 | int get _reportArgumentCount => 2; 50 | 51 | /// Initiates observation and returns the initial value. 52 | /// The callback will be passed the updated [value], and may optionally be 53 | /// declared to take a second argument, which will contain the previous value. 54 | open(callback) => super.open(callback); 55 | 56 | void _connect() { 57 | _directObserver = new _ObservedSet(this, _object); 58 | _check(skipChanges: true); 59 | } 60 | 61 | void _disconnect() { 62 | _value = null; 63 | if (_directObserver != null) { 64 | _directObserver.close(this); 65 | _directObserver = null; 66 | } 67 | // Dart note: the JS impl does not do this, but it seems consistent with 68 | // CompoundObserver. After closing the PathObserver can't be reopened. 69 | _path = null; 70 | _object = null; 71 | } 72 | 73 | void _iterateObjects(void observe(obj, prop)) { 74 | _path._iterateObjects(_object, observe); 75 | } 76 | 77 | bool _check({bool skipChanges: false}) { 78 | var oldValue = _value; 79 | _value = _path.getValueFrom(_object); 80 | if (skipChanges || _value == oldValue) return false; 81 | 82 | _report(_value, oldValue, this); 83 | return true; 84 | } 85 | } 86 | 87 | /// A dot-delimieted property path such as "foo.bar" or "foo.10.bar". 88 | /// 89 | /// The path specifies how to get a particular value from an object graph, where 90 | /// the graph can include arrays and maps. Each segment of the path describes 91 | /// how to take a single step in the object graph. Properties like 'foo' or 92 | /// 'bar' are read as properties on objects, or as keys if the object is a [Map] 93 | /// or a [Indexable], while integer values are read as indexes in a [List]. 94 | // TODO(jmesserly): consider specialized subclasses for: 95 | // * empty path 96 | // * "value" 97 | // * single token in path, e.g. "foo" 98 | class PropertyPath { 99 | /// The segments of the path. 100 | final List