built_value

Description:

built value

Built Values for Dart - Introduction #
Built Value provides:

Immutable value types;
EnumClass, classes that behave like enums;
JSON serialization.

Immutable collections are from
built_collection.
See the API docs.
Articles #

built_value for Immutable Object Models
built_value for Serialization
Building a Chat App in Dart
End to End Testing in One Short Second with Dart
Moving Fast with Dart Immutable Values
Flutter JSON Serialization
Flutter TODO App Example
using built_value, built_redux, and flutter_built_redux
Building a (large) Flutter app with Redux
Some Options for Deserializing JSON with Flutter

Tutorials #

Custom Serializers
Flutter + built_value + Reddit Tutorial;
video;
source code

Tools #

Json to Dart built_value class converter
Json or js Object to Dart built_value class converter
VSCode extension
IntelliJ plugin

Examples #
For an end to end example see the
chat example, which was
demoed at the Dart Summit 2016.
The
data model,
used both client and server side, uses value types, enums and serialization from
built_value.
Simple examples are
here.
Since v5.2.0 codegen is triggered by running pub run build_runner build to
do a one-off build or pub run build_runner watch to continuously watch your
source and update the generated output when it changes. Note that you need a
dev dependency on built_value_generator and build_runner. See the example
pubspec.yaml.
If using Flutter, the equivalent command is flutter packages pub run build_runner build.
Alternatively, put your built_value classes in a separate Dart package with no dependency
on Flutter. You can then use built_value as normal.
If using a version before v5.2.0, codegen is triggered via either a
build.dart
to do a one-off build or a
watch.dart
to continuously watch your source and update generated output.
Value Types #
Value types are, for our purposes, classes that are considered
interchangeable if their fields have the same values.
Common examples include Date, Money and Url. Most code introduces
its own value types. For example, every web app probably has some
version of Account and User.
Value types are very commonly sent by RPC and/or stored for later
retrieval.
The problems that led to the creation of the Built Value library have
been
discussed at great length
in the context of
AutoValue
for Java.
In short: creating and maintaining value types by hand requires a lot of
boilerplate. It's boring to write, and if you make a mistake, you very
likely create a bug that's hard to track down.
Any solution for value types needs to allow them to participate in object
oriented design. Date, for example, is the right place for code that
does simple date manipulation.
AutoValue
solves the problem for Java with code generation, and Built Values does
the same for Dart. The boilerplate is generated for you, leaving you to
specify which fields you need and to add code for the behaviour of the
class.
Generating boilerplate for Value Types #
Value types require a bit of boilerplate in order to connect it to generated
code. Luckily, even this bit of boilerplate can be automated using code
snippets support in your favourite text editor. For example, in IntelliJ you
can use the following live template:
abstract class $CLASS_NAME$ implements Built<$CLASS_NAME$, $CLASS_NAME$Builder> {
$CLASS_NAME$._();
factory $CLASS_NAME$([void Function($CLASS_NAME$Builder) updates]) = _$$$CLASS_NAME$;
}
copied to clipboard
Using this template, you would only have to manually enter a name for your data
class, which is something that can't be automated.
Enum Class #
Enum Classes provide classes with enum features.
Enums are very helpful in modelling the real world: whenever there are a
small fixed set of options, an enum is a natural choice. For an object
oriented design, though, enums need to be classes. Dart falls short here,
so Enum Classes provide what's missing!
Design:

Constants have name and toString, can be used in switch statements,
and are real classes that can hold code and implement interfaces
Generated values method that returns all the enum values in a BuiltSet (immutable set)
Generated valueOf method that takes a String

