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

• Browsers and Node.js 18+ are supported.

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';
import { JsonLdDocumentLoader } from 'jsonld-document-loader';

// Establish JSON-LD context
const CONTEXT_URL = 'https://example.com/my-context/v1'; 
const CONTEXT = {
  '@context': {
    ex: 'https://example.com/my-context/v1#', 
    type: '@type', 
    Example: 'ex:Example', 
    label: 'ex:label', 
    content: 'ex:content'
  }
};
const loader = new JsonLdDocumentLoader();
loader.addStatic(CONTEXT_URL, CONTEXT)
const myLoader = loader.build();

const myDocument = {
  '@context': CONTEXT_URL,
  type: 'Note',
  label: 'CBOR-LD',
  content: 'CBOR-LD is awesome!'
};

// encode a JSON-LD Javascript object into CBOR-LD bytes
const outputCborldBytes = await encode({ 
  jsonldDocument: myDocument, 
  documentLoader: myLoader 
});

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

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

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

// decode the CBOR-LD bytes into a Javascript object
// Note: reuses JSON-LD `myLoader` from encode example above
const outputJsonldDocument = await cborld.decode({
  cborldBytes: inputCcborldBytes,
  documentLoader: myLoader
});

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: mailto:support@digitalbazaar.com

License

BSD-3-Clause © Digital Bazaar