tessl/npm-msgpackr

Ultra-fast MessagePack implementation with extensions for records and structured cloning

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Operations

Name: tessl/npm-msgpackr
Author: tessl

Basic MessagePack serialization and deserialization functions providing high-performance encoding and decoding of JavaScript values to/from binary MessagePack format.

Capabilities

Pack Function

Serializes a JavaScript value to MessagePack binary format using the default packr instance.

/**
 * Serializes a JavaScript value to MessagePack binary format
 * @param value - The value to serialize
 * @param encodeOptions - Optional encoding options (buffer mode flags)
 * @returns Buffer containing the MessagePack encoded data
 */
function pack(value: any, encodeOptions?: number): Buffer;

Usage Examples:

import { pack } from "msgpackr";

// Basic serialization
const data = { name: "Alice", age: 25, active: true };
const packed = pack(data);

// With arrays and nested objects
const complex = {
  users: [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" }
  ],
  metadata: { version: "1.0", timestamp: new Date() }
};
const packedComplex = pack(complex);

// With buffer mode options
const packedWithOptions = pack(data, REUSE_BUFFER_MODE);

Encode Function

Alias for the pack function, providing the same functionality with alternative naming.

/**
 * Alias for pack - serializes a JavaScript value to MessagePack binary format
 * @param value - The value to serialize
 * @param encodeOptions - Optional encoding options (buffer mode flags)
 * @returns Buffer containing the MessagePack encoded data
 */
function encode(value: any, encodeOptions?: number): Buffer;

Unpack Function

Deserializes MessagePack binary data back to JavaScript values using the default unpackr instance.

/**
 * Deserializes MessagePack binary data back to JavaScript values
 * @param messagePack - Buffer or Uint8Array containing MessagePack data
 * @param options - Optional unpacking options or byte offset
 * @returns The deserialized JavaScript value
 */
function unpack(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;

type UnpackOptions = { 
  start?: number;    // Starting byte offset
  end?: number;      // Ending byte offset  
  lazy?: boolean;    // Enable lazy unpacking
} | number;          // Or just a numeric offset

Usage Examples:

import { unpack } from "msgpackr";

// Basic deserialization
const packed = /* MessagePack buffer */;
const data = unpack(packed);

// With byte range options
const partialData = unpack(packed, { start: 10, end: 50 });

// With numeric offset
const offsetData = unpack(packed, 10);

// With lazy unpacking
const lazyData = unpack(packed, { lazy: true });

Decode Function

Alias for the unpack function, providing the same functionality with alternative naming.

/**
 * Alias for unpack - deserializes MessagePack binary data back to JavaScript values
 * @param messagePack - Buffer or Uint8Array containing MessagePack data
 * @param options - Optional unpacking options or byte offset
 * @returns The deserialized JavaScript value
 */
function decode(messagePack: Buffer | Uint8Array, options?: UnpackOptions): any;

Unpack Multiple Function

Deserializes multiple MessagePack values from a single buffer, either returning an array or processing via callback.

/**
 * Deserializes multiple MessagePack values from a single buffer
 * @param messagePack - Buffer containing multiple MessagePack encoded values
 * @returns Array of deserialized values
 */
function unpackMultiple(messagePack: Buffer | Uint8Array): any[];

/**
 * Deserializes multiple MessagePack values with callback processing
 * @param messagePack - Buffer containing multiple MessagePack encoded values
 * @param forEach - Callback function called for each unpacked value
 */
function unpackMultiple(
  messagePack: Buffer | Uint8Array, 
  forEach: (value: any, start?: number, end?: number) => any
): void;

Usage Examples:

import { unpackMultiple } from "msgpackr";

// Unpack to array
const buffer = /* Buffer with multiple MessagePack values */;
const values = unpackMultiple(buffer);
console.log(values); // [value1, value2, value3, ...]

// Process with callback
unpackMultiple(buffer, (value, start, end) => {
  console.log(`Value: ${value}, range: ${start}-${end}`);
  // Process each value individually
});

// Stream-like processing
const results = [];
unpackMultiple(buffer, (value) => {
  if (value.type === 'important') {
    results.push(value);
  }
});

Error Handling

The core functions may throw errors in the following scenarios:

Invalid MessagePack data: When the input buffer contains malformed MessagePack data
Buffer underrun: When the buffer ends unexpectedly during unpacking
Type errors: When trying to pack unsupported JavaScript values
Memory errors: When buffers are too large or system memory is exhausted

import { pack, unpack } from "msgpackr";

try {
  const packed = pack(someData);
  const unpacked = unpack(packed);
} catch (error) {
  if (error.incomplete) {
    // Handle incomplete MessagePack data
    console.log('Incomplete data at position:', error.lastPosition);
    console.log('Partial values:', error.values);
  } else {
    // Handle other errors
    console.error('Packing/unpacking error:', error.message);
  }
}

Constants

const REUSE_BUFFER_MODE: number;     // Reuse internal buffers for performance
const RESET_BUFFER_MODE: number;    // Reset buffers between operations
const RESERVE_START_SPACE: number;  // Reserve space at buffer start