proto-parser

library1.6.3jsnpmunverified

proto-parser is a JavaScript/TypeScript library specifically designed to parse Protocol Buffer (proto) files and generate an Abstract Syntax Tree (AST). Currently at version 0.0.9, it is in early development, suggesting potential for rapid updates and API evolution, though no explicit release cadence is mentioned beyond frequent updates. Unlike `protobuf.js`, on which it is partially based and from which it reuses some code, `proto-parser` focuses exclusively on the parsing aspect, omitting encoding/decoding functionalities. This specialization results in a smaller codebase, improved performance, and a 'purer' AST structure. It offers native TypeScript support and aims for basic AST compatibility with `protobuf.js`, making it suitable for users who primarily need to analyze or transform proto definitions without the overhead of runtime message handling.

serialization

npm install proto-parser

github ↗package ↗

INSTALL

IMPORT

SIG · PROTO-PARSER

proto-parser

serializationjavascriptv1.6.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import * as t from 'proto-parser'; const protoDocument = t.parse(content);

✗ import { parse } from 'proto-parser'; // 'parse' is not a direct named export

The `parse` function is exported under a namespace `t` (or similar alias) when using `import * as t from 'proto-parser';`

ProtoDocument

✓ import type { ProtoDocument } from 'proto-parser';

✗ import { ProtoDocument } from 'proto-parser'; // Should use 'import type' for type-only imports.

For TypeScript, `ProtoDocument`, `ProtoError`, and `ParseOption` are type exports. You can also access them via the namespace import, e.g., `t.ProtoDocument`.

CommonJS require

✓ const protoParser = require('proto-parser'); const protoDocument = protoParser.parse(content);

✗ const { parse } = require('proto-parser'); // 'parse' is not a direct named export from CJS module.

The main exports are structured as a namespace object in CommonJS environments.

Demonstrates parsing a proto3 file content string into an AST, with options.

import * as t from 'proto-parser'; const content = ` syntax = 'proto3'; package myapp.v1; // A simple message for demonstration message Foo { string key = 1; // Unique identifier int32 value = 2; // Associated integer value repeated string tags = 3; // List of tags } `; const protoDocument = t.parse(content, { keepCase: false, resolve: true }) as t.ProtoDocument; if (protoDocument && 'root' in protoDocument && protoDocument.root && protoDocument.root.nested) { console.log('Successfully parsed proto file. Root definition:'); console.log(JSON.stringify(protoDocument.root.nested.Foo, null, 2)); } else if ('message' in protoDocument) { console.error('Parsing failed:', protoDocument.message); // Handle ProtoError case } else { console.error('Unexpected parsing result.'); }

Debug

Known issues

breakingThe package is currently at version 0.0.9, indicating an early development stage. APIs are subject to frequent changes without strict adherence to semantic versioning for breaking changes, as it's pre-1.0.0.

fix

Refer to the latest README and changelog (if available) for up-to-date API usage. Pin exact versions for stability.

affects: <1.0.0

gotchaWhile the AST structure aims for 'basic compatibility' with `protobuf.js`, there might be subtle differences in field names, types, or nesting that could break tools or logic expecting exact `protobuf.js` AST output. Proto-parser prioritizes a 'purer' AST.

fix

Thoroughly test any code that processes the AST generated by `proto-parser` if it was originally designed for `protobuf.js`'s AST. Inspect the generated AST structure carefully.

affects: >=0.0.1

gotchaThis library is strictly a proto file *parser* and does not include functionality for encoding or decoding Protocol Buffer messages. Users requiring a full protobuf solution will need to integrate other libraries for runtime message handling.

fix

For message encoding/decoding, consider using `protobuf.js` or Google's official `google-protobuf` library in conjunction with `proto-parser` if AST generation is a separate requirement.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: protoParser.parse is not a function

Attempting to destructure `parse` directly from a CommonJS `require` or incorrect named import in ESM when the function is exposed via a namespace object.

fix

For ESM, use `import * as t from 'proto-parser';` then `t.parse(...)`. For CommonJS, use `const protoParser = require('proto-parser');` then `protoParser.parse(...)`.

TS2305: Module ''proto-parser'' has no exported member 'ProtoDocument'.

Attempting to import `ProtoDocument` as a value or directly via `import { ProtoDocument } from 'proto-parser';` when it's a type export or exposed via a namespace.

fix

For TypeScript, use `import type { ProtoDocument } from 'proto-parser';` for explicit type imports, or access it via a namespace import like `t.ProtoDocument` if you've done `import * as t from 'proto-parser';`.

Error: unexpected token '<EOF>'

The input string provided to `parse()` contains malformed Protocol Buffer syntax, leading to parsing errors.

fix

Review the proto content string for syntax errors, missing semicolons, incorrect keywords, or incomplete definitions. Ensure it's a valid proto3 or proto2 file content.

Upgrade

Version history

1.6.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/lancewuz/proto-parser ↗

packagehttps://www.npmjs.com/package/proto-parser ↗