cbor-redux

cbor-redux

The Concise Binary Object Representation (CBOR) data format (RFC 7049) implemented in pure JavaScript with an API surface like the built-in JSON functions. Rewritten in TypeScript for the browser, Deno, and Node.

Using CBOR

Like the JSON API, this library is synchronous. Simply import into your runtime: Deno, browser, Node ESM, or Node CommonJS. Browser imports can be handled via your favorite bundler, or using Skypack CDN.

// This is an example Deno import statement.
import { CBOR } from "https://deno.land/x/cbor_redux@1.0.0/mod.ts";

const initial = { Hello: "World", how: "are you?" };
const encoded = CBOR.encode(initial, ["Hello"]);
const decoded = CBOR.decode(encoded);
console.log(decoded); // Output: { Hello: "World" }

Unrecognized CBOR tags will be emitted as instances of TaggedValue, allowing an application to use custom handling. Simple values in CBOR that are reserved or unassigned will be emitted as instances of SimpleValue so that they may be handled directly.

For users who need more power and control, the entire library API is documented at doc.deno.land.

Supported Features

• Concise Binary Object Representation (RFC 7049, partial RFC 8949, see below)
• CBOR Sequences (RFC 8742)
• Proper support for large integers; integers larger than a JavaScript number may safely hold will be decoded as bigint. Values of bigint will be encoded when provided by the application.
• Typed Arrays (RFC 8746)
• Tags (RFC 8949)
• Simple Values (RFC 8949)
• Rejection with mode: 'strict' of duplicate keys in key/value dictionaries (RFC 8152)
• Preferred serialization

Unsupported features from RFC 8949

Implementing "deterministic encoding" per spec in RFC 8949 is mostly done. The only missing piece is lexicographical sorting of binary keys in CBOR dictionaries. This is potentially a prohibitively expensive encoding operation, as all keys must be encoded and sorted before the map is added to the resulting CBOR value output. With the current encoder, the most obvious, clearly-readable path is to iterate over all the keys before accessing the data, which would be a second iteration over the finalized sorted array of keys.

If anyone has ideas, input, or would like to contribute code to this effort, please do. This is the only missing piece from RFC 8949 of which we are currently aware.

Contributing code and issues

Issues

Please report bugs! I maintain this library in my free time, so please do not expect immediate turn-around for your bug.

Feel free to drop an issue abotu a missing feature of CBOR. Please reference the appropriate RFC number and explain how you believe the library should behave.

No matter why you're opening an issue, please provide:

• The environment OS
• The JavaScript runtime, and version
• An example working piece of code that reproduces your issue.

Code

This project accepts pull requests! If you have a fix for a bug or an implementation of a CBOR feature, bring it. You'll be credited here in the readme.

Ground rules:

1. Please adhere to the Contributor Covenant v2.1
2. Use vanilla TypeScript; no explicit Node, Deno, or browser references permitted except for tests
3. Reference an open issue; if one does not exist, please create one

If you have a history of commits and would like maintianer status to help triage issues and deploy code faster, please open an issue requesting access. Don't be put off by the fact that this codebase targets Deno. It is compiled and released for browser and Node; Deno is not a hard prerequisite for contributing (but it does help).

Contributors

• Patrick Gansterer (paroga): Original author
• Aaron Huggins (aaronhuggins): Fork maintainer
• Maik Riechert (letmaik): Added support for Node
• Sangwhan Moon (cynthia): Performance improvements
• Kevin Wooten (kdubb): Added TaggedValue feature
• Glenn Engel (glenne): Support for Typed Arrays
• Matt Vollrath (mvollrath): Optimized byte array encoding
• Sami Vaarala (svaarala): Fixed bug in codepoint handling
• Timothy Cyrus (tcyrus): Various quality improvements
• Benny Neugebauer (bennycode): Various quality improvements
• Tyler Young: Various quality improvements