data-bind-mapper

A class 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 internal maps, 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 DataBindMapper from 'data-bind-mapper';

or using a script tag

<script src="//cdn.jsdelivr.net/npm/data-bind-mapper"></script>

then

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

new DataBindMapper()
  .onCreateObj(() => {
    const obj = {};
    myView.add(obj);
    return obj;
  })
  .onUpdateObj((obj, d) => { obj.double = d.val * 2 })
  .onRemoveObj(obj => myView.delete(obj))
  .digest(myData);

API reference

Initialisation

new DataBindMapper()

Methods

| Method | Description | |-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | getObj(datum) | Returns the object associated with this data element, or undefined if not found. | | getData(obj) | Returns the data element associated with this object, or undefined if not found. | | entries() | Returns all the data elements and associated objects, formatted as an array of tuples. | | id(str or fn) | Data element accessor function or attribute for the id to use when indexing the data. Should refer to a property unique to the data element. | | onCreateObj(fn(datum)) | The method to create an entering view object for a new data element that does not yet have a corresponding object. The data element is passed as single argument: d => { ... }. The method should return a new object. | | onUpdateObj(fn(obj, datum)) | The method to update an existing bound object with new data. The object and the data element are passed as arguments: (obj, d) => { ... }. This method is also called for entering objects after onCreateObj. | | onRemoveObj(fn(obj, id)) | The method to handle exiting objects which no longer have a corresponding data element. The unbound object and the lost data id are passed as arguments: (obj, id) => { ... }. | | digest(data) | Receives a new array of data which is diffed with the existing one and invokes onCreateObj, onUpdateObj and onRemoveObj as needed. | | clear() | Removes all registered data and objects. Equivalent to doing .digest([]). |