Spine Dart Client Library

Dart-based client for Spine applications. A facade for sending domain commands and querying entity states.

Visit the Pub package registry for the latest version of the package.

The package provides the following:

Dart client library;
generated Protobuf Dart types:
- standard types (google.protobuf and google.protobuf.plugin);
- required Spine types (from base, time, core, client, web, and firebase-web).

The package does not include Protobuf sources or descriptor sets. Refer to respective Maven artifacts for those.

Usage

Prerequisites

Users of this library are required to use the Spine Protobuf Dart plugin.

In order to compile Protobuf into Dart, one needs to:

Activate the protoc_plugin Pub package: pub activate global protoc_plugin.

Apply the Proto Dart plugin:

buildscript {
    classpath "io.spine.tools:spine-proto-dart-plugin:$spineVersion"
}

apply plugin: 'io.spine.tools.proto-dart-plugin'

The Protoc plugin generates .pb.dart files. Spine Proto Dart plugin configures the Protoc plugin. By default, the .pb.dart files are generated under lib for the main scope and under test for the test scope.

Also Spine Proto Dart plugin generates types.dart — a type registry file. The type registry serves for reflection needs of the spine_client package.

Example

The example beneath demonstrates how to perform a simple query and post a bunch of commands using the client library.

// Import `spine_client` and helper libraries.
import 'package:spine_client/spine_client.dart';
import 'package:spine_client/web_firebase_client.dart';
import 'package:spine_client/time.dart';

// Import the Firebase client library.
import 'package:firebase/firebase.dart' as fb;

// Import your model types, generated from Protobuf.
import 'example/acme/task/commands.pb.dart';
import 'example/acme/task/view.pb.dart';

// Import the type registry which contains all your model types.
// Generated by Spine Proto Dart Gradle plugin.
import 'types.dart' as exampleTypes;

void main() {
    var actorId = UserId()
            ..value = '$myUserId';
    var requests = ActorRequestFactory(actorId);
    var firebase = RestClient(
            fb.Database.getInstance(myFirebaseDbJsObject()),
            'https://example-org-42.firebaseio.com'
    );
    var client = BackendClient('https://example.org',
                               firebase,
                               typeRegistries: [myTypes.types()]);
    // Fetch all `TaskView` projections and mark all tasks as done.
    client.fetch(requests.query().all(TaskView()))
          .forEach((taskView) {
              var markDone = MarkTaskDone()
                      ..id = taskView.id
                      ..who_completed = actorId;
              client.post(requests.command().create(markDone));
          });
}

Maintenance

Publishing locally

This package is published by Travis CI on a pull request merge.

Should there be a need in publishing the package from a local machine, this may be done as follows:

in client-dart/build.gradle change the value of publicationDir to a location on your computer but outside the project directory;
run ./gradlew stagePubPublication;
in the selected directory, run pub publish and follow the instructions;
don't forget to revert the changes to client-dart/build.gradle.

Note: in order to be able to do this, you have to be an uploader for this package.

Adding uploader

As an uploader, you may add other uploaders for this package by running:

pub uploader --package spine_client add <email>

Removing uploader

As an uploader, you may remove other uploaders for this package by running:

pub uploader --package spine_client remove <email>