JavaScript CBOR-LD Processor

A JavaScript CBOR-LD Process for Web browsers and Node.js apps.

Table of Contents

• Background
• Install
• Usage
• API
• Contribute
• Commercial Support
• License

Background

This library provides a CBOR-LD Processor for Web browsers and Node.js applications.

Install

This software requires and supports maintained recent versions of Node.js and browsers. Updates may remove support for older unmaintained platform versions. Please use dependency version lock files and testing to ensure compatibility with this software.

NPM

npm install @digitalbazaar/cborld

Git

To install locally (for development):

git clone https://github.com/digitalbazaar/cborld.git
cd cborld
npm install

Usage

This library provides two primary functions for encoding and decoding CBOR-LD data.

Encode to CBOR-LD

To encode a JSON-LD document as CBOR-LD:

import {encode} from '@digitalbazaar/cborld';

const jsonldDocument = {
  '@context': 'https://www.w3.org/ns/activitystreams',
  type: 'Note',
  summary: 'CBOR-LD',
  content: 'CBOR-LD is awesome!'
};

// encode a JSON-LD Javascript object into CBOR-LD bytes
// Note: user must provide their own JSON-LD `documentLoader`
const cborldBytes = await encode({
  jsonldDocument,
  documentLoader,
  // use standard compression (set to `0` to use no compression)
  registryEntryId: 1
});

To decode a CBOR-LD document to JSON-LD:

import {decode} from '@digitalbazaar/cborld';

// get the CBOR-LD bytes
const cborldBytes = await fs.promises.readFile('out.cborld');

// decode the CBOR-LD bytes into a Javascript object
// Note: user must provide their own JSON-LD `documentLoader`
const jsonldDocument = await cborld.decode({cborldBytes, documentLoader});

API

NOTE: Please check encode.js and decode.js for the latest API options.

Functions

encode(options) ⇒ Uint8Array

Encodes a given JSON-LD document into a CBOR-LD byte array.

decode(options) ⇒ object

Decodes a CBOR-LD byte array into a JSON-LD document.

Typedefs

diagnosticFunction : function

A diagnostic function that is called with diagnostic information. Typically set to console.log when debugging.

documentLoaderFunction ⇒ string

Fetches a resource given a URL and returns it as a string.

encode(options) ⇒ Promise<Uint8Array>

Encodes a given JSON-LD document into a CBOR-LD byte array.

Kind: global function Returns: Uint8Array - - The encoded CBOR-LD bytes.

Param	Type	Description
options	object	The options to use when encoding to CBOR-LD.
options.jsonldDocument	object	The JSON-LD Document to convert to CBOR-LD bytes.
options.documentLoader	documentLoaderFunction	The document loader to use when resolving JSON-LD Context URLs.
[options.appContextMap]	Map	A map of JSON-LD Context URLs and their encoded CBOR-LD values (must be values greater than 32767 (0x7FFF)).
[options.appTermMap]	Map	A map of JSON-LD terms and their associated CBOR-LD term codecs.
[options.diagnose]	diagnosticFunction	A function that, if provided, is called with diagnostic information.

decode(options) ⇒ Promise<object>

Decodes a CBOR-LD byte array into a JSON-LD document.

Kind: global function Returns: object - - The decoded JSON-LD Document.

Param	Type	Description
options	object	The options to use when decoding CBOR-LD.
options.cborldBytes	Uint8Array	The encoded CBOR-LD bytes to decode.
options.documentLoader	function	The document loader to use when resolving JSON-LD Context URLs.
[options.appContextMap]	Map	A map of JSON-LD Context URLs and their associated CBOR-LD values. The values must be greater than 32767 (0x7FFF)).
[options.appTermMap]	Map	A map of JSON-LD terms and their associated CBOR-LD term codecs.
[options.diagnose]	diagnosticFunction	A function that, if provided, is called with diagnostic information.

diagnosticFunction : function

A diagnostic function that is called with diagnostic information. Typically set to console.log when debugging.

Kind: global typedef

Param	Type	Description
message	string	The diagnostic message.

documentLoaderFunction ⇒ string

Fetches a resource given a URL and returns it as a string.

Kind: global typedef Returns: string - The resource associated with the URL as a string.

Param	Type	Description
url	string	The URL to retrieve.

Examples:

TBD

Contribute

Please follow the existing code style.

PRs accepted.

If editing the README, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com

License

BSD-3-Clause © Digital Bazaar