Skip this section if you're using defi-react because React handles DOM rendering by its own.

It creates a bridge between value of a property and a state of HTML node on the page: from a simple input to a complicated widget (the complexity of elements is unlimited). After using this function, it isn't necessary to monitor the synchronizations between model and view.

Note that a bunch of common binders can be found at common-binders package. Also the function, by default, supports all form elements without need to pass binder argument.

The function acepts three arguments: a property name, HTML node and a binding rule (a binder). In its turn, a binder is an ordinary object and it can have the following properties: on, getValue, setValue, initialize, destroy (Read more here: binder). All the five properties are optional. It also allows to declare one-way data bindings (any direction).

The bindNode function supports the many-to-many bindings. Several elements can be bound to one property and several properties can be bound to one element, including ones from different objects.

defi.bindNode(object, 'myKey', '.my-element', {
    on: 'click',
    getValue() { ... },
    setValue() { ... }
});

For example, you want to bind a property of an object to a input[type="checkbox"] node:

defi.bindNode(obj, 'myKey', '.my-checkbox', {
    // when is element state changed?
    // - after 'click' event
    on: 'click',
    // how to extract element state?
    // - return 'checked' value
    getValue: ({ node }) => node.checked,
    // how to set element state?
    // - set 'checked' value
    setValue: (v, { node }) => node.checked = !!v,
});

After binding is declared, you can set value of an object property in your most habitual way and HTML node (in this case, a checkbox) will change its state immediately. After clicking on the checkbox, the property value will be changed to the corresponding one as well.

// sets checked = true
obj.myKey = true;

