Erlpack

Erlpack is a fast encoder and decoder for the Erlang Term Format (ETF) version 131 for JavaScript. It provides a native implementation for high-performance encoding and decoding of data structures compatible with Erlang and Elixir systems, making it ideal for applications that need to communicate with Erlang/Elixir services or implement protocols like Discord's gateway.

Package Information

• Package Name: erlpack
• Package Type: npm
• Language: JavaScript (with C++ native bindings)
• Installation: npm install erlpack

Core Imports

const erlpack = require('erlpack');

For ES modules:

import * as erlpack from 'erlpack';

Basic Usage

const erlpack = require('erlpack');

// Encoding JavaScript data to ETF binary format
const data = {
  user: 'alice',
  age: 25,
  active: true,
  tags: ['admin', 'user'],
  score: 98.5
};

const packed = erlpack.pack(data);
console.log(packed); // Buffer containing ETF binary data

// Decoding ETF binary data back to JavaScript
const unpacked = erlpack.unpack(packed);
console.log(unpacked); // Original JavaScript object

Capabilities

Data Encoding

Encodes JavaScript data structures into Erlang Term Format (ETF) version 131 binary format.

/**
 * Encodes JavaScript data structures into ETF binary format
 * @param {any} data - JavaScript value to encode
 * @returns {Buffer} Buffer containing ETF-encoded binary data
 * @throws {Error} "Out of memory" when insufficient memory
 * @throws {Error} "Unknown error" for other encoding failures
 */
function pack(data) {}

Supported JavaScript Types:

• null, undefined → ETF nil atom
• true, false → ETF true/false atoms
• string → ETF binary/string
• number (0-255) → ETF small integer
• number (int32 range) → ETF integer
• number (float) → ETF new float
• object → ETF map/dictionary
• array → ETF list
• [] (empty array) → ETF nil list

Usage Examples:

// Basic data types
erlpack.pack(null);        // nil atom
erlpack.pack(true);        // true atom
erlpack.pack(false);       // false atom
erlpack.pack("hello");     // binary string
erlpack.pack(42);          // integer
erlpack.pack(3.14);        // float

// Complex structures
erlpack.pack({
  name: "Alice",
  age: 30,
  hobbies: ["reading", "coding"]
});

erlpack.pack([1, "two", 3.0, true, null]);

Data Decoding

Decodes ETF binary data back into JavaScript data structures.

/**
 * Decodes ETF binary data into JavaScript data structures
 * @param {Buffer|Uint8Array} data - ETF-encoded binary data to decode
 * @returns {any} Decoded JavaScript value
 * @throws {Error} "Attempting to unpack a non-object." when data is not Buffer/Uint8Array
 * @throws {Error} "Zero length buffer." when buffer is empty
 * @throws {Error} "Unsupported erlang term type identifier found" for unknown ETF types
 * @throws {Error} "Reading beyond the end of the buffer" for malformed data
 * @throws {Error} "Reading a byte passes the end of the buffer." for single byte read errors
 * @throws {Error} "Reading two bytes passes the end of the buffer." for double byte read errors
 * @throws {Error} "Reading three bytes passes the end of the buffer." for triple byte read errors
 * @throws {Error} "Reading sequence past the end of the buffer." for sequence read errors
 * @throws {Error} "Unpacking beyond the end of the buffer" for general unpacking errors
 * @throws {Error} "Unable to decode big ints larger than 8 bytes" for oversized integers
 */
function unpack(data) {}

Supported ETF Types:

• ETF nil atom → null
• ETF true/false atoms → boolean
• ETF atoms → string
• ETF binary/string → string
• ETF small integer → number
• ETF integer → number
• ETF new float → number
• ETF big integers (≤8 bytes) → number
• ETF big integers (>8 bytes) → string
• ETF lists → array
• ETF nil list → []
• ETF maps/dictionaries → object
• ETF tuples → array
• ETF compressed terms → automatically decompressed
• ETF references → {node: string, id: number[], creation: number}
• ETF ports → {node: string, id: number, creation: number}
• ETF PIDs → {node: string, id: number, serial: number, creation: number}
• ETF exports → {mod: string, fun: string, arity: number}

Usage Examples:

// Decode from Buffer
const buffer = Buffer.from('\\x83m\\x00\\x00\\x00\\x05hello', 'binary');
erlpack.unpack(buffer); // "hello"

// Decode from Uint8Array
const uint8Array = new Uint8Array([0x83, 0x6a]); // ETF nil list
erlpack.unpack(uint8Array); // []

// Handle complex structures
const complexBuffer = Buffer.from('\\x83t\\x00\\x00\\x00\\x01m\\x00\\x00\\x00\\x04namem\\x00\\x00\\x00\\x05Alice', 'binary');
erlpack.unpack(complexBuffer); // {name: "Alice"}

Error Handling

Both pack and unpack functions throw exceptions for various error conditions:

Pack Errors

• "Out of memory": Insufficient memory for encoding operation
• "Unknown error": General encoding failure

Unpack Errors

• "Attempting to unpack a non-object.": Input is not Buffer or Uint8Array
• "Zero length buffer.": Empty buffer provided
• "Unsupported erlang term type identifier found": Unknown ETF type code
• "Reading beyond the end of the buffer": Malformed or truncated data
• "Reading a byte passes the end of the buffer.": Single byte read error
• "Reading two bytes passes the end of the buffer.": Double byte read error
• "Reading three bytes passes the end of the buffer.": Triple byte read error
• "Reading sequence past the end of the buffer.": Sequence read error
• "Unpacking beyond the end of the buffer": General unpacking error
• "Unable to decode big ints larger than 8 bytes": Integer too large to decode

Error Handling Example:

try {
  const packed = erlpack.pack(data);
  const unpacked = erlpack.unpack(packed);
} catch (error) {
  console.error('ETF operation failed:', error.message);
  // Handle specific error types based on error.message
}

Performance Notes

• Erlpack uses native C++ implementation for optimal performance
• Suitable for high-throughput applications and real-time communication
• Requires native compilation during installation (node-gyp)
• Binary data handling is memory-efficient using Node.js Buffer objects

Electron/Libchromium Compatibility

When using erlpack in Electron applications, you may need to convert blink::WebArrayBuffer to Node.js Buffer before unpacking. See the project README for native code examples if this conversion is needed in your environment.