logo
CBOR.js - JavaScript API

Table of Contents

n/a1.  Introduction
n/a2.  CBOR Wrapper Objects
n/a2.1.  CBOR.Int
n/a2.1.1.  CBOR.Int Methods
n/a2.1.1.1.  getInt53()
n/a2.1.1.2.  getInt8()
n/a2.1.1.3.  getUint8()
n/a2.1.1.4.  getInt16()
n/a2.1.1.5.  getUint16()
n/a2.1.1.6.  getInt32()
n/a2.1.1.7.  getUint32()
n/a2.1.1.8.  getInt64()
n/a2.1.1.9.  getUint64()
n/a2.1.1.10.  getBigInt()
n/a2.2.  CBOR.BigInt
n/a2.2.1.  CBOR.BigInt Methods
n/a2.2.1.1.  getInt64()
n/a2.2.1.2.  getUint64()
n/a2.2.1.3.  getBigInt()
n/a2.3.  CBOR.Float
n/a2.3.1.  CBOR.Float Methods
n/a2.3.1.1.  getFloat16()
n/a2.3.1.2.  getFloat32()
n/a2.3.1.3.  getFloat64()
n/a2.3.1.4.  CBOR.Float.createExtendedFloat()
n/a2.3.1.5.  getExtendedFloat64()
n/a2.3.2.  CBOR.Float Properties
n/a2.3.2.1.  length
n/a2.4.  CBOR.NonFinite
n/a2.4.1.  CBOR.NonFinite Methods
n/a2.4.1.1.  getNonFinite()
n/a2.4.1.2.  getNonFinite64()
n/a2.4.1.3.  isNaN()
n/a2.4.1.4.  isSimple()
n/a2.4.1.5.  getSign()
n/a2.4.1.6.  setSign()
n/a2.4.1.7.  CBOR.NonFinite.createPayload()
n/a2.4.1.8.  getPayload()
n/a2.4.2.  CBOR.NonFinite Properties
n/a2.4.2.1.  length
n/a2.5.  CBOR.String
n/a2.5.1.  CBOR.String Methods
n/a2.5.1.1.  getString()
n/a2.6.  CBOR.Bytes
n/a2.6.1.  CBOR.Bytes Methods
n/a2.6.1.1.  getBytes()
n/a2.7.  CBOR.Boolean
n/a2.7.1.  CBOR.Boolean Methods
n/a2.7.1.1.  getBoolean()
n/a2.8.  CBOR.Null
n/a2.9.  CBOR.Array
n/a2.9.1.  CBOR.Array Methods
n/a2.9.1.1.  add()
n/a2.9.1.2.  get()
n/a2.9.1.3.  remove()
n/a2.9.1.4.  update()
n/a2.9.1.5.  insert()
n/a2.9.1.6.  toArray()
n/a2.9.1.7.  encodeAsSequence()
n/a2.9.2.  CBOR.Array Properties
n/a2.9.2.1.  length
n/a2.10.  CBOR.Map
n/a2.10.1.  CBOR.Map Methods
n/a2.10.1.1.  set()
n/a2.10.1.2.  setDynamic()
n/a2.10.1.3.  merge()
n/a2.10.1.4.  update()
n/a2.10.1.5.  get()
n/a2.10.1.6.  getConditionally()
n/a2.10.1.7.  containsKey()
n/a2.10.1.8.  remove()
n/a2.10.1.9.  getKeys()
n/a2.10.1.10.  setSortingMode()
n/a2.10.2.  CBOR.Map Properties
n/a2.10.2.1.  length
n/a2.11.  CBOR.Tag
n/a2.11.1.  CBOR.Tag Methods
n/a2.11.1.1.  getTagNumber()
n/a2.11.1.2.  get()
n/a2.11.2.  CBOR.Tag Properties
n/a2.11.2.1.  cotxId
n/a2.11.2.2.  cotxObject
n/a2.12.  CBOR.Simple
n/a2.12.1.  CBOR.Simple Methods
n/a2.12.1.1.  getSimple()
n/a3.  Time Objects
n/a3.1.  getDateTime()
n/a3.2.  getEpochTime()
n/a4.  Common Wrapper Methods
n/a4.1.  encode()
n/a4.2.  clone()
n/a4.3.  equals()
n/a4.4.  toDiag()
n/a4.5.  toString()
n/a4.6.  isNull()
n/a4.7.  checkForUnread()
n/a4.8.  scan()
n/a5.  Decoding CBOR
n/a5.1.  CBOR.decode()
n/a5.2.  CBOR.initDecoder()
n/a5.3.  Decoder.decodeWithOptions()
n/a5.4.  Decoder.getByteCount()
n/a5.5.  CBOR.diagDecode()
n/a5.6.  CBOR.diagDecodeSequence()
n/a6.  Utility Methods
n/a6.1.  CBOR.addArrays()
n/a6.2.  CBOR.compareArrays()
n/a6.3.  CBOR.toHex()
n/a6.4.  CBOR.fromHex()
n/a6.5.  CBOR.toBase64Url()
n/a6.6.  CBOR.fromBase64Url()
n/a6.7.  CBOR.toBigInt()
n/a6.8.  CBOR.fromBigInt()
n/a6.9.  CBOR.createDateTime()
n/a6.10.  CBOR.createEpochTime()
n/a7.  JavaScript Number Considerations
n/a7.1.  Integer Numbers
n/a7.2.  Floating-Point Numbers
n/a8.  Diagnostic Notation
n/a9.  Deterministic Encoding
n/a10.  Using the CBOR API
n/a10.1.  Encode CBOR Data
n/a10.2.  Decode CBOR Data
n/a10.3.  Decode Variant CBOR Data
n/a10.4.  Decode CBOR Diagnostic Notation
n/a10.5.  Encode CBOR Sequence
n/a10.6.  Decode CBOR Sequence
n/a11.  Error Handling
n/a12.  Version