Serialization #
Built Values comes with JSON serialization support which allows you to
serialize a complete data model of Built Values, Enum Classes and
Built Collections. The
chat example shows
how easy this makes building a full application with Dart on the server and
client.
Here are the major features of the serialization support:
It fully supports object oriented design: any object model that you can
design can be serialized, including full use of generics and interfaces.
Some other libraries require concrete types or do not fully support generics.
It allows different object oriented models over the same data. For
example, in a client server application, it's likely that the client and server
want different functionality from their data model. So, they are allowed to have
different classes that map to the same data. Most other libraries enforce a 1:1
mapping between classes and types on the wire.
It requires well behaved types. They must be immutable, can use
interface but not concrete inheritance, must have predictable nullability,
hashCode, equals and toString. In fact, they must be Enum Classes, Built
Collections or Built Values. Some other libraries allow badly behaved types to
be serialized.
It supports changes to the data model. Optional fields can be added or
removed, and fields can be switched from optional to required, allowing your
data model to evolve without breaking compatbility. Some other libraries break
compatibility on any change to any serializable class.
It's modular. Each endpoint can choose which classes to know about;
for example, you can have multiple clients that each know about only a subset of
the classes the server knows. Most other libraries are monolithic, requiring all
endpoints to know all types.
It has first class support for validation via Built Values. An important
part of a powerful data model is ensuring it's valid, so classes can make
guarantees about what they can do. Other libraries also support validation
but usually in a less prominent way.
It's pluggable. You can add serializers for your own types, and you can add
plugins
which run before and after all serializers. This could be used to
interoperate with other tools or to add hand coded high performance serializers
for specific classes. Some other libraries are not so extensible.
It was designed to be multi language, mapping to equivalent object models in
Java and other languages. Currently only Dart is supported. The need for other
languages didn't materialize as servers are typically either written in Dart
or owned by third parties. Please open an issue if you'd like to explore
support in more languages.
Common Usage #
While full, compiled examples are available in
example/lib,
a common usage example is shown here. This example assumes that you are writing
a client for a JSON API representing a person that looks like the following:
{
"id": 12345,
"age": 35,
"first_name": "Jimmy",
"hobbies": ["jumping", "basketball"]
}
copied to clipboard
The corresponding dart class employing built_value might look like this. Note
that it is using the
@nullable
annotation to indicate that the field does not have to be present on the
response, as well as the
@BuiltValueField
annotation to map between the property name on the response and the name of the
member variable in the Person class.
import 'package:built_value/built_value.dart';
import 'package:built_value/serializer.dart';
import 'package:built_collection/built_collection.dart';

part 'person.g.dart';

abstract class Person implements Built<Person, PersonBuilder> {
static Serializer<Person> get serializer => _$personSerializer;

// Can never be null.
int get id;

@nullable
int get age;

@nullable
@BuiltValueField(wireName: 'first_name')
String get firstName;

@nullable
BuiltList<String> get hobbies;

Person._();
factory Person([void Function(PersonBuilder) updates]) = _$Person;
}
copied to clipboard
FAQ #
How do I check a field is valid on instantiation? #
The value class private constructor runs when all fields are initialized and
can do arbitrary checks:
abstract class MyValue {
MyValue._() {
if (field < 0) {
throw ArgumentError(field, 'field', 'Must not be negative.');
}
}
copied to clipboard
How do I process a field on instantiation? #
Add a hook that runs immediately before a builder is built. For example, you
could sort a list, so it's always sorted directly before the value is created:
abstract class MyValue {
@BuiltValueHook(finalizeBuilder: true)
static void _sortItems(MyValueBuilder b) =>
b..items.sort();
copied to clipboard
How do I set a default for a field? #
Add a hook that runs whenever a builder is created:
abstract class MyValue {
@BuiltValueHook(initializeBuilder: true)
static void _setDefaults(MyValueBuilder b) =>
b
..name = 'defaultName'
..count = 0;
copied to clipboard
Should I check in and/or publish in the generated .g.dart files? #
See the build_runner
docs. You usually should not check in generated files, but you do need to publish
them.
Features and bugs #
Please file feature requests and bugs at the issue tracker.