montoux.follow.core — montoux/follow 1.0.0

Followers are a tool for bringing Functional Reactive Programming ideas to a ClojureScript stack, e.g. for use with React. A follower is a data transformation function raised to operate over state, where state can be encapsulated by Atoms, or other followers. When state changes, the follower will recompute its internal value and notify listeners so they can respond to the change.

When a state update occurs, the API performs a topological sort then updates followers in order to ensure that each follower will only recompute once per state change (each listener will only be called once).

Followers are stateful objects with references to their state sources, so they need to be cleaned up manually when they are no longer required (JavaScript Weak References are not widely available).

bind cljs

(bind follower & args)

Given an unbound follower created by lift, binds the follower to its arguments by adding watches. Binding will trigger an initial state calculation for the follower, and notify any watches that already exist that an initial state has been established. Once a follower has been bound it must be explicitly disposed by calling dispose, which will remove watches and destroy internal state. If provided, arguments should be refs that encapsulate appropriate state and match the follower's encapsulated function's arity.

disposable? cljs

(disposable? obj)

dispose cljs

(dispose follower)

Remove and dispose of a follower. JavaScript doesn't have widespread support for weak references yet, so followers must be disposed of manually.

follow cljs

(follow f & args)

Create a follower and binds it a list of IDeref/IWatchable refs in one step. The follower should be destroyed with dispose.

Follower cljs

follower? cljs

(follower? follower)

IDisposable cljs protocol

-dispose cljs

(-dispose this)

IFollower cljs protocol

-update cljs

(-update this)

Update the follower's cached state, if applicable. Returns [old new] states, or nil if no change.

latch cljs

(latch transform-fn)

(latch transform-fn initial-state)

Creates an object implements IFn and captures the result of applying transform-fn every time it is invoked. Implements IWatchable so observers will be notified with the new result every time it is invoked.

Latch cljs

lift cljs

(lift f & args)

Constructs an unbound follower from a function. The arity remains the same, but arguments to the follower should be stateful (refs). Arguments do not have to be provided here, they can be provided later with partial or bind. Followers constructed with lift do not need to be disposed, they are not linked until bind is called.

notify cljs

(notify ref old new)

This function should be invoked by API implementors when a state change has occurred for a particular follower. It will notify all listeners of the reference, then call update-all on any follower of the reference. Provides compatibility with cljs.core/-notify-all while supporting followers as well as atoms.

partial cljs

(partial follower & args)

Partially apply args (refs) to an unbound follower without binding the follower. Refs and their values should match the follower's encapsulated function's arity. This operation mutates the follower so that when it is bound the given refs will be derefed to provide arguments to the encapsulated function.

topo-sort cljs

(topo-sort children-fn xs)

Generic topological sort. children-fn should return a list of nodes reachable from the specified node.

topo-sort-followers cljs

(topo-sort-followers & followers)

Topologically sort the provided list of IWatch implementors using their 'watches' field. Returns a partially ordered list of reachable followers. Throws an exception if a cycle is detected.

update-all cljs

(update-all & followers)

This function should be invoked by API implementors when a state change has occurred that is known to affect a group of followers. The function will perform a topological sort of the followers, update them, then notify their listeners.