@thi.ng/msgpack

[!NOTE] This is one of 192 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please 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

ESM import:

import * as msg from "@thi.ng/msgpack";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/msgpack"></script>

JSDelivr documentation

For Node.js REPL:

const msg = 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