Class: Binding

Binding

Wraps immutable collection. Provides convenient read-write access to nested values. Allows to create sub-bindings (or views) narrowed to a subpath and sharing the same backing value. Changes to these bindings are mutually visible.

Terminology:

  • (sub)path - path to a value within nested associative data structure, example: 'path.t.0.some.value';
  • backing value - value shared by all bindings created using sub method.

Features:

  • can create sub-bindings sharing same backing value. Sub-binding can only modify values down its subpath;
  • allows to conveniently modify nested values: assign, update with a function, remove, and so on;
  • can attach change listeners to a specific subpath;
  • can perform multiple changes atomically in respect of listener notification.

Constructor

new Binding(pathopt, sharedInternalsopt)

Binding constructor.
Parameters:
Name Type Attributes Description
path Array.<String> <optional>
binding path, empty array if omitted
sharedInternals Object <optional>
shared relative bindings internals:
  • backingValue - backing value;
  • metaBinding - meta binding;
  • metaBindingListenerId - meta binding listener id;
  • listeners - change listeners;
  • cache - bindings cache.
Source:
See:

Members

(static) META_NODE :String

Meta node name.
Type:
  • String
Deprecated:
  • Use Util.META_NODE instead.
Source:

Methods

(static) asArrayPath(pathAsString) → {Array}

Convert string path to array path.
Parameters:
Name Type Description
pathAsString String path as string
Source:
Returns:
path as an array
Type
Array

(static) asStringPath(pathAsAnArray) → {String}

Convert array path to string path.
Parameters:
Name Type Description
pathAsAnArray Array.<String> path as an array
Source:
Returns:
path as a string
Type
String

(static) init(backingValueopt, metaBindingopt) → {Binding}

Create new binding with empty listeners set.
Parameters:
Name Type Attributes Description
backingValue Immutable.Map <optional>
backing value, empty map if omitted
metaBinding Binding <optional>
meta binding
Source:
Returns:
fresh binding instance
Type
Binding

addListener(subpathopt, cb) → {String}

Add change listener.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
cb function function receiving changes descriptor
Source:
See:
Returns:
unique id which should be used to un-register the listener
Type
String

addOnceListener(subpathopt, cb) → {String}

Add change listener triggered only once.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
cb function function receiving changes descriptor
Source:
See:
Returns:
unique id which should be used to un-register the listener
Type
String

atomically(promiseopt) → {TransactionContext}

Create transaction context. If promise is supplied, transaction will be automatically cancelled and reverted (if already committed) on promise failure.
Parameters:
Name Type Attributes Description
promise Promise <optional>
ES6 promise
Source:
Returns:
transaction context
Type
TransactionContext

clear(subpathopt) → {Binding}

Clear nested collection. Does '.clear()' on Immutable values, nullifies otherwise.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
Source:
Returns:
this binding
Type
Binding

disableListener(listenerId) → {Binding}

Disable listener.
Parameters:
Name Type Description
listenerId String listener id
Source:
Returns:
this binding
Type
Binding

enableListener(listenerId) → {Binding}

Enable listener.
Parameters:
Name Type Description
listenerId String listener id
Source:
Returns:
this binding
Type
Binding

get(subpathopt) → {*}

Get binding value.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
Source:
Returns:
value at path or null
Type
*

getPath() → {Array}

Get binding path.
Source:
Returns:
binding path
Type
Array

isChanged(alternativeBackingValue, compareopt)

Check if binding value is changed in alternative backing value.
Parameters:
Name Type Attributes Description
alternativeBackingValue Immutable.Map alternative backing value
compare function <optional>
alternative compare function, does reference equality check if omitted
Source:

isRelative(otherBinding) → {Boolean}

Check if this and supplied binding are relatives (i.e. share same backing value).
Parameters:
Name Type Description
otherBinding Binding potential relative
Source:
Returns:
Type
Boolean

merge(subpathopt, preserveopt, newValue) → {Binding}

Deep merge values.
Parameters:
Name Type Attributes Default Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
preserve Boolean <optional>
false preserve existing values when merging
newValue * new value
Source:
Returns:
this binding
Type
Binding

meta(subpathopt) → {Binding}

Get binding's meta binding.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers; b.meta('path') is equivalent to b.meta().sub('path')
Source:
Returns:
meta binding or undefined
Type
Binding

remove(subpathopt) → {Binding}

Delete value.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
Source:
Returns:
this binding
Type
Binding

removeListener(listenerId) → {Boolean}

Un-register the listener.
Parameters:
Name Type Description
listenerId String listener id
Source:
Returns:
true if listener removed successfully, false otherwise
Type
Boolean

set(subpathopt, newValue) → {Binding}

Set binding value.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
newValue * new value
Source:
Returns:
this binding
Type
Binding

sub(subpathopt) → {Binding}

Bind to subpath. Both bindings share the same backing value. Changes are mutually visible.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
Source:
Returns:
new binding instance, original is unaffected
Type
Binding

toJS(subpathopt) → {*}

Convert to JS representation.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
Source:
Returns:
JS representation of data at subpath
Type
*

unlinkMeta() → {Boolean}

Unlink this binding's meta binding, removing change listener and making them totally independent. May be used to prevent memory leaks when appropriate.
Source:
Returns:
true if binding's meta binding was unlinked
Type
Boolean

update(subpathopt, f) → {Binding}

Update binding value.
Parameters:
Name Type Attributes Description
subpath String | Array <optional>
subpath as a dot-separated string or an array of strings and numbers
f function update function
Source:
Returns:
this binding
Type
Binding

withBackingValue(newBackingValue) → {Binding}

Update backing value.
Parameters:
Name Type Description
newBackingValue Immutable.Map new backing value
Source:
Returns:
new binding instance, original is unaffected
Type
Binding

withDisabledListener(listenerId, f) → {Binding}

Execute function with listener temporarily disabled. Correctly handles functions returning promises.
Parameters:
Name Type Description
listenerId String listener id
f function function to execute
Source:
Returns:
this binding
Type
Binding