BSER Binary Serialization

Common errors

• TypeError: bser.loadFromBuffer is not a function

  cause Attempting to call `loadFromBuffer` on an `undefined` or improperly imported `bser` object, often due to incorrect CommonJS `require` or failed ESM `import` in a dual-module setup.
  fix Ensure the module is correctly imported in CommonJS: `const bser = require('bser');`. If in ESM, confirm your build system or Node.js environment correctly handles CommonJS module interop, or use `import bser from 'bser'` if it's a default export (less likely for this package).

• Error: Invalid BSER buffer

  cause The input `Buffer` provided to `bser.loadFromBuffer` or `bunser.append` does not conform to the BSER binary serialization format, indicating corrupted data or an incorrect protocol.
  fix Verify the source of the buffer data. Ensure the sending side is correctly encoding data using `bser.dumpToBuffer` and that no data corruption or truncation occurs during transmission. Implement `try...catch` around `loadFromBuffer` and `bunser.on('error', ...)` for `BunserBuf`.

• Data is not being processed from BunserBuf after `append` call

  cause The asynchronous `BunserBuf` is being used, but no listener has been attached to its `'value'` event, so decoded objects are emitted but not captured or processed.
  fix Always attach a listener to the `'value'` event of your `BunserBuf` instance: `bunser.on('value', function(obj) { console.log('Decoded object:', obj); });`. Also consider handling the `'error'` event for robustness.

Warnings

• gotcha The `bser.loadFromBuffer` and `bser.dumpToBuffer` APIs are synchronous. While suitable for small IPC payloads, using them with very large buffers can block the Node.js event loop, leading to performance bottlenecks and unresponsiveness in high-throughput applications.
  Fix: For potentially large or streaming data, prefer the asynchronous `BunserBuf` API, which processes data incrementally and emits 'value' events, preventing event loop blocking.
• gotcha The `bser.loadFromBuffer` function throws an error directly if the input buffer is not a valid BSER stream. This requires explicit `try...catch` blocks for robust error handling to prevent application crashes.
  Fix: Always wrap calls to `bser.loadFromBuffer` in a `try...catch` block to handle malformed BSER input gracefully, e.g., `try { const obj = bser.loadFromBuffer(buf); } catch (e) { console.error('BSER decode error:', e); }`.
• gotcha The `BunserBuf` API is entirely event-driven for asynchronous decoding. Data is not returned directly but emitted via the `'value'` event. Developers new to event emitters might overlook attaching this listener, resulting in data appearing to be 'lost' or not processed.
  Fix: Ensure you always register an event listener for the `'value'` event on `BunserBuf` instances, e.g., `bunser.on('value', (obj) => { /* process obj */ });`. Other events like `'error'` should also be handled.
• gotcha The `bser` package is primarily distributed and documented as a CommonJS module using `require()`. While Node.js can sometimes interop with CommonJS modules from ESM, directly using `import { Name } from 'bser'` syntax in an ESM context might lead to unexpected `undefined` imports or runtime errors without specific `package.json` `exports` configurations (which are not explicitly provided by `bser`).
  Fix: In ESM projects, consider using a dynamic `import('bser').then(bser => { ... })` or consult bundler-specific configurations to handle CommonJS modules. If possible, stick to `require()` if your project largely remains CommonJS.
• gotcha BSER is explicitly 'intended to be used for local-IPC only' and its strings are 'represented as binary with no specific encoding'. This means it's not suitable for cross-platform or network communication where explicit character encoding (e.g., UTF-8) and network framing protocols are critical for interoperability and security.
  Fix: Adhere to the intended use case for local IPC. For network communication or data exchange requiring specific character encodings, consider alternatives like JSON, Protocol Buffers, or custom protocols with defined encoding standards.

Install

• npm install bser npm
• yarn add bser yarn
• pnpm add bser pnpm

Imports

• bser
  wrong:

  import * as bser from 'bser';

  correct:

  const bser = require('bser');

  The 'bser' package is primarily a CommonJS module. Direct ES Module 'import' statements may not work as expected or require specific bundler configurations without explicit 'exports' map in package.json.
• loadFromBuffer
  wrong:

  import { loadFromBuffer } from 'bser';

  correct:

  const { loadFromBuffer } = require('bser');

  While CommonJS allows destructuring, the package is predominantly consumed by importing the entire module object first. Attempting named ESM imports may fail.
• BunserBuf
  wrong:

  import { BunserBuf } from 'bser';

  correct:

  const BunserBuf = require('bser').BunserBuf;

  BunserBuf is a class exported as a property of the main 'bser' module object, not a direct named export from the module root in CommonJS. ESM import attempts may not correctly resolve it.

Quickstart

Demonstrates basic synchronous BSER encoding (`dumpToBuffer`) and asynchronous decoding (`BunserBuf`) for IPC over a Unix domain socket, including event handling for streamed data.

const net = require('net');
const bser = require('bser');

// Simulate a socket server
const server = net.createServer(socket => {
  console.log('Client connected.');

  const bunser = new bser.BunserBuf();

  bunser.on('value', obj => {
    console.log('Server received (decoded):', obj);
    // Echo back a response
    const response = bser.dumpToBuffer(['pong', obj[1]]);
    socket.write(response);
  });

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

  socket.on('end', () => {
    console.log('Client disconnected.');
  });

  socket.on('error', err => {
    console.error('Server socket error:', err);
  });
});

const SOCKET_PATH = '/tmp/bser-socket';
server.listen(SOCKET_PATH, () => {
  console.log(`Server listening on ${SOCKET_PATH}`);

  // Simulate a client
  const client = net.connect(SOCKET_PATH, () => {
    console.log('Client connected to server.');
    const payload = ['hello', 'world', 123];
    const encoded = bser.dumpToBuffer(payload);
    console.log('Client sending (encoded):', encoded);
    client.write(encoded);

    const clientBunser = new bser.BunserBuf();
    clientBunser.on('value', obj => {
      console.log('Client received (decoded):', obj);
      client.end(); // End client after receiving response
    });
    client.on('data', buf => {
      clientBunser.append(buf);
    });

    client.on('error', err => {
      console.error('Client socket error:', err);
    });
  });

  client.on('end', () => {
    console.log('Client disconnected. Server closing.');
    server.close();
  });
});