Registry / serialization / algorand-msgpack

algorand-msgpack

library1.1.0jsnpmunverified

This library, `algorand-msgpack`, is a TypeScript/JavaScript implementation of the MessagePack binary serialization format, currently at version 1.1.0. It's a fork of the popular `@msgpack/msgpack` library, maintaining a similar API but introducing several key enhancements. These include improved BigInt support that allows for greater interoperability with other MessagePack implementations by not solely encoding BigInts as int64/uint64, and the ability to decode raw strings as `Uint8Array`s to handle non-UTF-8 encoded strings. Additionally, it provides support for number and binary map keys within JavaScript Maps. The most recent significant update in v1.1.0 introduced the `RawBinaryString` class, enabling encoding byte arrays as MessagePack strings and offering corresponding decoding options. While it doesn't have a strict release cadence, updates appear to be driven by the needs of the Algorand ecosystem. It's designed to be a universal library, compatible with Node.js (v14 and above) and browser environments, and ships with comprehensive TypeScript type definitions.

serialization type-stubs

npm install algorand-msgpack

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ALGORAND-MSGPACK

algorand-msgpack

serializationjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

encode

✓ import { encode } from 'algorand-msgpack'

✗ import { encode } from '@msgpack/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

✓ import { decode } from 'algorand-msgpack'

✗ const { decode } = require('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`.

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!");

Debug

Known issues

breakingThis 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.1.0

gotchaThis 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

noderequiredRequired runtime environment, specified by engines field.

Agent activity

63 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/algorand/msgpack-javascript ↗

packagehttps://www.npmjs.com/package/algorand-msgpack ↗

homepagehttps://msgpack.org/ ↗