1.  Introduction

This document describes a JavaScript API for encoding and decoding CBOR [RFC8949link] data using the [CBOR::Corelink] cross platform profile. The API loosely mimics the "JSON" object by exposing a single global object, unsurprisingly named "CBOR". To minimize the need for application developers having detailed knowledge of CBOR, the CBOR.js API provides a set of high-level wrapper objects. The wrapper objects are used for encoding CBOR data items, as well as being the result of CBOR decoding. The CBOR.js API provides some specific features including:

Note: in this specification CBOR data items are subsequently referred to as "CBOR objects".

Although this document describes a JavaScript API, it may also serve as a guide for CBOR::Core implementations for other software platforms.

2.  CBOR Wrapper Objects

This section describes the wrapper objects and their specific methods. Note that using the "new" operator with a wrapper object is flagged as an error. The following table lists the wrapper objects and their relation to the CBOR objects (here expressed in CDDL [RFC8610link] notation) supported by this specification:
CDDLWrapper ObjectJavaScriptNotes
int CBOR.Int Number 1
bigint CBOR.BigInt BigInt 1
float CBOR.Float Number 2, 3
CBOR.NonFinite BigInt 3
bstr CBOR.Bytes Uint8Array
tstr CBOR.String String
bool CBOR.Boolean Boolean
null CBOR.Null
[] CBOR.Array
{} CBOR.Map
#6.n CBOR.Tag
#7.n CBOR.Simple
  1. Also see Integer Numbers.
  2. Also see Floating-Point Numbers.
  3. Also see Non-Finite Numbers.

The wrapper concept adds strict type checking to the API. That is, if an application expects a CBOR integer and calls getInt32(), a CborException will be thrown if the referenced object is not an instance of CBOR.Int or if the CBOR integer is out of range for signed 32-bit objects.

