observe 0.13.1+1

observe

Support for marking objects as observable, and getting notifications when those objects are mutated.

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 make implementing and using Observable objects easy.

You can provide an observable object in two ways. The simplest way is to use dirty checking to discover changes automatically:

import 'package:observe/observe.dart';
import 'package:observe/mirrors_used.dart'; // for smaller code

class Monster extends Unit with Observable {
  @observable int health = 100;

  void damage(int amount) {
    print('$this takes $amount damage!');
    health -= amount;
  }

  toString() => 'Monster with $health hit points';
}

main() {
  var obj = new Monster();
  obj.changes.listen((records) {
    print('Changes to $obj were: $records');
  });
  // No changes are delivered until we check for them
  obj.damage(10);
  obj.damage(20);
  print('dirty checking!');
  Observable.dirtyCheck();
  print('done!');
}
 

A more sophisticated approach is to implement the change notification manually. This avoids the potentially expensive Observable.dirtyCheck operation, but requires more work in the object:

import 'package:observe/observe.dart';
import 'package:observe/mirrors_used.dart'; // for smaller code

class Monster extends Unit with ChangeNotifier {
  int _health = 100;
  @reflectable get health => _health;
  @reflectable set health(val) {
    _health = notifyPropertyChange(#health, _health, val);
  }

  void damage(int amount) {
    print('$this takes $amount damage!');
    health -= amount;
  }

  toString() => 'Monster with $health hit points';
}

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!');
}
 

Note: by default this package uses mirrors to access getters and setters marked with @reflectable. Dart2js disables tree-shaking if there are any uses of mirrors, unless you declare how mirrors are used (via the MirrorsUsed annotation).

As of version 0.10.0, this package doesn't declare @MirrorsUsed. This is because we intend to use mirrors for development time, but assume that frameworks and apps that use this pacakge will either generate code that replaces the use of mirrors, or add the @MirrorsUsed declaration themselves. For convenience, you can import package:observe/mirrors_used.dart as shown on the first example above. That will add a @MirrorsUsed annotation that preserves properties and classes labeled with @reflectable and properties labeled with @observable.

If you are using the package:observe/mirrors_used.dart import, you can also make use of @reflectable on your own classes and dart2js will preserve all of its members for reflection.

Tools exist to convert the first form into the second form automatically, to get the best of both worlds.

0.13.1+1

  • Update to logging <0.12.0.

0.13.1

  • Update to analyzer <0.26.0.

0.13.0+2

  • Fixed close in PathObserver so it doesn't leak observers.
  • Ported the benchmarks from observe-js.

0.13.0+1

  • Widen the constraint on analyzer.

0.13.0

  • Don't output log files by default in release mode, and provide option to turn them off entirely.

  • Changed the api for the ObserveTransformer to use named arguments.

0.12.2+1

  • Cleanup some method signatures.

0.12.2

0.12.1+1

  • Expand stack_trace version constraint.

0.12.1

  • Upgraded error messages to have a unique and stable identifier.

0.12.0

  • Old transform.dart file removed. If you weren't use it it, this change is backwards compatible with version 0.11.0.

0.11.0+5

  • Widen the constraint on analyzer.

0.11.0+4

  • Raise the lower bound on the source_maps constraint to exclude incompatible versions.

0.11.0+3

  • Widen the constraint on source_maps.

0.11.0+2

  • Widen the constraint on barback.

0.11.0+1

  • Switch from source_maps' Span class to source_span's SourceSpan class.

0.11.0

  • Updated to match observe-js#e212e74 (release 0.3.4), which also matches observe-js#fa70c37 (release 0.4.2).

  • ListPathObserver has been deprecated (it was deleted a while ago in observe-js). We plan to delete it in a future release. You may copy the code if you still need it.

  • PropertyPath now uses an expression syntax including indexers. For example, you can write a.b["m"] instead of a.b.m.

  • breaking change: PropertyPath no longer allows numbers as fields, you need to use indexers instead. For example, you now need to write a[3].d instead of a.3.d.

  • breaking change: PathObserver.value= no longer discards changes (this is in combination with a change in template_binding and polymer to improve interop with JS custom elements).

0.10.0+3

  • minor changes to documentation, deprecated discardListChages in favor of discardListChanges (the former had a typo).

0.10.0

  • package:observe no longer declares @MirrorsUsed. The package uses mirrors for development time, but assumes frameworks (like polymer) and apps that use it directly will either generate code that replaces the use of mirrors, or add the @MirrorsUsed declaration themselves. For convinience, you can import 'package:observe/mirrors_used.dart', and that will add a @MirrorsUsed annotation that preserves properties and classes labeled with @reflectable and properties labeled with @observable.

  • Updated to match observe-js#0152d54

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  observe: "^0.13.1+1"

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support pub. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:observe/observe.dart';

About

Observable properties and objects for use in template_binding. Template Binding extends HTML and the DOM APIs to support a sensible separation between the UI (DOM) of a document or application and its underlying data (model). Updates to the model are reflected in the DOM and user input into the DOM is immediately assigned to the model.

Author

Email web-ui-dev@dartlang.org Polymer.dart Authors

Homepage

www.dartlang.org/polymer-dart/

Documentation

www.dartdocs.org/documentation/observe/0.13.1%2B1/index.html#observe

Uploader

dgrove@google.com
sigmund@google.com
jmesserly@google.com
nweiz@google.com
jakemac@google.com
jacobr@google.com

Share