Skip to content
/ cbor Public

TypeScript implementation of the CBOR specification

License

Notifications You must be signed in to change notification settings

jprochazk/cbor

Repository files navigation

Build Status David GitHub

TypeScript implementation of the Concise Binary Object Representation RFC 7049. From the official website:

CBOR is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation.

The API is self-explanatory:

// Initialize some data
const json = {
    "key": "value",
    "another key": [
        1, 2, 3
    ],
    "number": 3.141592653589793
    "nulls are also encoded": null
};

const encoded = CBOR.encode(json); // ArrayBuffer
const decoded = CBOR.decode(encoded); // Object

// You can also encode into a pre-allocated buffer
const encoded = CBOR.encodeInto(new ArrayBuffer(4096), data);

Usage

The library is targeted for both Node and Browsers using NPM:

> npm install cbor@npm:jprochazk/cbor

This installs the library under the cbor alias.

// as CommonJS
const CBOR = require("cbor");

// as an ES module
import CBOR from "cbor";

CBOR.encode(...);
CBOR.decode(...);

Or included in the page as a static script from the unkpg CDN:

<script src="https://unpkg.com/@jprochazk/[email protected]"></script>
<script>
    // after including the script in the page, the CBOR object is available globally
    CBOR.encode(...);
    CBOR.decode(...);
</script>

Benchmarks

Benchmark is available here.

Browser CBOR.decode CBOR.encode CBOR.encodeInto
Chrome 5225 ops/s 8998 ops/s 9268 ops/s
Firefox 20454 ops/s 22323 ops/s 22900 ops/s

Results are on a i5-8600k intel processor. Your mileage may vary. The JSON data used in the test is 2 KB decoded and 1.8 KB encoded. I specifically chose this data, because it encodes badly (lots of nested objects with only a single property). The benchmark suggests the library can encode/decode around 10 MB/s in Chrome and around 50 MB/s in Firefox. Hopefully, these are meaningful results.

Notes

There are a few things from the specification which are currently unimplemented:

  • Tags, and the items they represent:
    • date/time, bignum/bigfloat as byte string, and others
  • 16-bit float (IEEE754 binary16)
  • Integers larger than 32 bit (BigInt)

If you need one or more of these features, submit an issue.