In this post, I'll cover the "why" of gRPC, the structure of protobuf files, and some of the Typescript interop offered by two NodeJS packages for gRPC: 

This post assumes some familiarity with microservice architecture and RESTful API calls. With all APIs, including the well known REST and SOAP flavors, there are two players:

A deep discussion on the "how" and "why" of RESTful microservices (statelessness, etc.) is best left for another post. Instead, we'll dive into gRPC, an alternative to REST and SOAP that's been gaining some traction recently. gRPC is another protocol for two back-end services can use to communicate that confers some unique advantages.

gRPC is an efficient means of service to service communication and is an alternative to REST and SOAP. gRPC sends messages over HTTP/2 using a binary serialization standard called protocol buffers. Google initially released the gRPC serialization standard in 2016. Protocol buffers are often referred to in the shorthand "protobufs". 

RPC is a ubiquitous term that stands for "Remote Procedure Call", a fancy way of saying that we want to run some code on another machine. The "g" doesn't actually stand for "Google", even though they created and continue to maintain gRPC. They use the letter G to name releases, such as version 1.12, 

Like any HTTP request made with a library like Axios/Fetch in Node or HttpClient in .NET, gRPC is language agnostic. As such, clients needn't concern themselves over the implementation details of the API on the server. Rather, they need only be aware that the gRPC service exists to serve the request, as well as the name and shape of the request and response.

gRPC comes with a couple of advantages, or rather, use cases in which it might be preferable to REST.

Now that we know a little more about what gRPC is and when we might consider it for a project, let's dive into an example using Typescript.

"Hello, World" for the tiny gRPC service we'll build starts with our service definition. Whatever language our caller or server are using isn't really important just yet. Google maintains reference 

 for protocol buffer version 3, the newest production-ready version of the syntax. In our contract, we want a single function that accepts a 

// greeter_service.proto

syntax = "proto3";

package greeter_service;

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

Pretty straightforward, but let's break this down.

syntax = "proto3";

package greeter_service;

You'll see something like this at the top of most protobufs. 

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

 methods/functions that some service must provide, as well as the types of the request and response messages. A single .proto file can contain multiple logical  

 keywords, and a single service can have as many 

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

 keyword specifies the shape of the messages that will be passed back and forth. It's possible to nest messages, just like nesting objects in JSON. Arrays are there as well. This allows for some pretty robust messages with structures that everyone who's used to JSON should be familiar with.

The only thing that should stand out as a little unusual here are the things that look like assignment operators (=) with a number after them. These numbers specify the 

 for each field in the message. This is the order in which the binary data will be arranged before the messages are transmitted. Having a mismatched field order between client and server 

 cause errors, or might not. Imagine having two string fields with mismatched field order. The server would just see two strings, but we might end up with data from the 

 field on the server! Quite tricky to debug. 

Now that we've got a protobuf definition, let's build a Typescript service that can handle the request. I ran a few commands to set up my dependencies in a brand new Node project.

For this project, we start with an empty npm package that I've called 

. The project consists solely of the following:

npm i @grpc/grpc-js @grpc/proto-loader ts-node

npm i --save-dev rimraf typescript ts-node-dev

Of these, the two gRPC packages and rimraf will be part of our build workflow. We'll also need a couple of scripts:

"scripts": {
  "dev": "tsnd --transpile-only --ignore-watch node_modules ./src/main.ts",
  "generate": "rimraf ./proto && proto-loader-gen-types --longs=String --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --outDir=proto greeter_service.proto"
}

 will generate the types necessary for us to write code for our handler and server setup. 

 script looks a little daunting, but that's largely due to the number of 

 folder at the project root that consists of several helper types. Since we added 

 to .gitignore, we won't source control this folder. Furthermore, any time our protobuf definition changes, we can simply run the script again.

A handler refers to a function on the server that will be invoked whenever a client calls a given RPC. The handler's job is to accept the request message specified in the protobuf, and provide the required response message. For our simple case, we'll need a Greet function that accepts an object with 

 properties, that returns an object consisting of a single 

With Typescript, we can use the generated type 

 to specify what the shape of our handler (a Javascript object) should look like:

// ./src/greeter.handler.ts

