All Projects → improbable-eng → Ts Protoc Gen

improbable-eng / Ts Protoc Gen

Licence: apache-2.0
Protocol Buffers Compiler (protoc) plugin for TypeScript and gRPC-Web.

Programming Languages

typescript
32286 projects
ts
41 projects

Projects that are alternatives of or similar to Ts Protoc Gen

Buf
A new way of working with Protocol Buffers.
Stars: ✭ 3,328 (+264.51%)
Mutual labels:  grpc, protocol-buffers, protoc
Protodot
transforming your .proto files into .dot files (and .svg, .png if you happen to have graphviz installed)
Stars: ✭ 107 (-88.28%)
Mutual labels:  grpc, protocol-buffers, protoc
Prototool
Your Swiss Army Knife for Protocol Buffers
Stars: ✭ 4,932 (+440.2%)
Mutual labels:  grpc, protocol-buffers, protoc
Rules protobuf
Bazel rules for building protocol buffers and gRPC services (java, c++, go, ...)
Stars: ✭ 206 (-77.44%)
Mutual labels:  grpc, protocol-buffers, protoc
protopatch
protoc-gen-go patch utility
Stars: ✭ 58 (-93.65%)
Mutual labels:  protocol-buffers, protoc
dalal-street-server
Server for Pragyan's Dalal Street
Stars: ✭ 65 (-92.88%)
Mutual labels:  protocol-buffers, grpc
docker-protobuf
An all-inclusive protoc Docker image
Stars: ✭ 105 (-88.5%)
Mutual labels:  grpc, protoc
Kroto Plus
gRPC Kotlin Coroutines, Protobuf DSL, Scripting for Protoc
Stars: ✭ 400 (-56.19%)
Mutual labels:  grpc, protocol-buffers
grpc-chat
Simple Chat Server/Client implemented with gRPC
Stars: ✭ 107 (-88.28%)
Mutual labels:  protocol-buffers, grpc
Joyrpc
high-performance, high-extensibility Java rpc framework.
Stars: ✭ 290 (-68.24%)
Mutual labels:  grpc, plugin
Python Betterproto
Clean, modern, Python 3.6+ code generator & library for Protobuf 3 and async gRPC
Stars: ✭ 412 (-54.87%)
Mutual labels:  grpc, plugin
protocell
Conjures up convenient OCaml types and serialization functions based on protobuf definition files
Stars: ✭ 18 (-98.03%)
Mutual labels:  protocol-buffers, protoc
protop
protobufs, packaged. https://protop.io
Stars: ✭ 68 (-92.55%)
Mutual labels:  protocol-buffers, grpc
aip-go
Go SDK for implementing resource-oriented gRPC APIs.
Stars: ✭ 47 (-94.85%)
Mutual labels:  protocol-buffers, grpc
protobuf-d
Protocol Buffers Compiler Plugin and Support Library for D
Stars: ✭ 32 (-96.5%)
Mutual labels:  protocol-buffers, protoc
Protolock
Protocol Buffer companion tool. Track your .proto files and prevent changes to messages and services which impact API compatibility.
Stars: ✭ 394 (-56.85%)
Mutual labels:  protocol-buffers, protoc
Protobuf
A pure Elixir implementation of Google Protobuf
Stars: ✭ 442 (-51.59%)
Mutual labels:  protocol-buffers, protoc
Protobuf
[Looking for new ownership] Protocol Buffers for Go with Gadgets
Stars: ✭ 4,998 (+447.43%)
Mutual labels:  grpc, protocol-buffers
Protoreflect
Reflection (Rich Descriptors) for Go Protocol Buffers
Stars: ✭ 651 (-28.7%)
Mutual labels:  grpc, protocol-buffers
grpc-graphql-gateway
A protoc plugin that generates graphql execution code from Protocol Buffers.
Stars: ✭ 239 (-73.82%)
Mutual labels:  protocol-buffers, grpc

Master Build NPM NPM Apache 2.0 License

ts-protoc-gen

Protoc Plugin for generating TypeScript Declarations

This repository contains a protoc plugin that generates TypeScript declarations (.d.ts files) that match the JavaScript output of protoc --js_out=import_style=commonjs,binary. This plugin can also output service definitions as both .js and .d.ts files in the structure required by grpc-web, and as .d.ts files in the structure required by grpc-node.

This plugin is tested and written using TypeScript 2.7.

