# protocol-buffers

> Protocol Buffers for Node.js

Latest version **5.0.0** (published 2022-03-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install protocol-buffers
pnpm add protocol-buffers
yarn add protocol-buffers
bun add protocol-buffers
```

Provides the command `protocol-buffers`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2022-03-23 |
| First published | 2014-05-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 49.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 760 |
| Author | Mathias Buus |
| Maintainers | mafintosh |
| Keywords | protobuf, protocol, buffers, protocolbuffers, encode, decode, google, serialize, parse, levelup, encodings, encoding |

## Links

- npm: https://www.npmjs.com/package/protocol-buffers
- Repository: https://github.com/mafintosh/protocol-buffers
- Issues: https://github.com/mafintosh/protocol-buffers/issues
- npm.io page: https://npm.io/package/protocol-buffers

## Dependencies (6)

- [varint](https://npm.io/package/varint.md) ^6.0.0
- [signed-varint](https://npm.io/package/signed-varint.md) ^2.0.0
- [generate-function](https://npm.io/package/generate-function.md) ^2.0.0
- [protocol-buffers-schema](https://npm.io/package/protocol-buffers-schema.md) ^3.1.1
- [generate-object-property](https://npm.io/package/generate-object-property.md) ^1.2.0
- [protocol-buffers-encodings](https://npm.io/package/protocol-buffers-encodings.md) ^1.1.0

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 5.0.0 (latest) — 2022-03-23
- 4.2.0 — 2020-06-11
- 4.1.2 — 2020-02-18
- 4.1.1 — 2020-02-07
- 4.1.0 — 2018-09-18
- 4.0.4 — 2018-02-15
- 4.0.3 — 2018-02-15
- 4.0.2 — 2018-01-17
- 4.0.1 — 2018-01-17
- 4.0.0 — 2018-01-17
- 3.2.1 — 2016-11-26
- 3.2.0 — 2016-11-25
- 3.1.8 — 2016-11-04
- 3.1.7 — 2016-11-03
- 3.1.6 — 2016-02-23
- … 49 more at https://npm.io/package/protocol-buffers/versions

## README

# protocol-buffers

[Protocol Buffers](https://developers.google.com/protocol-buffers/) for Node.js

```
npm install protocol-buffers
```

[![build status](https://github.com/mafintosh/protocol-buffers/actions/workflows/test.yml/badge.svg)](https://github.com/mafintosh/protocol-buffers/actions/workflows/test.yml)
![dat](http://img.shields.io/badge/Development%20sponsored%20by-dat-green.svg?style=flat)

## 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

``` js
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`

``` js
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

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

Nested emums are accessed as properties on the corresponding message

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

See the [Google Protocol Buffers docs](https://developers.google.com/protocol-buffers/) 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.

``` sh
# 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

``` js
var messages = require('./messages')

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

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

``` js
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:

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

[imports]: https://developers.google.com/protocol-buffers/docs/proto3#importing_definitions

## 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

```
Benchmarking JSON (baseline)
  Running object encoding benchmark...
  Encoded 1000000 objects in 2142 ms (466853 enc/s)

  Running object decoding benchmark...
  Decoded 1000000 objects in 970 ms (1030928 dec/s)

  Running object encoding+decoding benchmark...
  Encoded+decoded 1000000 objects in 3131 ms (319387 enc+dec/s)

Benchmarking protocol-buffers
  Running object encoding benchmark...
  Encoded 1000000 objects in 2089 ms (478698 enc/s)

  Running object decoding benchmark...
  Decoded 1000000 objects in 735 ms (1360544 dec/s)

  Running object encoding+decoding benchmark...
  Encoded+decoded 1000000 objects in 2826 ms (353857 enc+dec/s)
```

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`.

``` js
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)
  })
})
```

## License

MIT

---
_Source: https://npm.io/package/protocol-buffers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._