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 for node and the browser. It efficiently encodes plain objects and custom classes and works out of the box with .proto files.

This is the development branch of protobuf.js 6. Are you looking for the current stable branch?

• Examples
  A few examples to get you started.

• Module Structure
  A brief introduction to the structure of the exported module.

• Documentation
  A list of available documentation resources.

• Building
  How to build the library and its components yourself.

• Compatibility
  Notes on compatibility regarding browsers and optional libraries.

$> npm install dcodeIO/protobuf.js

// awesome.proto
package awesomepackage;
syntax = "proto3";

message AwesomeMessage {
    string awesomefield = 1;
}

var protobuf = require("protobufjs");

protobuf.load("awesome.proto", function(err, root) {
    if (err) throw err;
    
    // Obtain a message type
    var AwesomeMessage = root.lookup("awesomepackage.AwesomeMessage");
    // or, if you prefer: root.object.awesomepackage.AwesomeMessage

    // Create a new message
    var message = AwesomeMessage.create({ awesomefield: "AwesomeString" });

    // Encode a message (note that reflection encodes to a writer and we need to call finish)
    var buffer = AwesomeMessage.encode(message).finish();
    // ... do something with buffer

    // Or, encode a plain object (note that reflection encodes to a writer and we need to call finish)
    var buffer = AwesomeMessage.encode({ awesomefield: "AwesomeString" }).finish();
    // ... do something with buffer

    // Decode a buffer
    var message = AwesomeMessage.decode(buffer);
    // ... do something with message
});

You can also use promises by omitting the callback:

protobuf.load("awesome.proto")
    .then(function(root) {
       ...
    });

...
var Root  = protobuf.Root,
    Type  = protobuf.Type,
    Field = protobuf.Field;

var AwesomeMessage = new Type("AwesomeMessage").add(new Field(1, "awesomefield", "string"));

var root = new Root().define("awesomepackage").add(AwesomeMessage);

// Continue at "Create a new message" above
...

...
var Prototype = protobuf.Prototype;

function AwesomeMessage(properties) {
    Prototype.call(this, properties);
}
protobuf.inherits(AwesomeMessage, root.lookup("awesomepackage.AwesomeMessage") /* or use reflection */);

var message = new AwesomeMessage({ awesomefield: "AwesomeString" });

// Encode a message (note that classes encode to a buffer directly)
var buffer = AwesomeMessage.encode(message);
// ... do something with buffer

// Or, encode a plain object (note that classes encode to a buffer directly)
var buffer = AwesomeMessage.encode({ awesomefield: "AwesomeString" });
// ... do something with buffer

// Decode a buffer
var message = AwesomeMessage.decode(buffer);
// ... do something with message

The library exports a flat protobuf namespace with the following members, ordered by category:

• load(filename: string|Array, [root: Root], [callback: function(err: Error, [root: Root])]): Promise [source]
  Loads one or multiple .proto files into the specified root or creates a new one when omitted.

• tokenize(source: string): Object [source]
  Tokenizes the given .proto source and returns an object with useful utility functions.

• parse(source: string): Object [source]
  Parses the given .proto source and returns an object with the parsed contents.

  • package: string|undefined
    The package name, if declared.

  • imports: Array|undefined
    File names of imported files, if any.

  • publicImports: Array|undefined
    File names of publicly imported files, if any.

  • weakImports: Array|undefined
    File names of weakly imported files, if any.

  • syntax: string|undefined
    Source syntax, if defined.

  • root: Root
    The root namespace.

• Writer [source]
  Wire format writer using Uint8Array if available, otherwise Array.

• BufferWriter extends Writer [source]
  Wire format writer using node buffers.

• Reader [source]
  Wire format reader using Uint8Array if available, otherwise Array.

• BufferReader extends Reader [source]
  Wire format reader using node buffers.

• Encoder [source]
  Wire format encoder using code generation on top of reflection.

• Decoder [source]
  Wire format decoder using code generation on top of reflection.

• ReflectionObject [source]
  Base class of all reflection objects.

• Namespace extends ReflectionObject [source]
  Base class of all reflection objects containing nested objects.

• Root extends Namespace [source]
  Root namespace.

• Type extends Namespace [source]
  Reflected message type.

• Field extends ReflectionObject [source]
  Reflected message field.

• MapField extends Field [source]
  Reflected message map field.

• Enum extends ReflectionObject [source]
  Reflected enum.

• Service extends Namespace [source]
  Reflected service.

• Method extends ReflectionObject [source]
  Reflected service method.

• inherits(clazz: Function, type: Type, [options: Object.<string,*>]): Prototype [source]
  Inherits a custom class from the message prototype of the specified message type.

• Prototype [source]
  Runtime message prototype ready to be extended by custom classes or generated code.

• util: Object [source]
  Utility functions.

• types: Object [source]
  Common type constants.

• Google's Developer Guide

• protobuf.js API Documentation

To build the library or its components yourself, clone it from GitHub and install the development dependencies:

$> git clone https://github.com/dcodeIO/protobuf.js.git
$> cd protobuf.js
$> npm install --dev

Building the development and production versions with their respective source maps to dist/:

$> npm run build

Building the documentation to docs/:

$> npm run docs

Building the TypeScript definition to types/:

$> npm run types

• protobuf.js requires an ES5-capable browser. If typed arrays are not supported, it uses plain arrays instead.

• The library will try to generate optimized type specific encoders and decoders at runtime, which requires Function (basically eval) support. If code generation fails, it uses an equivalent but slower fallback.

• If you'd like to use node's buffer API in the browser, you can use feross/buffer for example and assign its constructor, or that of any compatible library, to protobuf.util.Buffer.

• If you need a proper way to work with 64 bit values (uint64, int64 etc.), you can install long.js alongside this library. Just as with buffers, you can assign its constructor to protobuf.util.Long. All 64 bit numbers will then be returned as a Long instance instead of a possibly unsafe JavaScript number (see).

License: Apache License, Version 2.0, bundled external libraries may have their own license