timostamm/protobuf-ts

Protobuf and RPC for TypeScript

protobuf-ts

Protocol buffers and RPC for Node.js and the Web Browser. Pure TypeScript.

For the following .proto file:

syntax = "proto3";

message Person {
    string name = 1;
    uint64 id = 2;
    int32 years = 3;
    optional bytes data = 5;
}

protobuf-ts generates code that can be used like this:

let pete: Person = {
    name: "pete", 
    id: 123n, // it's a bigint
    years: 30
    // data: new Uint8Array([0xDE, 0xAD, 0xBE, 0xEF]);
};

let bytes = Person.toBinary(pete);
pete = Person.fromBinary(bytes);

pete = Person.fromJsonString('{"name":"pete", "id":"123", "years": 30}')

What are protocol buffers?

Protocol buffers is an interface definition language and binary serialization format.
Data structures defined in .proto files are platform-independent and can be used in many languages.
To learn more about the capabilities, please check the official language guide.

Quickstart

• npm install @protobuf-ts/plugin

  installs the plugin and the compiler "protoc"

• download the example file msg-readme.proto and place it into a protos/ directory

• npx protoc --ts_out . --proto_path protos protos/msg-readme.proto

  generates msg-readme.ts
  if your protoc version asks for it, add the flag "--experimental_allow_proto3_optional"

Features

• implements the canonical proto3 JSON format
• implements the binary format and respects unknown fields
• strictly conforms to the protobuf spec
• generates clients that can be used with the gRPC web, Twirp or gRPC protocol
• generates native gRPC servers and clients for usage with @grpc/grpc-js
• supported by Twirp-TS for Twirp servers running on Node.js
• automatically installs protoc (with Yarn berry, please use node-protoc)
• can optimize for speed or code size
• supports proto3 optionals
• supports bigint for 64 bit integers
• every message type has methods to compare, clone, merge and type guard messages
• provides reflection information, including custom options
• supports all well-known-types with custom JSON representation and helper methods
• uses standard TypeScript enums
• runs in the Web Browser and in Node.js
• uses an algebraic data type for oneof groups
• can generate TypeScript or JavaScript
• available as a plugin on the BSR
• can be used with buf

Read the MANUAL to learn more.

Copyright

• The code to decode UTF8 is Copyright 2016 by Daniel Wirtz, licensed under BSD-3-Clause.
• The code to encode and decode varint is Copyright 2008 Google Inc., licensed under BSD-3-Clause.
• The files plugin.ts and descriptor.ts are Copyright 2008 Google Inc., licensed under BSD-3-Clause
• The gRPC status codes are Copyright 2016 gRPC authors, licensed under Apache-2.0.
• The Twirp error codes are Copyright 2018 Twitch Interactive, Inc., licensed under Apache-2.0.
• The proto files in proto/google and test-conformance/proto are Copyright Google Inc. / Google LLC, licensed under Apache-2.0 / BSD-3-Clause.
• All other files are licensed under Apache-2.0, see LICENSE.

Support