More interesting example: binding object property to a jQuery UI widget (of course you can use any other library, jQuery isn't something specially supported).

<div class="my-slider"></div>

defi.bindNode(obj, 'myKey', '.my-slider', {
    // when is element state changed?
    // - after 'slide' event
    // (a function can be used to listen to any non-DOM events)
    on: (callback, { node }) => $(node).on('slide', callback),
    // how to extract element state?
    // - return 'value' of the widget
    getValue: ({ node }) => $(node).slider('option', 'value'),
    // how to set element state?
    // - set 'value'
    setValue: (v, { node }) => $(node).slider('option', 'value', v),
    // how to initialize the widget?
    // you can initialize the slider in any way,
    // but 'initialize' function provides some syntactic sugar
    initialize: ({ node }) => $(node).slider({ min: 0, max: 100 }),
});

// will set the slider value 42
obj.myKey = 42;

It looks easy but you may ask a question: "What should I do to avoid writing these rules every time?". Indeed, there can be a lot of elements of the same type on the page: text fields, drop down menus, fields from the HTML5 specification as well as third party widgets.

As observed in this documentation, the third argument is not obligatory for the ones of the bindNode function. This problem is solved by the defi.defaultBinders array which contains functions checking an HTML node against a set of rules and returns corresponding binder or undefined. You get an opportunity to reduce your code a great deal, putting binding rules into a separate part of your code and to use a syntax for binding without the third argument:

defi.bindNode(obj, 'myKey', '.my-element');

How to do it? You should add a function checking an element against a set of rules to the beginning of the defi.defaultBinders array.

const checkboxBinder = () => {
    return {
        on: 'click',
        getValue: ({ node }) => node.checked,
        setValue: (v, { node }) => node.checked = !!v,
    }
};

// the unshift function adds the function
// to the beginning of the defi.defaultBinders array
defi.defaultBinders.unshift(node => {
    // check if the element is a checkbox
    if(node.tagName == 'INPUT' && node.type == 'checkbox') {
        // if checking is OK, return a new binder
        return checkboxBinder();
    }
});

defi.bindNode(obj, 'myKey', '.my-checkbox');
obj.myKey = true;

What should you do if you need to pass arguments for initializing some plugin or a widget? You can call the function that returns a binder manually.

const uiSlider = (min, max) => {
    return {
        on: 'slide',
        getValue: ({ node }) => $(node).slider('option', 'value'),
        setValue: (v, { node }) => $(node).slider('option', 'value', v),
        initialize: ({ node }) => $(node).slider({ min, max }),
    }
};

defi.bindNode(obj, 'myKey1', '.my-slider1', uiSlider(0, 100));
defi.bindNode(obj, 'myKey2', '.my-slider2', uiSlider(1, 1000));
obj.myKey1 = 42;
obj.myKey2 = 999;

defi.defaultBinders OOB has a support for all form elements without any exception: select (including multiple), textarea, output, input (including all types from the specification of HTML5: text, checkbox, radio, range, number, date, search, time, datetime, datetime-local, color and others). That means it is not necessary to designate a binder for standard elements.

<input type="color" class="my-color-input">

defi.bindNode(obj, 'myColor', '.my-color-input');
obj.myColor = '#66bb6a';

Besides, after the binding, a new non-standard :bound(KEY) CSS selector is available for you.

defi.bindNode(obj, 'myKey', '.my-element');

// will find the element '.my-inner-element' inside '.my-element'
defi.bindNode(obj, 'myAnotherKey', ':bound(myKey) .my-inner-element');

And the syntax of possible event names is extended:

defi.bindNode(obj, 'myKey', '.my-element');

// will handle the click on the '.my-element' element
defi.on(obj, 'click::myKey', () => { ... });

// will handle the click on the '.my-element .my-inner-element'
defi.on('click::myKey(.my-inner-element)', () => { ... });

If a node is not found "Bound element is missing" error will be thrown. See an option optional: true below.

Important features of the function and special flags

The fourth argument of bindNode function is options. This object can include special flags or custom data which will be passed to bind and bind:KEY event handlers.

defi.on(obj, 'bind:x', evt => {
    console.log(evt.foo); // bar
});
defi.bindNode(obj, 'x', node, binder, { foo: 'bar' });

To understand important features of bindNode it is important to read information below but it's not required to remember all these flags.

A flag exactKey=false

If key string includes a dot then such string will be interpreted as a path to a property of nested object. The library will listen all changes of given object tree.

obj.a = { b: { c: 'foo' } };
defi.bindNode(obj, 'a.b.c', node);

obj.a.b.c = 'bar'; // updates node by bar

const oldB = obj.a.b;

obj.a.b = { c: 'baz' }; // updates node by baz

// the node is not updated because
// the connection with the object subtree is destroyed
oldB.c = 'fuu';

In case if you need to use property name as is, use exactKey flag with true value.

obj['a.b.c'] = 'foo';
defi.bindNode(obj, 'a.b.c', node, binder, {
    exactKey: true
});
obj['a.b.c'] = 'bar';

A flag getValueOnBind

When getValue is given then a state of an element will be extracted and assigned to bound property immediately after bindNode call in case if the property has undefined value. To force this behavior even if the property has non-undefined value use getValueOnbind flag with true value. To cancel this behavior use the same flag with false value.

A flag setValueOnBind

When setValue is given then the value of the property will be set as element state immediately after bindNode call in case if the property has non-undefined value. To force this behavior even if the property is undefined use setValueOnBind flag with true value. To cancel this behavior use the same flag but with false value.

Flags debounceGetValue=true and debounceSetValue=true

One of the most important feature of bindNode is that the logic of property change and the logic of element state change uses the debounce pattern. It means that if bound property is changed many times in a short time then bound element state will be updated only once after small delay (thanks to debounceSetValue=true). If element state is changed many times in a short time (eg corresponding DOM event is triggered), the property gets new value only once after minimum delay (thanks to debounceGetValue=true).

const input = document.querySelector('.my-input');
defi.bindNode(obj, 'x', input);
obj.x = 'foo';
console.log(input.value === 'foo'); // false
setTimeout(() => {
    console.log(input.value === 'foo'); // true
});

To cancel this behavior (e. g. initiate synchronous binding) use debounceSetValue and/or debounceGetValue flags with false value.

Flags debounceSetValueOnBind=false and debounceGetValueOnBind=false

As described above bindNode uses debounce pattern on property change and on bound node change. This doesn't apply to a moment when bindNode is called. To remind, when the function is called a property or a node is changed immediately. When debounceGetValueOnBind and/or debounceSetValueOnBind are set to true then debounce is turned on for binding initialization as well.

Flags debounceSetValueDelay=0 and debounceGetValueDelay=0

These flags allow to set debounce delay. debounceSetValueDelay is used when debounceSetValue or debounceSetValueOnBind is true, debounceGetValueDelay is used when debounceGetValue or debounceGetValueOnBind is true.

A flags optional=false

bindNode doesn't throw an error of missing node if optional: true is set.

A flag useExactBinder=false

Even if you pass a binder to bindNode, the framework tries to find default binder at defi.defaultBinders and extend it by properties of the passed object. This feature makes possible to use partially re-defined default binder.

For example, we want to bind input[type="text"] to a property. By default, the standard binder contains "on" property with "input" value for this kind of node. It means that the value of the object property and node state will be synchronized when a user releases a key of the keyboard or pastes text from clipboard. In case if you want synchronization to be performed after the "blur" DOM event, you need to pass an object containing the only "on" property as the third argument. This object will extend the default binder, having retained getValue and setValue values.

defi.bindNode(obj, 'myKey', '.my-input', { on: 'blur' });

To cancel this behavior and use the binder as is, you can use useExactBinder flag with true value.

defi.bindNode(obj, 'x', node, binder, {
    useExactBinder: true
});

To the defi.bindNode function an object can be passed to avoid multiple invocation of the function and reduce code. Keys of the object are property names and values can get the following look:

• A node;
• An object with properties node and binder;
• An array of objects with properties node and binder;

If binder arg is passed as the second argument then it wil be used as the binder for those elements for which a binder wasn't specified.

Skip this section if you're using defi-react because React handles DOM rendering by its own.

calc creates a dependency of a property (target argument) on values of other properties (source argument). When source property is changed, target is re-calculated automatically.

source arg has a few variations.

A string

A target property is dependent on source property.

obj.b = 1;
defi.calc(obj, 'a', 'b', b => b * 2);
console.log(obj.a); // 2

An array of strings

A target is dependent on properties listed at source array.

obj.b = 1;
obj.c = 2;
obj.d = 3;
defi.calc(obj, 'a', ['b', 'c', 'd'], (b, c, d) => b + c + d);
console.log(obj.a); // 6

An object with properties object and key

At this case target property is dependent on a property from another object.

const someObject = { b: 1 };
defi.calc(obj, 'a', {
    object: someObject,
    key: 'b'
}, b => b * 2);

console.log(obj.a); // 2

key property also accepts an array of property names.

const someObject = {
    b: 1,
    c: 2,
    d: 3
};
defi.calc(obj, 'a', {
    object: someObject,
    key: ['b', 'c', 'd']
}, (b, c, d) => b + c + d);

console.log(obj.a); // 6

An array of object with properties object and key

This variation allows to define dependency from properties of different objects.

const someObjectX = {
    b: 1,
    c: 2
};
const someObjectY = {
    d: 3
};
defi.calc(obj, 'a', [{
    object: someObjectX,
    key: ['b', 'c']
}, {
    object: someObjectY,
    key: 'd'
}], (b, c, d) => b + c + d);

console.log(obj.a); // 6

A combination of strings (own properties) and objects

obj.b = 1;
obj.c = 2;

const someObject = {
    d: 3,
    e: 4
};

defi.calc(obj, 'a', ['b', 'c', {
    object: someObject,
    key: ['d', 'e']
}], (b, c, d, e) => b + c + d + e);

console.log(obj.a); // 10

For reasons of code purity, the combination of strings and objects inside source array is not recommended. Instead, pass an object whose object property refers to source object. An example below makes the same job as shown at the previous example.

obj.b = 1;
obj.c = 2;

const someObject = {
    d: 3,
    e: 4
};

defi.calc(obj, 'a', [{
    object: obj, // the target object
    keys: ['b', 'c']
}, {
    object: someObjectX,
    key: ['d', 'e']
}], (b, c, d, e) => b + c + d + e);

console.log(obj.a); // 10

A path to source property

If source property name includes a dot then the function initiates a dependency on a property from nested object.

obj.b = { c: { d: 1 } };
obj.e = { f: { g: 2 } };

defi.calc(obj, 'a', ['b.c.d', 'e.f.g'], (d, g) => d + g);

console.log(obj.a); // 3

The same thing works for external sources.

obj.b = { c: { d: 1 } };
const someObject = { e: { f: { g: 2 } } };

defi.calc(obj, 'a', [{
    object: obj
    key: 'b.c.d'
}, {
    object: someObject
    key; 'e.f.g'
}], (d, g) => d + g);

console.log(obj.a); // 3

The function is protected from circular references (for example, a depends on b, b depends on c and c depends on a) and if there is a calculation problem, it does not block the page and does not throw an exception about the stack over-flow.

As you may noticed, arguments of handler function always follow the same order as source properties appear.

In case if you want to change a value of one source property and make it so that target property will not be recalculated, then use defi.set function with skipCalc flag.

defi.calc(obj, 'a', 'b', handler);
defi.set(obj, 'b', newValue, {
    skipCalc: true
});

Important features of the function and special flags

The fifth argument of calc function is options (you also can call them just "options"). As usual this object can include special flags or custom data which will be passed to change:TARGET event handler.

defi.on(obj, 'change:a', evt => {
    console.log(evt.foo); // 'bar'
});

defi.calc(obj, 'a', source, handler, { foo: 'bar' });

A flag debounceCalc=true

After calc is called, a target property is calculated with no delays. But when source property is changed the debounce pattern is used. That means that target property will be changed in few milliseconds and only once even if source properties was changed many times in a short time.

obj.b = 1;
obj.c = 2;
obj.d = 3;

defi.calc(obj, 'a', ['b', 'c', 'd'], (b, c, d) => b + c + d);

defi.on(obj, 'change:a', () => {
    // the handler will be called only once
    // despite that source properties was changed thrice
    console.log(`a is changed to ${obj.a}`); // a is changed to 60
});

obj.b = 10;
obj.c = 20;
obj.d = 30;
console.log(obj.a); // 6 instead of 60

To cancel debounce pattern when source properties are changed, in other words to make the calculation synchronously pass debounceCalc with false value to the function.

obj.b = 1;
obj.c = 2;
obj.d = 3;

defi.calc(obj, 'a', ['b', 'c', 'd'], (b, c, d) => b + c + d, {
    debounceCalc: false
});

defi.on(obj, 'change:a', () => {
    // the handler will be called thrice
    // every time when b, c or d are changed

    // a is changed to... 15, 33, 60
    console.log(`a is changed to ${obj.a}`);
});

obj.b = 10;
obj.c = 20;
obj.d = 30;
console.log(obj.a); // 60

A flag debounceCalcOnInit=false

As described above, target property is calculated immediately after the calc is called. To turn on debounce on calc call pass debounceCalcOnInit with true value to the function.

defi.on(obj, 'change:a', () => {
    // the handler will be called only once in a moment
    console.log(`a is changed to ${obj.a}`); // a is changed to 6
});

obj.b = 1;
obj.c = 2;
obj.d = 3;

defi.calc(obj, 'a', ['b', 'c', 'd'], (b, c, d) => b + c + d, {
    debounceCalcOnInit: true
});

console.log(obj.a); // undefined

In real world debounceCalcOnInit flag is unlikely to be useful. Just keep in mind that you can enable "total debounce" if needed.

A flag debounceCalcDelay=0

The flag can be used to set debounce delay when debounceCalc or debounceCalcOnInit is set as true.

A flag setOnInit=true

It is known that target property gets new value after calc is called. To cancel this behavior and don't calculate a property immediately use setOnInit with false value.

defi.calc(obj, 'a', 'b', b => b * 2, {
    setOnInit: false
});

console.log(obj.a); // undefined

// but if obj.b is changed the target property will be calculated
obj.b = 1;

A flag exactKey=false

As described above, it's possible to use a path to source property using a string that contains dots. In case if you need to use exact name of source property use exactKey with true value.

obj['foo.bar.baz'] = 1;
defi.calc(obj, 'a', 'foo.bar.baz', fooBarBaz => fooBarBaz * 2, {
    exactKey: true
});
console.log(obj.a); // 2

A flag promiseCalc=false

This flag allows to return Promise instance from the calculating function. Target property gets its value from resolved promise.

Warning! Promise cannot be canceled. Use the promiseCalc feature carefully and don't allow multiple calls of heavy functions.

defi.calc(obj, 'a', ['b', 'c'], (b, c) => {
    return new Promise(resolve => {
        setTimeout(() => {
            resolve(a + b)
        }, 1000);
    });
}, {
    promiseCalc: true
});

obj.b = 1;
obj.c = 2;

// "a" will be changed in a second

defi.calc(obj, 'response', 'data', async (data) => {
    const resp = await fetch(url, {
        method: 'post',
        body: data
    });

    return resp.json();
}, {
    promiseCalc: true
});

The first argument is an object whose keys are property names and values are objects with the following data:

• source - which properties the target property is depended on;
• handler - a function which returns a new value of a property (by default it equals to (value) => value);
• options - calc options.

The third argument contains common options which extend options of every item (but they still have higher priority than common options).

source can take any kind of look as described above (a string, an array of strings etc).

The function accepts any object and returns an instance of a class which adopts functions allowing them to be called in a chain.

Skip this section if you're using defi-react because React handles DOM rendering by its own.

Returns a binder corresponding to an element. If it is not found, it returns undefined. The function uses defi.defaultBinders for the search.

This function is used for transforming property value on its changing. For example, you want the property value to be always either of a certain type or an integer value, or to be no less than zero and no more than a hundred etc.

It deletes a handler which has been created before. All arguments (except of a target object of course) are optional. You can delete both all the events (without passing event names) and separate ones (having passed only the event name, the event name and the handler).

The function adds an event handler for an object. Refer to the complete list of possible events with the description here: eventNames. Also check out a short article about events.

In the defi.on function the object with the key-event pairs can be passed to avoid multiple invocation of the function.

The list of supported flags:

• silent - do not call the change and change:KEY events
• silentHTML - do not change states of bound HTML nodes
• force - call the change and change:KEY events even though the property value has not been changed
• forceHTML - change a state of bound element even though the property value has not been changed. This option is usable if the bound element has been rendered after the binding (for example, some option tags have been added to select tag)
• skipMediator - prevents the property transformation by defi.mediate
• skipCalc - prevents the work of dependencies created with defi.calc
• define - makes the property to be "listenable" by "change" event by setting defi-specific accessors

After adding event handlers using defi.on any event can be fired manually using this function.

Skip this section if you're using defi-react because React handles DOM rendering by its own.

Using this function you can delete a binding between a property and HTML node, which has been added recently and no longer needed.