/proto-parser

A JavaScript parser for protocol buffers files.

Primary LanguageJavaScript

proto-parser CircleCI codecov npm version

A parser for proto files.

Table of Contents

Introduction

The purpose of proto-parser is to generate an AST for a proto file, regardless of injecting upper functions into the AST structure, such as encoding/decoding.

proto-parser vs protobuf.js

Proto-parser is developed based on protobuf.js, and uses some codes of protobuf.js。

Compared with protobuf.js, proto-parser is more focused on parsing. so, proto-parser gains some advantages:

  • have less code and higher performance
  • output more pure AST structure
  • support TypeScript

Note that, the AST structure generated by proto-parser keeps basic compatible with that by protobuf.js.

Usage

Install

npm install proto-parser

Coding

A code example:

import * as t from 'proto-parser';

const content = `
syntax = 'proto3';
message Foo {
  string key = 1;
}
`;

const protoDocument = t.parse(content) as t.ProtoDocument;
console.log(JSON.stringify(protoDocument, null, 2));

The resulted AST:

{
  "syntax": "proto3",
  "root": {
    "name": "",
    "fullName": "",
    "syntaxType": "ProtoRoot",
    "nested": {
      "Foo": {
        "name": "Foo",
        "fullName": ".Foo",
        "comment": null,
        "syntaxType": "MessageDefinition",
        "fields": {
          "key": {
            "name": "key",
            "fullName": ".Foo.key",
            "comment": null,
            "type": {
              "value": "string",
              "syntaxType": "BaseType"
            },
            "id": 1,
            "required": false,
            "optional": true,
            "repeated": false,
            "map": false
          }
        }
      }
    }
  },
  "syntaxType": "ProtoDocument"
}

API

> parse(source: string, option?: ParseOption): ProtoDocument | ProtoError

Parse the content of a proto file to an AST.

The definition of ParseOption:

interface ParseOption {
  // Set whether to keep the origin case. The default value is true.
  keepCase?: boolean

  // Set whether to enable alternateCommentMode. The default value is true.
  alternateCommentMode?: boolean 

  // Set whether to resolve types. The default value is true.
  resolve?: boolean

  // Set whether to weak resolve types(do not throw errors when resolve failed).
  // The default value is true.
  weakResolve?: boolean

  // Set whether to return pure json Object. The default value is true.
  toJson?: boolean
}

License

MIT