A more user-friendly API

Is anyone here opposed to maybe adding a more user-friendly API to this library.

Right now it takes a fair amount of boilerplate to do what is essentially JSON.parse(encoded) or JSON.stringify(obj).

Plus, there doesn’t seem to be a way to get the same objects out on the decode end as were put into the encoding step. This means even more boilerplate code to translate certain fields from numbers into enum strings. Considering this is probably the most common use case it seems worth it to make this a simple one-step call like buffer = encode(schema, obj) and obj = decode(schema, buffer). And preferably, the input to encode and the output of decode should have deep equality.

[kjvalencik]

@download13 Thanks for sharing your thoughts! This library has a focus on performance and makes sacrifices in other areas such as usability. However, I agree that there is definitely room for improvement in ergonomics! I’ll try to add my thoughts one at a time.

it seems worth it to make this a simple one-step call like buffer = encode(schema, obj)

One of the things this library does to make things fast is generate code for serialization instead of using a generic provider. This allows the JS engine to perform optimizations such as inlining and limits the amount of branching.

Unfortunately, compiling is quite expensive and shouldn’t be performed on every call. This makes your version of encode and decode difficult to achieve.

However, there is probably some improvement that could be made to simplify write calls. Currently, pbf objects are passed in to allow object pooling of the buffers. If we added a default value and returned pbf from write calls (allowing chaining) encoding could be much more simple.

Type.write = function (obj, pbf = new Pbf()) {
	/* normal generated code */

	return pbf;
};

const encoded = Type.encode(obj).finish();

This means even more boilerplate code to translate certain fields from numbers into enum strings

This is definitely one of the sources of the most boilerplate and it would be great to translate these on the way in / out. We would probably want this optional to prevent the branching and string allocations for use cases that do not need it.

And preferably, the input to encode and the output of decode should have deep equality.

The primary reason for this is defaults as defined by the protobuf standard. This is also mentioned in https://github.com/mapbox/pbf/issues/80. If compiling had a flag to opt out of default values, this could be achieved.

Lastly, if you are looking to simplify the compilation process, take a look at pbf-loader for webpack.

[kjvalencik]

Yep, so you can write something like:

switch (msg.type) {
    case Tile.GeomType.POINT:
    case Tile.GeomType.LINESTRING:
}