gRPC Protocol Buffer Inspector

Common errors

• TypeError: grpc.load is not a function

  cause You are likely using `@grpc/grpc-js` which does not expose `grpc.load` directly. Instead, `proto-loader` is used for loading `.proto` files.
  fix If you are using `@grpc/grpc-js`, you cannot use `grpc-inspect` directly as it depends on the old `grpc` package. Consider migrating your protobuf loading to `@grpc/proto-loader` and implement custom inspection logic, or use tools designed for modern gRPC.

• Error: Cannot find module 'grpc'

  cause The `grpc` package, which `grpc-inspect` depends on, is not installed or cannot be resolved in your project.
  fix Install the deprecated `grpc` package: `npm install grpc`. Be aware that this package is unmaintained and may have compatibility issues with newer Node.js versions.

• SyntaxError: Named export 'grpcInspect' not found. The requested module 'grpc-inspect' is a CommonJS module, which may not support all module.exports as named exports.

  cause You are attempting to `import grpcInspect from 'grpc-inspect'` in an ES Module context, but `grpc-inspect` is a CommonJS module and does not provide named ESM exports.
  fix Use the CommonJS `require` syntax: `const grpcInspect = require('grpc-inspect');`. If you must use it in an ESM file, you can try `import grpcInspect from 'grpc-inspect';` after configuring your bundler or Node.js to handle CJS imports, or use dynamic import `const grpcInspect = await import('grpc-inspect');`.

Warnings

• breaking The `grpc-inspect` package heavily relies on the deprecated `grpc` npm package for loading `.proto` files. The `grpc` package has been superseded by `@grpc/grpc-js` and `@grpc/proto-loader`, which have different APIs and behaviors. Using `grpc-inspect` with modern gRPC setups (e.g., `@grpc/grpc-js`) will likely require significant refactoring or may not be directly compatible.
  Fix: Consider alternatives like `@grpc/proto-loader` for protobuf introspection or tools like `grpcurl` for live service inspection. If `grpc-inspect` functionality is critical, you may need to implement custom parsing logic or downgrade your gRPC dependency (not recommended for production).
• breaking This package is effectively abandoned, with its last update over seven years ago. It is not maintained and may have unaddressed bugs, security vulnerabilities, or incompatibilities with newer Node.js versions or underlying system libraries.
  Fix: Avoid using this package for new projects. For existing projects, evaluate the risk of using unmaintained software and plan for migration to actively maintained alternatives.
• gotcha The package uses CommonJS (`require`) syntax and does not officially support ES Modules (`import`). Attempting to `import` it directly in an ESM context will result in errors.
  Fix: If used in an ESM project, you must wrap it in a CommonJS context or use dynamic `import()` with caution, understanding the limitations. Ideally, migrate to ESM-first libraries for protobuf inspection.
• gotcha Loading `.proto` files requires careful path resolution, especially when using `grpc.load`. Relative paths might not resolve as expected in different execution environments.
  Fix: Always use `path.resolve(__dirname, 'your_file.proto')` or similar robust path resolution methods to ensure the `.proto` file is found correctly, especially when deploying or running tests.

Install

• npm install grpc-inspect npm
• yarn add grpc-inspect yarn
• pnpm add grpc-inspect pnpm

Imports

• grpcInspect
  wrong:

  import grpcInspect from 'grpc-inspect';

  correct:

  const grpcInspect = require('grpc-inspect');

  The package is primarily designed for CommonJS (`require`). Direct ESM `import` is not supported and will fail.
• descriptor.namespaceNames
  wrong:

  import { namespaceNames } from 'grpc-inspect';

  correct:

  const gi = require('grpc-inspect');
  const proto = grpc.load(pbpath);
  const d = gi(proto);
  const namespaces = d.namespaceNames();

  Utility methods like `namespaceNames()` are available on the descriptor object returned by the main `grpc-inspect` function, not as top-level named exports.

Quickstart

Demonstrates loading a protobuf definition using the deprecated `grpc` package and then using `grpc-inspect` to generate and explore an inspectable descriptor object, showcasing namespace, service, and method introspection.

const grpcInspect = require('grpc-inspect');
const grpc = require('grpc');
const path = require('path');
const fs = require('fs');

// Create a dummy .proto file for demonstration
const pbpath = path.resolve(__dirname, 'helloworld.proto');
const protoContent = `
syntax = "proto3";

package helloworld;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}`;

fs.writeFileSync(pbpath, protoContent);

try {
  // Load the protobuf definition using the deprecated 'grpc' package
  const proto = grpc.load(pbpath);

  // Inspect the loaded protobuf definition
  const descriptor = grpcInspect(proto);

  console.log('--- Namespaces ---');
  console.dir(descriptor.namespaceNames());

  console.log('\n--- Services in helloworld namespace ---');
  console.dir(descriptor.serviceNames('helloworld'));

  console.log('\n--- Greeter service methods ---');
  console.dir(descriptor.methods('Greeter'));

  console.log('\n--- Full Descriptor Object (truncated) ---');
  // console.dir(descriptor, { depth: null }); // Uncomment for full object
  console.dir(descriptor.namespaces.helloworld.messages.HelloRequest); // Example message inspection

} catch (error) {
  console.error('Error loading or inspecting proto:', error.message);
  console.error('This package uses the deprecated `grpc` module, which may cause issues with modern Node.js versions or `@grpc/grpc-js`.');
} finally {
  // Clean up the dummy proto file
  fs.unlinkSync(pbpath);
}