BSER Binary Serialization

BSER is a binary serialization scheme that can be used as an alternative to JSON. BSER uses a framed encoding that makes it simpler to use to stream a sequence of encoded values.

It is intended to be used for local-IPC only and strings are represented as binary with no specific encoding; this matches the convention employed by most operating system filename storage.

For more details about the serialization scheme see Watchman's docs.

As of version 3.0.0 this package is ESM only ("type": "module"). It has no dependencies and requires Node.js >= 20.19; CommonJS consumers can still load it with require() thanks to require(esm) support in Node.js. It is published as @superbfowle/bser-esm. It is published as @superbfowle/bser-esm.

API

import * as bser from '@superbfowle/bser-esm';

bser.loadFromBuffer

The is the synchronous decoder; given an input string or buffer, decodes a single value and returns it. Throws an error if the input is invalid.

const obj = bser.loadFromBuffer(buf);

bser.dumpToBuffer

Synchronously encodes a value as BSER.

const encoded = bser.dumpToBuffer(['hello']);
console.log(bser.loadFromBuffer(encoded)); // ['hello']

Integer handling

BigInt values are encoded as BSER int64. On decode, int64 values that fit exactly in a JS number (within Number.MAX_SAFE_INTEGER) are returned as numbers; anything larger (or smaller) is returned as a BigInt. In versions prior to 3.0.0, node-int64 objects were used for the out-of-range case.

BunserBuf

The asynchronous decoder API is implemented in the BunserBuf object. You may incrementally append data to this object and it will emit the decoded values via its value event.

import {BunserBuf} from '@superbfowle/bser-esm';

const bunser = new BunserBuf();

bunser.on('value', obj => {
  console.log(obj);
});

Then in your socket data event:

bunser.append(buf);

Example

Read BSER from socket:

import {BunserBuf} from '@superbfowle/bser-esm';
import net from 'node:net';

const bunser = new BunserBuf();

bunser.on('value', obj => {
  console.log('data from socket', obj);
});

const socket = net.connect('/socket');

socket.on('data', buf => {
  bunser.append(buf);
});

Write BSER to socket:

socket.write(bser.dumpToBuffer(obj));