@grpc/grpc-js

What is @grpc/grpc-js?

The @grpc/grpc-js package is a pure JavaScript implementation of gRPC, which stands for gRPC Remote Procedure Calls. It allows you to define service methods and their input/output types using Protocol Buffers, and it handles the networking layer transparently. This package is used to build client and server applications that communicate over the gRPC protocol, which is particularly suited for microservices and other distributed systems where performance and scalability are important.

What are @grpc/grpc-js's main functionalities?

Defining a gRPC Service

This code demonstrates how to define a gRPC service using a .proto file. The service definition includes the RPC methods that can be called remotely.

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;

Creating a gRPC Server

This code sample shows how to create a gRPC server, add a service to it, and start listening for client requests on a specified port.

const grpc = require('@grpc/grpc-js');

const server = new grpc.Server();
server.addService(yourService.service, {
  yourMethod: (call, callback) => {
    // Implement your method logic here
    callback(null, response);
  }
});
server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {
  server.start();
});

Creating a gRPC Client

This code snippet illustrates how to create a gRPC client that can call methods on a gRPC server. The client uses the service definition from a .proto file to make properly structured 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 client = new protoDescriptor.your_package.YourService('localhost:50051', grpc.credentials.createInsecure());

client.yourMethod({ yourRequestField: 'yourValue' }, (error, response) => {
  // Handle the response or error
});

Other packages similar to @grpc/grpc-js

grpc

The 'grpc' package is the original Node.js gRPC library, which relies on the C-based gRPC core library. It provides similar functionality to @grpc/grpc-js but requires native dependencies. The @grpc/grpc-js package was created as a pure JavaScript alternative, eliminating the need for native compilation and simplifying deployment, especially in serverless environments.

protobufjs

While 'protobufjs' is not a direct alternative to @grpc/grpc-js, it is a related package that provides tools for working with Protocol Buffers, which are an integral part of gRPC. It allows you to encode and decode Protocol Buffers messages but does not handle the gRPC networking layer.

thrift

Apache Thrift is another RPC framework that can be used as an alternative to gRPC. It supports multiple programming languages and has its own interface definition language (IDL). The 'thrift' package for Node.js allows you to build clients and servers using the Thrift protocol, which, like gRPC, is designed for efficient communication between services.

README

Pure JavaScript gRPC Client

Note: This is an beta-level release. Some APIs may not yet be present and there may be bugs. Please report any that you encounter

Installation

Node 10 is recommended. The exact set of compatible Node versions can be found in the engines field of the package.json file.

npm install @grpc/grpc-js

Features

• Unary and streaming calls
• Cancellation
• Deadlines
• TLS channel credentials
• Call credentials (for auth)
• Simple reconnection
• Channel API

This library does not directly handle .proto files. To use .proto files with this library we recommend using the @grpc/proto-loader package.

Some Notes on API Guarantees

The public API of this library follows semantic versioning, with some caveats:

• Some methods are prefixed with an underscore. These methods are internal and should not be considered part of the public API.
• The class Call is only exposed due to limitations of TypeScript. It should not be considered part of the public API.
• In general, any API that is exposed by this library but is not exposed by the grpc library is likely an error and should not be considered part of the public API.