{"id":15500,"library":"algorand-msgpack","title":"Algorand MessagePack","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/algorand/msgpack-javascript","tags":["javascript","msgpack","MessagePack","serialization","universal","typescript"],"install":[{"cmd":"npm install algorand-msgpack","lang":"bash","label":"npm"},{"cmd":"yarn add algorand-msgpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add algorand-msgpack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime environment, specified by engines field.","package":"node","optional":false}],"imports":[{"note":"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.","wrong":"import { encode } from '@msgpack/msgpack'","symbol":"encode","correct":"import { encode } from 'algorand-msgpack'"},{"note":"Primarily designed for ESM. While CommonJS `require` might work with transpilation, direct ESM imports are recommended for modern Node.js and browser environments.","wrong":"const { decode } = require('algorand-msgpack')","symbol":"decode","correct":"import { decode } from 'algorand-msgpack'"},{"note":"Introduced in v1.1.0. This class is used for explicit handling of raw binary strings during encoding and decoding, often requiring specific `DecoderOptions`.","symbol":"RawBinaryString","correct":"import { RawBinaryString } from 'algorand-msgpack'"}],"quickstart":{"code":"import { deepStrictEqual } from \"assert\";\nimport { encode, decode, RawBinaryString } from \"algorand-msgpack\";\n\nconst object = {\n  nil: null,\n  integer: 1,\n  float: Math.PI,\n  string: \"Hello, world!\",\n  binary: Uint8Array.from([1, 2, 3]),\n  array: [10, 20, 30],\n  map: { foo: \"bar\" },\n  timestampExt: new Date(),\n  // Example of using RawBinaryString introduced in v1.1.0\n  rawString: new RawBinaryString(Uint8Array.from([0x68, 0x65, 0x6c, 0x6c, 0x6f])) \n};\n\nconst encoded: Uint8Array = encode(object);\n\n// When decoding, enable options if expecting RawBinaryString instances\nconst decoded = decode(encoded, {\n  useRawBinaryStringClass: true, \n  rawBinaryStringValues: true \n});\n\ndeepStrictEqual(decoded, object);\nconsole.log(\"MessagePack encoding and decoding successful!\");","lang":"typescript","description":"Demonstrates basic encoding and decoding of a complex JavaScript object, including the use of `RawBinaryString` for explicit binary string handling, ensuring data integrity."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.0"},{"fix":"Ensure your Node.js runtime environment is version 14 or later. Upgrade Node.js if necessary.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update all import statements in your code from `@msgpack/msgpack` to `algorand-msgpack`.","cause":"Attempting to import from the original `@msgpack/msgpack` package instead of the forked `algorand-msgpack`.","error":"Module not found: Error: Can't resolve '@msgpack/msgpack' in '...' OR Failed to resolve module specifier \"@msgpack/msgpack\""},{"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.","cause":"Mismatch in BigInt handling between `algorand-msgpack` and other MessagePack implementations, or expecting BigInts to be serialized without specific configuration.","error":"TypeError: Cannot mix BigInt and other types, use explicit conversion"}],"ecosystem":"npm"}