kind 0.2.0

A data modeling framework. Easy serialization and observation object graphs. The API is usable without code generation. Includes database primitives such as GeoPoint and UUID.

Overview

This is Kind framework for serialization / persistence / reactive state management.

This is an initial experimental version. The APIs are not frozen.

What it gives you?

• Convert graphs to/from JSON trees.
  • Use kind.jsonTreeEncode / kind.jsonTreeDecode).
• Convert graphs to/from Protocol Buffers (and GRPC) trees.
  • Use kind.protobufTreeEncode / kind.protobufTreeDecode.
• Use databases (upcoming).
  • Our sibling package database will use this framework in future.
• Reactive programming
  • The package has ReactiveSystem for observing views and mutations of reactive states in the isolate. JSON / Protobuf deserialization methods construct reactive objects by default.
• Various small helpers for data layer programming.
  • Use kind.instanceValidate to validate instances. For instance, if you have StringKind(minLengthInRunes:3, maxLines:1), you get a debugging-friendly error message when you validate instance "a".
  • Use kind.randomExample to generate random instances of the kind.
  • Frameworks may use kind.newList to construct a memory-efficient lists without knowing the type. For instance, Float32Kind, will give you a dart:typed_data Float32List rather than normal List<double> when you ask for a non-growable list.
  • Frameworks may use entityKind.meaning to understand kinds and properties in terms of other vocabularies (such as schema.org schemas).

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

Built-in string formats

• stringKindForEmailAddress (email address)
• stringKindForMarkdown (Markdown formatted content)
• stringKindForPhoneNumber (phone number)
• stringKindForUrl (URL)

Data primitives

• Date (like DateTime, but does not define time)
• DateTimeWithTimeZone (like DateTime, but allows any time zone)
• GeoPoint (geographical latitude/longitude coordinates)
• Uuid (128-bit object identifier)

Reactive collection classes

• ReactiveIterable
• ReactiveList
• ReactiveMap
• ReactiveSet

Some alternatives

For serialization

• built_value
  • Generates code for immutable values and JSON serialization.
• json_serializable
  • Generates code for JSON serialization.
• protobuf
  • Generates code for Protocol Buffers serialization.

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-0 <3.0.0'

dependencies:
  kind: ^0.2.0

2.Write data models

In this example, we use Field helper to avoid writing reactive getters / setters:

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

// Encode
final json = person.getKind().jsonTreeEncode(person);

// Decode
final person = Person.kind.jsonTreeDecode(json);

Protocol Buffers

// Encode
final generatedMessage = person.getKind().protobufTreeEncode(person);

// Decode
final person = Person.kind.protobufTreeDecode(generatedMessage);

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.

For mutable classes

...without reactive programming support

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();
  },
);

...with reactive programming support

You can use ReactiveMixin for implementing reactive getters and setters:

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

For immutable classes

...without reactive programming support

// 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),
      );
    };
  },
);

...with reactive programming support

You can use ReactiveMixin for implementing reactive getters:

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