@msgpack/msgpack

What is @msgpack/msgpack?

@msgpack/msgpack is an npm package that provides functionality for encoding and decoding data using the MessagePack format. MessagePack is a binary serialization format that is more efficient than JSON in terms of both size and speed. This package allows you to serialize JavaScript objects into a compact binary format and deserialize them back into JavaScript objects.

What are @msgpack/msgpack's main functionalities?

Encoding Data

This feature allows you to encode a JavaScript object into a MessagePack binary format. The `encode` function takes a JavaScript object and returns a Buffer containing the binary data.

const msgpack = require('@msgpack/msgpack');
const data = { foo: 'bar', num: 42 };
const encoded = msgpack.encode(data);
console.log(encoded);

Decoding Data

This feature allows you to decode a MessagePack binary format back into a JavaScript object. The `decode` function takes a Buffer containing the binary data and returns the original JavaScript object.

const msgpack = require('@msgpack/msgpack');
const encoded = Buffer.from([0x82, 0xa3, 0x66, 0x6f, 0x6f, 0xa3, 0x62, 0x61, 0x72, 0xa3, 0x6e, 0x75, 0x6d, 0x2a]);
const decoded = msgpack.decode(encoded);
console.log(decoded);

Custom Extension Types

This feature allows you to define custom extension types for encoding and decoding. You can use `addExtPacker` to specify how to serialize a custom type and `addExtUnpacker` to specify how to deserialize it.

const msgpack = require('@msgpack/msgpack');
class MyType {
  constructor(value) {
    this.value = value;
  }
}
msgpack.addExtPacker(0x01, MyType, (obj) => msgpack.encode(obj.value));
msgpack.addExtUnpacker(0x01, (data) => new MyType(msgpack.decode(data)));
const myObj = new MyType('custom data');
const encoded = msgpack.encode(myObj);
const decoded = msgpack.decode(encoded);
console.log(decoded);

Other packages similar to @msgpack/msgpack

msgpack-lite

msgpack-lite is another npm package for MessagePack serialization. It is designed to be lightweight and fast, with a focus on performance. Compared to @msgpack/msgpack, msgpack-lite may have fewer features but is optimized for speed and small bundle size.

notepack.io

notepack.io is a fast and small MessagePack implementation for JavaScript. It is designed to be highly efficient and is often used in performance-critical applications. Compared to @msgpack/msgpack, notepack.io is more focused on performance and may offer better speed at the cost of some additional features.

msgpack5

msgpack5 is a pure JavaScript implementation of the MessagePack format. It supports both encoding and decoding, as well as custom extension types. Compared to @msgpack/msgpack, msgpack5 offers similar functionality but may have different performance characteristics and API design.

README

MessagePack for JavaScript

This is a JavaScript/ECMA-262 implementation of MessagePack, an efficient binary serilization format:

https://msgpack.org/

This library is compatible with the "August 2017" revision of MessagePack specification at the point where timestamp ext was added.

Stability

This is under development until v1.0.0. Any API will change without notice.

Synopsis

import { deepStrictEqual } from "assert";
import { encode, decode } from "@msgpack/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(),
};

const encoded: Uint8Array = encode(object);

deepStrictEqual(decode(encoded), object);

Install

This library is publised as @msgpack/msgpack in npmjs.com.

npm install @msgpack/msgpack

API

encode(data: unknown, options?): Uint8Array

It encodes data and returns a byte array as Uint8Array.

decode(buffer: ArrayLike<number> | Uint8Array, options?): unknown

It decodes buffer in a byte buffer and returns decoded data as uknown.

decodeAsync(stream: AsyncIterable<ArrayLike<number> | Uint8Array>, options?): Promise<unknown>

It decodes stream in an async iterable of byte arrays and returns decoded data as uknown wrapped in Promise. This function works asyncronously.

Extension Types

To handle MessagePack Extension Types, this library provides ExtensionCodec class.

Here is an example to setup custom extension types that handles Map and Set classes in TypeScript:

import { encode, decode, ExtensionCodec } from "@msgpack/msgpack";

const extensionCodec = new ExtensionCodec();

// Set<T>
const SET_EXT_TYPE = 0 // Any in 0-127
extensionCodec.register({
  type: SET_EXT_TYPE,
  encode: (object: unknown): Uint8Array | null => {
    if (object instanceof Set) {
      return encode([...object]);
    } else {
      return null;
    }
  },
  decode: (data: Uint8Array) => {
    const array = decode(data) as Array<unknown>;
    return new Set(array);
  },
});

