gRPC utility library for loading .proto files. 

gRPC utility library for loading .proto files

grpc-packages

murgatroid99

nicolasnoble

@grpc/proto-loader

 * 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

Object.defineProperty(exports, "__esModule", { value: true });

const camelCase = require("lodash.camelcase");

const useNameFmter = ({ outputTemplate, inputTemplate }) => {

    if (outputTemplate === inputTemplate) {

        throw new Error('inputTemplate and outputTemplate must differ');

        outputName: (n) => outputTemplate.replace(templateStr, n),

        inputName: (n) => inputTemplate.replace(templateStr, n)

        for (let i = 0; i < this.indentValue; i += 1) {

            this.textParts.push(this.indentText);

    return Array.isArray(obj.nestedArray);

    return name.startsWith('.') ? name.substring(1) : name;

    /* If the thing we are importing is defined in a message, it is generated in

    if (to.parent instanceof Protobuf.Type) {

    return stripLeadingPeriod(to.fullName).replace(/\./g, '/');

    return stripLeadingPeriod(to.fullName).replace(/\./g, '/') + '.ts';

    const depth = stripLeadingPeriod(from.fullName).split('.').length - 1;

function getRelativeImportPath(from, to) {

    return `import type { ${importedTypes} } from '${filePath}';`;

    return `import type { ${importedTypes} } from '${filePath}.ts';`;

function getChildMessagesAndEnums(namespace) {

    for (const nested of namespace.nestedArray) {

        if (nested instanceof Protobuf.Type || nested instanceof Protobuf.Enum) {

            messageList.push(...getChildMessagesAndEnums(nested));

function formatComment(formatter, comment, options) {

    if (!comment && !(options === null || options === void 0 ? void 0 : options.deprecated)) {

        for (const line of comment.split('\n')) {

            formatter.writeLine(` * ${line.replace(/\*\//g, '* /')}`);

    if (options === null || options === void 0 ? void 0 : options.deprecated) {

        formatter.writeLine(' * @deprecated');

const typeBrandHint = `This field is a type brand and is not populated at runtime. Instances of this type should be created using type assertions.

https://github.com/grpc/grpc-node/pull/2281`;

function formatTypeBrand(formatter, messageType) {

    formatComment(formatter, typeBrandHint);

    formatter.writeLine(`__type: '${messageType.fullName}'`);

function getTypeNamePermissive(fieldType, resolvedType, repeated, map, options) {

    const { inputName } = useNameFmter(options);

            return 'number | string | Long';

            return 'Buffer | Uint8Array | string';

                throw new Error('Found field with no usable type');

            const typeInterfaceName = getTypeInterfaceName(resolvedType);

            if (resolvedType instanceof Protobuf.Type) {

                    return inputName(typeInterfaceName);

                    return `${inputName(typeInterfaceName)} | null`;

                return inputName(typeInterfaceName);

function getFieldTypePermissive(field, options) {

    const valueType = getTypeNamePermissive(field.type, field.resolvedType, field.repeated, field.map, options);

    if (field instanceof Protobuf.MapField) {

        const keyType = field.keyType === 'string' ? 'string' : 'number';

        return `{[key: ${keyType}]: ${valueType}}`;

function generatePermissiveMessageInterface(formatter, messageType, options, nameOverride) {

        formatComment(formatter, messageType.comment, messageType.options);

    if (messageType.fullName === '.google.protobuf.Any') {

        /* This describes the behavior of the Protobuf.js Any wrapper fromObject

        formatter.writeLine(`export type ${inputName('Any')} = AnyExtension | {`);

        formatter.writeLine('  type_url: string;');

        formatter.writeLine('  value: Buffer | Uint8Array | string;');

  "description": "gRPC utility library for loading .proto files",

    "format": "clang-format -i -style=\"{Language: JavaScript, BasedOnStyle: Google, ColumnLimit: 80}\" src/*.ts test/*.ts",

    "lint": "tslint -c node_modules/google-ts-style/tslint.json -p . -t codeFrame --type-check",

    "generate-golden": "node ./build/bin/proto-loader-gen-types.js --keepCase --longs=String --enums=String --defaults --oneofs --json --includeComments --inputTemplate=I%s --outputTemplate=O%s -I deps/gapic-showcase/schema/ deps/googleapis/ -O ./golden-generated --grpcLib @grpc/grpc-js google/showcase/v1beta1/echo.proto",

    "validate-golden": "rm -rf ./golden-generated-old && mv ./golden-generated/ ./golden-generated-old && npm run generate-golden && diff -rb ./golden-generated ./golden-generated-old"

    "url": "https://github.com/grpc/grpc-node.git"

    "url": "https://github.com/grpc/grpc-node/issues"

    "proto-loader-gen-types": "./build/bin/proto-loader-gen-types.js"

A utility package for loading `.proto` files for use with gRPC, using the latest Protobuf.js package.

Please refer to [protobuf.js' documentation](https://github.com/dcodeIO/protobuf.js/blob/master/README.md)

to understands its features and limitations.

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

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

protoLoader.load(protoFileName, options).then(packageDefinition => {

  const packageObject = grpcLibrary.loadPackageDefinition(packageDefinition);

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`:

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](https://github.com/grpc/proposal/blob/master/L70-node-proto-loader-type-generator.md). The arguments mostly match the `load` function's options; the full usage information is as follows:

proto-loader-gen-types.js [options] filenames...

      --help             Show help                                     [boolean]

      --version          Show version number                           [boolean]

      --keepCase         Preserve the case of field names

                                                      [boolean] [default: false]

      --longs            The type that should be used to output 64 bit integer

                         values. Can be String, Number[string] [default: "Long"]

      --enums            The type that should be used to output enum fields. Can

                         be String                  [string] [default: "number"]

      --bytes            The type that should be used to output bytes fields.

                         Can be String, Array       [string] [default: "Buffer"]

      --defaults         Output default values for omitted fields

      --arrays           Output default values for omitted repeated fields even

                         if --defaults is not set     [boolean] [default: false]

      --objects          Output default values for omitted message fields even

      --oneofs           Output virtual oneof fields set to the present field's

                         name                         [boolean] [default: false]

      --json             Represent Infinity and NaN as strings in float fields.

                         Also decode google.protobuf.Any automatically

      --includeComments  Generate doc comments from comments in the original

                         files                        [boolean] [default: false]

  -I, --includeDirs      Directories to search for included files        [array]

  -O, --outDir           Directory in which to output files  [string] [required]

      --grpcLib          The gRPC implementation library that these types will

                         be used with. If not provided, some types will not be

                         generated                                      [string]

      --inputTemplate    Template for mapping input or "permissive" type names

                                                        [string] [default: "%s"]

      --outputTemplate   Template for mapping output or "restricted" type names

                                                [string] [default: "%s__Output"]

      --inputBranded     Output property for branded type for  "permissive"

                         types with fullName of the Message as its value

      --outputBranded    Output property for branded type for  "restricted"

import * as protoLoader from '@grpc/proto-loader';

import { ProtoGrpcType } from './proto/example';

import { ExampleHandlers } from './proto/example_package/Example';

import type { ProtoGrpcType } from './proto/example.ts';

import type { ExampleHandlers } from './proto/example_package/Example.ts';

const packageDefinition = protoLoader.loadSync('./proto/example.proto');

const proto = (grpc.loadPackageDefinition(

server.addService(proto.example_package.Example.service, exampleServer);

		{
		"name": "@grpc/proto-loader",
		"version": "0.7.10",
		"version": "0.7.11",
		"author": "Google Inc.",
		@@ -5,0 +5,0 @@ "contributors": [

		@@ -135,3 +135,3 @@ #!/usr/bin/env node
		}
		return `import type { ${importedTypes} } from '${filePath}';`;
		return `import type { ${importedTypes} } from '${filePath}.ts';`;
		}
		@@ -138,0 +138,0 @@ function getChildMessagesAndEnums(namespace) {

		@@ -117,4 +117,4 @@ # gRPC Protobuf Loader
		import * as protoLoader from '@grpc/proto-loader';
		import { ProtoGrpcType } from './proto/example';
		import { ExampleHandlers } from './proto/example_package/Example';
		import type { ProtoGrpcType } from './proto/example.ts';
		import type { ExampleHandlers } from './proto/example_package/Example.ts';

		@@ -121,0 +121,0 @@ const exampleServer: ExampleHandlers = {

Improved metrics