Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mcollina/msgpack5
A msgpack v5 implementation for node.js, with extension points / msgpack.org[Node]
https://github.com/mcollina/msgpack5
Last synced: 6 days ago
JSON representation
A msgpack v5 implementation for node.js, with extension points / msgpack.org[Node]
- Host: GitHub
- URL: https://github.com/mcollina/msgpack5
- Owner: mcollina
- License: mit
- Created: 2014-07-17T07:46:48.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-02-12T09:03:13.000Z (11 months ago)
- Last Synced: 2025-01-02T17:13:21.825Z (13 days ago)
- Language: JavaScript
- Homepage:
- Size: 647 KB
- Stars: 493
- Watchers: 15
- Forks: 77
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-list - msgpack5
- awesome-nodejs-pure-js - msgpack5
README
msgpack5 [](https://github.com/mcollina/msgpack5/actions?query=workflow%3ACI)
========
A msgpack v5 implementation for node.js and the browser, with extension point support.
Install
-------
```bash
npm install msgpack5 --save
```
Usage
-----
```js
var msgpack = require('msgpack5')() // namespace our extensions
, a = new MyType(2, 'a')
, encode = msgpack.encode
, decode = msgpack.decode
msgpack.register(0x42, MyType, mytipeEncode, mytipeDecode)
const hex = encode({ 'hello': 'world' }).toString('hex')
console.log(hex)
// 81a568656c6c6fa5776f726c64
const obj = decode(Buffer.from(hex, 'hex'))
console.log(obj)
// { hello: 'world' }
console.log(decode(encode({ 'hello': 'world' })))
// { hello: 'world' }
console.log(encode(a).toString('hex'))
// d5426161
console.log(decode(encode(a)) instanceof MyType)
// true
console.log(decode(encode(a)))
// { value: 'a', size: 2 }
function MyType(size, value) {
this.value = value
this.size = size
}
function mytipeEncode(obj) {
var buf = new Buffer(obj.size)
buf.fill(obj.value)
return buf
}
function mytipeDecode(data) {
var result = new MyType(data.length, data.toString('utf8', 0, 1))
, i
for (i = 0; i < data.length; i++) {
if (data.readUInt8(0) != data.readUInt8(i)) {
throw new Error('should all be the same')
}
}
return result
}
```
In the Browser
-----------
This library is compatible with [Browserify](http://npm.im/browserify).
If you want to use standalone, grab the file in the `dist` folder of
this repo, and use in your own HTML page, the module will expose a
`msgpack5` global.
```
```
### To build
```
npm run build
```
API
---
## API
* msgpack()
* msgpack().encode()
* msgpack().decode()
* msgpack().registerEncoder()
* msgpack().registerDecoder()
* msgpack().register()
* msgpack().encoder()
* msgpack().decoder()
-------------------------------------------------------
### msgpack(options(obj))
Creates a new instance on which you can register new types for being
encoded.
options:
- `forceFloat64`, a boolean to that forces all floats to be encoded as 64-bits floats. Defaults to false.
- `sortKeys`, a boolean to force a determinate keys order
- `compatibilityMode`, a boolean that enables "compatibility mode" which doesn't use bin format family and str 8 format. Defaults to false.
- `disableTimestampEncoding`, a boolean that when set disables the encoding of Dates into the [timestamp extension type](https://github.com/msgpack/msgpack/blob/master/spec.md#timestamp-extension-type). Defaults to false.
- `preferMap`, a boolean that forces all maps to be decoded to `Map`s rather than plain objects. This ensures that `decode(encode(new Map())) instanceof Map` and that iteration order is preserved. Defaults to false.
- `protoAction`, a string which can be `error|ignore|remove` that determines what happens when decoding a plain object with a `__proto__` property which would cause prototype poisoning. `error` (default) throws an error, `remove` removes the property, `ignore` (not recommended) allows the property, thereby causing prototype poisoning on the decoded object.
-------------------------------------------------------
### encode(object)
Encodes `object` in msgpack, returns a [bl](http://npm.im/bl).
-------------------------------------------------------
### decode(buf)
Decodes buf from in msgpack. `buf` can be a `Buffer` or a [bl](http://npm.im/bl) instance.
In order to support a stream interface, a user must pass in a [bl](http://npm.im/bl) instance.
-------------------------------------------------------
### registerEncoder(check(obj), encode(obj))
Register a new custom object type for being automatically encoded.
The arguments are:
- `check`, a function that will be called to check if the passed
object should be encoded with the `encode` function
- `encode`, a function that will be called to encode an object in binary
form; this function __must__ return a `Buffer` which include the same type
for [registerDecoder](#registerDecoder).
-------------------------------------------------------
### registerDecoder(type, decode(buf))
Register a new custom object type for being automatically decoded.
The arguments are:
- `type`, is a greater than zero integer identificating the type once serialized
- `decode`, a function that will be called to decode the object from
the passed `Buffer`
-------------------------------------------------------
### register(type, constructor, encode(obj), decode(buf))
Register a new custom object type for being automatically encoded and
decoded. The arguments are:
- `type`, is a greater than zero integer identificating the type once serialized
- `constructor`, the function that will be used to match the objects
with `instanceof`
- `encode`, a function that will be called to encode an object in binary
form; this function __must__ return a `Buffer` that can be
deserialized by the `decode` function
- `decode`, a function that will be called to decode the object from
the passed `Buffer`
This is just a commodity that calls
[`registerEncoder`](#registerEncoder) and
[`registerDecoder`](#registerDecoder) internally.
-------------------------------------------------------
### encoder(options)
Builds a stream in object mode that encodes msgpack.
Supported options:
* `wrap`, objects should be passed to encoder in wrapped object {value: data}. Wrap option should be used if you need to pass null to encoder.
-------------------------------------------------------
### decoder(options)
Builds a stream in object mode that decodes msgpack.
Supported options:
* `wrap`, decoded objects returned in wrapped object {value: data}. Wrap option should be used if stream contains msgpack nil.
LevelUp Support
---------------
__msgpack5__ can be used as a LevelUp
[`valueEncoding`](https://github.com/rvagg/node-levelup#leveluplocation-options-callback) straight away:
```js
var level = require('level')
, pack = msgpack()
, db = level('foo', {
valueEncoding: pack
})
, obj = { my: 'obj' }
db.put('hello', obj, function(err) {
db.get('hello', function(err, result) {
console.log(result)
db.close()
})
})
```
Related projects
----------------
- [msgpack5rpc](http://npmjs.com/package/msgpack5rpc): An implementation of the
[msgpack-rpc spec](https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md)
on top of this library.
Disclaimer
----------
This library is built fully on JS and on [bl](http://npm.im/bl) to
simplify the code. Every improvement that keeps the same API is welcome.
Acknowledgements
----------------
This project was kindly sponsored by [nearForm](http://nearform.com).
This library was originally built as the data format for
[JSChan](http://npm.im/jschan).
License
-------
MIT