// Map<T>
const MAP_EXT_TYPE = 1; // Any in 0-127
extensionCodec.register({
  type: 1,
  encode: (object: unknown): Uint8Array => {
    if (object instanceof Map) {
      return encode([...object]);
    } else {
      return null;
    }
  },
  decode: (data: Uint8Array) => {
    const array = decode(data) as Array<[unknown, unknown]>;
    return new Map(array);
  },
});

// and later
import { encode, decode } from "@msgpack/msgpack";

const encoded = = encode([new Set<any>(), new Map<any, any>()], { extensionCodec });
const decoded = decode(encoded, { extensionCodec });

Not that extension types for custom objects must be [0, 127], while [-1, -128] is reserved for MessagePack itself.

Handling BigInt with ExtensionCodec

This library does not handle BigInt by default, but you can handle it with ExtensionCodec like this:

import { deepStrictEqual } from "assert";
import { encode, decode, ExtensionCodec } from "../src";

const BIGINT_EXT_TYPE = 0; // Any in 0-127
const extensionCodec = new ExtensionCodec();
extensionCodec.register({
  type: BIGINT_EXT_TYPE,
  encode: (input: unknown) => {
    if (typeof input === "bigint") {
      return encode(input.toString());
    } else {
      return null;
    }
  },
  decode: (data: Uint8Array) => {
    return BigInt(decode(data));
  },
});

const value = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
const encoded: = encode(value, { extensionCodec });
deepStrictEqual(decode(encoded, { extensionCodec }), value);

MessagePack Mapping Table

The following table shows how JavaScript values are mapped to MessagePack formats and vice versa.

Source Value	MessagePack Format	Value Decoded
null, undefined	nil format family	null (*1)
boolean (true, false)	bool format family	boolean (true, false)
number (53-bit int)	int format family	number (53-bit int)
number (64-bit float)	float format family	number (64-bit float)
string	str format family	string
ArrayBufferView	bin format family	Uint8Array (*2)
Array	array format family	Array
Object	map format family	Object (*3)
Date	timestamp ext format family	Date (*4)

• *1 Both null and undefined are mapped to nil (0xC0) type, and are decoded into null
• *2 Any ArrayBufferViews including NodeJS's Buffer are mapped to bin family, and are decoded into Uint8Array
• *3 In handling Object, it is regarded as Record<string, unknown> in terms of TypeScript
• *4 MessagePack timestamps may have nanoseconds, which will lost when it is decoded into JavaScript Date. This behavior can be overrided by registering -1 for the extension codec.

Prerequsites

ECMA-262

• ES5 language features
• Typed Arrays (ES2015; caniuse: typedarrays)
• String.prototype.padStart (ES2017; caniuse: pad-start-end)
• Async iterations / for await of syntax (ES2018)

You can use polyfills for all of them with TypeScript downlevel compilation.

NodeJS

If you use this library in NodeJS v10 or later is required, but NodeJS v12 is recommended because it includes the V8 feature of Improving DataView performance in V8.

Benchmark

Benchmark on NodeJS/v12.1.0

operation	op	ms	op/s
buf = Buffer.from(JSON.stringify(obj));	493600	5000	98720
buf = JSON.stringify(obj);	959600	5000	191920
obj = JSON.parse(buf);	346100	5000	69220
buf = require("msgpack-lite").encode(obj);	358300	5000	71660
obj = require("msgpack-lite").decode(buf);	270400	5000	54080
buf = require("@msgpack/msgpack").encode(obj);	594300	5000	118860
obj = require("@msgpack/msgpack").decode(buf);	343100	5000	68620

Note that Buffer.from() for JSON.stringify() is added to emulate I/O where a JavaScript string must be converted into a byte array encoded in UTF-8, whereas MessagePack's encode() returns a byte array.

Distrubition

The NPM package distributed in npmjs.com includes both ES2015+ and ES5 files:

• /dist is compiled into ES2015+
• /dist.es5 is compiled into ES5 and bundled to singile file

If you use NodeJS and/or webpack, their module resolvers use the suitable one automatically.

Maintenance

CI

• See .travis.yml for details

Relase Engineering

# run tests on NodeJS, Chrome, and Firefox
make test

# edit the changelog
code CHANGELOG.md

# prepare release engineering
npm version major|minor|patch
git push origin master

# run the publishing task
make publish

License

Copyright 2019 The MessagePack community.

This software uses the ISC license:

https://opensource.org/licenses/ISC

See LICENSE for details.

Changelog

v1.0.0 2019/05/11

• Initial stable release