diffusion
Version:
Diffusion JavaScript client
110 lines (101 loc) • 3.89 kB
JavaScript
var _interface = require('util/interface')._interface;
/**
* Optional extension provided by {@link diffusion.datatypes.DataType} implementations that support
* incremental changes to values.
* <P>
* Each implementation specifies a <code>value</code> type and a <code>delta</code> type.
* Two values, oldValue and new Value, can be compared to produce a delta using
* {@link diffusion.datatypes.DeltaType#diff}. The delta can be separately applied to oldValue to
* create newValue using {@link diffusion.datatypes.DeltaType#apply}.
* <h5>Deferred parsing</h5>
* Implementations can choose not to fully validate values when they are read,
* but instead defer parsing until it is required. Consequently, all methods
* that accept values may throw an error.
*
* @class diffusion.datatypes.DeltaType
* @since 5.7
*/
module.exports = _interface('DeltaType', [
/**
* The name of this delta type
*
* @returns {String} The name
* @function diffusion.datatypes.DeltaType#name
*/
'name',
/**
* Create a delta from two values.
* <P>
* If there are many differences between oldValue and newValue, the result
* might require more bytes to transmit than the new value, or be
* computationally expensive to apply. In this case, it is better to discard
* oldValue and publish newValue in its place. This can be checked using
* {@link diffusion.datatypes.DeltaType#isValueCheaper}.
* <P>
* The implementation can return the special constant {@link diffusion.datatypes.DeltaType#noChange}
* to indicate the old value and new value are equivalent and there is no change
* to publish.
*
* @param {Object} oldValue- The old value
* @param {Object} newValue - The new value
* @return {Object} The delta between values
*
* @function diffusion.datatypes.DeltaType#diff
*/
'diff',
/**
* Apply a delta to a value.
*
* @param {Object} old - The old value
* @param {Object} delta - The delta to apply
* @return {Object} The new value generated applying the delta to the old value
* @throws Error if the value or delta is invalid
*
* @function diffusion.datatypes.DeltaType#apply
*/
'apply',
/**
* Parse a delta from binary.
*
* @param {Buffer} binary - The binary data
* @param {Number} [offset] - The offset from which to start reading from the buffer
* @param {Number} [length] - The length of data to read from the buffer
* @return {Object} The delta
* @throws Error if the binary is invalid
*
* @function diffusion.datatypes.DeltaType#readDelta
*/
'readDelta',
/**
* Serialise a delta to binary.
*
* @param {Object} delta - The delta to serialise
* @return {Buffer} The serialised form of the delta
* @throws Error if the delta cannot be serialised
*
* @function diffusion.datatypes.DeltaType#writeDelta
*/
'writeDelta',
/**
* Constant returned by {@link diffusion.datatypes.DeltaType#diff} to indicate that
* both values are equivalent.
*
* @return {Object} unique object representing no change in value
*
* @function diffusion.datatypes.DeltaType#noChange
*/
'noChange',
/**
* Calculate if <code>value</code> is cheaper than the <code>delta</code>. The
* result is typically determined by the length of the serialised form, but may
* also consider the complexity of the delta.
*
* @param {Object} value - The value to compare
* @param {Object} delta - The delta to compare
* @return {Boolean} <code>true</code> if the value is considered cheaper than the delta
* @throws Error if the value or delta is invalid
*
* @function diffusion.datatypes.DeltaType#isValueCheaper
*/
'isValueCheaper'
]);