https://github.com/mprot/msgpack-js
A MessagePack implementation for JavaScript and TypeScript.
https://github.com/mprot/msgpack-js
javascript messagepack msgpack serialization typescript
Last synced: about 2 months ago
JSON representation
A MessagePack implementation for JavaScript and TypeScript.
- Host: GitHub
- URL: https://github.com/mprot/msgpack-js
- Owner: mprot
- License: mit
- Created: 2017-09-06T11:19:58.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-09-24T09:51:09.000Z (9 months ago)
- Last Synced: 2025-03-29T16:03:30.987Z (2 months ago)
- Topics: javascript, messagepack, msgpack, serialization, typescript
- Language: TypeScript
- Homepage:
- Size: 72.3 KB
- Stars: 37
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# msgpack-js
`msgpack-js` is a [MessagePack](http://msgpack.org/) implementation for JavaScript and TypeScript.
## Encoding
To encode objects into the binary MessagePack format, an `encode` function is provided:
```typescript
function encode(v: T, typ?: Type): Uint8Array;
```
This function takes an object of an arbitrary type and converts it to its binary representation. If the type of the object is known in advance, an optional `typ` parameter could be passed to indicate the encoding algorithm. For an automatic type detection this parameter could be omitted.
## Decoding
To decode binary MessagePack data into objects, a `decode` function is provided:
```typescript
function decode(buf: BufferSource, typ?: Type): T;
```
This function takes a buffer containing the binary data and converts it to an object. The buffer could either be an `ArrayBuffer` or an `ArrayBufferView` and should contain valid MessagePack data. If a certain type is expected, an optional `typ` parameter could be passed. For automatic detection from the buffer's content this parameter could be omitted.
## Example
```typescript
import {encode, decode} from "messagepack";
const bin1 = encode({foo: 7, bar: "seven"});
const obj = decode(bin1);
console.log(obj);
const bin2 = encode("foobar");
const str = decode(bin2);
console.log(str);
```
## Types
Sometimes even a JavaScript developer wants to have a little bit more type safety. In this situation specific types could be passed to the `encode` and `decode` functions. If the object or the binary data has an incompatible type, an error will be thrown.
The following types are supported:
* `Nil` for null values,
* `Bool` for boolean values,
* `Int` for signed integer values,
* `Uint` for unsigned integer values,
* `Float` for floating-point values,
* `Bytes` for binary data,
* `Str` for string values,
* `Arr` for arrays,
* `Map` for objects,
* `Raw` for already encoded values,
* `Time` for date and time values, and
* `Any` for automatically detecting the type and forward it to one of the types above.
The `Arr` and `Map` types provide generic encoding and decoding for their elements, i.e. `Arr` and `Map` essentially equal `Any[]` and `Map` respectively. If more stringent element types are required, the `TypedArr` and `TypedMap` functions could be used instead:
```typescript
import {TypedArr, TypedMap, Int, Str} from "messagepack";
const IntArray = TypedArr(Int);
const IntStrMap = TypedMap(Int, Str);
```
### Structs
A struct is an object type with a predefined shape. To define such a type, the function
```typescript
function Struct(fields: Fields): Type>;
```
can be used, which creates a type out of the predefined fields. All fields, that do not belong to the struct definition, will be omitted during the encoding and decoding process. To save some bytes and allow name changes, a struct is not simply encoded as a map with string keys. Instead, each field consists of a name, a type, and an ordinal, where the ordinal is used to uniquely identify a field.
Here is an example, how define a struct:
```typescript
import {Struct, Int, Str} from "messagepack";
const S = Struct({
// ordinal: [name, type],
1: ["foo", Int],
2: ["bar", Str],
});
```
If only the encoding or decoding capability is necessary, the functions
```typescript
function structEncoder(fields: Fields): EncodeFunc;
function structDecoder(fields: Fields): DecodeFunc;
```
can be used to create encoder and decoder functions respectively.
### Unions
A union is a value, that can be one of several types. To define a union type, the function
```typescript
function Union(branches: Branches): Type;
```
can be used, which creates a type out of the predefined branches. Each branch consists of an ordinal and a type. If a type should be encoded or decoded, that is not part of the union definition, an exception will be thrown. Also, `branches` needs to define a function to determine the ordinal number from a value.
Here is an example, how to define a union:
```typescript
import {Union, Int, Str} from "messagepack";
const U = Union({
// ordinal: type,
1: Int,
2: Str,
ordinalOf(v) {
switch(typeof v) {
case "string": return 1;
case "number": return 2;
default: new TypeError("invalid union type");
}
},
});
```
If only the encoding or decoding capability is necessary, the functions
```typescript
function unionEncoder(branches: Branches): EncodeFunc;
function unionDecoder(branches: Branches): DecodeFunc;
```
can be used to create encoder and decoder functions respectively.