diffusion/src/data/json/json.js

Diffusion JavaScript client

var _interface = require('util/interface')._interface;
var Bytes = require('../bytes');

/**
 * Immutable JSON data. The value is stored internally as a buffer.
 * <P>
 * To create an instance from an object, obtain a {@link diffusion.datatypes.JSONDataType}
 * implementation from <code>diffusion.datatypes.json()</code> and call 
 * {@link diffusion.datatypes.JSONDataType#parse}.
 * <P>
 * The encapsulated value can be accessed by calling {@link diffusion.datatypes.JSON#get}.
 * <P>
 * <h4>CBOR representation</h4>
 * <p>
 * Internally the value is stored and transmitted not as a JSON string, but in
 * CBOR format to reduce memory and network overhead. CBOR (Concise Binary
 * Object Representation) is a standardized format for binary representation of
 * structured data defined by <a href= "https://tools.ietf.org/html/rfc7049">RFC
 * 7049</a>. See <a href="http://www.cbor.io">www.cbor.io</a>.
 *
 * <p>
 * Rather than working with JSON strings it is possible, and usually preferable,
 * for applications to work directly with the underlying CBOR-format binary
 * representation. This avoids creating intermediate JSON strings, and allows
 * access to CBOR features such as the byte string data type.
 *
 * <p>
 * Each JSON value is represented as a single CBOR data item. CBOR supports
 * composite data types just like JSON, so this data item can be an array or a
 * map of other data items. The JSON <code>null</code> value is represented by the
 * CBOR <code>null</code> value.
 *
 * <p>
 * A particular advantage of working directly with the CBOR-format data is that
 * binary data can be written to the value as a data item using the CBOR byte
 * string type. The data item will be stored as part of the JSON value in binary
 * form and transmitted without further conversion.
 *
 * @class diffusion.datatypes.JSON
 * @augments diffusion.datatypes.Binary
 * @since 5.7
 */
module.exports = _interface('JSON', Bytes, [

    /**
     * Get this instance's value. Use this method to access the provided data when a
     * {@link diffusion.datatypes.JSON} instance is received through the API.
     *
     * @example
     * session.subscribe("foo").asType(diffusion.datatypes.json()).on('value', function(path, spec, value) {
     *     // Get the actual value from the JSON instance
     *     var data = value.get();
     * });
     *
     * @return {Object} The JSON value
     * @function diffusion.datatypes.JSON#get
     */
    'get',

    /**
     * Compare this JSON value with an earlier version to create a delta.
     * <P>
     * Convenient equivalent to:
     * <code>diffusion.datatypes.json().deltaType(type).diff(original, this);</code>
     * <P>
     * Standard JSON objects may also be provided as the value to diff instead of a {@link diffusion.datatypes.JSON}
     * instance.
     *
     * @example
     * var binaryDelta = jsonValue.diff({ foo : "bar" });
     *
     * @example
     * var jsonDelta = jsonValue.diff({ foo : "bar" }, "json");
     *
     * @param {diffusion.datatypes.JSON|Object} original - The value to diff against this
     * @param {String} [type="binary"] - The type of delta to generate
     * @return {diffusion.datatypes.BinaryDelta} A delta representing the difference between this and the provided value
     *
     * @function diffusion.datatypes.JSON#diff
     */
    'diff',

    /**
     * Compare this JSON value with an earlier version to create a structural {@link JSONDelta json delta}.
     * <P>
     *
     * Convenient equivalent to:
     * <code>this.diff(original, "json");</code>
     * <P>
     * Standard JSON objects may also be provided as the value to diff instead of a {@link diffusion.datatypes.JSON}
     * instance.
     *
     * @example
     * var delta = jsonValue.jsonDiff({ foo : "bar" });
     *
     * @param {diffusion.datatypes.JSON|Object} original - The value to diff against this
     * @return {diffusion.datatypes.JSONDelta} A delta representing the difference between this and the provided value
     *
     * @function diffusion.datatypes.JSON#jsonDiff
     */
    'jsonDiff',

    /**
     * Apply a delta to this JSON value to create a new value.
     * <P>
     * Convenient equivalent to:
     * <code>diffusion.datatypes.JSON().deltaType(delta).apply(this, delta);</code>
     *
     * @param {Object} delta - The binary delta to apply to this value
     * @return {DataTypes.JSON} A new instance derived from applying the delta to this value
     * @throws Error if the delta is invalid
     *
     * @function diffusion.datatypes.JSON#apply
     */
    'apply'
]);