compiled_mirrors 0.1.0

  • README.md
  • Example
  • Installing
  • Versions
  • 5

Compiled Mirrors

Statically reflecting Dart classes.

Reflection in Dart through dart:mirrors is a powerful tool for building tests and assorted utilities. However, when compiled to JavaScript and run in a browser, mirrors can severely reduce code's performance. In Flutter, mirrors are disabled entirely.

Compiled Mirrors generates a reflection of Dart classes annotated with @compileMirrors. This allows you to do a number of interesting things.

Testing complex classes

My focus has been on using this as a testing utility for evaluating the fields between two complex objects. For example, suppose we have the following class:

class Person {
  final String firstName;
  final String lastName;
  final int age;
  final Location birthplace;
  final Location residence;
  final University almaMater;

  Person(this.firstName, this.lastName, this.gender, this.age,
      this.birthplace, this.residence, this.almaMater);

  factory Person.fromParents(Person mother, Person father) {
    // Make a new person with traits of both parents.
  }
}

Suppose we want to test the fromParents factory. We'd need to build an expected Person for the results of the test, and an actual Person:

test('fromParents Person factory', () {
  var expected = new Person(/* various fields */);
  var actual = new Person.fromParents(testMother, testFather);

Without an equality definition for this person, we need to test against every field in the Person object:

  expect(actual.firstName, expected.firstName);
  expect(actual.lastName, expected.lastName);
  // boilerplate continues.
});

Very verbose!

Also, if we decide later on that we want to add a birthDate field to Person, the test will pass even if the factory generates a birthDate we didn't expect! This is a bug waiting to happen.

Mirrored fields

We can avoid this problem with a mirror of the object's fields. If we compile a mirror for the Person object, we can generate an automatically-updating equality test:

test('fromParents Person factory', () {
  var expected = new Person(/* various fields */);
  var actual = new Person.fromParents(testMother, testFather);
  var expectedFields = new Person$CompiledMirror(expected).fields;
  var actualFields = new Person$CompiledMirror(actual).fields;
  for (var fieldName in expectedFields.keys) {
    expect(actualFields[fieldName](), expectedFields[fieldName]());
  }
});

Much simpler and much more reliable!

Other uses

There are other uses for mirrors. If there's a use case that you'd like a compiled mirror for, please file an issue.

example/lib/example.dart

import 'package:compiled_mirrors/compiled_mirrors.dart';
import 'package:compiled_mirrors/equality.dart';

import 'example.compiled_mirrors.dart';

@compileMirror
class Example {
  String foo;
  int bar;

  @override
  bool operator ==(Object other) =>
      MirrorEquality.equals(this, other, (c) => new Example$CompiledMirror(c));

  @override
  int get hashCode =>
      MirrorEquality.hash(this, (c) => new Example$CompiledMirror(c));

  @override
  String toString() =>
      MirrorEquality.asString(this, (c) => new Example$CompiledMirror(c));
}

Use this package as a library

1. Depend on it

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


dependencies:
  compiled_mirrors: ^0.1.0

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:compiled_mirrors/compiled_mirrors.dart';
  
Version Uploaded Documentation Archive
0.1.0 Mar 28, 2017 Go to the documentation of compiled_mirrors 0.1.0 Download compiled_mirrors 0.1.0 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
9
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
5
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Fix dependencies in pubspec.yaml.

Running pub upgrade failed with the following output:

ERR: The current Dart SDK version is 2.1.0.
 
 Because compiled_mirrors depends on quiver >=0.3.0 <=0.29.0+1 which requires SDK version <2.0.0, version solving failed.

Maintenance issues and suggestions

Add SDK constraint in pubspec.yaml. (-50 points)

For information about setting SDK constraint, please see https://www.dartlang.org/tools/pub/pubspec#sdk-constraints.

Fix platform conflicts. (-20 points)

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

Running dartdoc failed. (-10 points)

Make sure dartdoc runs without any issues.

Maintain CHANGELOG.md. (-20 points)

Changelog entries help clients to follow the progress in your code.

Package is getting outdated. (-70.68 points)

The package was released 89 weeks ago.

The description is too short. (-20 points)

Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.