protobufjs

What is protobufjs?

The protobufjs npm package provides a comprehensive suite of tools for working with Protocol Buffers (protobuf), a method of serializing structured data. It allows users to encode and decode protobuf messages, generate and work with static code, and handle dynamic message building and parsing.

What are protobufjs's main functionalities?

Loading .proto files

This feature allows users to load .proto files and use the defined protobuf structures within their JavaScript code.

const protobuf = require('protobufjs');
protobuf.load('awesome.proto', function(err, root) {
  if (err) throw err;
  const AwesomeMessage = root.lookupType('awesomepackage.AwesomeMessage');
  // ... use AwesomeMessage
});

Encoding and decoding messages

With protobufjs, users can encode JavaScript objects into binary protobuf format and decode binary messages into JavaScript objects.

const message = AwesomeMessage.create({ awesomeField: 'AwesomeString' });
const buffer = AwesomeMessage.encode(message).finish();
const decodedMessage = AwesomeMessage.decode(buffer);

Reflection and runtime message building

This feature allows users to work with protobuf messages dynamically at runtime using JSON descriptors, without the need for generated static code.

const root = protobuf.Root.fromJSON(jsonDescriptor);
const AwesomeMessage = root.lookupType('awesomepackage.AwesomeMessage');
const errMsg = AwesomeMessage.verify({ awesomeField: 'AwesomeString' });
if (errMsg) throw Error(errMsg);
const message = AwesomeMessage.create({ awesomeField: 'AwesomeString' });

Static code generation

Protobufjs can generate static code from .proto files, which can be used for better performance and type safety.

protobuf.load('awesome.proto', function(err, root) {
  if (err) throw err;
  protobuf.codegen(root, { keepCase: true }, function(err, output) {
    if (err) throw err;
    // output will contain the generated static code
  });
});

Other packages similar to protobufjs

@apollo/protobufjs

This is a fork of the original protobufjs package with some modifications. It is used within the Apollo tooling ecosystem but generally offers similar functionality to protobufjs.

google-protobuf

This is the official Protocol Buffers runtime library for JavaScript. It is provided by Google and offers similar serialization and deserialization capabilities. However, it may not be as feature-rich or flexible as protobufjs in terms of dynamic message handling and may require more setup for code generation.

pbf

Pbf is a fast, lightweight Protocol Buffers implementation in JavaScript. It focuses on performance and is smaller in size compared to protobufjs. However, it might not offer the same level of functionality, especially in terms of reflection and dynamic message building.

README

ProtoBuf.js - protobuf for JavaScript

Till now: Provides a parser for .proto files in plain JavaScript. More is planned.

Parser

Should be compliant with protoc. No validation of type references yet, just parsing.

npm install protobufjs

var ProtoBuf = require("protobufjs"),
    fs = require("fs"),
    util = require("util");

var proto = fs.readFileSync("test.proto");
var parser = new ProtoBuf.DotProto.Parser(proto);
var ast = parser.parse();
console.log(util.inspect(ast, false, null, true));

Builder

TODO

Encoder

TODO

Decoder

TODO

Features

• CommonJS compatible
• RequireJS/AMD compatible
• Shim compatible (include the script, then use var ProtoBuf = dcodeIO.ProtoBuf;)
• node.js compatible, also available via npm
• Closure Compiler ADVANCED_OPTIMIZATIONS compatible (fully annotated)
• Fully documented (jsdoc3)
• ByteBuffer.js is the only dependency
• Small footprint

License

Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html