Class: Decoder

Defined in:	src/decoder.coffee
Inherits:	BinaryParseStream

Overview

Decode a stream of CBOR bytes by transforming them into equivalent JavaScript data. Because of the limitations of Node object streams, special symbols are emitted instead of NULL or UNDEFINED. Fix those up by calling Decoder.nullcheck.

Several other internal events are emitted, but I hope you never need to care about them.

Events:

'data'

(object) A complete top-level CBOR item has been parsed

'end'

The input stream is fully parsed

'error'

(Error) An error has occurred in parsing

Variables Summary

NOT_FOUND =

NOT_FOUND

A symbol returned from Decoder.decodeFirst when no object was found.

Class Method Summary

. (void) nullcheck(val) Check the given value for a symbol encoding a NULL or UNDEFINED value in the CBOR stream.
. (anything) decodeFirstSync(input, options = { encoding: 'hex' }) Decode the first CBOR item in the input, synchronously.
. (anything) decodeAllSync(input, options = { encoding: 'hex' }) Decode all of the CBOR items in the input.
. (undefined, Promise) decodeFirst(input, options = { encoding: 'hex' }, cb) Decode the first CBOR item in the input.
. (undefined, Promise) decodeAll(input, options = { encoding: 'hex' }, cb) Decode all of the CBOR items in the input.

Class Method Details

. (void) nullcheck(val)

Check the given value for a symbol encoding a NULL or UNDEFINED value in the CBOR stream.

Examples:

myDecoder.on('data', function(val) {
  val = Decoder.nullcheck(val);
  ...
});

Parameters:

value ( Any ) — the value to check

. (anything) decodeFirstSync(input, options = { encoding: 'hex' })

Decode the first CBOR item in the input, synchronously. This will throw an exception if the input is not valid CBOR.

Parameters:

input ( String, Buffer ) — the input to parse
options ( Object, String ) — options Decoding options. If string, the input encoding.

Options Hash: (options):

encoding ( String ) — the input encoding, when the input is a string.
tags ( Object ) — mapping from tag number to function(v), where v is the decoded value that comes after the tag, and where the function returns the correctly-created value for that tag.
max_depth ( Number ) — the maximum depth to parse. -1 (the default) for "until you run out of memory". Set this to a finite positive number for un-trusted inputs. Most standard inputs won't nest more than 100 or so levels; I've tested into the millions before running out of memory.

Returns:

( anything ) — The parsed value

. (anything) decodeAllSync(input, options = { encoding: 'hex' })

Decode all of the CBOR items in the input. This will throw an exception if the input is not valid CBOR; a zero-length input will return an empty array.

Parameters:

input ( String, Buffer ) — the input to parse
options ( Object, String ) — options Decoding options. If string, the input encoding.

Options Hash: (options):

encoding ( String ) — the input encoding, when the input is a string.
tags ( Object ) — mapping from tag number to function(v), where v is the decoded value that comes after the tag, and where the function returns the correctly-created value for that tag.
max_depth ( Number ) — the maximum depth to parse. -1 (the default) for "until you run out of memory". Set this to a finite positive number for un-trusted inputs. Most standard inputs won't nest more than 100 or so levels; I've tested into the millions before running out of memory.

Returns:

( anything ) — An array of the parsed values.

. (undefined, Promise) decodeFirst(input, options = { encoding: 'hex' }, cb)

Decode the first CBOR item in the input. This will error if there are more bytes left over at the end, and optionally if there were no valid CBOR bytes in the input. Emits the Decoder.NOT_FOUND Symbol in the callback if no data was found and the required option is false.

Parameters:

input ( String, Buffer ) — the input to parse
options ( Object, String ) — options Decoding options. If string, the input encoding.
cb ( Function ) — an (error, value) callback.

Options Hash: (options):

encoding ( String ) — the input encoding, when the input is a string.
required ( Boolean ) — give an error if no valid CBOR is found in the inoput.
tags ( Object ) — mapping from tag number to function(v), where v is the decoded value that comes after the tag, and where the function returns the correctly-created value for that tag.
max_depth ( Number ) — the maximum depth to parse. -1 (the default) for "until you run out of memory". Set this to a finite positive number for un-trusted inputs. Most standard inputs won't nest more than 100 or so levels; I've tested into the millions before running out of memory.

Returns:

( undefined, Promise ) — If cb not specified, returns a Promise fulfilled with the first parsed value.

. (undefined, Promise) decodeAll(input, options = { encoding: 'hex' }, cb)

Decode all of the CBOR items in the input. This will error if there are more bytes left over at the end.

Parameters:

input ( String, Buffer ) — the input to parse
options ( Object, String ) — options Decoding options. If string, the input encoding.
cb ( Function ) — an (error, [values]) callback.

Options Hash: (options):

encoding ( String ) — the input encoding, when the input is a string.
tags ( Object ) — mapping from tag number to function(v), where v is the decoded value that comes after the tag, and where the function returns the correctly-created value for that tag.
max_depth ( Number ) — the maximum depth to parse. -1 (the default) for "until you run out of memory". Set this to a finite positive number for un-trusted inputs. Most standard inputs won't nest more than 100 or so levels; I've tested into the millions before running out of memory.

Returns:

( undefined, Promise ) — If cb not specified, returns a Promise fulfilled with an array of the parsed values.

Constructor Details

# (void) constructor(options)

Create a parsing stream.

Parameters:

options ( Object, String ) — options Decoding options.

Options Hash: (options):

tags ( Object ) — mapping from tag number to function(v), where v is the decoded value that comes after the tag, and where the function returns the correctly-created value for that tag.
max_depth ( Number ) — the maximum depth to parse. -1 (the default) for "until you run out of memory". Set this to a finite positive number for un-trusted inputs. Most standard inputs won't nest more than 100 or so levels; I've tested into the millions before running out of memory.