Advanced purely functional Value Links for React, implemented with TypeScript

This package is dependency-free implementation of value links with powerful API extensions.

• Features:
  • Support for pure render optimization.
  • Purely functional updates of enclosed objects and arrays.
  • Declarative binding to UI event handlers.
  • Form validation.
  • Offhand boolean link creation for checkboxes and radio groups.
  • Backward compatible with standard React 0.14 links API
  • TypeScript source and type definitions.

React 15.x will remove built-in value link support from standard controls, so reference implementation of 'linked' tags is included. - Standard tags: <Input /> (with validation), <Select />, <TextArea /> - Custom tags: <Radio />, <Checkbox />

var linkToArray = Link.state( this, 'phonebook' );

var list = linkToArray.map( ( itemLink, i ) => (
    <div key={ i }>
        <Input valueLink={ itemLink.at( 'name' ) } />            
    </div>
));

This technology is one of the key components of NestedReact architecture, helping you to build large-scale React applications with a powerful and fast NestedTypes classical OO models.

Changes in 1.2

• Rewritten with TypeScript. Type definitions are available in valuelink.d.ts
• Link.state now cache unchanged links in the component, so pure render optimization now works with value links.
• link.action behaves as link.update in 1.x. Rename.
  • Use Link.value( value, requestChange ) to create custom links, or...
  • ...extend Link class to create your custom bindings. For an example, see an implementation of StateLink.

Installation

npm install valuelink

CommonJS module, MIT License. No side dependencies.

// Links
import Link from 'valuelink'

// You'll need this components with React 15.x instead of standard ones.
import { Input, TextArea, Select, Radio, Checkbox } from 'valuelink/tags.jsx'

API

Create link

• Create custom link: Link.value( value, requestChange )

  var customLink = Link.value( this.value, x => this.value = x );

• Create link to react component's state attribute:

  var nameLink = Link.state( this, 'name' );

For TypeScript users. Link actually is parametric type Link< T >, where T is the type of the enclosed value. And both Link.value< T > and Link.state< T > are parametric functions. For Link.state type is always inferred as Object, so you can refine it manually:

```javascript
const nameLink = Link.state< string >( this, 'name' );
```

Update link

• Set link value: link.set( x ) or link.requestChange( x )

  <button onClick={ () => boolLink.set( !boolLink.value ) } />

• Purely functional link value: link.update( prevValue => newValue ). Plain objects and arrays are shallow copied by update and action functions, thus it's safe just to update the value in place.

  <button onClick={ () => boolLink.update( x => !x ) } />
      <button onClick={ () => objLink.update( obj => {
                                  obj.a = 1;
                                  return obj;
                              }) } />
  

• Create action to handle UI event: link.action( ( prevValue, Event ) => newValue )

  <button onClick={ boolLink.action( x => !x ) } />
  ...
  const setValue = ( x, e ) => e.target.value;
  ...
  <input  value={ link.value }
          onChange={ link.action( setValue ) } />

Links validation

Links has link.check( condition, error = 'Invalid value' ) method which can be used to check the sequence of conditions. Checks can be chained.

condition is predicate function linkValue => isValid taking link value as an argument. Whenever condition returns falsy value, link.error will take the value of corresponding error. link.error field may be analyzed by custom <Input /> control to indicate an error.

This mechanics can be used to add ad-hoc validation in render.

• Simple asserts:

  var numLink = List.state( this, 'num' )
                  .check( x => x >= 0 && x <=5 );
                  
  console.log( numLink.error );                    

• Validation asserts with custom error objects

  var numLink = List.state( this, 'num' )
                  .check( x => x >= 0 && x <=5, 'Number must be between 0 and 5' );
                  
  console.log( numLink.error );                    

• Chained validation asserts

  var numLink = List.state( this, 'num' )
                  .check( x => x >= 0, 'Negative numbers are not allowed' )
                  .check( x => x <= 5, 'Number should be not greater than 5' );
                  
  console.log( numLink.error );                    

Links to object and arrays

If linked value is plain object or array, it's possible to generate links to their members. Whenever this derivative links will be updated, it will lead to proper purely functional update of the whole structure. I.e. if you have array in component state, and link to its element will be updated, it will lead to proper update of stateful component.

• Take link to array or object member: link.at( key )

      const firstElementLink = arrayLink.at( 0 );

  or

      const nameLink = objectLink.at( 'name' );

• Map and filter through array or object: link.map( iterator )

  var list = stringArrayLink.map( ( itemLink, index ) => {
      if( itemLink.value ){        
          return (
              <div key={ index }>
                  <Input valueLink={ itemLink } />            
              </div>
          );
      }
  });

Offhand boolean links

• Link to the presence of value in array: arrayLink.contains( value )

  const optionXLink = arrayLink.contains( 'optionX' );

• Link to value equality: link.equals( value )

  const optionXLink = stringLink.equals( 'optionX' );

Data binding examples

Here are the set of working examples for typical data binding use cases. Sources are here.