What is pbf?
The pbf npm package is a low-level library for reading and writing Protocol Buffers (protobuf), a language-neutral, platform-neutral, extensible mechanism for serializing structured data. It is designed to be both efficient in performance and small in size, making it ideal for applications like map data processing in browsers or on servers.
What are pbf's main functionalities?
Reading Protocol Buffers
This code sample demonstrates how to read data from a Protocol Buffers file. It uses the Pbf instance to parse the buffer based on predefined tags and assigns the parsed data to a JavaScript object.
const Pbf = require('pbf');
const { readFileSync } = require('fs');
const buffer = readFileSync('data.pbf');
const pbf = new Pbf(buffer);
const data = pbf.readFields(readData, {});
function readData(tag, data, pbf) {
if (tag === 1) data.name = pbf.readString();
else if (tag === 2) data.version = pbf.readVarint();
}
Writing Protocol Buffers
This code sample shows how to write data to a Protocol Buffers file. It creates a new Pbf instance, writes data into it by specifying tags, and then writes the serialized data to a file.
const Pbf = require('pbf');
const { writeFileSync } = require('fs');
const data = { name: 'Example', version: 1 };
const pbf = new Pbf();
writeData(data, pbf);
pbf.finish();
writeFileSync('output.pbf', Buffer.from(pbf.buffer));
function writeData(obj, pbf) {
pbf.writeStringField(1, obj.name);
pbf.writeVarintField(2, obj.version);
}
Other packages similar to pbf
protobufjs
protobufjs is a more feature-rich library for working with Protocol Buffers in JavaScript. Unlike pbf, which focuses on minimalism and speed, protobufjs offers a comprehensive suite of tools including a CLI for generating static code and a more extensive API for manipulating protobuf schemas dynamically. This makes protobufjs better suited for applications requiring complex protobuf handling.
google-protobuf
google-protobuf is the official Protocol Buffers library for JavaScript, developed by Google. It provides robust support for the full range of protobuf features, including reflection and extensions, which are not supported by pbf. This package is ideal for users looking for official support and the most complete implementation of the Protocol Buffers specification.
pbf
A low-level, ultra-lightweight (2.9KB gzipped) protocol buffers implementation in JavaScript for browsers and Node.
Designed to be a building block for writing a customized, lazy decoder for a stable protobuf schema.
If you need an all-purpose protobuf JS library that does most of the work for you,
take a look at protocol-buffers.
Install
Node and Browserify:
npm install pbf
Making a browser build:
npm install
npm run build-dev
npm run build-min
Example
Reading
var pbf = new Pbf(buffer),
name, version, layerName;
pbf.readFields(function(tag) {
if (tag === 1) name = pbf.readString();
else if (tag === 2) version = pbf.readVarint();
else if (tag === 3) {
pbf.readMessage(function(tag) {
if (tag === 1) layerName = pbf.readString();
});
}
});
Writing
var pbf = new Pbf();
pbf.writeStringField(1, 'Hello world');
pbf.writeVarintField(2, 300);
var layer = new Pbf();
layer.writeStringField(1, 'foobar');
pbf.writeMessage(3, layer);
var buffer = pbf.finish();
API
Create a Protobuf object, optionally given a Buffer
as input data (or Uint8Array
in browsers):
var pbf = Protobuf( buf);
Protobuf object properties:
pbf.length;
pbf.pos;
Reading
Read a sequence of fields:
pbf.readFields(function (tag) {
if (tag === 1) pbf.readVarint();
else if (tag === 2) pbf.readString();
else ...
});
It optionally accepts an object that will be passed to the reading function for easier construction of decoded data,
and also passes the Protobuf object as a third argument:
var result = pbf.readFields(callback, {})
function callback(tag, result, pbf) {
if (tag === 1) result.id = pbf.readVarint();
}
To read an embedded message, use pbf.readMessage(fn[, obj])
(in the same way as read
).
Read values:
var value = pbf.readVarint();
var packed = pbf.readPacked('UInt32');
For lazy or partial decoding, simply save the position instead of reading a value,
then later set it back to the saved value and read:
var fooPos = -1;
pbf.readFields(function (tag) {
if (tag === 1) fooPos = pbf.pos;
});
...
pbf.pos = fooPos;
pbf.readMessage(readFoo);
Basic reading methods:
readVarint()
readSVarint()
readFixed32()
readFixed64()
readSFixed32()
readSFixed64()
readBoolean()
readFloat()
readDouble()
readString()
readBytes()
readPacked(type)
skip(value)
Writing
Write values:
pbf.writeVarint(123);
pbf.writeString("Hello world");
Field writing methods:
writeVarintField(tag, val)
writeSVarintField(tag, val)
writeFixed32Field(tag, val)
writeFixed64Field(tag, val)
writeSFixed32Field(tag, val)
writeSFixed64Field(tag, val)
writeBooleanField(tag, val)
writeFloatField(tag, val)
writeDoubleField(tag, val)
writeStringField(tag, val)
writeBytesField(tag, buffer)
writePacked(tag, type, items)
writeMessage(tag, pbf)
Scalar writing methods:
writeVarint(val)
writeSVarint(val)
writeSFixed32(val)
writeSFixed64(val)
writeFloat(val)
writeDouble(val)
writeString(val)
writeBytes(buffer)
Misc methods:
realloc(minBytes)
- pad the underlying buffer size to accommodate the given number of bytes;
note that the size increases exponentially, so it won't necessarily equal the size of data writtenfinish()
- make the current buffer ready for reading and return the data as a buffer slicedestroy()
- dispose the buffer
For an example of a real-world usage of the library, see vector-tile-js.
Changelog
1.1.2 (Dec 26 2014)
Brings tons of improvements and fixes over the previous version (0.0.2
).
Basically makes the library complete.
Improvements
- Improved performance of both reading and writing.
- Made the browser build 3 times smaller.
- Added convenience
readFields
and readMessage
methods for a much easier reading API. - Added reading methods:
readFloat
, readBoolean
, readSFixed32
, readSFixed64
. - Added writing methods:
writeUInt64
, writeSFixed32
, writeSFixed64
. - Improved
readDouble
and readString
to use native Buffer methods under Node. - Improved
readString
and writeString
to use HTML5 TextEncoder
and TextDecoder
where available. - Made
Pbf
buffer
argument optional. - Added extensive docs and examples in the readme.
- Added an extensive test suite that brings test coverage up to 100%.
Breaking API changes
- Renamed
readBuffer
/writeBuffer
to readBytes
/writeBytes
. - Renamed
readUInt32
/writeUInt32
to readFixed32
/writeFixed32
, etc. - Renamed
writeTaggedVarint
to writeVarintField
, etc. - Changed
writePacked
signature from (type, tag, items)
to (tag, type, items)
.
Bugfixes
- Fixed
readVarint
to handle varints bigger than 6 bytes. - Fixed
readSVarint
to handle number bigger than 2^30
. - Fixed
writeVarint
failing on some integers. - Fixed
writeVarint
not throwing an error on numbers that are too big. - Fixed
readUInt64
always failing. - Fixed writing to an empty buffer always failing.