Completely boilerplate-free

• State is stored in modifiable and observable atoms (more about this in a minute)
• No glue code needed to transform external state into props or internal React component state
• No need for

  
  Bacon.combineTemplate({
    todos: todosProperty,
    counter: counterProperty
  })
    .takeUntil(componentUnmountStream)
    .onValue(state => this.setState(state))
                    

• ... or ...

  
  const mapStateToProps = (state, ownProps) => ({
    todos: state.todos,
    counter: state.counter
  })
  const mapDispatchToProps = ...
  const WrappedComponent = connect(mapStateToProps, mapDispatchToProps)(TodoComponent)
                    

• ... etc.

Observable life-cycle is automatic

• Calmm subscribes to your observables when a component is mounted
• ... and unsubscribes when unmounted
• ... but only when the VDOM path is actually being rendered:

  
  const UselessComponent = ({ observable }) =>
    <div>
      {new Date().getFullYear() >= YEAR_OF_LINUX_DESKTOP
        ? observable
        : 'The year of the desktop linux desktop is not yet here'}
    </div>
                    

  observable is only subscribed to if the year of linux desktop has been reached.

• Enables you to lazily process dependent computations, which is very useful for expensive computations, or computations that may not need to be processed at all.
• ... and you get this without writing a single line of extra code.

When an observable changes only the relevant part of the VDOM is updated

  const MyComponent = ({ observable }) =>
    <div>
      <ComplexComponent />
      The value of observable is: <strong>{observable}</strong>
    </div>
              

• When observable changes, only the strong element is re-rendered
• Fast incremental VDOM updates
• No need for shouldComponentUpdate
• Eliminates need for render optimization in vast majority of cases
• There are exceptions though

You can write your components using functional React components

• No need for createClass or React.Component
• The function is only called once, on mount
• Concise components, with a lot of the React boilerplate removed

Example: working with values and observables

const MultiplyByTwo = ({ number }) => <div>{number * 2}</div>
              

Does not work with observables.

const MultiplyByTwo = ({ number }) => <div>{number.map(it => it * 2)}</div>
              

Does not work with plain values.

import * as U from 'karet.util'
import * as R from 'kefir.ramda'

const MultiplyByTwoA = ({ number }) => <div>{U.mapValue(it => it * 2, number)}</div>
const MultiplyByTwoB = ({ number }) => <div>{R.multiply(number, 2)}</div>
              

Works with both!

U.mapValue and R.multiply are lifted to work with both plain values and observables.

Lifted functions

• If you have a function that works with plain values, lifting it means that the lifted version can accept plain values and observables as arguments.
• When a lifted function is called with only plain values as arguments, the result is computed immediately and is also a plain value.
• When any of the arguments is an observable, the result is an observable as well.
• karet.util (and baret.util) contain a lot of useful utility functions, many of which are lifted.
• Calmm also has a few wrapper libraries that lift the functions of the wrapped libraries, i.e. kefir.ramda and kefir.partial.lenses.
• It is easy to lift your own functions to work with observables:

  
  import * as U from 'karet.util'
  
  const includes = U.lift((xs, x) => xs.includes(x))
  const obsOfBooleans = includes(obsOfArrays, obsOfValues)
                    

Examples of lifted utility functions in calmm

const PositiveAndLessThan100 = ({ number }) =>
  <div>
    Is {number} positive and less than 100:
    {U.ifElse(
      U.and(R.gte(number, 0), R.lt(number, 100)),
      'yes',
      'no')}
  </div>
              

Also possible to write

const PositiveAndLessThan100 = ({ number }) => {
  const test = U.lift(number => number >= 0 && number < 100)
  return (
    <div>
      Is {number} positive and less than 100: {U.ifElse(test(number), 'yes', 'no')}
    </div>
  )
}
              

or

const PositiveAndLessThan100 = ({ number }) =>
  <div>
    Is {number} positive and less than 100:
    {U.mapValue(number => (number >= 0 && number < 100) ? 'yes' : 'no', number)}
  </div>
              

If you have complex conditions it is sometimes useful to break down the logic into a separate lifted function for readability.

Examples of lifted utility functions in calmm

• What you saw in the previous examples were examples of dependent computations.
• When the inputs change, so do the outputs. The output can be a plain value, instance of a component, etc.
• When the observables change, the dependent computations are re-run, keeping your UI consistent with your application state.
• Even complex and asynchronous computations are quite trivial compared to many other tools.

Example of an asynchronous dependent computation

const Search = ({ text = U.atom('') }) => {
  const getSearchUrl = text => `https://my.api/search?text=${encodeURIComponent(text)}`

  const results = U.thru(
    text,
    U.debounce(300),
    U.flatMapLatest(text => U.thru(
      U.fromPromise(() => fetch(getSearchUrl(text))),
      U.startWith(undefined)
    )),
    U.startWith([])
  )

  return (
    <div>
      <U.Input value={text} />
      {U.ifElse(
        R.is(Array, results),
        <ul>
          {U.mapElems((result, i) => <li key={i}>{result}</li>, results)}
        </ul>,
        'Loading'
      )}
    </div>
  )
}
              

Example: decompose state to child components

const counters = Atom([0, 0, 0])

<Counter count={counters.view(0)} />
<Counter count={counters.view(1)} />
<Counter count={counters.view(2)} />
              

Example: filter a list to only show some elements

