Protobuf.js

<h1><p align="center"><img alt="protobuf.js" src="https://github.com/protobufjs/protobuf.js/raw/master/pbjs.svg" height="100" /><br/>protobuf.js</p></h1> <p align="center"> <a href="https://github.com/protobufjs/protobuf.js/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/protobufjs/protobuf.js/test.yml?branch=master&label=build&logo=github" alt=""></a> <a href="https://github.com/protobufjs/protobuf.js/actions/workflows/release.yaml"><img src="https://img.shields.io/github/actions/workflow/status/protobufjs/protobuf.js/release.yaml?branch=master&label=release&logo=github" alt=""></a> <a href="https://npmjs.org/package/protobufjs"><img src="https://img.shields.io/npm/v/protobufjs.svg?logo=npm" alt=""></a> <a href="https://npmjs.org/package/protobufjs"><img src="https://img.shields.io/npm/dm/protobufjs.svg?label=downloads&logo=npm" alt=""></a> <a href="https://www.jsdelivr.com/package/npm/protobufjs"><img src="https://img.shields.io/jsdelivr/npm/hm/protobufjs?label=requests&logo=jsdelivr" alt=""></a> </p>

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 with TypeScript support for Node.js and the browser. It's easy to use, does not sacrifice on performance, has good conformance and works out of the box with .proto files!

Contents

• Installation<br /> How to include protobuf.js in your project.

• Usage<br /> A brief introduction to using the toolset.

  • Valid Message
  • Toolset<br />

• Examples<br /> A few examples to get you started.

  • Using .proto files
  • Using JSON descriptors
  • Using reflection only
  • Using custom classes
  • Using services
  • Usage with TypeScript<br />

• Additional documentation<br /> A list of available documentation resources.

• Performance<br /> A few internals and a benchmark on performance.

• Compatibility<br /> Notes on compatibility regarding browsers and optional libraries.

• Building<br /> How to build the library and its components yourself.

Installation

Node.js

npm install protobufjs --save

// Static code + Reflection + .proto parser
var protobuf = require("protobufjs");

// Static code + Reflection
var protobuf = require("protobufjs/light");

// Static code only
var protobuf = require("protobufjs/minimal");

The optional command line utility to generate static code and reflection bundles lives in the protobufjs-cli package and can be installed separately:

npm install protobufjs-cli --save-dev

Browsers

Pick the variant matching your needs and replace the version tag with the exact release your project depends upon. For example, to use the minified full variant:

<script src="//cdn.jsdelivr.net/npm/protobufjs@7.X.X/dist/protobuf.min.js"></script>

| Distribution | Location |--------------|-------------------------------------------------------- | Full | https://cdn.jsdelivr.net/npm/protobufjs/dist/ | Light | https://cdn.jsdelivr.net/npm/protobufjs/dist/light/ | Minimal | https://cdn.jsdelivr.net/npm/protobufjs/dist/minimal/

All variants support CommonJS and AMD loaders and export globally as window.protobuf.

Usage

Because JavaScript is a dynamically typed language, protobuf.js utilizes the concept of a valid message in order to provide the best possible performance (and, as a side product, proper typings):

Valid message

A valid message is an object (1) not missing any required fields and (2) exclusively composed of JS types understood by the wire format writer.

There are two possible types of valid messages and the encoder is able to work with both of these for convenience:

• Message instances (explicit instances of message classes with default values on their prototype) naturally satisfy the requirements of a valid message and
• Plain JavaScript objects that just so happen to be composed in a way satisfying the requirements of a valid message as well.

In a nutshell, the wire format writer understands the following types:

