diffusion/src/data/datatype.js

Diffusion JavaScript client

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

/**
 * A data type is specified for a particular value type. It provides methods to
 * convert values to and from binary. Diffusion provides several {@link diffusion.datatypes.DataType}
 * implementations.
 * <P>
 * A data type can optionally support incremental changes to values, represented
 * by one or more types of <em>delta</em>. A delta is the difference between two
 * values. For large or composite values that change in small steps, it is more
 * efficient to transmit an initial value followed by a delta for each change
 * than to transmit a complete value for each change. The data type provides an
 * implementation of {@link diffusion.datatypes.DeltaType} for each type of delta it
 * supports via {@link diffusion.datatypes.DataType#deltaType}.
 *
 * @class diffusion.datatypes.DataType
 * @since 5.7
 */
module.exports = _interface('DataType', [
    /**
     * The external type identifier.
     *
     * @returns {String} The name of this datatype.
     * @function diffusion.datatypes.DataType#name
     */
    'name',

    /**
     * Parse a value from binary.
     *
     * @param {Buffer} input - The binary data
     * @param {Number} [offset] - The offset to start reading from the provided buffer
     * @param {Number} [length] - The length of the data to read
     * @returns {Object} An instance of this data type value
     * @throws Error if the data is invalid for this type
     *
     * @function diffusion.datatypes.DataType#readValue
     */
    'readValue',

    /**
     * Serialise a value to binary
     *
     * @param {Object} value - The value to serialise
     * @returns {Buffer} The serialised value as a buffer
     * @throws Error if the value can not be serialised
     *
     * @function diffusion.datatypes.DataType#writeValue
     */
    'writeValue',


    /**
     * Test whether this data type is compatible with <code>valueType</code>. Compatibility with a
     * <code>valueType</code> means than any valid binary representation of a <code>value</code> can be
     * {@link diffusion.datatypes.DataType#readAs read as} an instance of <code>valueType</code>.
     * <P>
     * Every data type should be compatible with the following:
     * <ul>
     * <li><code>Value Type</code> &ndash; the class corresponding to the data type's value type.</li>
     * </ul>
     * <P>
     * For a data type with a value type of <code>X</code>, <code>readAs(X, buffer)</code> is equivalent to
     * <code>readValue(buffer)</code>.
     *
     * @param {Function} valueType - the type to check
     * @return {Boolean} <code>true</code> if a binary representation created by this data type can read as an instance
     * of <code>valueType</code>
     * @function diffusion.datatypes.DataType#canReadAs
     * @since 6.0
     */
    'canReadAs',

    /**
     * Create a value of a compatible class from binary.
     *
     * @param {Function} valueType - the type of the result
     * @param {Buffer} buffer - the binary data
     * @param {Number} [offset=0] - the offset to read data from the buffer
     * @param {Number} [length=buffer.length] - the length of data to read from the buffer
     * @return {Object} the value in the form of the specified type
     * @throws Error if <code>valueType</code> is incompatible with this data type, or <code>buffer</code> does not
     * represent a valid value.
     * @function diffusion.datatypes.DataType#readAs
     * @since 6.0
     */
    'readAs',

    /**
     * Obtain a {@link diffusion.datatypes.DeltaType} by name or delta type.
     *
     * @example
     * // Get by name
     * var deltas = datatype.deltaType("binary");
     *
     * @example
     * // Get by type
     * var deltas = datatype.deltaType(delta);
     *
     * @param {String} [name] - The name, as returned by {@link diffusion.datatypes.DeltaType#name}
     * @param {Object} [delta] - The delta, from which a type-appropriate delta support will be derived
     * @returns {diffusion.datatypes.DeltaType} the delta support

     * @function diffusion.datatypes.DataType#deltaType
     */
    'deltaType'
]);