A collection of experimental utilities for working with Karet.

• Reference

This library provides a large number of named exports. Typically one just imports the library as:

import * as U from "karet.util"

Many of the functions in this library are lifted so that they accept both ordinary values and observables as inputs. When such functions are given only ordinary values as inputs, they return immediately with the result value. OTOH, when such a function is given at least an observable as an input, they return an observable of results. Lifted functions are indicated in this documentation by marking lifted arguments and results with an asterisk *.

U.seq allows one to pipe a value through a sequence of functions. In other words, U.seq(x, fn_1, ..., fn_N) is roughly equivalent to fn_N( ... fn_1(x) ... ). It serves a similar purpose as the ->> macro of Clojure or the |> operator of F# and Elm, for example, or the >| operator defined in a Usenet post by some rando.

For example:

U.seq(1, x => x + 1, x => -x)
// -2

A common technique in JavaScript is to use method chaining: x.fn_1().fn_2(). A problem with method chaining is that it requires having objects with methods. Sometimes you may need to manipulate values that are not objects, like null and undefined, and other times you may want to use functions that are not directly provided as methods and it may not be desirable to monkey patch such methods.

U.seq is designed to work with partially applied curried functions that take the object as their last argument and can be seen as providing a flexible alternative to method chaining.

U.seqPartial allows one to pipe a value through a sequence of function in such a way that if the value becomes undefined the process is stopped and undefined is returned without calling the remaining functions.

U.scope simply calls the given thunk. IOW, U.scope(fn) is equivalent to (fn)(). You can use it to create a new scope at expression level.

For example:

U.scope((x = 1, y = 2) => x + y)
// 3

U.toPartial takes the given function and returns a curried version of the function that immediately returns undefined if any of the arguments passed is undefined and otherwise calls the given function with arguments.

For example:

U.toPartial((x, y) => x + y)(1, undefined)
// undefined

U.toPartial((x, y) => x + y)(1, 2)
// 3

U.show logs the given value to console and returns the value.

U.refTo is designed for getting a reference to the DOM element of a component:

const Component = ({dom = U.variable()}) =>
  <div ref={U.refTo(dom)}>
    ...
  </div>

React calls the ref callback with the DOM element on mount and with null on unmount. However, U.refTo does not write null to the variable. The upside of skipping null and using an initially empty variable rather than an atom is that once the variable emits a value, you can be sure that it refers to a DOM element.

U.cns is designed for creating a list of class names for the className property. It concatenates the given optional strings with a space between.

For example:

U.cns("a-class-name", false, "another-one", undefined)
// "a-class-name another-one"

U.getProps returns an event callback that gets the values of the properties given in the template from the event target.

For example:

const TextInput = ({value}) =>
  <input type="text"
         value={value}
         onChange={U.getProps({value})}/>

const Checkbox = ({checked}) =>
  <input type="checkbox"
         checked={checked}
         onChange={U.getProps({checked})}/>

U.mapElemsWithIds perform a cached incremental map over state containing an array of values with unique ids. On changes, the mapping function is only called for elements that were not in the state previously. U.mapElemsWithIds is particularly designed for rendering a list of potentially stateful components efficiently.

For example:

const state = U.atom([
  {id: 1, value: "Keep"},
  {id: 2, value: "Calmm"},
  {id: 3, value: "and"},
  {id: 4, value: "React!"}
])

const Elems = ({elems}) =>
  <ul>
    {U.seq(elems,
           U.mapElemsWithIds("id", (elem, id) =>
             <li key={id}>{U.view("value", elem)}</li>))}
  </ul>

U.mapElemsWithIds is asymptotically optimal in the sense that any change (new elements added or old elements removed, positions of elements changed, ...) has Theta(n) complexity. That is the best that can be achieved with plain arrays.

U.bus() creates a new observable Bus stream. A Bus stream has the following methods:

• bus.push(value) to explicitly emit value value,
• bus.error(value) to explicitly emit error error, and
• bus.end() to explicitly end the stream after which all the methods do nothing.

Kefir operations in curried form.

Ramda functions lifted to take Kefir observables.