Installation

npm

As a prerequisite, download or install protoc (the protocol buffer compiler) for your platform from the github releases page or via a package manager (ie: brew, apt).

For the latest stable version of the ts-protoc-gen plugin:

npm install ts-protoc-gen

For our latest build straight from master:

npm install [email protected]

bazel

The bazel rules have been moved to a separate project here. There is a migration guide for existing users.

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for more information.

Usage

As mentioned above, this plugin for protoc serves two purposes:

  1. Generating TypeScript Definitions for CommonJS modules generated by protoc
  2. Generating gRPC service clients for use with grpc-web or grpc-node.

Generating TypeScript Definitions for CommonJS modules generated by protoc

By default, protoc will generate ES5 code when the --js_out flag is used (see javascript compiler documentation). You have the choice of two module syntaxes, CommonJS or closure. This plugin (ts-protoc-gen) can be used to generate Typescript definition files (.d.ts) to provide type hints for CommonJS modules only.

To generate TypeScript definitions you must first configure protoc to use this plugin and then specify where you want the TypeScript definitions to be written to using the --ts_out flag.

# Path to this plugin
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="${OUT_DIR}" \
    users.proto base.proto

In the above example, the generated folder will contain both .js and .d.ts files which you can reference in your TypeScript project to get full type completion and make use of ES6-style import statements, eg:

import { MyMessage } from "../generated/users_pb";

const msg = new MyMessage();
msg.setName("John Doe");

Generating gRPC Service Stubs for use with grpc-web

gRPC is a framework that enables client and server applications to communicate transparently, and makes it easier to build connected systems.

grpc-web is a comparability layer on both the server and client-side which allows gRPC to function natively in modern web-browsers.

To generate client-side service stubs from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the service=grpc-web param to the --ts_out flag, eg:

# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="service=grpc-web:${OUT_DIR}" \
    users.proto base.proto

The generated folder will now contain both pb_service.js and pb_service.d.ts files which you can reference in your TypeScript project to make RPCs.

Note Note that these modules require a CommonJS environment. If you intend to consume these stubs in a browser environment you will need to use a module bundler such as webpack. Note Both js and d.ts service files will be generated regardless of whether there are service definitions in the proto files.

import {
  UserServiceClient,
  GetUserRequest
} from "../generated/users_pb_service";

const client = new UserServiceClient("https://my.grpc/server");
const req = new GetUserRequest();
req.setUsername("johndoe");
client.getUser(req, (err, user) => {
  /* ... */
});

Generating gRPC Service Stubs for use with grpc-node

This plugin can generate .d.ts files for gRPC service definitions as required by grpc-node.

To generate these declaration files from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the service=grpc-node param to the --ts_out flag, eg:

# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"

# Path to the grpc_node_plugin
PROTOC_GEN_GRPC_PATH="./node_modules/.bin/grpc_tools_node_protoc_plugin"

# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"

protoc \
    --plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
    --plugin=protoc-gen-grpc=${PROTOC_GEN_GRPC_PATH} \
    --js_out="import_style=commonjs,binary:${OUT_DIR}" \
    --ts_out="service=grpc-node:${OUT_DIR}" \
    --grpc_out="${OUT_DIR}" \
    users.proto base.proto

The generated folder will now contain both _grpc_pb.js and _grpc_pb.d.ts files which you can reference in your TypeScript project to make RPCs.

Note This plugin does not generate the _grpc_pb.js files itself; those are generated by the protoc-gen-grpc plugin. This plugin only generates the _grpc_pb.d.ts files.

Using @grpc/grpc-js instead of grpc

Add a mode parameter to generate files that import @grpc/grpc-js instead of grpc, for example:

--ts_out="service=grpc-node,mode=grpc-js:${OUT_DIR}"

You'll also need to specify the grpc_js option within the --grpc_out flag, for example:

--grpc_out="grpc_js:${OUT_DIR}"

If you're consuming the server interface types you'll need to use version @grpc/[email protected] or higher.

Examples

Gotchas

By default the google-protobuf library will use the JavaScript number type to store 64bit float and integer values; this can lead to overflow problems as you exceed JavaScript's Number.MAX_VALUE. To work around this, you should consider using the jstype annotation on any 64bit fields, ie:

message Example {
  uint64 bigInt = 1 [jstype = JS_STRING];
}
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].