ts-proto

What is ts-proto?

The ts-proto npm package is a TypeScript code generator for Protocol Buffers (protobufs). It allows you to generate TypeScript types and client code from .proto files, making it easier to work with protobufs in TypeScript projects.

What are ts-proto's main functionalities?

Generate TypeScript Types

This feature allows you to generate TypeScript types from your .proto files. The generated types can be used in your TypeScript code to ensure type safety when working with protobuf messages.

protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=. your_proto_file.proto

Generate gRPC Client Code

This feature generates gRPC client code for your .proto files. The generated client code can be used to make gRPC calls from your TypeScript code.

protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=. --ts_proto_opt=outputServices=grpc-js your_proto_file.proto

Generate JSON Serialization Code

This feature generates JSON serialization and deserialization methods for your protobuf messages. This is useful for converting protobuf messages to and from JSON format.

protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=. --ts_proto_opt=outputJsonMethods=true your_proto_file.proto

Other packages similar to ts-proto

protobufjs

protobufjs is a popular library for working with Protocol Buffers in JavaScript and TypeScript. It provides a runtime library for parsing and serializing protobuf messages, as well as a code generator for generating TypeScript definitions. Unlike ts-proto, protobufjs does not generate gRPC client code.

grpc-tools

grpc-tools is a package that provides the protoc compiler and gRPC plugins for generating gRPC client and server code. It supports multiple languages, including JavaScript and TypeScript. However, grpc-tools does not generate TypeScript types directly from .proto files, which is a key feature of ts-proto.

grpc-web

grpc-web is a JavaScript implementation of gRPC for browser clients. It allows you to use gRPC in web applications. While grpc-web focuses on enabling gRPC in the browser, ts-proto focuses on generating TypeScript types and client code for Node.js and browser environments.

README

Goals

• Pure TypeScript/ES6 modules
• Only codegen import, no runtime reflection support (just simpler)
• Currently ambivalent about browser support (we use GraphQL instead)

Assumptions

• TS/ES6 module name is the proto package

Todo

• Long
• OneOf
• RPC

Typing Approach

• Missing fields on read
  • When decoding from binary, we setup a prototype for our returned object, which has default values.
    • This assumes missing keys trigger the default value, e.g. storing key=undefined would subvert the approach
  • When decoding from JSON, we may have missing keys.
    • We could convert them to our prototype.
  • When using an instantiated object, our types enforce all keys to be set.