protobuf-ts

README

protobuf-ts

Protobuf and RPC for Node.js and the Web Browser.

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}')

Quickstart

• grab the msg-readme.proto
• npm install @protobuf-ts/plugin
• protoc --plugin node_modules/.bin/protoc-gen-ts --ts_out . msg-readme.proto
• add the --experimental_allow_proto3_optional flag if your protoc version asks for it

Features

• implements the canonical proto3 JSON format
• implements the binary format and respects unknown fields
• provides gRPC web clients
• provides Twirp clients
• supports Angular dependency injection and pipes
• 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

Read the MANUAL to learn more.

Copyright

• The algorithm to decode UTF8 is Copyright 2016 by Daniel Wirtz, licensed under BSD-3-Clause.
• The algorithm 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 test-fixtures/google and test-fixtures/conformance 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.

Building this project

Building this project requires node (14.5.0), npm, protoc (3.12.3), make, bazel, git.
The entire project can be built by running make.