simple-bound
A simple data binding library for node and browser with no dependencies.
npm install --save simple-bound
For more options see installation
Why?
Many JavaScript libraries and frameworks use some form of data-binding under the hood. That binding usually comes in various shapes and sizes, all of which end up in the "vendor" part of your project. But currently there's no truly utilitary and versatile solution. So most of the time you want to use the power of, let's say, two-way binding in you own library or project - you have to code that part from scratch.
Bound
aims to change that.
Bound
is currently in the alpha state, there might be some a lot of bugs. Feel free to report them in the issues section. 🙂
Table of contents
What is Bound?
Bound is a small and customizable library that allows precise data binding management.
But what is data binding?
Data binding is a general technique that binds data sources of two general types (provider
and consumer
, master
and slave
) and syncronizes them.
For example, let's imagine two objects bound together using this technique:
object1 /* { property: 'value'} */ object2 /* { property: 'value'} */ object1property = 'new value'console // outputs 'new value' object2property = 'another value'console // outputs 'another value'
As we can see here, both objects seem to react to changes in one another, updating their properties reactively.
Most applications and frameworks use this approach to synchronize their models and views, as described in this article.
But data-binding is not only useful for synchronizing views to models - there are a lot of applications as use-cases for this technique. And Bound
aims to cover as most of them as possible.
It does not focus entirely on model-view data-binding, but rather tries to encapsulate the whole concept of data binding, allowing you to control where your bindings go and what your bindings do.
General concepts
All "members" of the data-binding relationship can be called subscribers. There are two general types of data flow between subscribers in data-binding: two-way (when both objects' properties react to each other, example above) and one-way.
In one-way data-binding there exist two types of binding subscribers:
- "masters" - dictate changes to all other subscribers in the relationship.
- "slaves" - accept changes from masters but cannot broadcast/dicate their own changes
Bound
allows to handle both one-way and two-way data bindings with ease.
Installation
Install as dependency
npm install --save simple-bound# or yarn add simple-bound
Import and use
ES
// You also can import separate modules:
CommonJS
const Bound = default;
Script tag
Simple example
Let's say you want to bind two objects together in a way that a change to one object would automatically change the other.
It's very simple to do with Bound
:
const obj1 = prop: 'foo'; const obj2 = prop: 'foo'; // Send the proto object to snapshot the structure.const bound = obj1 /* Used for snapshoting the object structure, not for the actual binding */; // Bind both objects via Bound instance:bound;bound; obj1prop = 'bar';console;// -> "bar"// Magic!
How it works
Binding relationships
Each time a new binding relationship is created, the data is stored inside that relationship. After that, subscribers can be added to the relationship.
Each "master" subscriber's value points to the value inside the relationship, therefore automatically sharing it with others:
let obj = test: 'foo' ;let obj2 = test: 'foo' ; const binding = /* twoWay */ true /* defaultValue */ ''; binding;binding; // Now both obj.test and obj2.test point to the same variable inside `binding`
Each "slave" subscriber's value remains within its original container, but is updated whenever a master's value changes via a notification:
let obj = test: 'foo' ;let obj2 = test: 'foo' ; const binding = /* twoWay */ false /* defaultValue */ ''; binding;binding; obj2test = 'bar'; // Nothing happens here, obj.test is still 'foo' objtest = 'new value'; // Notification is sent to obj2, updating its `test` property to 'new value'
Object relationships
The Bound
class groups relationships together in a form of an object to subscribe all of their fields to changes.
Essentially, it maps all bound object's properties to their binding relationships using internal storage that contains these relationships in a map identical to the object itself.
API
API can seem a bit tricky at first, because the concept of data-binding does not imply any uniformal way of doing it.
We recommend checking out an interactive playground at RunKit for better intuitive understanding of how things work.
TLDR
Click to expand
; // Creates a Bound instance from an object snapshotconst bound = test: 'foo' nested: property: 2 ; boundboundObject // The first actual bound object.boundstorage // Stores bindings in a structure identical to the original object. let obj = test: 'foo' let obj2 = test: 'foo' // Creates a Bound instance from the object and returns instance.boundObjectconst justABoundObject = ; justABoundObject__bound__ // Bound instancejustABoundObject__bound__; justABoundObjecttest = 'bar';console; // -> "bar" justABoundObject__bound__storage // { test: Binding {} }justABoundObject__bound__boundObject // === justABoundObject obj = justABoundObject__bound__; // obj is now free from bindings // Binding classconst binding = /* twoWay */ false /* defaultValue */ ''; binding;binding; // Updates all subscribersbinding; // obj.test === 'test' && obj2.test === 'test' // Master: updates all subscribersobjtest = 'foo'; // obj2.test === 'foo' && binding.get() === 'foo' // Slave: updates only itselfobj2test = 'bar'; // obj.test === 'foo' && binding.get() === 'foo' // Master: updates all subscribersobjtest = 'baz'; // obj2.test === 'baz' && binding.get() === 'baz' binding; // By object referencebinding; // By indexbinding;
Binding
Stores and updates single property bindings.
Can be thought of as a primitive in terms of data-binding.
Its main responsibility is to manage single-property bindings, hence the name - Binding
as in "one, single binding".
It helps to manipulate bindings on the lowest possible level.
Creation of a Binding
instance is equivalent to the creation of a new data-binding relationship.
Each newly added member "subscribes" to notifications about changes in the relationship's value.
Binding constructor
/* is always two-way */ false /* default initial value */ 'value'
argument | type | description |
---|---|---|
twoWay | boolean |
Determines if all the bindings associated with the instance should be two-way |
defaultValue | any |
Sets the default value for subscribers that do not have a value. |
Binding instance
const instance = false 'value';
Properties
instance.subscribers: Array<ISubscriber>Contains an array of subscribers in the following format:
obj: subscriberObjectprop: 'subscriberObjectPropertyKey'role: 'slave' | 'master' | undefined
instance.twoWay: booleanREAD-ONLY
Defines if a binding should always be 2-way and ignore roles.
instancevaluePROTECTED
Stores the value of the binding relationship for "masters".
instance.plugins: Array<IBindingPlugin>An array of plugins to use.
Methods
instanceA generic get function that is applied to subscribers. Gets
instance.value
.
intanceA generic set function that is applied to subscribers. Sets
instance.value
and notifies subscribers.
instanceAsynchroniously notifies slave subscribers about the value change.
instanceBinds an object prop and subscribes it to master-subscribers' changes.
instanceinstanceBinds an object prop as a master or slave and subscribes it to master-subscribers' changes
instance // by referenceinstance // by indexUnbinds an object's property and unsubscribes it from changes.
instanceClears all subscribers from the binding.
Binding static fields
Bindingconfig ===debug: falseGlobal binding config. Changes affect all instances.
BindingChecks subscribers' objects for reference and prop-name equality.
Bound
Allows multiple full-object bindings.
Stores bindings and binds objects together, providing the highest possible abstraction level for bindings.
Bound constructor
property: 'value'
Creates an instance of Bound using a proto object.
Bound instance
const bound = property: 'value' ;
Bound properties
bound.storage: IBindingStorageStores bindings in a structure that is identical to the binding-prototype-object.
boundboundObjectA bound object created from a constuctor's snapshot object. Contains an instance of the Bound class itself by the
__bound__
key.
Bound methods
boundBinds an object to all other current subscribers. If the second argument is false
boundUnbinds an object and destroys all of its listeners
Bound static fields
Boundconfig ===debug: falseGlobal binding config. Changes affect all instances.
BoundChecks whether an object has already been bound.
Coming Soon
- Plugins
- Event listeners
- Interceptors and pipes (maybe?)