Overview #

An unified data layer framework that enables serialization, persistence, and state management for any Dart class. This an early version and the APIs are not frozen. The package requires a null-safe Flutter SDK 2.0.0 or later.

Links #

• Official API reference
• Issue tracker
• Github project

Features #

• Encode/decode JSON.
  • The package can handle most JSON serialization requirements.
• Encode/decode Protocol Buffers.
  • The package can handle most Protocol Buffers (and GRPC) serialization requirements.
• Use databases (upcoming).
  • Our sibling package database will use this framework in future.
• Observe views / mutations in graphs
  • The package has ReactiveSystem for observing views and mutations of reactive states in the isolate.
  • When you are deserializing JSON or Protocol Buffers, you get reactive objects by default.

Overview of APIs #

Built-in kinds #

• Booleans
  • BoolKind
• Integers
  • Int8Kind
  • Int16Kind
  • Int32Kind
  • Int64Kind
  • Int64FixNumKind
  • Uint8Kind
  • Uint16Kind
  • Uint32Kind
  • Uint64Kind
• Floating-point numbers
  • Float32Kind
  • Float64Kind
• Date and time
  • DateKind
  • DateTimeKind
  • DateTimeWithTimeZoneKind
• Strings and bytes
  • StringKind
  • BytesKind
• Lists and sets
  • ListKind
  • SetKind
• Others
  • EnumKind
  • GeoPointKind
  • JsonKind
  • NullableKind
  • ObjectKind
  • OneOfKind
  • UuidKind
• Your custom models
  • CompositePrimitiveKind
  • EntityKind
• Recommended StringKind instances:
  • stringKindForEmailAddress (email address)
  • stringKindForMarkdown (Markdown formatted content)
  • stringKindForPhoneNumber (phone number)
  • stringKindForUrl (URL)

Other APIs #

• Date (unlike DateTime, has only date)
• DateTimeWithTimeZone (unlike DateTime, allows arbitrary time zone)
• GeoPoint (geographical latitude/longitude coordinates)
• ReactiveIterable
• ReactiveList
• ReactiveMap
• ReactiveSet
• Uuid (128-bit object identifier)

Some alternatives #

• For serialization
  • built_value
  • json_serializable
  • protobuf
• For state management
  • get
  • get_it
  • fish_redux
  • flutter_redux
  • mobx
  • riverpod

Getting started #

1.Adding dependency #

In pubspec.yaml, you should have something like:

environment:
  sdk: '>=2.12.0 <3.0.0'

dependencies:
  kind: ^0.3.0

2.Write data models #

In the following example, we use Field. Wrapping values inside Field simplifies state observation. If you want to use normal Dart getters / setters, see "Alternative approaches" section below.

class Person extends Entity {
  static final EntityKind<Person> kind = EntityKind<Person>(
    name: 'Person',
    build: (b) {
      b.optionalString(
        id: 1,
        name: 'fullName',
        minLength: 1,
        field: (e) => e.fullName,
      );
      b.requiredSet<Person>(
        id: 2,
        name: 'friends',
        itemsKind: Person.kind,
        field: (e) => e.friends,
      );
      b.constructor = () => Person();
    },
  );

  /// Full name.
  late final Field<String?> fullName = Field<String?>(this);

  /// Friends.
  late final SetField<Person> friends = SetField<Person>(this);

  @override
  EntityKind getKind() => kind;
}

Serialization #

JSON #

Use jsonTreeEncode(...) and jsonTreeDecode(...):

// Person --> JSON tree
final json = person.getKind().jsonTreeEncode(person);

// JSON tree --> Person
final person = Person.kind.jsonTreeDecode(json);

Protocol Buffers #

For encoding/decoding Protocol Buffers bytes, use protobufBytesEncode(...) and protobufBytesDecode(...):

// Person --> bytes
final generatedMessage = Person.kind.protobufBytesEncode(person);

// bytes --> Person
final person = Person.kind.protobufBytesDecode(bytes);

For encoding/decoding package:protobuf GeneratedMessage, use protobufTreeEncode(...) and protobufTreeDecode(...):

// Person --> GeneratedMessage
final generatedMessage = Person.kind.protobufTreeEncode(person);

// GeneratedMessage --> Person
final person = Person.kind.protobufTreeDecode(generatedMessage);

You can also generate GeneratedMessage classes with GRPC tooling and merge messages.

Alternative approaches to specifying data classes #

Why / why not? #

The alternative approaches:

• Do not force you to deviate from the way you normally write classes.
• Perform better when you have millions of objects.
• Do not support reactive programming with ReactiveSystem unless you write a lot error-prone boilerplate code.
  • In future, we may release a code generator that generates boilerplate for you, but there will inevitably going to be some complexity unless Dart language designers decide to support something like decorator annotations.

Mutable and non-reactive #

You just define getter and setter in Prop for ordinary Dart fields:

class Person {
  /// Full name.
  String? fullName = '';

  /// Friends.
  final Set<Person> friends = {};
}

/// EntityKind for [Person].
final EntityKind<Person> personKind = EntityKind<Person>(
  name: 'Person',
  build: (builder) {
    builder.optionalString(
      id: 1,
      name: 'fullName',
      getter: (t) => t.fullName,
      setter: (t,v) => t.fullName = v,
    );
    builder.requiredSet<Person>(
      id: 2,
      name: 'friends',
      itemsKind: personKind,
      getter: (t) => t.friends,
    );
    builder.constructor = () => Person();
  },
);

Mutable and reactive #

You can use ReactiveMixin for implementing getters and setters that send notifications to ReactiveSystem:

class Person extends Entity with ReactiveMixin {
  String? _fullName;
  final Set<Person> _friends = ReactiveSet<Person>();

  /// Full name of the person.
  String? get fullName => beforeGet(_fullName);
  set fullName(String? value) => _fullName = beforeSet(_fullName, value);

  /// Friends of the person.
  Set<Person> get friends => beforeGet(_friends);

  @override
  EntityKind<Person> getKind() => personKind;
}

// The `personKind` is identical to the previous example.
// ...

Immutable and non-reactive #

// Extending Entity is optional, but recommended.
class Person {
  /// Full name of the person.
  final String? name;

  /// Friends of the person.
  final Set<Person> friends;

  Person({
    this.fullName,
    this.friends = const {},
  });
}

/// EntityKind for [Person].
final EntityKind<Person> personKind = EntityKind<Person>(
  name: 'Person',
  build: (builder) {
    final fullName = builder.optionalString(
      id: 1,
      name: 'fullName',
      getter: (t) => t.fullName,
    );
    final friends = builder.requiredSet<Person>(
      id: 2,
      name: 'friends',
      itemsKind: personKind,
      getter: (t) => t.friends,
    );
    builder.constructorFromData = (data) {
      return Person(
        name: data.get(fullName),
        friends: data.get(friends),
      );
    };
  },
);

Immutable and reactive #

You can use ReactiveMixin for implementing getters and setters that send notifications to ReactiveSystem:

// Extending Entity is optional, but recommended.
class Person extends Entity with ReactiveMixin {
  final String? _fullName;
  final Set<Person> _friends;

  /// Full name of the person.
  String? get fullName => beforeGet(_fullName);

  /// Friends of the person.
  Set<Person> get friends => beforeGet(_friends);

  Person({
    required String? name,
    Set<Person> friends = const {},
  }) :
    _fullName = name,
    _friends = ReactiveSet<Person>.wrap(friends);

  @override
  EntityKind<Person> getKind() => personKind;
}

// The `personKind` is identical to the previous example.
// ...