protocol-buffers

> 编程语言

Open source

Protocol Buffers for Node.js

760 stars0 likes2 views

Website GitHub

About

Protocol Buffers for Node.js

protocol-buffers

Protocol Buffers for Node.js

bash

npm install protocol-buffers

Usage

Assuming the following test.proto file exists

proto

enum FOO {
  BAR = 1;
}

message Test {
  required float num  = 1;
  required string payload = 2;
}

message AnotherOne {
  repeated FOO list = 1;
}

Use the above proto file to encode/decode messages by doing

javascript

var protobuf = require('protocol-buffers')

// pass a proto file as a buffer/string or pass a parsed protobuf-schema object
var messages = protobuf(fs.readFileSync('test.proto'))

var buf = messages.Test.encode({
  num: 42,
  payload: 'hello world'
})

console.log(buf) // should print a buffer

To decode a message use Test.decode

javascript

var obj = messages.Test.decode(buf)
console.log(obj) // should print an object similar to above

Enums are accessed in the same way as messages

javascript

var buf = messages.AnotherOne.encode({
  list: [
    messages.FOO.BAR
  ]
})

Nested emums are accessed as properties on the corresponding message

javascript

var buf = message.SomeMessage.encode({
  list: [
    messages.SomeMessage.NESTED_ENUM.VALUE
  ]
})

See the Google Protocol Buffers docs for more information about the available types etc.

Compile to a file

Since v4 you can now compile your schemas to a JavaScript file you can require from Node. This means you do not have runtime parse the schemas, which is useful if using in the browser or on embedded devices. It also makes the dependency footprint a lot smaller.

bash

# first install the cli tool
npm install -g protocol-buffers

# compile the schema
protocol-buffers test.proto -o messages.js

# then install the runtime dependency in the project
npm install --save protocol-buffers-encodings

That's it! Then in your application you can simply do

javascript

var messages = require('./messages')

var buf = messages.Test.encode({
  num: 42
})

The compilation functionality is also available as a JavaScript API for programmatic use:

javascript

var protobuf = require('protocol-buffers')

// protobuf.toJS() takes the same arguments as protobuf()
var js = protobuf.toJS(fs.readFileSync('test.proto'))
fs.writeFileSync('messages.js', js)

Imports

The cli tool supports protocol buffer imports by default.

Currently all imports are treated as public and the public/weak keywords not supported.

To use it programmatically you need to pass-in a filename & a resolveImport hooks:

javascript

var protobuf = require('protocol-buffers')
var messages = protobuf(null, {
  filename: 'initial.proto',
  resolveImport (filename) {
    // can return a Buffer, String or Schema
  }
})

Performance

This module is fast.

It uses code generation to build as fast as possible encoders/decoders for the protobuf schema. You can run the benchmarks yourself by doing npm run bench.

On my Macbook Air it gives the following results

…

Note that JSON parsing/serialization in node is a native function that is really fast.

Leveldb encoding compatibility

Compiled protocol buffers messages are valid levelup encodings. This means you can pass them as valueEncoding and keyEncoding.

javascript

var level = require('level')
var db = level('db')

db.put('hello', {payload:'world'}, {valueEncoding:messages.Test}, function(err) {
  db.get('hello', {valueEncoding:messages.Test}, function(err, message) {
    console.log(message)
  })
})