Bufio: Buffer & Serialization Utilities

Common errors

• ReferenceError: require is not defined

  cause Attempting to import the CommonJS-only `bufio` library using an ESM `import` statement in an environment that does not support it, or in a file configured as an ES module.
  fix For Node.js projects, ensure the file using `bufio` is a CommonJS module (e.g., `.js` file without `"type": "module"` in `package.json`, or explicitly `.cjs`). Use `const bio = require('bufio');` to import the library.

• TypeError: bio.write is not a function

  cause Incorrectly attempting to destructure named exports (`import { write } from 'bufio';`) when `bufio` exports a single object or function as its default (and only) export in CommonJS.
  fix Import the entire module using `const bio = require('bufio');` and access `write` as a property: `const bw = bio.write();`.

• TypeError: bio.Struct is not a constructor

  cause Similar to `bio.write`, this error occurs if `Struct` is attempted to be imported as a named export or accessed incorrectly.
  fix After importing the entire module with `const bio = require('bufio');`, access `Struct` as a property: `class MyStruct extends bio.Struct {}`.

Warnings

• gotcha Bufio is primarily a CommonJS library. Attempting to use `import` statements directly in a pure ESM project will result in errors like 'require is not defined' or 'bufio does not provide an export named X'.
  Fix: Use `const bio = require('bufio');` for all imports. If in an ESM module, consider a wrapper or a build step to handle CommonJS modules, or use dynamic import `import('bufio').then(bio => ...)`. Alternatively, for Node.js 12+, you might be able to use `createRequire` from `module`.
• breaking The library is not actively maintained since its last update in 2018. This means it may not receive updates for security vulnerabilities, bug fixes, or compatibility with newer Node.js versions or JavaScript language features.
  Fix: Evaluate whether the unmaintained status poses a risk for your application, especially for security-critical operations involving low-level buffer manipulation. Consider auditing the code for known vulnerabilities or exploring more actively maintained alternatives if possible.
• gotcha Bufio does not provide TypeScript declaration files (`.d.ts`). Developers using TypeScript will need to write their own declaration files or use `any` types, losing type safety.
  Fix: Create a `bufio.d.ts` file in your project or use a declaration merging pattern to provide type definitions for the `bufio` module. Example: `declare module 'bufio' { export = any; }` (less ideal) or more specific typings for `Writer`, `Reader`, and `Struct`.
• gotcha This library assumes a deep understanding of binary serialization and buffer manipulation. Errors in specifying lengths, types, or endianness can lead to corrupted data or security vulnerabilities.
  Fix: Thoroughly test all serialization and deserialization routines. Ensure that byte order, string encodings, and numerical sizes are explicitly matched between writing and reading operations.

Install

• npm install bufio npm
• yarn add bufio yarn
• pnpm add bufio pnpm

Imports

• bio
  wrong:

  import bio from 'bufio';

  correct:

  const bio = require('bufio');

  Bufio is primarily a CommonJS library. There is no official ESM entry point as of v1.2.3, so direct `import` statements will likely fail in pure ESM contexts.
• BufferWriter (via bio.write)
  wrong:

  import { write } from 'bufio';

  correct:

  const bw = bio.write();

  `write` is a factory method on the main `bio` object, not a named export. It returns a `BufferWriter` instance.
• BufferReader (via bio.read)
  wrong:

  import { read } from 'bufio';

  correct:

  const br = bio.read(buffer);

  `read` is a factory method on the main `bio` object, not a named export. It returns a `BufferReader` instance.
• Struct
  wrong:

  import { Struct } from 'bufio';

  correct:

  class MyStruct extends bio.Struct {}

  `Struct` is a constructor property on the main `bio` object, not a named export. It serves as a base class for custom serialization schemas.

Quickstart

Demonstrates both basic buffer writer/reader usage and the creation of a custom serializable `Struct` class, including encoding and decoding to/from various formats.

const assert = require('assert');
const bio = require('bufio');

// Basic Usage: Write and Read
const bw = bio.write();
bw.writeU64(100);
bw.writeString('foo');
const data = bw.render();

const br = bio.read(data);
assert.strictEqual(br.readU64(), 100);
assert.strictEqual(br.readString(3), 'foo');

// Struct Usage: Define custom serializable objects
class MyStruct extends bio.Struct {
  constructor() {
    super();
    this.str = 'hello';
    this.value = 0;
  }

  write(bw) {
    bw.writeVarString(this.str, 'ascii');
    bw.writeU64(this.value);
    return this;
  }

  read(br) {
    this.str = br.readVarString('ascii');
    this.value = br.readU64();
    return this;
  }
}

const obj = new MyStruct();
obj.str = 'world';
obj.value = 12345;

console.log('Original object:', obj);
console.log('Encoded Buffer (Hex):', obj.toHex());

const decodedObj = MyStruct.fromHex(obj.toHex());
console.log('Decoded object:', decodedObj);
assert.deepStrictEqual(obj, decodedObj);