Changes to the API

[nicbn]

Hello, I'd like to change the project so that the API is streamlined and in pair with dart:convert Codec API.

These are some really big changes so I'd like to know what you think about these before I start working on this.

The higher level construct is CborCodec which exposes CborDecoder and CborEncoder which are stream adapters. The decoder can concatenate the whole stream before doing the actual decode.

These encodings and decodings work on the CborValue abstract type. Each type that the CBOR can encode or decode is a subtype of this. Below follows the fields of each value. The idea of having streams and futures is that streamed decoding and encoding may be performed with no API breaks.

CborValue
│   Iterable<CborTag> tags;
│   CborHint hint;
├── CborInt
│       int value;
├── CborBytes
│   │   Stream<List<int>> bytes;
│   ├── CborDateTimeEpoch
│   │       DateTime dateTime;
│   ├── CborBigInt
│   │       BigInt value;
│   ├── CborDecFraction
│   │       BigInt exp;
│   │       BigInt mantissa;
│   ├── CborBigFloat
│   │      BigInt exp;
│   │      BigInt mantissa;
│   └── CborEncodedCbor
├── CborString
│   │   Future<String> string;
│   ├── CborDateTimeString
│   │       DateTime dateTime;
│   ├── CborBase64Url
│   │       Stream<List<int>> decoded;
│   ├── CborBase64
│   │       Stream<List<int>> decoded;
│   ├── CborBase16
│   │       Stream<List<int>> decoded;
│   ├── CborRegex
│   └── CborMime
├── CborArray<V>
│      Stream<CborValue> values;
├── CborMap<K, V>
│      Stream<MapEntry<CborValue, CborValue>> entries;
├── CborFloat
│      double value;
├── CborBool
│      bool value;
├── CborNull
└── CborUndef

CborCodec
CborEncoder
CborDecoder

(Did I forget anything?)

The idea is that the hints are encoded as types as well. The is operator can be used to check the type. Floats and ints are encoded with the smallest possible representation.

Future idea: library simple.dart that implements Codec that work with dynamic and encodes and decodes in a best-effort fashion and discards data such as hints that go unused.

Any thoughts?

[shamblett]

Its always been an ambition to add streamed based decoding, the README says this at the bottom -

Streamed decoding may be supported in future versions.

So this would be a good addition to the package.

It'll no doubt be a fair bit of work but the advantage is the unit test suite, this is robust and comprehensive, any updates made can be fully tested running this suite. Streamlining of the type structure to support this is fine.

I've created a branch off master called issue28, please base any PR's you produce on this branch for now, all development can be done and tested on this.

[shamblett]

The API rewrite PR #29 has been merged into its issue branch at this point, this leaves the following work to be done in future PR's -

1. Add CBOR-JSON conversion Codec.
2. Add simple API that exposes only a Encoder and Decoder that convert from bytes to dart objects, without the CBOR types.

See #29 for more details.

[shamblett]

OK, merge to master has been completed on #38 final prep ffor the next release in progress @nicbn.

[nicbn]

I've made some modifications for future-proofing at #39, which makes it possible to change the way some implementatios are done without breaking changes

[shamblett]

OK, I want to publish version 5.0.0 shortly, probably weekend or just before. I think we are in good shape to do this now, any thing else we need to do we can do on further issues, is this OK with you @nicbn ?

[nicbn]

Sure

[shamblett]

Package version 5.0.0 now published, this closes this issue.