Algorand MessagePack

Common errors

• Module not found: Error: Can't resolve '@msgpack/msgpack' in '...' OR Failed to resolve module specifier "@msgpack/msgpack"

  cause Attempting to import from the original `@msgpack/msgpack` package instead of the forked `algorand-msgpack`.
  fix Update all import statements in your code from `@msgpack/msgpack` to `algorand-msgpack`.

• TypeError: Cannot mix BigInt and other types, use explicit conversion

  cause Mismatch in BigInt handling between `algorand-msgpack` and other MessagePack implementations, or expecting BigInts to be serialized without specific configuration.
  fix Review the BigInt support documentation for `algorand-msgpack`. You may need to use specific `EncoderOptions` or `DecoderOptions` to align BigInt serialization/deserialization with your requirements or other systems.

Warnings

• breaking This library is a fork of `@msgpack/msgpack` and introduces behavioral changes for BigInt handling, raw string decoding, and map key types. While the API is similar, direct replacement without understanding these differences may lead to subtle data corruption or unexpected behavior.
  Fix: Thoroughly review the fork's specific changes documented in the README (e.g., BigInt support, raw string decoding options, map key types) and adjust your encoding/decoding logic or expectations accordingly.
• gotcha The `RawBinaryString` class, introduced in v1.1.0, requires explicit decoder options (`useRawBinaryStringClass`, `rawBinaryStringKeys`, `rawBinaryStringValues`) to decode MessagePack strings back into `RawBinaryString` instances. Without these options, they will be decoded as standard JavaScript strings or `Uint8Array`s.
  Fix: When calling `decode()`, pass an options object with `useRawBinaryStringClass: true` and either `rawBinaryStringKeys: true` or `rawBinaryStringValues: true` (or both) if you intend to receive `RawBinaryString` objects.
• gotcha This library explicitly requires Node.js version 14 or higher as per its `engines` field. Running in older Node.js environments may result in runtime errors or unexpected behavior.
  Fix: Ensure your Node.js runtime environment is version 14 or later. Upgrade Node.js if necessary.

Install

• npm install algorand-msgpack npm
• yarn add algorand-msgpack yarn
• pnpm add algorand-msgpack pnpm

Imports

• encode
  wrong:

  import { encode } from '@msgpack/msgpack'

  correct:

  import { encode } from 'algorand-msgpack'

  This is a fork of the original library; ensure you import from 'algorand-msgpack' to access its specific features and avoid 'module not found' errors.
• decode
  wrong:

  const { decode } = require('algorand-msgpack')

  correct:

  import { decode } from 'algorand-msgpack'

  Primarily designed for ESM. While CommonJS `require` might work with transpilation, direct ESM imports are recommended for modern Node.js and browser environments.
• RawBinaryString

  import { RawBinaryString } from 'algorand-msgpack'

  Introduced in v1.1.0. This class is used for explicit handling of raw binary strings during encoding and decoding, often requiring specific `DecoderOptions`.

Quickstart

Demonstrates basic encoding and decoding of a complex JavaScript object, including the use of `RawBinaryString` for explicit binary string handling, ensuring data integrity.

import { deepStrictEqual } from "assert";
import { encode, decode, RawBinaryString } from "algorand-msgpack";

const object = {
  nil: null,
  integer: 1,
  float: Math.PI,
  string: "Hello, world!",
  binary: Uint8Array.from([1, 2, 3]),
  array: [10, 20, 30],
  map: { foo: "bar" },
  timestampExt: new Date(),
  // Example of using RawBinaryString introduced in v1.1.0
  rawString: new RawBinaryString(Uint8Array.from([0x68, 0x65, 0x6c, 0x6c, 0x6f])) 
};

const encoded: Uint8Array = encode(object);

// When decoding, enable options if expecting RawBinaryString instances
const decoded = decode(encoded, {
  useRawBinaryStringClass: true, 
  rawBinaryStringValues: true 
});

deepStrictEqual(decoded, object);
console.log("MessagePack encoding and decoding successful!");