@grpc/proto-loader

What is @grpc/proto-loader?

The @grpc/proto-loader package is used to load .proto files and generate JavaScript objects. It is primarily used in conjunction with gRPC, a high-performance, open-source universal RPC framework, to dynamically load protocol buffer definitions at runtime.

What are @grpc/proto-loader's main functionalities?

Loading .proto files

This feature allows you to load .proto files and create a package definition that can be used to make RPC calls.

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('your_proto_file.proto', {});
const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
const yourService = protoDescriptor.your_package.YourService;

Customizing the loader options

This feature allows you to customize how the .proto files are loaded by specifying options such as whether to keep the original field casing or convert enums to strings.

const options = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('your_proto_file.proto', options);

Asynchronous loading of .proto files

This feature allows you to load .proto files asynchronously, which can be useful if you want to handle the loading process without blocking the event loop.

const protoLoader = require('@grpc/proto-loader');
protoLoader.load('your_proto_file.proto', {}).then(packageDefinition => {
  const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
  // Use protoDescriptor to create gRPC service client
}).catch(err => {
  console.error('Error loading .proto file', err);
});

Other packages similar to @grpc/proto-loader

protobufjs

Protobufjs is a pure JavaScript implementation of Protocol Buffers. It provides similar functionality to @grpc/proto-loader but with additional features like creating .proto files programmatically and a more complex API for handling protocol buffers.

grpc-tools

grpc-tools is a package that includes protocol buffer compiler (protoc) and a plugin for generating gRPC service code. It is used for generating static service code from .proto files, as opposed to the dynamic loading approach of @grpc/proto-loader.

grpc-web

grpc-web provides a JavaScript library that lets browser clients access a gRPC service. It is similar to @grpc/proto-loader in that it deals with gRPC and protocol buffers, but it is specifically designed for web clients.

README

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

npm install @grpc/proto-loader

Usage

const protoLoader = require('@grpc/proto-loader');
const grpcLibrary = require('grpc');
// OR
const grpcLibrary = require('@grpc/grpc-js');

protoLoader.load(protoFileName, options).then(packageDefinition => {
  const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition);
});
// OR
const packageDefinition = protoLoader.loadSync(protoFileName, options);
const 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:

const options = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
}