| Field type | Expected JS type (create, encode) | Conversion (fromObject) |------------|-----------------------------------|------------------------ | s-/u-/int32<br />s-/fixed32 | number (32 bit integer) | <code>value | 0</code> if signed<br />value >>> 0 if unsigned | s-/u-/int64<br />s-/fixed64 | Long-like (optimal)<br />number (53 bit integer) | Long.fromValue(value) with long.js<br />parseInt(value, 10) otherwise | float<br />double | number | Number(value) | bool | boolean | Boolean(value) | string | string | String(value) | bytes | Uint8Array (optimal)<br />Buffer (optimal under node)<br />Array.<number> (8 bit integers) | base64.decode(value) if a string<br />Object with non-zero .length is assumed to be buffer-like | enum | number (32 bit integer) | Looks up the numeric id if a string | message | Valid message | Message.fromObject(value) | repeated T | Array<T> | Copy | map<K, V> | Object<K,V> | Copy

• Explicit undefined and null are considered as not set if the field is optional.
• Maps are objects where the key is the string representation of the respective value or an 8 characters long hash string for Long-likes.

Toolset

With that in mind and again for performance reasons, each message class provides a distinct set of methods with each method doing just one thing. This avoids unnecessary assertions / redundant operations where performance is a concern but also forces a user to perform verification (of plain JavaScript objects that might just so happen to be a valid message) explicitly where necessary - for example when dealing with user input.

Note that Message below refers to any message class.

• Message.verify(message: Object): null|string<br /> verifies that a plain JavaScript object satisfies the requirements of a valid message and thus can be encoded without issues. Instead of throwing, it returns the error message as a string, if any.

  var payload = "invalid (not an object)";
  var err = AwesomeMessage.verify(payload);
  if (err)
    throw Error(err);
  

• Message.encode(message: Message|Object [, writer: Writer]): Writer<br /> encodes a message instance or valid plain JavaScript object. This method does not implicitly verify the message and it's up to the user to make sure that the payload is a valid message.

  var buffer = AwesomeMessage.encode(message).finish();
  

• Message.encodeDelimited(message: Message|Object [, writer: Writer]): Writer<br /> works like Message.encode but additionally prepends the length of the message as a varint.

• Message.decode(reader: Reader|Uint8Array): Message<br /> decodes a buffer to a message instance. If required fields are missing, it throws a util.ProtocolError with an instance property set to the so far decoded message. If the wire format is invalid, it throws an Error.

  try {
    var decodedMessage = AwesomeMessage.decode(buffer);
  } catch (e) {
      if (e instanceof protobuf.util.ProtocolError) {
        // e.instance holds the so far decoded message with missing required fields
      } else {
        // wire format is invalid
      }
  }
  

• Message.decodeDelimited(reader: Reader|Uint8Array): Message<br /> works like Message.decode but additionally reads the length of the message prepended as a varint.

• Message.create(properties: Object): Message<br /> creates a new message instance from a set of properties that satisfy the requirements of a valid message. Where applicable, it is recommended to prefer Message.create over Message.fromObject because it doesn't perform possibly redundant conversion.

  var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });
  

• Message.fromObject(object: Object): Message<br /> converts any non-valid plain JavaScript object to a message instance using the conversion steps outlined within the table above.

  var message = AwesomeMessage.fromObject({ awesomeField: 42 });
  // converts awesomeField to a string
  

• Message.toObject(message: Message [, options: ConversionOptions]): Object<br /> converts a message instance to an arbitrary plain JavaScript object for interoperability with other libraries or storage. The resulting plain JavaScript object might still satisfy the requirements of a valid message depending on the actual conversion options specified, but most of the time it does not.

  var object = AwesomeMessage.toObject(message, {
    enums: String,  // enums as string names
    longs: String,  // longs as strings (requires long.js)
    bytes: String,  // bytes as base64 encoded strings
    defaults: true, // includes default values
    arrays: true,   // populates empty arrays (repeated fields) even if defaults=false
    objects: true,  // populates empty objects (map fields) even if defaults=false
    oneofs: true    // includes virtual oneof fields set to the present field's name
  });
  

For reference, the following diagram aims to display relationships between the different methods and the concept of a valid message:

<p alig