import { GreeterServiceHandlers } from "../proto/greeter_service/GreeterService";

export const greeterHandler: GreeterServiceHandlers = {
	Greet: (call, callback) => {
		const { name, location } = call.request;
		callback(null, {
			greeting: `Hello, ${name}, how is the weather in ${location}?`,
		});
	},
}


When the handler is invoked, the request data is available on the 

 function is used to "return" the response to the client, in lieu of the return statement you'd typically see in an Express REST API. The first parameter in 

 is reserved for an error, if the server happens to catch an Exception and wants to report it back to the caller. If we had more than one RPC in our protobuf, we'd just implement them as siblings of 

Finally, we're ready to start the server by writing the implementation for 

// ./src/main.ts (Server project)

import { Server, ServerCredentials } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { loadPackageDefinition } from "@grpc/grpc-js";
import { ProtoGrpcType } from "../proto/greeter_service";
import { greeterHandler } from "./greeter.handler";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);
grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});


There's a lot to unpack here, but the actual code is only around 6-8 lines long.

// Loading the service definition from the protobuf
const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

 function, which constructs a utility object for us based on the service definition that it parses from the specified .proto file. We'll use this in a bit.

// Construct the server and add the Greeter Service, mapping greeterHandler 
const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);

 helper object by adding the GreeterService to our gRPC server. Importantly, this step is where we set up the mapping between the gRPC service and the handler that we created earlier to handle requests to this service.

grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});

Lastly, we start the service using 0.0.0.0:50051 as an alias for localhost, port 50051. When using SSL on a production server, 

, but this will suffice for dev work. In the callback, we show a helpful message and finally start the server.

 on our server, we'll be able to make Greet requests to the handler using any gRPC client like 

. To finish the example, though, let's create a new project and make our own client using Typescript.

For the initial setup, I created an npm package called 

and performed the following initial setup steps: 

 to generate types, just like on the server!

Your client might end up becoming an Express service, a GraphQL service, a serverless function deployed in Azure/AWS, or a CRON job. As such, I'll show the bare minimum code necessary to get a response from the Greeter Service. The rest is left as an exercise for the reader. We'll do our client implementation in 

// ./src/main.ts (Client project)

import { credentials, loadPackageDefinition } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { ProtoGrpcType } from "../proto/greeter_service";
import { GreetRequest } from "../proto/greeter_service/GreetRequest";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

const greetRequest: GreetRequest = {
	name: "Justin",
	location: "MA",
};

greeterClient.Greet(greetRequest, (err, response) => {
	if (err) {
		console.error(err);
	} else {
		console.log(response.greeting);
	}
});

We can break this into a couple of distinct parts.

// Create the client 
const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

Much like server creation, we load the package definition for the Greeter Service from the protobuf. This time though, we use this definition to construct a client object instead. After specifying our server's address and our credentials, we're now ready to make requests.

// Create the request object
const greetRequest: GreetRequest = {
	name: "Justin",
	location: "MA",
};

// Invoke the RPC "Greet"
greeterClient.Greet(greetRequest, (err, response) => {
	if (err) {
		console.error(err);
	} else {
		console.log(response.greeting);
	}
});

 type, it's easy to make sure that our request is structured properly. From there, it's as simple as calling 

 on the client, and handling the response in the callback.  As long as the server is running, the output of this code is:

'Hello, Justin, how is the weather in MA?'

When you're used to working with Promises and async functions, you can Promisify this code with a wrapper function, like so:

// ./src/main.ts

import { credentials, loadPackageDefinition } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { ProtoGrpcType } from "../proto/greeter_service";
import { GreetRequest } from "../proto/greeter_service/GreetRequest";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;
const greeterClient = new proto.greeter_service.GreeterService("0.0.0.0:50051", credentials.createInsecure());

const start = async () => {
	const greetRequest: GreetRequest = {
		name: "Justin",
		location: "MA",
	};
	const response = await greet(greetRequest);
	console.log(response);
}

const greet = (request: GreetRequest): Promise<GreetResponse> => {
	return new Promise((resolve, reject) => {
		greeterClient.Greet(request, (err, response) => {
			if (err) {
				reject(err);
			} else {
				resolve(response);
			}
		});
	});
}