Also see Common Wrapper Methods and Time Objects.
2.1.  CBOR.Int
SyntaxCBOR.Int(value)
DescriptionConstructor. Creates a CBOR integer object.
Also see Integer Numbers.
ParameterTypeDescription
valueNumberInteger to be wrapped.
ReturnsDescription
CBOR.IntObject.
2.1.1.  CBOR.Int Methods
2.1.1.1.  getInt53()
SyntaxgetInt53()
DescriptionGet CBOR integer.
If the return value is outside the range Number.MIN_SAFE_INTEGER (-9007199254740991) to Number.MAX_SAFE_INTEGER (9007199254740991), a CborException is thrown.
Also see getBigInt().
Since 53-bit integers are specific to JavaScript, this method should be used with caution in cross-platform scenarios.
ReturnsDescription
NumberDecoded integer.
2.1.1.2.  getInt8()
SyntaxgetInt8()
DescriptionGet CBOR integer.
If the return value is outside the range -0x80 to 0x7f, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.3.  getUint8()
SyntaxgetUint8()
DescriptionGet CBOR integer.
If the return value is outside the range 0 to 0xff, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.4.  getInt16()
SyntaxgetInt16()
DescriptionGet CBOR integer.
If the return value is outside the range -0x8000 to 0x7fff, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.5.  getUint16()
SyntaxgetUint16()
DescriptionGet CBOR integer.
If the return value is outside the range 0 to 0xffff, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.6.  getInt32()
SyntaxgetInt32()
DescriptionGet CBOR integer.
If the return value is outside the range -0x80000000 to 0x7fffffff, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.7.  getUint32()
SyntaxgetUint32()
DescriptionGet CBOR integer.
If the return value is outside the range 0 to 0xffffffff, a CborException is thrown.
ReturnsDescription
NumberDecoded integer.
2.1.1.8.  getInt64()
SyntaxgetInt64()
DescriptionGet CBOR integer.
If the return value is outside the range -0x8000000000000000 to 0x7fffffffffffffff, a CborException is thrown.
ReturnsDescription
BigIntDecoded big integer.
2.1.1.9.  getUint64()
SyntaxgetUint64()
DescriptionGet CBOR integer.
If the return value is outside the range 0 to 0xffffffffffffffff, a CborException is thrown.
ReturnsDescription
BigIntDecoded big integer.
2.1.1.10.  getBigInt()
SyntaxgetBigInt()
DescriptionGet CBOR integer of any size.
Also see Integer Numbers.
ReturnsDescription
BigIntDecoded big integer.
2.2.  CBOR.BigInt
SyntaxCBOR.BigInt(value)
DescriptionConstructor. Creates a CBOR big integer object.
Also see Integer Numbers.
ParameterTypeDescription
valueBigIntBig integer to be wrapped.
ReturnsDescription
CBOR.BigIntObject.
2.2.1.  CBOR.BigInt Methods
2.2.1.1.  getInt64()
SyntaxgetInt64()
DescriptionGet CBOR integer.
If the return value is outside the range -0x8000000000000000 to 0x7fffffffffffffff, a CborException is thrown.
ReturnsDescription
BigIntDecoded big integer.
2.2.1.2.  getUint64()
SyntaxgetUint64()
DescriptionGet CBOR integer.
If the return value is outside the range 0 to 0xffffffffffffffff, a CborException is thrown.
ReturnsDescription
BigIntDecoded big integer.
2.2.1.3.  getBigInt()
SyntaxgetBigInt()
DescriptionGet CBOR integer of any size.
Also see Integer Numbers.
ReturnsDescription
BigIntDecoded big integer.
2.3.  CBOR.Float
SyntaxCBOR.Float(value)
DescriptionConstructor. Creates a CBOR float object.
For supporting NaN and Infinity, also see Non-Finite Numbers.
ParameterTypeDescription
valueNumberFloating-point number to be wrapped.
ReturnsDescription
CBOR.FloatObject.
2.3.1.  CBOR.Float Methods
2.3.1.1.  getFloat16()
SyntaxgetFloat16()
DescriptionGet CBOR floating-point value.
If the CBOR object is not a 16-bit IEEE 754 item, a CborException is thrown.
ReturnsDescription
NumberDecoded floating-point number.
2.3.1.2.  getFloat32()
SyntaxgetFloat32()
DescriptionGet CBOR floating-point value.
If the CBOR object is not a 16-bit or 32-bit IEEE 754 item, a CborException is thrown.
ReturnsDescription
NumberDecoded floating-point number.
2.3.1.3.  getFloat64()
SyntaxgetFloat64()
DescriptionGet CBOR floating-point value.
ReturnsDescription
NumberDecoded floating-point number.
2.3.1.4.  CBOR.Float.createExtendedFloat()
SyntaxCBOR.Float.createExtendedFloat(value)
DescriptionConstructor. Creates a CBOR float object.
Unlike CBOR.Float(), this method also supports one of the non-finite values, Number.NaN, Number.POSITIVE_INFINITY, and Number.NEGATIVE_INFINITY.
ParameterTypeDescription
valueNumberFloating-point number to be wrapped.
ReturnsDescription
CBOR.WrapperInstantiated CBOR.Float or CBOR.NonFinite object.
2.3.1.5.  getExtendedFloat64()
SyntaxgetExtendedFloat64()
DescriptionGet CBOR floating-point value.
Note that this method makes it transparent for applications if the returned value is a "regular" float, or one of the non-finite values, Number.NaN, Number.POSITIVE_INFINITY, or Number.NEGATIVE_INFINITY.
ReturnsDescription
NumberDecoded floating-point number.
2.3.2.  CBOR.Float Properties
2.3.2.1.  length
NameTypeDescription
lengthNumberLength in bytes of the underlying CBOR IEEE 754 type.
2.4.  CBOR.NonFinite
SyntaxCBOR.NonFinite(value)
DescriptionConstructor. Creates a CBOR non-finite float object.
The argument must be a valid 16, 32, or 64-bit non-finite number in IEEE 754 encoding.
ParameterTypeDescription
valueBigIntNon-finite floating-point number to be wrapped.
ReturnsDescription
CBOR.NonFiniteObject.
2.4.1.  CBOR.NonFinite Methods
2.4.1.1.  getNonFinite()
SyntaxgetNonFinite()
DescriptionGet actual non-finite object (value).
This method returns the value of a non-finite object. The value is provided in the most compact form based on CBOR serialization rules.
ReturnsDescription
BigIntDecoded non-finite number as a BigInt.
2.4.1.2.  getNonFinite64()
SyntaxgetNonFinite64()
DescriptionGet expanded non-finite object (value).
This method returns the value of a non-finite object after it has been expanded to 64 bits. That is, a received 7c01 will be returned as 7ff0040000000000.
ReturnsDescription
BigIntDecoded non-finite number as a BigInt.
2.4.1.3.  isNaN()
SyntaxisNaN()
DescriptionCheck if non-finite object is a NaN.
This method returns true for all conformant NaN variants, else false is returned.
ReturnsDescription
BooleanResult.
2.4.1.4.  isSimple()
SyntaxisSimple()
DescriptionCheck if non-finite object is simple.
This method returns true if the non-finite object is a Number.NaN, Number.POSITIVE_INFINITY, or Number.NEGATIVE_INFINITY, else false is returned.
ReturnsDescription
BooleanResult.
2.4.1.5.  getSign()
SyntaxgetSign()
DescriptionGet sign bit of non-finite object.
This method returns true if the sign bit is 1, else false is returned.
Also see setSign().
ReturnsDescription
BooleanResult.
2.4.1.6.  setSign()
SyntaxsetSign(sign)
DescriptionSet sign bit of non-finite object.
The sign bit is expressed as a boolean. true = 1, false = 0.
Also see getSign().
ParameterTypeDescription
signBooleanSign bit.
ReturnsDescription
thisCurrent object.
2.4.1.7.  CBOR.NonFinite.createPayload()
SyntaxCBOR.NonFinite.createPayload(payload)
DescriptionCreates a payload object.
For details turn to Payload option.
ParameterTypeDescription
payloadBigIntPayload data.
ReturnsDescription
CBOR.NonFiniteInstantiated CBOR.NonFinite object.
2.4.1.8.  getPayload()
SyntaxgetPayload()
Description Get payload data.
This method is the "consumer" counterpart to CBOR.NonFinite.createPayload().
ReturnsDescription
BigIntPayload.
2.4.2.  CBOR.NonFinite Properties
2.4.2.1.  length
NameTypeDescription
lengthNumberLength in bytes of the underlying CBOR IEEE 754 type.
2.5.  CBOR.String
SyntaxCBOR.String(textString)
DescriptionConstructor. Creates a CBOR text-string (tstr) object.
ParameterTypeDescription
textStringStringString to be wrapped.
ReturnsDescription
CBOR.StringObject.
2.5.1.  CBOR.String Methods
2.5.1.1.  getString()
SyntaxgetString()
DescriptionGet CBOR text-string.
ReturnsDescription
StringDecoded text-string.
2.6.  CBOR.Bytes
SyntaxCBOR.Bytes(byteString)
DescriptionConstructor. Creates a CBOR byte-string (bstr) object.
ParameterTypeDescription
byteStringUint8ArrayBinary data to be wrapped.
ReturnsDescription
CBOR.BytesObject.
2.6.1.  CBOR.Bytes Methods
2.6.1.1.  getBytes()
SyntaxgetBytes()
DescriptionGet CBOR byte-string.
ReturnsDescription
Uint8ArrayDecoded byte-string.
2.7.  CBOR.Boolean
SyntaxCBOR.Boolean(value)
DescriptionConstructor. Creates a CBOR boolean (bool) object.
ParameterTypeDescription
valueBooleanBoolean to be wrapped.
ReturnsDescription
CBOR.BooleanObject.
2.7.1.  CBOR.Boolean Methods
2.7.1.1.  getBoolean()
SyntaxgetBoolean()
DescriptionGet CBOR boolean.
ReturnsDescription
BooleanDecoded boolean.
2.8.  CBOR.Null
SyntaxCBOR.Null()
DescriptionConstructor. Creates a CBOR null object. Also see isNull().
ReturnsDescription
CBOR.NullObject.
2.9.  CBOR.Array
SyntaxCBOR.Array()
DescriptionConstructor. Creates an empty CBOR array object.
ReturnsDescription
CBOR.ArrayObject.
2.9.1.  CBOR.Array Methods
2.9.1.1.  add()
Syntaxadd(object)
DescriptionAdd CBOR object to the array.
ParameterTypeDescription
objectCBOR.WrapperObject to be appended to the array.
ReturnsDescription
thisCurrent object.
2.9.1.2.  get()
Syntaxget(index)
DescriptionGet CBOR object at a specific position in the array.
ParameterTypeDescription
indexNumberArray index (0..length-1).
ReturnsDescription
CBOR.WrapperRetrieved object.
2.9.1.3.  remove()
Syntaxremove(index)
DescriptionRemove CBOR object at a specific position in the array.
ParameterTypeDescription
indexNumberArray index (0..length-1).
ReturnsDescription
CBOR.WrapperPrevious object.
2.9.1.4.  update()
Syntaxupdate(index, object)
DescriptionUpdate CBOR object at a specific position in the array.
ParameterTypeDescription
indexNumberArray index (0..length-1).
objectCBOR.WrapperUpdate object.
ReturnsDescription
CBOR.WrapperPrevious object.
2.9.1.5.  insert()
Syntaxinsert(index, object)
DescriptionInsert CBOR object before an object at a specific position in the array.
ParameterTypeDescription
indexNumberArray index (0..length).
If index is equal to length, object is appended.
objectCBOR.WrapperUpdate object.
ReturnsDescription
thisCurrent object.
2.9.1.6.  toArray()
SyntaxtoArray()
DescriptionCopy array.
ReturnsDescription
[CBOR.Wrapper...]JavaScript array holding a copy of current CBOR.Wrapper objects.
2.9.1.7.  encodeAsSequence()
SyntaxencodeAsSequence()
DescriptionReturn the objects in the array as a CBOR sequence using Deterministic Encoding.
ReturnsDescription
Uint8ArrayCBOR encoded data.
2.9.2.  CBOR.Array Properties
2.9.2.1.  length
NameTypeDescription
lengthNumberNumber of objects in the array.
2.10.  CBOR.Map
SyntaxCBOR.Map()
DescriptionConstructor. Creates an empty CBOR map object.
ReturnsDescription
CBOR.MapObject.
2.10.1.  CBOR.Map Methods
2.10.1.1.  set()
Syntaxset(key, object)
DescriptionSet map entry. If key is already defined, a CborException is thrown.
Note: key order is of no importance since Deterministic Encoding performs the required map sorting automatically. Also see setSortingMode().
Note: this implementation presumes that key objects are immutable. That is, the following code will throw a CborException:
let key = CBOR.Array();
let map = CBOR.Map().set(key, CBOR.Int(5));
key.add(CBOR.String("data")); // Mutating key object
By defining key objects inline (chaining) or by preset variable declarations, key objects of any complexity can be used.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
objectCBOR.WrapperObject (value).
ReturnsDescription
thisCurrent object.
2.10.1.2.  setDynamic()
SyntaxsetDynamic(dynamic)
DescriptionSet map entries using a function or =>.
This method permits using chaining with dynamic or optional map elements. Consult test file dynamic.js for examples.
ParameterTypeDescription
dynamicfunction|=>Function or => operator with one parameter holding this.
ReturnsDescription
thisCurrent object.
2.10.1.3.  merge()
Syntaxmerge(map)
DescriptionMerge maps. Performs a set() operation for each member of the map argument.
ParameterTypeDescription
mapCBOR.MapCBOR map wrapper object.
ReturnsDescription
thisCurrent object.
2.10.1.4.  update()
Syntaxupdate(key, object, existing)
DescriptionUpdate map entry.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
objectCBOR.WrapperObject (value).
existingBooleanIf existing is true, key must be defined, else a CborException is thrown.
If existing is false, a map entry will be created for key if not already defined.
ReturnsDescription
CBOR.WrapperPrevious object. May be null.
2.10.1.5.  get()
Syntaxget(key)
DescriptionGet map entry. If key is undefined, a CborException is thrown.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
ReturnsDescription
CBOR.WrapperRetrieved object.
2.10.1.6.  getConditionally()
SyntaxgetConditionally(key, defaultObject)
DescriptionGet map entry conditionally.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
defaultObjectCBOR.WrapperObject to return if key is undefined.
Note: defaultObject may be null.
ReturnsDescription
CBOR.WrapperRetrieved or default object.
2.10.1.7.  containsKey()
SyntaxcontainsKey(key)
DescriptionCheck map for key presence.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
ReturnsDescription
Booleantrue or false.
2.10.1.8.  remove()
Syntaxremove(key)
DescriptionRemove map entry. If key is undefined, a CborException is thrown.
ParameterTypeDescription
keyCBOR.WrapperKey (name).
ReturnsDescription
CBOR.WrapperRemoved object (value).
2.10.1.9.  getKeys()
SyntaxgetKeys()
DescriptionGet map keys.
ReturnsDescription
[CBOR.Wrapper...]JavaScript array holding a copy of current key objects.
2.10.1.10.  setSortingMode()
SyntaxsetSortingMode(preSortedKeys)
DescriptionSet the sorting mode of the CBOR.Map() object during set() operations.
Typical usage:
let map = CBOR.Map().setSortingMode(true)
This method may be called multiple times which could be useful if you have a moderate set of unsorted meta data keys combined with a sorted large table-like set of keys. Note that this method has no effect on decoding operations.
ParameterTypeDescription
preSortedKeysBooleanIf true, keys must be provided in (CBOR wise) ascending order which can improve performance for maps having a huge number of keys. Improper key order causes a CborException to be thrown. By default, map keys are sorted internally.
ReturnsDescription
thisCurrent object.
2.10.2.  CBOR.Map Properties
2.10.2.1.  length
NameTypeDescription
lengthNumberNumber of map entries.
2.11.  CBOR.Tag
SyntaxCBOR.Tag(tagNumber, object)
DescriptionConstructor. Creates a CBOR tag object.
The CBOR tag constructor accepts any valid parameters but performs thorough syntax checks on tag 0 (CBOR date/time), tag 1 (CBOR epoch time), and tag 1010 [COTXlink].
ParameterTypeDescription
tagNumberBigIntTag number.
objectCBOR.WrapperObject to be wrapped in a tag.
ReturnsDescription
CBOR.TagObject.
2.11.1.  CBOR.Tag Methods
2.11.1.1.  getTagNumber()
SyntaxgetTagNumber()
DescriptionGet CBOR tag number.
ReturnsDescription
BigIntDecoded tag number.
2.11.1.2.  get()
Syntaxget()
DescriptionGet tagged CBOR object.
ReturnsDescription
CBOR.WrapperRetrieved object.
2.11.2.  CBOR.Tag Properties
2.11.2.1.  cotxId
NameTypeDescription
cotxIdStringCOTX [COTXlink] support: object ID string.
Only valid for COTX tags. See also getTagNumber().
2.11.2.2.  cotxObject
NameTypeDescription
cotxObjectCBOR.WrapperCOTX [COTXlink] support: wrapped object.
Only valid for COTX tags. See also getTagNumber().
2.12.  CBOR.Simple
SyntaxCBOR.Simple(value)
DescriptionConstructor. Creates a CBOR simple value object.
If value is outside the range 0-23 and 32-255, a CborException is thrown.
A primary use case for simple types in the range of 0-19 and 32-255, is serving as a limited set of unique and reserved labels (keys) in CBOR maps.
ParameterTypeDescription
valueNumberSimple value.
ReturnsDescription
CBOR.SimpleObject.
2.12.1.  CBOR.Simple Methods
2.12.1.1.  getSimple()
SyntaxgetSimple()
DescriptionGet simple value.
ReturnsDescription
NumberReturned simple value.

