diffusion/src/data/json/json-datatype.js

Diffusion JavaScript client

var _interface = require('util/interface')._interface;
var DataType = require('../datatype');

/**
 * JSON data type.
 * <P>
 * Accessed via:
 * <code>diffusion.datatypes.json();</code>
 * <P>
 * The JSON Data Type provides {@link diffusion.datatypes.JSON} values, which are a wrapper around native JSON objects.
 * <P>
 * For efficiency, the JSON value is serialized in binary form following
 * the CBOR specification.
 * <P>
 * The implementation provides support for binary deltas.
 *
 * JSON instances defer parsing of underlying binary data until required. If the data
 * is not valid, an Error may be thrown when {@link diffusion.datatypes.JSON#get} is called.
 *
 * @class diffusion.datatypes.JSONDataType
 * @augments diffusion.datatypes.DataType
 * @since 5.7
 *
 * @property {diffusion.datatypes.JSON} diffusion.datatypes.JSONDataType.JSON - The JSON data type value class
 */
module.exports = _interface('JSONDataType', DataType, [

    /**
     * Returns a new {@link diffusion.datatypes.JSON} instance from a native JS object.
     * <P>
     * Passing a string will produce a JSON instance encoding a single string token. To produce a JSON datatype
     * instance from a JSON string, use {@link diffusion.datatypes.JSONDataType#fromJsonString} instead.
     * <P>
     * This is useful in cases where providing the raw value may be ambiguous for SDK methods that infer the datatype
     * from provided arguments, such as {@link Session.messages#sendRequest}.
     *
     * @example
     * // Value from object
     * var value = jsondatatype.from({
     *     foo : "bar",
     *     baz : [1, 2, 3]
     * });
     *
     * @example
     * // Datatype instance from string
     * var value = jsondatatype.from("this is a simple string");
     *
     * @param {Object} object - The object data
     * @return {diffusion.datatypes.JSON} a JSON data-type instance
     *
     * @function diffusion.datatypes.JSONDataType#from
     */
    'from',

    /**
     * Returns a new {@link diffusion.datatypes.JSON} instance from a JSON string.
     * <P>
     * Precision for numeric types is lost in the translation to the internal
     * CBOR binary form and non-significant white space is not preserved.
     *
     * @example
     * // Datatype instance from a JSON string.
     * var value = jsondatatype.fromJsonString("{\"foo\" : \"bar\"}");
     *
     * // The value contains the parsed object representation
     * value.get(); // => { foo : "bar" }
     *
     * @param {String} string - The JSON string
     * @return {diffusion.datatypes.JSON} A JSON data-type instance
     *
     * @function diffusion.datatypes.JSONDataType#fromJsonString
     * @since 5.9
     */
    'fromJsonString'
]);