protoc-gen-grpc-gateway-ts

README

protoc-gen-grpc-gateway-ts

protoc-gen-grpc-gateway-ts is a TypeScript client generator for the grpc-gateway project. It generates idiomatic TypeScript clients that connect the web frontend and golang backend fronted by grpc-gateway.

Features:

1. Idiomatic Typescript clients and messages.
2. Supports both one way and server side streaming gRPC calls.
3. POJO request construction guarded by message type definitions, which is way easier compare to grpc-web.
4. No need to use swagger/open api to generate client code for the web.

Getting Started:

Install protoc-gen-grpc-gateway-ts

You will need to install protoc-gen-grpc-gateway-ts before it could be picked up by the protoc command. Just run go install github.com/grpc-ecosystem/protoc-gen-grpc-gateway-ts

Sample Usage:

protoc-gen-grpc-gateway-ts should be used along with the protoc command. A sample invocation looks like the following:

protoc --grpc-gateway-ts_out=ts_import_roots=$(pwd),ts_import_root_aliases=base:. input.proto

As a result the generated file will be input.pb.ts in the same directory.

Parameters:

ts_import_roots

Since protoc plugins do not get the import path information as what's specified in protoc -I, this parameter gives the plugin the same information to figure out where a specific type is coming from so that it can generate import statement at the top of the generated typescript file. Defaults to $(pwd)

ts_import_root_aliases

If a project has setup an alias for their import. This parameter can be used to keep up with the project setup. It will print out alias instead of relative path in the import statement. Default to "".

ts_import_roots & ts_import_root_aliases are useful when you have setup import alias in your project with the project asset bundler, e.g. Webpack.

fetch_module_directory and fetch_module_filename

protoc-gen-grpc-gateway-ts generates a shared typescript file with communication functions. These two parameters together will determine where the fetch module file is located. Default to $(pwd)/fetch.pb.ts

use_proto_names

To keep the same convention with grpc-gateway v2 & protojson. The field name in message generated by this library is in lowerCamelCase by default. If you prefer to make it stick the same with what is defined in the proto file, this option needs to be set to true.

logtostderr

Turn on logging to stderr. Default to false.

loglevel

Defines the logging levels. Default to info. Valid values are: debug, info, warn, error

Notes:

Zero-value fields are omitted from the URL query parameter list for GET requests. Therefore for a request payload such as { a: "A", b: "" c: 1, d: 0, e: false } will become /path/query?a=A&c=1. A sample implementation is present within this proto file in theintegration_tests folder. For further explanation please read the following:

• https://developers.google.com/protocol-buffers/docs/proto3#default
• https://github.com/googleapis/googleapis/blob/master/google/api/http.proto

Examples:

The following shows how to use the generated TypeScript code.

Proto file: counter.proto

// file: counter.proto
message Request {
  int32 counter = 1;
}

message Response {
  int32 result = 1;
}

service CounterService {
  rpc Increase(Request) returns (Response);
  rpc Increase10X(Request) returns (stream Response);
}

Run the following command to generate the TypeScript client:

protoc --grpc-gateway-ts_out=. counter.proto

Then a counter.pb.ts file will be available at the current directory. You can use it like the following example.

import {CounterService} from './counter.pb'

// increase the given number once  
async function increase(base: number): Promise<number> {
  const resp = await CounterService.Increase({counter: base})
  return resp.result
} 

// increase the base repeatedly and return all results returned back from server
// the notifier after the request will be called once a result comes back from server streaming
async function increaseRepeatedly(base: number): Promise<number[]> {
  let results = []
  await CounterService.Increase10X({base}, (resp: Response) => {
    result.push(resp.result)
  })

  return results
}

License

Copyright 2020 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.