gRPC Protobuf Loader

A utility package for loading .proto files for use with gRPC, using the latest Protobuf.js package. Please refer to protobuf.js' documentation to understands its features and limitations.

Installation

1npm install @grpc/proto-loader

Usage

1const protoLoader = require('@grpc/proto-loader');
2const grpcLibrary = require('grpc');
3// OR
4const grpcLibrary = require('@grpc/grpc-js');
5
6protoLoader.load(protoFileName, options).then(packageDefinition => {
7  const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition);
8});
9// OR
10const packageDefinition = protoLoader.loadSync(protoFileName, options);
11const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition);

The options parameter is an object that can have the following optional properties:

Field name	Valid values	Description
keepCase	true or false	Preserve field names. The default is to change them to camel case.
longs	String or Number	The type to use to represent long values. Defaults to a Long object type.
enums	String	The type to use to represent enum values. Defaults to the numeric value.
bytes	Array or String	The type to use to represent bytes values. Defaults to Buffer.
defaults	true or false	Set default values on output objects. Defaults to false.
arrays	true or false	Set empty arrays for missing array values even if defaults is false Defaults to false.
objects	true or false	Set empty objects for missing object values even if defaults is false Defaults to false.
oneofs	true or false	Set virtual oneof properties to the present field's name. Defaults to false.
json	true or false	Represent Infinity and NaN as strings in float fields, and automatically decode google.protobuf.Any values. Defaults to false
includeDirs	An array of strings	A list of search paths for imported .proto files.

The following options object closely approximates the existing behavior of grpc.load:

1const options = {
2  keepCase: true,
3  longs: String,
4  enums: String,
5  defaults: true,
6  oneofs: true
7}

Generating TypeScript types

The proto-loader-gen-types script distributed with this package can be used to generate TypeScript type information for the objects loaded at runtime. More information about how to use it can be found in the @grpc/proto-loader TypeScript Type Generator CLI Tool proposal document. The arguments mostly match the load function's options; the full usage information is as follows:

1proto-loader-gen-types.js [options] filenames...
2
3Options:
4      --help             Show help                                     [boolean]
5      --version          Show version number                           [boolean]
6      --keepCase         Preserve the case of field names
7                                                      [boolean] [default: false]
8      --longs            The type that should be used to output 64 bit integer
9                         values. Can be String, Number[string] [default: "Long"]
10      --enums            The type that should be used to output enum fields. Can
11                         be String                  [string] [default: "number"]
12      --bytes            The type that should be used to output bytes fields.
13                         Can be String, Array       [string] [default: "Buffer"]
14      --defaults         Output default values for omitted fields
15                                                      [boolean] [default: false]
16      --arrays           Output default values for omitted repeated fields even
17                         if --defaults is not set     [boolean] [default: false]
18      --objects          Output default values for omitted message fields even
19                         if --defaults is not set     [boolean] [default: false]
20      --oneofs           Output virtual oneof fields set to the present field's
21                         name                         [boolean] [default: false]
22      --json             Represent Infinity and NaN as strings in float fields.
23                         Also decode google.protobuf.Any automatically
24                                                      [boolean] [default: false]
25      --includeComments  Generate doc comments from comments in the original
26                         files                        [boolean] [default: false]
27  -I, --includeDirs      Directories to search for included files        [array]
28  -O, --outDir           Directory in which to output files  [string] [required]
29      --grpcLib          The gRPC implementation library that these types will
30                         be used with. If not provided, some types will not be
31                         generated                                      [string]
32      --inputTemplate    Template for mapping input or "permissive" type names
33                                                        [string] [default: "%s"]
34      --outputTemplate   Template for mapping output or "restricted" type names
35                                                [string] [default: "%s__Output"]
36      --inputBranded     Output property for branded type for  "permissive"
37                         types with fullName of the Message as its value
38                                                      [boolean] [default: false]
39      --outputBranded    Output property for branded type for  "restricted"
40                         types with fullName of the Message as its value
41                                                      [boolean] [default: false]

Example Usage

Generate the types:

1$(npm bin)/proto-loader-gen-types --longs=String --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --outDir=proto/ proto/*.proto

Consume the types:

1import * as grpc from '@grpc/grpc-js';
2import * as protoLoader from '@grpc/proto-loader';
3import type { ProtoGrpcType } from './proto/example.ts';
4import type { ExampleHandlers } from './proto/example_package/Example.ts';
5
6const exampleServer: ExampleHandlers = {
7  // server handlers implementation...
8};
9
10const packageDefinition = protoLoader.loadSync('./proto/example.proto');
11const proto = (grpc.loadPackageDefinition(
12  packageDefinition
13) as unknown) as ProtoGrpcType;
14
15const server = new grpc.Server();
16server.addService(proto.example_package.Example.service, exampleServer);