data-joint

Library to perform data joins with any type of JavaScript objects. Useful in digest cycles where it's important to minimize changes to a view for performance reasons, such as DOM manipulation. The module binds data points to objects via hidden attributes, and performs diffing comparisons across multiple iterations to ensure objects are not created or removed unnecessarily, thus keeping view changes to a minimum.

Quick start

import dataJoint from 'data-joint';

or using a script tag

<script src="//unpkg.com/data-joint"></script>

then

const myData = [{ id: 0, val: 2 }, { id: 1, val: 4 }, { id: 2, val: 7 }];
const myView = new Set();

dataJoint(myData, [...myView], 
    obj => myView.add(obj), // append obj
    obj => myView.delete(obj), // remove obj
    {
        createObj: () => ({}),
        updateObj: (obj, d) => { obj.double = d.val * 2 },
        exitObj: obj => { obj.double = 0 },
        idAccessor: d => d.id
    }
);

API reference

Syntax

dataJoint(data, existingObjs, appendObjFn, removeObjFn, [{options}]);

Arguments

data: An array of data points. Each point should be an object that supports attribute binding.

existingObjs: An array of view objects to join the data with.

appendObjFn: The method to add a new object to the view. The object is passed as single argument: obj => { ... }.

removeObjFn: The method to remove an existing object from the view. The object is passed as single argument: obj => { ... }.

Options

An optional configuration object supporting the additional arguments:

Option	Description	Default
createObj	The method to create an entering view object for a new data point that does not have a corresponding object. The data point is passed as single argument: d => { ... }. The method should return a new object.	d => ({})
updateObj	The method to update an existing bound object with new data. The object and the data point are passed as arguments: (obj, d) => { ... }. This method is also called for entering objects after createObj.	(obj, d) => {}
exitObj	The method to handle exiting objects which no longer have a corresponding data point. The unbound object is passed as single argument: obj => { ... }. This method is called prior to removing it from the view via removeObjectFn.	obj => {}
objBindAttr	The attribute name used to bind data points to view objects. Each data point passed through the digest will be added this attribute, and it will be used for diffing across multiple iterations.	__obj
dataBindAttr	The attribute name used to bind view objects to data points. Each object maintained by the digest will be added this attribute, and it will be used for diffing across multiple iterations.	__data
idAccessor	A data point accessor function to extract the point unique identifier. This is used for comparing data points across multiple iterations. If no idAccessor is supplied, the data point object reference will be used instead for comparisons. The data point is passed as single argument: d => {...}. The method should return a unique identifier.	undefined
purge	A boolean value. If set to true it will bypass the data diffing, resulting in all the existingObjs being marked for removal and new objects created for the all the items in the input data.	false