start();


The amended version is a little simpler to work with when you're already deep inside a stack of async functions, possibly making other API calls using 

As with any technology, keep a few things in mind when considering gRPC as an addition to your architecture.

That last point kind of snuck in there, since the same caveats apply to RESTful API design. But it's important to keep in mind that the benefits of gRPC can't outweigh risky design decisions from the outset. "If you've got a hammer, everything looks like a nail" is true more often than we'd sometimes like to admit.

If you map out your service-to-service calls and they resemble this picture, you probably have some tech debt to pay down.

At Go Ahead Tours Engineering, gRPC has been our go-to choice of protocol when we happen to have need of service to service communication. 

gRPC can be a powerful REST or SOAP replacement if your use case calls for it. The strictness prescribed by protobufs can be a bit of a paradigm shift, but can also encourage good habits and a cleaner architecture. Like any technology, it's important to make sure that you aren't using gRPC as a solution in search of a problem. Take a step back from your use case and observe carefully. The speed and type safety offered by gRPC may be just what the doctor ordered!

 source code on Github. Not production ready!

gRPC Client Server Diagram

When developing  an API, we very often reach for REST.  In some cases, however, we can instead take advantage of a structured and speedy standard called gRPC.

gRPC Services with a Type Generation Example for NodeJS and Typescript

gRPC Services with Type Generation for NodeJS

At EF Go Ahead Tours Engineering, we use a tool called 

 often. Since we use TypeScript and GraphQL, it saves us a lot of time since we can create TypeScript types from our GraphQL schema. Let's set up a basic GraphQL schema to show how it works:

const typeDefs = gql`
    type Query {
        cart(id: ID!): Cart
        carts: [Cart!]
    }
    
    type Cart {
        items: [Product!]
        grandTotal: Int!
    }

    type Product {
        sku: String!
        price: Int!
    }
`

Pretty simple, we have a two queries and a basic eCommerce model. This sets up our contract with our API. Let's generate our application types. We can do this by installing the needed packages and the plugins for typescript:

npm i @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-resolvers

All of these packages gives us the functionality to generate both types and a typed resolver, with a pretty minimal configuration, as specified in a YAML file. Let's set one up:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers

This is an incredibly barebones configuration, only meant to show the TypeScript type generation, more details about configuration can be found 

All that's left is to run our generator and see what types we are able to use!

  "scripts": {
    "generate": "graphql-codegen"
  }  

at which point the command can be run with 

After this, we can see what types are generated in the 

 file! Having this tool is incredibly helpful for both back end and front end work, since our types can be generated from our GraphQL schema, which introduces coupling of the schema definition and the types that we can use within our apps. This makes GraphQL schemas 

, which means that the data and the types of that data is now available for us to use in TypeScript!

graphql-codegen works for both server and client side. Let's implement a basic resolver using our newly generated types:

import { Resolvers } from "./src/generated/types.ts"

export const resolvers: Resolvers => {
    Query: {
        cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
    }
}

 type from our generated schema, which gives us typechecking for all of our resolvers! This also includes typechecking for our parent type, our field arguments, and our context. Super easy! The package also splits out each individual resolver so one could do:

// ./src/cartResolvers.ts
import { CartResolvers } from "./src/generated/types.ts"

export const cartResolvers: CartResolvers => {
    cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
}

export const resolvers: Resolvers => {
    Query: {
        ...cartResolvers
    }
}

This makes creating typechecked resolvers with IntelliSense in VS Code very easy and guarantees static types from your schema. How can this tool also help us with the front end? After all, one of the benefits of using GraphQL is that we can query only the data we need. We can do this with a very minimal configuration update in our client side app, copying it from our GraphQL server configuration:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers
+     - typescript-react-apollo
+     - typescript-operations
+     - fragment-matcher
+ documents: "src/graphql/**.{ts, tsx, graphql}"

This configuration will scrape all of our graphql, ts, and tsx files in our 

 file. We'll also need to install the extra plugins that this config requires:

npm i @graphql-codegen/typescript-operations @graphql-codegen/fragment-matcher @graphql-codegen/typescript-react-apollo

