cbor-redux

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

GitHub last commit GitHub contributors npm collaborators GitHub top language
npm bundle size GitHub code size in bytes npm NPM
Quality Gate Status Maintainability Rating Security Rating Coverage

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 8949)
  • 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
  • “deterministic encoding” per spec in RFC 8949

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