3.  Time Objects

Since CBOR lacks dedicated (native) time-objects, section 3.4.1 and 3.4.2 of CBOR [RFC8949link] define tag 0 and 1 for this purpose. CBOR.js provides built-in decoders for these tags (CBOR.Tag). That is, if the current object is a tag 0, it is sufficient calling getDateTime(). Note that these methods are also available without the tag construct.
3.1.  getDateTime()
SyntaxgetDateTime()
DescriptionGet DateTime object.
This method performs a getString(). The returned string is subsequently used to initiate a JavaScript Date object.
If not all of the following conditions are met, a CborException is thrown:
  • The underlying object is a CBOR.String.
  • The string matches the ISO date/time format described in section 5.6 of [RFC3339link].
  • The optional sub-second field (.nnn) features less than ten digits.
  • The date/time object is within the range "0000-01-01T00:00:00Z" to "9999-12-31T23:59:59Z".
ReturnsDescription
DateDate object
3.2.  getEpochTime()
SyntaxgetEpochTime()
DescriptionGet EpochTime object.
Depending on the type of the current object, this method performs a getInt53() or a getFloat64(). The returned number is subsequently used to initiate a JavaScript Date object.
If not all of the following conditions are met, a CborException is thrown:
  • The underlying object is a CBOR.Int or CBOR.Float.
  • The Epoch [TIMElink] object is within the range 0 ("1970-01-01T00:00:00Z") to 253402300799 ("9999-12-31T23:59:59Z").