At EF Go Ahead Tours we use the first one quite a bit in most typical front-end applications, since we leverage a ton of GraphQL. A typical React component that fetches a cart by ID from our GraphQL server with a search parameter would look like:

// src/graphql/cart.graphql

query FindCart($id: ID!) {
    cart(id: $id) {
        items
        grandTotal
    }
}
        
// src/checkout/cart.tsx
import React from "react";
import { useFindCart } from "./src/generated/typedefs.ts";
import { Item } from "./Item";
import { Spinner } from "../shared/Spinner";

export const Cart: React.FC = () => {
    const cartId = new URLSearchParams(window.location.search).get("cartId");
    const { data, loading } = useFindCart({
        variables: {
            id: cartId ?? ""
        }
    });

   if (loading) {
        return <Spinner />
    }

    return (
        <>
            <h2>{data.grandTotal}</h2>
            {data?.items.map((item) => <Item item={item} />
        </>
    );
}

Where all of our queries and mutations, along with their variables are typechecked. This makes it very easy to build services alongside clients that consume those services, while maintaining type checking between the both of them. Graphql-codegen is an invaluable tool for us developers here at EF Go Ahead Tours. Without it we would never have been able to build services and front end applications with the speed of sharing types between client and server without the manual work of migrating types and the developer experience that using graphql-codegen affords us.

Untitled

GraphQL Codegen: What is it?

A seemingly common complaint regarding NestJS and TypeScript is the absence of interfaces in runtime code (since interfaces are removed during transpilation). This limitation prevents the use of constructor-based dependency injection and instead necessitates use of the 

 decorator. That decorator requires us to associate some "real" JavaScript token with the interface to resolve the dependency - often just a string of the interface name:

/* IAnimal.ts */
export interface IAnimal {
  speak(): string;
}

/* animal.service.ts */
export class Dog implements IAnimal {
  speak() {
    return "Woof";
  }
}

/* animal.module.ts */
@Module({
  providers: [{
    provide: "IAnimal",
    useClass: Dog,
  }]
})
export class AnimalModule

/* client.ts */
export class Client {
  constructor(@Inject("IAnimal") private animal: IAnimal) {}

  // Later...
  this.animal.speak();
}

This approach is adequate, but the "IAnimal" magic string is a little fragile and not actually associated with the interface. A modest improvement can be made by exporting a token with the interface:

/* IAnimal.ts */
export interface IAnimal {
  speak(): string;
}

export const IAnimalToken = "IAnimal";
// or slightly better...
export const IAnimalToken = Symbol("IAnimal");

/* animal.module.ts */
@Module({
  providers: [{
    provide: IAnimalToken,
    useClass: Dog,
  }]
})
export class AnimalModule

/* client.ts */
export class Client {
  constructor(@Inject(IAnimalToken) private animal: IAnimal) {}

  // Later...
  this.animal.speak();
}

At least now the token reference is consistent. Still, manually injecting tokens like this can be cumbersome and conceptually unsatisfying. What we would really like is a true JavaScript object in the place of the interface, which we can reference universally at runtime. What we would really like is...an abstract class!

/* IAnimal.ts */
export abstract class IAnimal {
    abstract speak(): string;
}

/* animal.service.ts */
// You can implement an abstract class without extending it!
export class Dog implements IAnimal {
  speak() {
    return "Woof";
  }
}

/* animal.module.ts */
@Module({
  providers: [{
    provide: IAnimal,
    useClass: Dog,
  }]
})
export class AnimalModule

/* client.ts */
export class Client {
  constructor(private animal: IAnimal) {}

  // Later...
  this.animal.speak();
}

Now a single, "real" JavaScript reference is used throughout the application to resolve the dependency. Whether or not the minor inconvenience of token-based dependency injection justifies this usage of abstract classes is a separate question. If you're feeling lazy, though, this is a convenient option!

NestJS logo with a cat in the background

TypeScript interfaces don't have meaning at runtime so NestJS can't use them as tokens for DI. Learn how to use abstract classes to fill that gap.

#typescript.

gRPC Services with a Type Generation Example for NodeJS and Typescript

GraphQL Codegen: What is it?

NestJS Dependency Injection with Abstract Classes