observe 0.15.1

  • README.md
  • Installing
  • Versions
  • 88


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

This library is used to observe changes to AutoObservable 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 AutoObservable {
  @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
  print('dirty checking!');

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.


  • Update to use new analyzer API


  • Update to be built on top of package:observable. Contains the following breaking changes:
    • Observable now lives in package:observable and behaves like the old ChangeNotifier did (except that it's now the base class) - with subclasses manually notifying listeners of changes via notifyPropertyChange().
    • ChangeNotifier has been removed.
    • ObservableList has been moved to package:observable.
    • ObservableMap has been moved to package:observable.
    • toObservable() has been moved to package:observable.
    • Observable (the one with dirty checking) in package:observe has been renamed AutoObservable


  • Fixed strong mode errors and warnings


  • Fixed strong mode errors and warnings


  • Add support for code_transformers 0.4.x.


  • Update to the test package.


  • Update to analyzer '^0.27.0'.


  • Sorting an already sorted list will no longer yield new change notifications.


  • Update to analyzer '<0.27.0'


  • Update to logging <0.12.0.


  • Update to analyzer <0.26.0.


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


  • Widen the constraint on analyzer.


  • 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.


  • Cleanup some method signatures.



  • Expand stack_trace version constraint.


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


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


  • Widen the constraint on analyzer.


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


  • Widen the constraint on source_maps.


  • Widen the constraint on barback.


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


  • 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).


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


  • 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:

  observe: "^0.15.1"

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. 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';
Version Uploaded Documentation Archive
0.15.1 May 3, 2017 Go to the documentation of observe 0.15.1 Download observe 0.15.1 archive
0.15.0 Nov 21, 2016 Go to the documentation of observe 0.15.0 Download observe 0.15.0 archive
0.14.0 Sep 30, 2016 Go to the documentation of observe 0.14.0 Download observe 0.14.0 archive
0.13.5 Mar 25, 2016 Go to the documentation of observe 0.13.5 Download observe 0.13.5 archive
0.13.4 Jan 22, 2016 Go to the documentation of observe 0.13.4 Download observe 0.13.4 archive
0.13.3+1 Jan 20, 2016 Go to the documentation of observe 0.13.3+1 Download observe 0.13.3+1 archive
0.13.3 Dec 16, 2015 Go to the documentation of observe 0.13.3 Download observe 0.13.3 archive
0.13.2 Dec 15, 2015 Go to the documentation of observe 0.13.2 Download observe 0.13.2 archive
0.13.1+3 Dec 7, 2015 Go to the documentation of observe 0.13.1+3 Download observe 0.13.1+3 archive
0.13.1+2 Aug 19, 2015 Go to the documentation of observe 0.13.1+2 Download observe 0.13.1+2 archive

All 81 versions...


This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Feb 14, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1


Describes how popular the package is relative to other packages. [more]
81 / 100
Code health derived from static analysis. [more]
95 / 100
Reflects how tidy and up-to-date the package is. [more]
95 / 100
Overall score:
Weighted score of the above. [more]


Detected platforms: web, other

Primary library: package:observe/observe.dart with components: mirrors.


  • Fix lib/src/dirty_check.dart.

    Strong-mode analysis of lib/src/dirty_check.dart failed with the following error:

    line: 129 col: 7
    The argument type '(Zone, ZoneDelegate, Zone, () → dynamic) → () → dynamic' can't be assigned to the parameter type '<R>(Zone, ZoneDelegate, Zone, () → R) → () → R'.

  • Fix issues reported by dartanalyzer.

    dartanalyzer reported 1 error(s) and 0 warning(s).

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • The description is too long.

    Search engines will display only the first part of the description. Try to keep it under 180 characters.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use observe.dart.

  • Use analysis_options.yaml.

    Rename old .analysis_options file to analysis_options.yaml.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.9.0 <2.0.0
analyzer >=0.29.11 <0.30.0 0.29.11 0.31.1
barback >=0.14.2 <0.16.0 0.15.2+14
code_transformers >=0.4.2 <0.6.0 0.5.1+3 0.5.1+4
func >=0.1.0 <2.0.0 1.0.0
logging >=0.9.0 <0.12.0 0.11.3+1
observable >=0.17.0 <0.21.0 0.20.4+3 0.21.0
path >=0.9.0 <2.0.0 1.5.1
smoke >=0.1.0 <0.4.0 0.3.6+3
source_maps >=0.9.4 <0.11.0 0.10.4
source_span ^1.0.0 1.4.0
utf ^0.9.0 0.9.0+4
Transitive dependencies
args 0.13.7 1.3.0
async 2.0.3 2.0.4
charcode 1.1.1
cli_util 0.0.1+2 0.1.2+1
collection 1.14.5
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
glob 1.1.5
html 0.13.2+2
isolate 1.1.0
matcher 0.12.1+4
meta 1.1.2
package_config 1.0.3
plugin 0.2.0+2
pool 1.3.4
quiver 0.27.0 0.28.0
string_scanner 1.0.2
typed_data 1.1.5
watcher 0.9.7+7
when 0.2.0
which 0.1.3
yaml 2.1.13
Dev dependencies
benchmark_harness >=1.0.0 <2.0.0
browser any
chart >=1.0.8 <2.0.0
stack_trace >=0.9.1 <2.0.0 1.9.2
test ^0.12.18+1