ReturnsDescription
DateDate object

4.  Common Wrapper Methods

The CBOR wrapper objects support a set of common methods, described in this sub-section.
4.1.  encode()
Syntaxencode()
DescriptionEncode (aka "serialize") this object.
Note: this method always return CBOR data using Deterministic Encoding.
ReturnsDescription
Uint8ArrayCBOR encoded data.
4.2.  clone()
Syntaxclone()
DescriptionCreate a new instance of this object, initialized with the original CBOR content.
ReturnsDescription
CBOR.WrapperDeep copy of this object.
4.3.  equals()
Syntaxequals(object)
DescriptionCompare this object with another CBOR object.
The result is true if and only if object is not null and is a CBOR.Wrapper, and the associated binary encodings (as provided by encode()) are equivalent.
ParameterTypeDescription
objectCBOR.WrapperArgument to compare with.
ReturnsDescription
Booleantrue if this object is equal to object, otherwise false.
4.4.  toDiag()
SyntaxtoDiag(prettyPrint)
DescriptionRender this object in Diagnostic Notation. In similarity to encode(), this method always produce data in Deterministic Encoding, irrespective to how the data was created. Also see: toString().
If this object (as well as possible child objects), conforms to the subset of data types supported by JSON, this method can also be used to generate JSON data.
ParameterTypeDescription
prettyPrintBooleanIf prettyPrint is true, additional white space is inserted between individual objects in maps and arrays, to make the result easier to read.
ReturnsDescription
StringTextual version of the wrapped CBOR content.
4.5.  toString()
SyntaxtoString()
DescriptionRender this object in Diagnostic Notation. Equivalent to calling toDiag() with a true argument.
ReturnsDescription
StringTextual version of the wrapped CBOR content.
4.6.  isNull()
SyntaxisNull()
DescriptionCheck for CBOR null.
Note: if checkForUnread() is used, this object will only be regarded as "read" if it actually is a CBOR null item.
Also see CBOR.Null().
ReturnsDescription
BooleanReturns true if this object holds a CBOR null item, otherwise false is returned.
4.7.  checkForUnread()
SyntaxcheckForUnread()
Description Check if this object including possible child objects has been read (like calling getInt53()). If not all of the associated objects have been read, a CborException is thrown.
The purpose of this method is to detect possible misunderstandings between parties using CBOR based protocols. Together with the strict type checking performed by the CBOR.js API, a programmatic counterpart to schema-based decoding can be achieved.
Note that array get(), map get(), and tag get() only locate objects, and thus do not count as "read".
To cope with elements that are redundant, scan() can be used:
let array = CBOR.diagDecode(`[3, {}]`);
let operation = array.get(0).getInt8();
array.get(1).scan();    // mark array[1] as read
array.checkForUnread();
ReturnsDescription
thisCurrent object.
4.8.  scan()
Syntaxscan()
DescriptionScan this object as well as possible child objects in order to make them appear as "read". This is only meaningful in conjunction with checkForUnread().
ReturnsDescription
thisCurrent object.