const todos = Atom([
  { title: 'Wash laundry', finished: false },
  { title: 'Buy groceries', finished: true },
  { title: 'Clean kitchen', finished: false }
])

const TodoList = ({ todos }) =>
  <div>
    <h2>Todo</h2>
    {U.mapElems(
      (todo, i) => <TodoItem key={i} todo={todo} />,
      todos
    )}
  </div>

const UnfinishedTodos = ({ todos }) => {
  const onlyUnfinishedLens = L.filter(todo => !todo.finished)
  return <TodoList todos={todos.view(onlyUnfinishedLens)} />
}
              

Example: change a value in an object

const obj = Atom({
  foo: {
    bar: [1, 2, 3]
  }
})

// focus the 2nd element of the foo.bar array
const slice = obj.view(['foo', 'bar', 1])

slice.set(20)
obj.get() // { foo: { bar: [ 1, 20, 3 ] }}

slice.modify(R.multiply(2))
obj.get() // { foo: { bar: [ 1, 40, 3 ] }}
              

Example: append a value to a list

const list = Atom({ items: ['x', 'y'] })
list.modify(L.set(['items', L.append], 'z'))
list.get() // { items: ['x', 'y', 'z'] }
              

const list = Atom({ items: ['x', 'y'] })
list.modify(L.set(['items'], 'z'))
list.get() // { items: 'z' }
                

const list = Atom(['x', 'y'])
list.modify(R.append('z')) // list.modify(L.set(L.append, 'z'))
list.get() // ['x', 'y', 'z']
                

Example: remove a value from a list

const list = Atom(['x', 'y', 'z'])
list.modify(L.remove(1))
list.get() // ['x', 'z']
              

Lensed atoms can also remove themselves

const list = Atom(['x', 'y', 'z'])
const item = list.view(1)
item.remove()
list.get() // ['x', 'z']
              

This is a very useful pattern when you want to have removable UI components where the remove button is in the removable component itself.

Lenses/optics are very powerful, this is just scratching the surface

• Fetch data from API and transform into format that UI expects.
• Make changes via UI, lenses are bidirectional so you can instantly PUT changes back to API. Just define the format of your data via lenses once.
• Define default & required values.
• Not just lenses. Traversals and isomorphisms.

• Define this.state.editing as an atom that is passed via an argument. You can use U.atom from karet.util library instead of having to import kefir.atom only for Atom definition.
• Refactor the edit and done buttons to change the state of the editing atom.
• Use U.view to decompose the contact prop into name, phone and email values; it works with plain values as well as atoms (our contact prop is a plain value for now).
• Use U.ifElse to determine whether the contact is being edited or not.
• After your component is no longer a class, you can remove the Component import.

• U.mapElems works with plain values as well. Our contacts prop is still a plain value for now.

• Use the existing plain state object as a default value for the atom.
• You can either use state.view(lens) or U.view(lens, state) to decompose the state atom. When using U.view you never need to worry whether the input is an atom or a plain value.
• Show the value of the state atom in a HTML element so you can see how it changes. Add the following to the root App component in index.js:

  <pre>{U.stringify(state, null, 2)}</pre>

• By now you have decomposed state all the way down to the Contact component. Implement onChange handler for the text input to update the corresponding atom's value.
• Alternatively you can use a convenient utility component U.Input.

• Atoms (and LensedAtoms) can easily be removed with atom.remove.

• Append an object with empty string (or any default value you want) for name, email and phone at the end of the contacts array in the state atom.

• Tip: U.cns is an useful utility function for this.
• Tip: U.cns is lifted, so you can give observables as inputs. U.when is quite useful also.

• Tip: Persist the editing state of a contact in the contacts atom instead of component local state.
• Tip: In the ContactList component create a derived computation which searches for a contact where the editing is set to true.

Bonus tasks

1. Add a search text input and filter the visible contacts by it. Persist the search text value in the root atom. L.filter will be useful.
2. Persist the root contact atom in local storage using the atom.storage library.
3. Add validation to the contact editing. Validate the email and phone number using the partial.lenses.validation library.

Example: Passing observables to non-calmm components

import * as React from 'karet'
import { Map } from '3rd-party-map'

<Map position={currentPositionAtom} />
              

React will throw an error if you try to pass an observable to the Map component, since it doesn't use karet/baret.

Easy way to fix this is using karet-lift attribute. If the Map component is used a lot, you can also create a lifted version of the component and use that.

import * as React from 'karet'
import * as U from 'karet.util'
import { Map } from '3rd-party-map'

const LiftedMap = React.fromClass(Map)
const LiftedMap2 = U.toKaret(Map) // this does the same

<Map position={currentPositionAtom} karet-lift />
<LiftedMap position={currentPositionAtom} />
              

Now the Map component will receive the position as a plain value.

Example: Using calmm components as children of non-calmm components

Calmm components should only render when they're mounted. If you're using calmm components as children of a non-calmm component this behavior is likely to break, because the parent container is being re-rendered which also causes the calmm components to re-render.

karet.util library has an useful utility function U.toReact which converts plain value props into observable props and stops re-rendering of the calmm component.

import * as U from 'karet.util'
import CalmmComponent from './components/calmm-component'

const CalmmComponentInterop = U.toReact(CalmmComponent)

class ReactComponent extends React.Component {
  render() {
    return <CalmmComponentInterop {...this.props} />
  }
}
              

Especially useful with libraries such as react-router.