msgpack

Important

‼️ Announcing the thi.ng user survey 2024 📋

Please participate in the survey here!
(open until end of February)

To achieve a better sample size, I'd highly appreciate if you could circulate the link to this survey in your own networks.

Discussion

Note

This is one of 189 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
  • Supported values
• Status
• Installation
• Dependencies
• API
• Authors
• License

About

Small & fast msgpack serialization & deserialization.

This implementation is a full rewrite & refactor of @ygoe/msgpack.js, based on this specification.

Supported values

• numbers (i8/16/32, u8/16/32, bigint signed/unsigned 64bit range, floats)
• strings (converted to UTF-8)
• plain JS objects
• arrays
• typed arrays (as bytes)
• Date objects
• null

Custom types can be serialized via a user-provided resolve() function which is expected to produce a msgpack-compatible representation of the custom type(s).

As with JSON.stringify(), undefined values will be serialized as null and object keys with undefined will be entirely omitted in the serialization.

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

yarn add @thi.ng/msgpack

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/msgpack"></script>

Skypack documentation

For Node.js REPL:

const msgpack = await import("@thi.ng/msgpack");

Package sizes (brotli'd, pre-treeshake): ESM: 1.56 KB

Dependencies

• @thi.ng/checks
• @thi.ng/errors
• @thi.ng/strings

API

Generated API docs

import { deserialize, serialize } from "@thi.ng/msgpack";
import { equiv } from "@thi.ng/equiv";

const obj = {
    small_i8: -0x0f,
    i8: -0x80,
    small_u8: 0xff,
    i16: -0x8000,
    u16: 0xfedc,
    i32: -0x8000_0000,
    u32: 0xffff_ffff,
    utf8_array: ["👋 Hello", "msgpack!", "🔥🤌"],
    now: new Date()
};

// encode to byte array
const bytes = serialize(obj);
console.log(bytes);
// Uint8Array(114) [ 137, 168, 115, 109, 97, 108, 108, ... ]

// comparison with JSON
const json = JSON.stringify(obj);
const ratio = bytes.length / json.length;
console.log(`msgpack: ${bytes.length}, json: ${json.length}, ratio: ${ratio.toFixed(2)}`);
// msgpack: 114, json: 178, ratio: 0.64

// roundtrip
const obj2 = deserialize(bytes);

// check equality
console.log(equiv(obj, obj2));
// true

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-msgpack,
  title = "@thi.ng/msgpack",
  author = "Karsten Schmidt",
  note = "https://thi.ng/msgpack",
  year = 2023
}

License

© 2023 - 2024 Karsten Schmidt // Apache License 2.0