cbor
Encode and parse data in the Concise Binary Object Representation (CBOR) data format (RFC7049).
-Installation:
$ npm install --save cbor
NOTE
-This package now requires node.js 4.1 or higher. If you want a version that
-works with older node.js versions, you can install like this:
-npm install 'hildjj/node-cbor#node0' --save
Documentation:
See the full API documentation.
-From the command line:
-$ bin/json2cbor package.json > package.cbor
-$ bin/cbor2json package.cbor
-$ bin/cbor2diag package.cbor
Example:
-var cbor = require('cbor');
-var assert = require('assert');
-
-var encoded = cbor.encode(true); // returns <Buffer f5>
-cbor.decodeFirst(encoded, function(error, obj) {
- // error != null if there was an error
- // obj is the unpacked object
- assert.ok(obj === true);
-});
-
-// Use integers as keys?
-var m = new Map();
-m.set(1, 2);
-encoded = cbor.encode(m); // <Buffer a1 01 02>
Allows streaming as well:
-var cbor = require('cbor');
-var fs = require('fs');
-
-var d = new cbor.Decoder();
-d.on('data', function(obj){
- console.log(obj);
-});
-
-var s = fs.createReadStream('foo');
-s.pipe(d);
-
-var d2 = new cbor.Decoder({input: '00', encoding: 'hex'});
-d.on('data', function(obj){
- console.log(obj);
-});
There is also support for synchronous decodes:
-try {
- console.log(cbor.decodeFirstSync('02')); // 2
- console.log(cbor.decodeAllSync('0202')); // [2, 2]
-} catch (e) {
- // throws on invalid input
-}
The sync encoding and decoding are exported as a
-leveldb encoding, as
-cbor.leveldb.
-Supported types
The following types are supported for encoding:
-
-- boolean
-- number (including -0, NaN, and ±Infinity)
-- string
-- Array, Set (encoded as Array)
-- Object (including null), Map
-- undefined
-- Buffer
-- Date,
-- RegExp
-- url.URL
-- bignumber
-
-Decoding supports the above types, including the following CBOR tag numbers:
-
-
-
-| Tag |
-Generated Type |
-
-
-
-
-| 0 |
-Date |
-
-
-| 1 |
-Date |
-
-
-| 2 |
-bignumber |
-
-
-| 3 |
-bignumber |
-
-
-| 4 |
-bignumber |
-
-
-| 5 |
-bignumber |
-
-
-| 32 |
-url.URL |
-
-
-| 35 |
-RegExp |
-
-
-
-Adding new Encoders
There are several ways to add a new encoder:
-ecodeCBOR method
This is the easiest approach, if you can modify the class being encoded. Add an
-encodeCBOR method to your class, which takes a single parameter of the encoder
-currently being used. Your method should return true on success, else false.
-Your method may call encoder.push(buffer) or encoder.pushAny(any) as needed.
-For example:
-class Foo {
- constructor () {
- this.one = 1
- this.two = 2
- }
- encodeCBOR (encoder) {
- const tagged = new Tagged(64000, [this.one, this.two])
- return encoder.pushAny(tagged)
- }
-}
You can also modify an existing type by monkey-patching an encodeCBOR function
-onto its prototype, but this isn't recommended.
-addSemanticType
Sometimes, you want to support an existing type without modification to that
-type. In this case, call addSemanticType(type, encodeFunction) on an existing
-Encoder instance. The encodeFunction takes an encoder and an object to
-encode, for example:
-class Bar {
- constructor () {
- this.three = 3
- }
-}
-const enc = new Encoder()
-enc.addSemanticType(Bar, (encoder, b) => {
- encoder.pushAny(b.three)
-})
Adding new decoders
Most of the time, you will want to add support for decoding a new tag type. If
-the Decoder class encounters a tag it doesn't support, it will generate a Tagged
-instance that you can handle or ignore as needed. To have a specific type
-generated instead, pass a tags option to the Decoder's constructor, consisting
-of an object with tag number keys and function values. The function will be
-passed the decoded value associated with the tag, and should return the decoded
-value. For the Foo example above, this might look like:
-const d = new Decoder({tags: { 64000: (val) => {
- // check val to make sure it's an Array as expected, etc.
- const foo = new Foo()
- foo.one = val[0]
- foo.two = val[1]
- return foo
-}}})
Developers
Get a list of build steps with npm run. I use npm run dev, which rebuilds,
-runs tests, and refreshes a browser window with coverage metrics every time I
-save a .coffee file. If you don't want to run the fuzz tests every time, set
-a NO_GARBAGE environment variable:
-env NO_GARBAGE=1 npm run dev
-
-
-