5.  Decoding CBOR

CBOR decoding comes in two flavors, binary and Diagnostic Notation. Both decoders return the result as CBOR wrapper objects. This section lists the decoder methods. Also see encode().
5.1.  CBOR.decode()
SyntaxCBOR.decode(cbor)
DescriptionDecode (aka "deserialize") CBOR object.
This method is equivalent to:
CBOR.initDecoder(cbor, 0).decodeWithOptions()
Unsupported or malformed CBOR data cause a CborException to be thrown.
ParameterTypeDescription
cborUint8ArrayCBOR binary data holding exactly one CBOR object.
ReturnsDescription
CBOR.WrapperObject.
5.2.  CBOR.initDecoder()
SyntaxCBOR.initDecoder(cbor, options)
DescriptionCreate a customized CBOR decoder. This decoding method presumes that the actual decoding is performed by one or more (for sequences only) calls to Decoder.decodeWithOptions().
Note that irrespective of options, the decoder maintains parsed data in the form required for Deterministic Encoding.
ParameterTypeDescription
cborUint8ArrayThe CBOR data (bytes) to be decoded.
optionsNumberThe decoder options. Multiple options can be combined using the binary OR-operator ("|"). A zero (0) sets the decoder default mode. The options are defined by the following constants:
CBOR.SEQUENCE_MODE:
If the CBOR.SEQUENCE_MODE option is defined, the following apply:
  • The decoder returns after having decoded a single CBOR object, while preparing for the next object.
  • If no data is found (EOF), null is returned (empty sequences are permitted).
Note that data that has not yet been decoded, is not verified for correctness.
CBOR.LENIENT_MAP_DECODING:
By default, the decoder requires that CBOR maps conform to the Deterministic Encoding rules.
The CBOR.LENIENT_MAP_DECODING option makes the decoder accept CBOR maps with arbitrary key ordering. Note that duplicate keys still cause a CborException to be thrown.
CBOR.LENIENT_NUMBER_DECODING:
By default, the decoder requires that CBOR numbers conform to the Deterministic Encoding rules.
The CBOR.LENIENT_NUMBER_DECODING option makes the decoder accept different representations of CBOR int/bigint and float objects, only limited by [RFC8949link].
ReturnsDescription
DecoderDecoder object to be used with Decoder.decodeWithOptions().
5.3.  Decoder.decodeWithOptions()
SyntaxDecoder.decodeWithOptions()
DescriptionDecode CBOR data with options.
Unsupported or malformed CBOR data cause a CborException to be thrown.
ReturnsDescription
CBOR.WrapperObject or null (for EOF sequences only).
5.4.  Decoder.getByteCount()
SyntaxDecoder.getByteCount()
DescriptionGet decoder byte count.
This is equivalent to the position of the next item to be read.
ReturnsDescription
NumberThe number of bytes read so far.
5.5.  CBOR.diagDecode()
SyntaxCBOR.diagDecode(cborText)
DescriptionDecode a CBOR object provided in Diagnostic Notation. Also see CBOR.diagDecodeSequence().
This method always returns CBOR data using Deterministic Encoding.
This method can also be used for decoding JSON data.
ParameterTypeDescription
cborTextStringCBOR in textual format.
ReturnsDescription
CBOR.WrapperObject.
5.6.  CBOR.diagDecodeSequence()
SyntaxCBOR.diagDecodeSequence(cborText)
DescriptionDecode CBOR objects provided in Diagnostic Notation. Unlike CBOR.diagDecode(), this method also accepts CBOR sequences, using a comma character (',') as a separator.
Note: empty sequences are permitted.
ParameterTypeDescription
cborTextStringCBOR in textual format.
ReturnsDescription
[CBOR.Wrapper...]JavaScript array holding zero or more objects.

6.  Utility Methods

