V2: JSON Types

[timostamm]

This PR adds an advanced feature with the plugin option json_types=true. If enabled, protoc-gen-es generates a JSON type for every Protobuf message.

Given this definition:

syntax = "proto3";

message Example {
  int32 amount = 1;
  bytes data = 2;
}

The following additional export is generated:

/**
 * JSON type for the message Example.
 */
export type ExampleJson = {
  /**
   * @generated from field: int32 amount = 1;
   */
  amount?: number;

  /**
   * @generated from field: bytes data = 2;
   */
  data?: string;
};

The JSON type matches exactly what toJson() will emit with standard serialization options, and toJson() will actually automatically return the JSON type if available:

const example = create(ExampleSchema, { amount: 123 });
const json: ExampleJson = toJson(ExampleSchema, example);

// Without json_types=true, the following would be a type error:
json.amount // number | undefined
json.data // string | undefined

For enumerations, a similar mechanism applies. We generate a union type with all JSON string values for the enum:

syntax = "proto3";

enum Format {
  FORMAT_UNSPECIFIED = 0;
  FORMAT_BINARY = 1;
  FORMAT_JSON = 2;
}

/**
 * JSON type for the enum Format.
 */
export type FormatJson = "FORMAT_UNSPECIFIED" | "FORMAT_BINARY" | "FORMAT_JSON";

With the functions enumToJson() and enumFromJson(), values can be converted between both representations. With isEnumJson(), unknown input can be narrowed down to known values. If JSON types are available, the functions are type safe:

const strVal: FormatJson = enumToJson(FormatSchema, Format.BINARY);

const enumVal: Format = enumFromJson(FormatSchema, strVal);

const someString: string = "FORMAT_BINARY";
if (isEnumJson(FormatSchema, someString)) {
  someString // FormatJson
}

[timostamm]

A simple example for a JSON type for a message.

[mikeki]

Will there be something similar for proto3 as well?, or is the v2 meaning for the future version of this package?

[timostamm]

@mikeki, V2 refers to version 2 of this project. You can try it out here: https://github.com/bufbuild/protobuf-es/releases/tag/v2.0.0-alpha.1

[mikeki]

@mikeki, V2 refers to version 2 of this project. You can try it out here: https://github.com/bufbuild/protobuf-es/releases/tag/v2.0.0-alpha.1

Got it! Yes these interfaces would be great. One thing I noticed is that the interface between toJson and toPlainMessage is different, and trying to access oneof and enum fields from the Message is very strange, I think the toJson interfaces are helpful for this but there might still be a gap here.