or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tool.mdindex.mdproto-loading.mdtype-definitions.md
tile.json

proto-loading.mddocs/

Protocol Buffer Loading

Core functionality for loading and parsing .proto files with various configuration options and formats.

Capabilities

Primary Loading Functions

load

Asynchronously loads .proto files with specified options.

/**
 * Load a .proto file with the specified options.
 * @param filename One or multiple file paths to load. Can be an absolute path or relative to an include path.
 * @param options Configuration options for parsing and conversion
 * @returns Promise resolving to PackageDefinition
 */
function load(
  filename: string | string[],
  options?: Options
): Promise<PackageDefinition>;

Usage Examples:

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

// Single file
const packageDef = await protoLoader.load("./protos/service.proto");

// Multiple files
const packageDef = await protoLoader.load([
  "./protos/service1.proto",
  "./protos/service2.proto"
], {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});

// With include directories
const packageDef = await protoLoader.load("service.proto", {
  includeDirs: ["./protos", "./external-protos"]
});

loadSync

Synchronously loads .proto files with specified options.

/**
 * Synchronously load .proto files with specified options
 * @param filename One or multiple file paths to load
 * @param options Configuration options for parsing and conversion
 * @returns PackageDefinition
 */
function loadSync(
  filename: string | string[],
  options?: Options
): PackageDefinition;

Usage Examples:

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

// Synchronous loading
const packageDef = protoLoader.loadSync("./protos/service.proto", {
  keepCase: true,
  longs: String,
  enums: String
});

// Multiple files synchronously
const packageDef = protoLoader.loadSync([
  "./protos/auth.proto",
  "./protos/users.proto"
]);

Alternative Loading Methods

fromJSON

Creates PackageDefinition from Protobuf.js JSON namespace.

/**
 * Create PackageDefinition from Protobuf.js JSON namespace
 * @param json Protobuf.js namespace object
 * @param options Configuration options for conversion
 * @returns PackageDefinition
 */
function fromJSON(
  json: Protobuf.INamespace,
  options?: Options
): PackageDefinition;

Usage Examples:

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

// Load from JSON representation
const protoJson = require('./compiled-proto.json');
const packageDef = protoLoader.fromJSON(protoJson, {
  longs: String,
  enums: String
});

loadFileDescriptorSetFromBuffer

Loads PackageDefinition from binary FileDescriptorSet buffer.

/**
 * Load PackageDefinition from binary FileDescriptorSet buffer
 * @param descriptorSet Binary buffer containing FileDescriptorSet
 * @param options Configuration options for conversion
 * @returns PackageDefinition
 */
function loadFileDescriptorSetFromBuffer(
  descriptorSet: Buffer,
  options?: Options
): PackageDefinition;

Usage Examples:

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

// Load from descriptor set file
const descriptorBuffer = fs.readFileSync("./compiled-descriptors.desc");
const packageDef = protoLoader.loadFileDescriptorSetFromBuffer(descriptorBuffer, {
  longs: String,
  defaults: true
});

loadFileDescriptorSetFromObject

Loads PackageDefinition from FileDescriptorSet object.

/**
 * Load PackageDefinition from FileDescriptorSet object
 * @param descriptorSet FileDescriptorSet object compatible with protobufjs descriptor format
 * @param options Configuration options for conversion
 * @returns PackageDefinition
 */
function loadFileDescriptorSetFromObject(
  descriptorSet: Parameters<typeof descriptor.FileDescriptorSet.fromObject>[0],
  options?: Options
): PackageDefinition;

Configuration Options

Options Interface

interface Options extends Protobuf.IParseOptions, Protobuf.IConversionOptions {
  includeDirs?: string[];
}

The Options interface extends Protobuf.js parsing and conversion options with additional proto-loader specific settings:

Conversion Options (from Protobuf.IConversionOptions)

OptionTypeDefaultDescription
keepCasebooleanfalsePreserve field names. Default is to change them to camel case
longsString | NumberLong objectThe type to use to represent long values
enumsStringnumberThe type to use to represent enum values
bytesArray | StringBufferThe type to use to represent bytes values
defaultsbooleanfalseSet default values on output objects
arraysbooleanfalseSet empty arrays for missing array values even if defaults is false
objectsbooleanfalseSet empty objects for missing object values even if defaults is false
oneofsbooleanfalseSet virtual oneof properties to the present field's name
jsonbooleanfalseRepresent Infinity and NaN as strings in float fields, and automatically decode google.protobuf.Any values

Parse Options (from Protobuf.IParseOptions)

OptionTypeDefaultDescription
alternateCommentModebooleanfalseWhether to recognize double-slash comments in addition to /* */ comments
preferTrailingCommentbooleanfalseWhether to prefer trailing comments over leading comments

Proto-loader Specific Options

OptionTypeDefaultDescription
includeDirsstring[]undefinedA list of search paths for imported .proto files

Common Configuration Examples:

// gRPC-compatible options (similar to legacy grpc.load behavior)
const grpcOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};

// JSON-friendly options
const jsonOptions = {
  longs: String,
  enums: String,
  bytes: String,
  defaults: true,
  json: true
};

// Minimal options for performance
const minimalOptions = {
  keepCase: false,
  longs: Number,
  enums: Number
};

Utility Functions

addCommonProtos

Loads Google's well-known proto files that aren't exposed by Protobuf.js.

/**
 * Load Google's well-known proto files that aren't exposed by Protobuf.js
 * Automatically called when importing @grpc/proto-loader
 * Includes: api, descriptor, source_context, type
 * Excludes: any, duration, empty, field_mask, struct, timestamp, wrappers (already in Protobuf.js)
 */
function addCommonProtos(): void;

This function is automatically called when importing the package, so Google's common proto types are available by default without manual invocation.

Note: The following Google Protocol Buffer types are made available:

  • google.protobuf.Api - API configuration
  • google.protobuf.DescriptorProto - Message descriptor
  • google.protobuf.SourceContext - Source context information
  • google.protobuf.Type - Type information

Types already available through Protobuf.js (not added by this function):

  • google.protobuf.Any, google.protobuf.Duration, google.protobuf.Empty
  • google.protobuf.FieldMask, google.protobuf.Struct, google.protobuf.Timestamp
  • google.protobuf.BoolValue, google.protobuf.StringValue, etc. (wrapper types)

Error Handling

Loading functions may throw or reject with errors in these scenarios:

  • File not found: When .proto files or include directories don't exist
  • Parse errors: When .proto files contain syntax errors
  • Import resolution failures: When imported .proto files cannot be found
  • Invalid options: When configuration options are malformed

Error Handling Examples:

// Async error handling
try {
  const packageDef = await protoLoader.load("service.proto", options);
} catch (error) {
  console.error("Failed to load proto:", error.message);
}

// Sync error handling
try {
  const packageDef = protoLoader.loadSync("service.proto", options);
} catch (error) {
  console.error("Failed to load proto synchronously:", error.message);
}