The CBOR.js implementation supports a set of utility methods.
6.1.  CBOR.addArrays()
SyntaxCBOR.addArrays(a, b)
DescriptionAdd two arrays.
ParameterTypeDescription
aUint8ArrayFirst array.
bUint8ArraySecond array.
ReturnsDescription
Uint8ArrayConcatenation of array a and b.
6.2.  CBOR.compareArrays()
SyntaxCBOR.compareArrays(a, b)
DescriptionCompare two arrays lexicographically.
ParameterTypeDescription
aUint8ArrayFirst array.
bUint8ArraySecond array.
ReturnsDescription
NumberIf a and b are identical, 0 is retuned. If a > b, a positive number is returned. If a < b, a negative number is returned.
6.3.  CBOR.toHex()
SyntaxCBOR.toHex(byteArray)
DescriptionEncode binary string to hexadecimal.
ParameterTypeDescription
byteArrayUint8ArrayZero or more bytes to be encoded.
ReturnsDescription
StringHexadecimal encoded data.
6.4.  CBOR.fromHex()
SyntaxCBOR.fromHex(hexString)
DescriptionDecode hexadecimal data into binary.
ParameterTypeDescription
hexStringStringString with zero or more hexadecimal pairs. Each pair represents one byte.
ReturnsDescription
Uint8ArrayThe resulting binary (bytes).
6.5.  CBOR.toBase64Url()
SyntaxCBOR.toBase64Url(byteArray)
DescriptionEncode binary string to base64Url.
ParameterTypeDescription
byteArrayUint8ArrayZero or more bytes to be encoded.
ReturnsDescription
StringBase64Url encoded data.
6.6.  CBOR.fromBase64Url()
SyntaxCBOR.fromBase64Url(base64)
DescriptionDecode base64Url encoded data into binary. Note that this method is permissive; it accepts base64 encoded data as well as data with or without '=' padding.
ParameterTypeDescription
base64StringString in base64Url notation. The string may be empty.
ReturnsDescription
Uint8ArrayThe resulting binary (bytes).
6.7.  CBOR.toBigInt()
SyntaxCBOR.toBigInt(byteArray)
DescriptionConvert binary string to BigInt.
ParameterTypeDescription
byteArrayUint8ArrayZero or more bytes representing an unsigned number.
ReturnsDescription
BigIntResulting BigInt number.
6.8.  CBOR.fromBigInt()
SyntaxCBOR.fromBigInt(value)
DescriptionConvert BigInt into binary string.
ParameterTypeDescription
valueBigIntValue to be converted must be greater or equal to zero.
ReturnsDescription
Uint8ArrayThe resulting binary (one or more bytes).
6.9.  CBOR.createDateTime()
SyntaxCBOR.createDateTime(instant, millis, utc)
DescriptionCreate DateTime object.
This method creates a date/time string in the ISO format described in section 5.6 of [RFC3339link]. The string is subsequently wrapped in a CBOR.String object.
If the instant object is outside the range "0000-01-01T00:00:00Z" to "9999-12-31T23:59:59Z", a CborException is thrown.
If millis is true the date/time string will feature milliseconds (.nnn) as well.
Sample code:
let iso = CBOR.createDateTime(new Date(), true, false);
console.log(iso.toString());
"2025-12-05T13:55:42.418+01:00"
Also see getDateTime().
ParameterTypeDescription
instantDateTime source object.
millisBooleanIf millis is true, the milliseconds of the instant object will be featured in the created time object. Note: if the millisecond part of the instant object is zero, millis is considered to be false.
If millis is false, the millisecond part of the instant object will not be used, but may after rounding, add a second to the created time object.
utcBooleanIf utc is true, the UTC time zone (denoted by a terminating Z) will be used, else the local time followed by the UTC offset (±hh:mm) will be used.
ReturnsDescription
CBOR.StringWrapper holding a DateTime object.
6.10.  CBOR.createEpochTime()
SyntaxCBOR.createEpochTime(instant, millis)
DescriptionCreate EpochTime object.
This method creates an Epoch [TIMElink] time stamp.
If the instant object is outside the range "1970-01-01T00:00:00Z" to "9999-12-31T23:59:59Z", a CborException is thrown.
If millis is true a CBOR.Float object holding seconds with a milliseconds fraction will be created, else a CBOR.Int object holding seconds will be created.
Sample code:
let epoch = CBOR.createEpochTime(new Date(), false);
console.log(epoch.toString());
1764939916
Also see getEpochTime().
ParameterTypeDescription
instantDateTime source object.
millisBooleanIf millis is true, the milliseconds of the instant object will be featured in the created time object. Note: if the millisecond part of the instant object is zero, millis is considered to be false.
If millis is false, the millisecond part of the instant object will not be used, but may after rounding, add a second to the created time object.
ReturnsDescription
CBOR.WrapperWrapper holding an EpochTime object.

7.  JavaScript Number Considerations

Since JavaScript natively only supports Number (backed by 64-bit IEEE 754 floating-point data), and BigInt (offering unlimited integers), it is important to understand how these number types are mapped to CBOR which offers two variants of integers and three variants of floating-point types.
7.1.  Integer Numbers
Due to the Number.MAX_SAFE_INTEGER limitation, CBOR protocols using integer objects where the magnitude may exceed 9007199254740991 (253-1), must for such objects turn to BigInt, otherwise run-time errors may occur.

Note that in all places in the CBOR.js API where an integer in the form of a JavaScript Number is expected, Number.isInteger(value) must be true, else a CborException will be thrown.

Note that selecting between CBOR.BigInt or CBOR.Int only affects the maximum numeric range with respect to JavaScript limits, not the CBOR encoding.

During CBOR decoding, the selection between CBOR.BigInt and CBOR.Int is governed by the decoded value with respect to JavaScript limits. Since integers within the range -9007199254740991 to 9007199254740991, will during decoding return a CBOR.Int although they could be associated by a BigInt variable, the methods getInt64(), getUint64(), and getBigInt(), are supported by the CBOR.Int wrapper as well.

The selection between the CBOR unsigned and negative integer variants is dealt with by the CBOR.js implementation, transparent to the API.

7.2.  Floating-Point Numbers
Although CBOR encoding depends on 16, 32, and 64-bit IEEE 754 variants, the CBOR.js implementation makes this transparent. The CBOR.Float wrapper object only exposes the JavaScript Number type.

For applications depending on non-finite numbers (NaN and Infinity), turn to Non-Finite Numbers.

8.  Diagnostic Notation

Creating CBOR data in diagnostic (textual) notation is provided by the toString() method.

However, through the CBOR.diagDecode() method, CBOR data may also be provided in diagnostic notation, making CBOR useful for local "config" and test data files as well.

Due to the Deterministic Encoding scheme used by CBOR.js, CBOR data can be bidirectionally converted between its native (binary) format and diagnostic notation without getting corrupted. Note though that text-binary-text "roundtrips" do not necessarily return identical text: 0x10 used as diagnostic notation input will return 16 as diagnostic notation output.

