tree: 05486a55904b1e94b20b0e0c81401d6b8bd7247d [path history] [tgz]
  1. BUILD.gn
  2. OWNERS
  3. README.md
  4. analysis_options.yaml
  5. lib/
  6. meta/
  7. pubspec.yaml
  8. test/
public/dart/sledge/README.md

The Sledge library.

The goal of this library is to offer a high level API to Ledger, with functionalities including:

  • Storing structured data in Ledger.
  • Primitives with automatic conflicts resolution strategies.
  • Ability to run efficient queries. (WIP)

Assumptions

To speed up the implementation of Sledge, the following assumptions were made:

  • Only Sledge uses Ledger.
  • Only one Ledger instance is used per process.

These assumptions will be fixed later on.

User guide

Creating a sledge instance

The first step in using Sledge is to create a new Sledge instance.

  import 'package:sledge/sledge.dart';
  ...
  Sledge sledge = new Sledge(componentContext);

Alternatively, if using Sledge from a Module:

Sledge sledge = new Sledge.fromModule(moduleContext));

Writing a document

Writing a document to Sledge is done in 3 steps:

  1. Create a Schema.
    Map<String, BaseType> schemaDescription = <String, BaseType>{
      'someField': new Boolean(),
      'someOtherField': new Integer()
    };
    Schema schema = new Schema(schemaDescription);
  1. Create a DocumentId
    DocumentId id = new DocumentId.fromIntId(schema, 2018);
  1. Create and write to a document
    await sledge.runInTransaction(() async {
      Document doc = await sledge.getDocument(id);
      doc['someField'].value = true;
      doc['someOtherField'].value = 42;
    });

Reading a document

    await sledge.runInTransaction(() async {
      Document doc = await sledge.getDocument(id);
      assert(doc['someField'].value == true);
      assert(doc['someOtherField'].value == 42);
    });

Inner workings

Types and Schemas

The structure of the data stored in Ledger is defined using Schemas. Schemas map strings to Types. The available Types are: Boolean, Integer, Double, Schemas, LastOneWinsString, LastOneWinsUint8List, IntCounter, DoubleCounter, BytelistMap, BytelistSet.

Values

Schemas describe the structures, but they can't hold any data. To store data we can create Values from Schemas. Every Type has an associated Value, for example:

  • Boolean -> BooleanValue
  • Integer -> IntegerValue
  • Schema -> NodeValue

Documents

Documents wrap values and offer facilities to interact with Sledge.

Testing

Host-side tests

These tests run on the host and use a fake Ledger.

cd $FUCHSIA_DIR
# Debug mode should be activated and the topaz test packages should be included, e.g.
# fx set x64 out/debug-x64 --args=is_debug=true --packages=topaz/packages/all
fx build
fx run-host-tests dart_sledge_tests

When testing is complete, reset to default packages with:

fx set x64 $FUCHSIA_DIR/out/release-x64 --args=is_debug=false

Device-side integration tests

To locally run these tests:

fx set x64 --product ermine --monolith topaz/packages/all --monolith topaz/packages/tests/all
fx build
fx run-test sledge_integration_tests

The results of the tests are visible in the logs:

fx syslog