Protocol Buffers Schema Parser

Common errors

• TypeError: schema.encode is not a function

  cause Attempting to use `protocol-buffers-schema` for binary encoding/decoding, which it does not support.
  fix This library only parses and stringifies Protobuf schema definitions. To encode or decode binary Protobuf messages, use a different library such as `protobuf.js` or `google-protobuf`.

• TypeError: Cannot read properties of undefined (reading 'parse')

  cause Incorrectly importing the `parse` function as a named export instead of accessing it from the default module object.
  fix For CommonJS, use `const schema = require('protocol-buffers-schema'); schema.parse(...)`. For ESM, use `import schema from 'protocol-buffers-schema'; schema.parse(...)`.

• SyntaxError: Unexpected token 'required' / 'optional'

  cause Parsing a `proto3` file that uses `required` or `optional` keywords for field rules without explicitly setting `syntax = "proto2"`. While `protocol-buffers-schema` supports both, `proto3` has different default field behaviors and `required`/`optional` are not standard field rules (except with Editions).
  fix Ensure `syntax = "proto2";` is present in your `.proto` file if you intend to use explicit `required`/`optional` field rules. If using `proto3` without Editions, these keywords are not valid for field rules.

Warnings

• gotcha This package is a schema parser only. It does NOT provide functionality for encoding or decoding actual Protocol Buffers binary messages. For binary serialization/deserialization, consider libraries like `protobuf.js`, `google-protobuf`, or `protobuf-es`.
  Fix: Use a dedicated Protobuf runtime library (e.g., `npm install protobufjs`) for encoding and decoding binary data.
• gotcha The package (v3.6.1, last published ~4 years ago for 3.6.0) might not fully support all modern Protocol Buffers language features introduced in newer `proto3` specifications or `Protobuf Editions`. Ensure compatibility if working with very recent .proto syntax.
  Fix: Review the parsed output carefully for newer syntax. If issues arise, consider alternative, more actively maintained Protobuf parsing solutions or pre-process your .proto files to simpler forms if possible.
• breaking Older versions of `protocol-buffers-schema` may have handled certain Protobuf syntax nuances differently. While no specific major breaking changes for schema parsing are widely documented for this library, the broader Protobuf ecosystem has had breaking changes, especially concerning generated code and runtime compatibility.
  Fix: Always use the latest stable version (3.6.1) to benefit from bug fixes and improved parsing logic. Consult the GitHub repository's commit history for specific changes between major versions if migrating from a very old version.

Install

• npm install protocol-buffers-schema npm
• yarn add protocol-buffers-schema yarn
• pnpm add protocol-buffers-schema pnpm

Imports

• schema
  wrong:

  const { parse } = require('protocol-buffers-schema')

  correct:

  import schema from 'protocol-buffers-schema'

  The package is a CommonJS module. In ESM, `import schema from 'protocol-buffers-schema'` or `import * as schema from 'protocol-buffers-schema'` is the correct way to import the module's default export, which is the object containing `parse` and `stringify`.
• parse
  wrong:

  import { parse } from 'protocol-buffers-schema'

  correct:

  import schema from 'protocol-buffers-schema'; schema.parse(protoString);

  The `parse` function is a property of the default exported module object, not a named export. Attempting to destructure it directly as a named export will result in `undefined`.
• stringify
  wrong:

  require('protocol-buffers-schema').stringify(schemaObject)

  correct:

  const schema = require('protocol-buffers-schema'); schema.stringify(schemaObject);

  While functional, chaining directly off `require()` is less readable and can complicate mocking in tests. Assigning to a variable first is preferred for clarity and consistency.

Quickstart

Demonstrates parsing a Protobuf schema string into a JavaScript object and then stringifying it back, also showing how to access parsed schema elements.

import { readFileSync } from 'fs';
import schema from 'protocol-buffers-schema';

// Create a dummy .proto file for demonstration
const protoContent = `
syntax = "proto2";

message Point {
  required int32 x = 1;
  required int32 y = 2;
  optional string label = 3;
}

message Line {
  required Point start = 1;
  required Point end = 2;
  optional string label = 3;
}
`;

// In a real scenario, this would be fs.writeFileSync('example.proto', protoContent);
// For this quickstart, we'll parse the string directly.

// Parse the .proto schema
const parsedSchema = schema.parse(protoContent);

// Log the parsed JavaScript object representation of the schema
console.log('Parsed Protobuf Schema:');
console.log(JSON.stringify(parsedSchema, null, 2));

// You can also stringify it back to .proto format
const stringifiedSchema = schema.stringify(parsedSchema);
console.log('\nStringified Protobuf Schema (reconstructed):');
console.log(stringifiedSchema);

// Example of accessing elements
console.log('\nFirst message name:', parsedSchema.messages[0].name);
console.log('First field of first message:', parsedSchema.messages[0].fields[0].name);