The following table shows how CBOR objects should be represented in diagnostic notation:
CDDLSyntaxCommentNotes
/ comment text / Multi-line comment. Multi-line comments are treated as whitespace and may thus also be used between CBOR objects. 6
# comment text Single-line comment. Single-line comments are terminated by a newline character ('\n') or EOF. Single-line comments may also terminate lines holding regular CBOR items. 6
integer {sign}{ 0b | 0o | 0x} n Arbitrary sized integers without fractional components or exponents.
For input data in diagnostic notation, binary, octal, and hexadecimal notation is also supported by prepending numbers with 0b, 0o, and 0x respectively. The latter also permit arbitrary insertions of '_' characters between digits to enable grouping of data like 0b100_000000001.
1, 2
float {sign}n.n{e ± n} Floating point values must include a decimal point and an optional exponent. 1, 2
float'hex data' Any valid 16, 32, or 64-bit float value, including NaN with payloads like float'7ff0800000000001'.
NaN Not a number in the default encoding (f97e00).
{sign}Infinity Infinity. 2
bstr h'hex data' Byte data provided in hexadecimal notation. Each byte must be represented by two hexadecimal digits. 3
b64'base64 data' Byte data provided in base64 or base64URL notation. Padding with '=' characters is optional. 3, 6
'text' Byte data provided as UTF-8 encoded text. 4, 5, 6
<< object... >> Construct holding zero or more comma-separated CBOR objects that are subsequently wrapped in a byte string. 6
tstr "text" UTF-8 encoded text string. 4, 5
bool true | false Boolean value.
null null Null value.
[] [ object... ] Array with zero or more comma-separated CBOR objects.
{} { key:value... } Map with zero or more comma-separated key/value pairs. Key and value pairs are expressed as CBOR objects, separated by a ':' character.
#6.nnn n( object ) Tag holding a CBOR object. 1
#7.nnn simple(n) Simple value. 1
, Separator character for CBOR sequences.
  1. The letter n in the Syntax column denotes one or more digits.
  2. The optional {sign} must be a single hyphen ('-') character.
  3. Input only: between tokens, the whitespace characters ' ', '\t', '\r', and '\n', are ignored.
  4. Input only: inside of string quotes, the control character '\n' becomes a part of the text string. For nomalizing line terminators, a single '\r' or the combination '\r\n' are rewritten as '\n'. To avoid getting newline characters ('\n') included in multi-line text strings, a line continuation marker consisting of a backslash ('\') immediately preceding the newline may be used.
  5. Text strings may also include the JavaScript compatible escape sequences '\'', '\"', '\\', '\b', '\f', '\n', '\r', '\t', and '\uhhhh'.
  6. Input only.

9.  Deterministic Encoding

While there are different ways you can encode certain CBOR objects, this is non-trivial to support in general purpose platform-based tools, not to mention the limited utility of such measures. Therefore the CBOR.js API implements specific (non-variant) encodings, aka "Deterministic Encoding". Fortunately, the selected encoding scheme is backward compatible with most existing CBOR decoders. However, for decoding (only), compliance with deterministic encoding rules may be relaxed, enabling the processing of CBOR data created by applications using "legacy" encoding schemes as well.

The determinism scheme is described in [CBOR::Corelink].

10.  Using the CBOR API

This section provides a few examples on how to use the CBOR API.
10.1.  Encode CBOR Data
The following code shows how you can create CBOR-encoded data:
let cbor = CBOR.Map()
               .set(CBOR.Int(1), CBOR.Float(45.7))
               .set(CBOR.Int(2), CBOR.String("Hi there!")).encode();

console.log(CBOR.toHex(cbor));
a201fb4046d9999999999a0269486920746865726521
10.2.  Decode CBOR Data
The following code shows how you can decode CBOR-encoded data, here using the result of the previous encoding example:
let map = CBOR.decode(cbor);

console.log(map.toString());  // Diagnostic notation
{
  1: 45.7,
  2: "Hi there!"
}

console.log('Value=' + map.get(CBOR.Int(1)).getFloat64());
Value=45.7
10.3.  Decode Variant CBOR Data
The following code shows how you can decode variant CBOR-encoded data:
let intOrString = CBOR.decode(cbor);
if (intOrString instanceof CBOR.Int) {
  let i = intOrString.getInt32();
  // Do something with i...
} else {
  // Throws a CborException if the object is not a CBOR.String
  let s = intOrString.getString();
  // Do something with s...
}
10.4.  Decode CBOR Diagnostic Notation
The following code shows how you can decode CBOR provided in Diagnostic Notation:
let cbor = CBOR.diagDecode(`{
# Comments are also permitted
  1: 45.7,
  2: "Hi there!"
}`).encode();

console.log(CBOR.toHex(cbor));
a201fb4046d9999999999a0269486920746865726521
10.5.  Encode CBOR Sequence
The following code shows how you can create CBOR sequences:
let cbor = CBOR.Array()
  .add(CBOR.Map().set(CBOR.Int(7), CBOR.String("Hi!")))
  .add(CBOR.Float(4.5))
  .encodeAsSequence();

console.log(CBOR.toHex(cbor));
a10763486921f94480
10.6.  Decode CBOR Sequence
The following code shows how you can decode CBOR sequences, here using the result of the previous encoding example:
let decoder = CBOR.initDecoder(cbor, CBOR.SEQUENCE_MODE);
let object;
while (object = decoder.decodeWithOptions()) {
  console.log('\n' + object.toString());
}

{
  7: "Hi!"
}

4.5

11.  Error Handling

Encoding and decoding errors throw CborException, derived from the JavaScript Error object.

12.  Version

API version: 1.0.16. Note that the current API version is accessible through the static property CBOR.version.
Document version: 2025-12-08