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

Protocol Buffers are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google (see).

protobuf.js is a pure JavaScript implementation on top of bytebuffer.js including a .proto parser, message class building and simple encoding and decoding. There is no compilation step required, it's super easy to use and it works out of the box on .proto files!

Getting started

• Step 1: Become familar with Google's Protocol Buffers (protobuf)
• Step 2: Head straight to our wiki for up to date usage information, changes and examples
• Step 3: Build something cool! :-)

Features

• RequireJS/AMD compatible
• node.js/CommonJS compatible, also available via npm
• Browser compatible
• Closure Compiler compatible (fully annotated, externs)
• Fully documented using jsdoc3
• Well tested through test.js
• bytebuffer.js is the only production dependency
• Fully compatible to the official implementation including advanced features
• proto2js command line utility

Documentation

• Read the official protobuf guide
• Read our wiki
• Read the API docs
• Check out the examples

Tests

• View source
• View report

Downloads

• Distributions
• ZIP-Archive
• Tarball

CDN usage

<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/VERSION/dist/protobuf.js"></script>

With VERSION replaced by a valid tag or just master for testing the latest master build.

Contributors

Daniel Wirtz (maintainer), Frank Xu, Dretch, shirmin, Nikolai Vavilov

License: Apache License, Version 2.0 - Logo derived from W3C HTML5 Logos (CC A 3.0)