diffusion/src/data/binary/binary.js

Diffusion JavaScript client

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

/**
 * A read-only binary value with support for binary deltas.
 *
 * <P>
 * Values are effectively immutable. Instances can be backed by
 * {@link diffusion.datatypes.BinaryDataType#from user-supplied buffers}.
 * Once a Binary has been constructed around a buffer, care must
 * be taken not to modify the data in the buffer because doing
 * so would violate immutability.
 *
 * @class diffusion.datatypes.Binary
 * @since 5.7
 */
module.exports = _interface('Binary', Bytes, [
    /**
     * Get the value as a Buffer.
     *
     * @return {Buffer} The buffer value
     * @function diffusion.datatypes.Binary#get
     */
    'get',

    /**
     * Compare this Binary value with an earlier version to create a delta.
     * <P>
     * Convenient equivalent to:
     * <code>diffusion.datatypes.binary().deltaSupport(type).diff(original, this);</code>
     * <P>
     * Buffers may also be provided as the value to diff instead of a {@link diffusion.datatypes.Binary} instance.
     *
     * @example
     * var delta = binaryValue.diff(new Buffer('Hello world'));
     *
     * @param {diffusion.datatypes.Binary|Buffer} 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.Binary#diff
     */
    'diff',

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