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

Diffusion JavaScript client

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

/**
 * An unmodifiable map describing the changes to a JSON value.
 *
 * <p>
 * The {@link diffusion.datatypes.JSONDelta#inserted JSONDelta#inserted} method returns a
 * {@link diffusion.datatypes.JSONDelta.ChangeMap ChangeMap} describing the parts
 * of the second JSON value not found in the first JSON value. Similarly,
 * {@link diffusion.datatypes.JSONDelta#removed JSONDelta#removed}
 * returns a <code>ChangeMap</code> describing the parts of the first JSON value
 * not found in the second JSON value.
 *
 * <p>
 * The map contains an entry for each change, as follows:
 * <ul>
 * <li>The key is a <a href= "https://tools.ietf.org/html/rfc6901">JSON
 * Pointer</a> syntax reference locating the change in the complete value.
 * Since a JSON value is a list of zero or more data items, the reference
 * always begins with an array index. For example, the first part is
 * identified by the JSON Pointer <code>/0</code>.
 * <li>The value is part of the complete value. It is returned as a parsed
 * value.
 * </ul>
 *
 * <p>
 * An error will be thrown if an invalid JSON pointer expression is passed to
 * {@link diffusion.datatypes.JSONDelta.ChangeMap#get get},
 * {@link diffusion.datatypes.JSONDelta.ChangeMap#containsKey containsKey},
 * {@link diffusion.datatypes.JSONDelta.ChangeMap#descendants descendants}, or
 * {@link diffusion.datatypes.JSONDelta.ChangeMap#intersection intersection}. This only
 * occurs if the expression does not start with <code>/</code> and is not empty.
 *
 * @class diffusion.datatypes.JSONDelta.ChangeMap
 */
_interface('ChangeMap', [
    /**
     * Retrieve a value from this change map, identified by a JSON Pointer.
     *
     * @param {String} pointer - The JSON Pointer expression
     * @returns {*} the change map value, if it exists, otherwise null
     * @throws Error if pointer is an invalid JSON Pointer expression
     * @function diffusion.datatypes.JSONDelta.ChangeMap#get
     */
    'get',

    /**
     * Determines if this change map contains an entry for a given JSON Pointer
     *
     * @param {String} pointer - The JSON Pointer expression
     * @returns {Boolean} true if an entry exists, false if not
     * @throws Error if pointer is an invalid JSON Pointer expression
     * @function diffusion.datatypes.JSONDelta.ChangeMap#containsKey
     */
    'containsKey',

    /**
     * Returns an array of map entries. Each entry is in the form of a key/value object pair.
     * <P>
     * The key is a JSON Pointer expression, in string form. The value will be parsed from the
     * underlying {@link diffusion.datatypes.JSON} object.
     *
     * @returns {Array} the entry array
     * @function diffusion.datatypes.JSONDelta.ChangeMap#entrySet
     *
     * @example
     * changeMap.entrySet().forEach(function(entry) {
     *     console.log(entry.key, entry.value);
     * });
     */
    'entrySet',

    /**
     * Returns a view of the portion of this map whose keys are descendants
     * of <code>pointer</code>. If <code>pointer</code> is contained in this map, it
     * will be included in the result.
     *
     * @param {String} pointer - the json pointer expression to derive descendants for
     * @returns {diffusion.datatypes.JSONDelta.ChangeMap} changemap of descendant changes
     * @throws Error if pointer is an invalid JSON Pointer expression
     *
     * @function diffusion.datatypes.JSONDelta.ChangeMap#descendants
     */
    'descendants',

    /**
     * Returns a view of the portion of this map whose keys are descendants
     * or parents of <code>pointer</code>. If <code>pointer</code> is contained in
     * this map, it will be included in the result.
     *
     * <p>This method can be used to determine whether a structural
     * delta affects a particular part of a JSON value. For example:
     *
     * <pre>
     * if (structuralDelta.removed().intersection("/contact/address").length) {
             *   // The structural delta removes elements that affect '/contact/address'.
             * }
     * if (structuralDelta.inserted().intersection("/contact/address").length) {
             *   // The structural delta inserts elements that affect '/contact/address'.
             * }
     * </pre>
     * </p>
     *
     * @param {String} pointer - the json pointer expression to derive intersection for
     * @returns {diffusion.datatypes.JSONDelta.ChangeMap} changemap of intersection changes
     * @throws Error if pointer is an invalid JSON Pointer expression
     *
     * @function diffusion.datatypes.JSONDelta.ChangeMap#intersection
     */
    'intersection'
]);

/**
 * Structural delta type for {@link JSON}.
 *
 * <p>
 * A JSONDelta describes the differences between two JSON values. Unlike a
 * {@link diffusion.datatypes.BinaryDelta binary delta}, a
 * structural delta can be queried to determine its effect. The
 * {@link diffusion.datatypes.JSONDelta#removed removed} and
 * {@link diffusion.datatypes.JSONDelta#inserted inserted} methods provide full
 * details of the differences between the two values.
 * <p>
 * An instance can be created from two JSON values using
 * {@link diffusion.datatypes.JSON#jsonDiff JSON#jsonDiff}.
 *
 * @class diffusion.datatypes.JSONDelta
 * @author Push Technology Limited
 * @since 5.9
 */
_interface('JSONDelta', [
    /**
     * Returns the parts of the first JSON value not found in the second JSON
     * value.
     *
     * @return {diffusion.datatypes.JSONDelta.ChangeMap}the removed parts. The JSON Pointer references used for the
     * keys are relative to first JSON value.
     *
     * @function diffusion.datatypes.JSONDelta#removed
     */
    'removed',

    /**
     * Returns the parts of the second JSON value not found in the first JSON
     * value.
     *
     * @return {diffusion.datatypes.JSONDelta.ChangeMap} the removed parts. The JSON Pointer references used for
     * the keys are relative to second JSON value.
     *
     * @function diffusion.datatypes.JSONDelta#inserted
     */
    'inserted',

    /**
     * Returns whether the two JSON values used to create this instance are
     * different.
     *
     * @return {Boolean} true if this delta has an effect
     *
     * @function diffusion.datatypes.JSONDelta#hasChanges
     */
    'hasChanges'
]);