re-frame-lib.subs — jfigueroama/re-frame 0.11.0-rc1

cache-and-return clj/s

(cache-and-return state query-v dynv r)

cache the reaction r

cache-lookup clj/s

(cache-lookup state query-v)

(cache-lookup state query-v dyn-v)

clear-all-handlers! clj/s

(clear-all-handlers! state)

Unregisters all existing subscription handlers.

clear-subscription-cache! clj/s

(clear-subscription-cache! state)

Causes all subscriptions to be removed from the cache. Does this by:

1. running on-dispose on all cached subscriptions
2. These on-dispose will then do the removal of themselves.

This is a development time tool. Useful when reloading Figwheel code after a React exception, because React components won't have been cleaned up properly. And this, in turn, means the subscriptions within those components won't have been cleaned up correctly. So this forces the issue.

kind clj/s

map-signals clj/s

(map-signals f signals)

Runs f over signals. Signals may take several forms, this function handles all of them.

reg-sub clj/s

(reg-sub state query-id & args)

For a given query-id, register a computation function inside the re-frame state and input signals.

At an abstract level, a call to this function allows you to register 'the mechanism' to later fulfil a call to (subscribe state [query-id ...]).

To say that another way, reg-sub allows you to create a template for a node in the signal graph. But note: reg-sub does not cause a node to be created. It simply allows you to register the template from which such a node could be created, if it were needed, sometime later, when the call to subscribe is made.

reg-sub needs four things:

• a state, which is the re-frame state created with new-state in core ns
• a query-id
• the required inputs for this node
• a computation function for this node

The query-id is always the 1st argument to reg-sub and it is typically a namespaced keyword.

A computation function is always the last argument and it has this general form: (input-signals, query-vector) -> a-value

What goes in between the 1st and last args can vary, but whatever is there will define the input signals part of the template, and, as a result, it will control what values the computation functions gets as a first argument.

There's 3 ways this function can be called - 3 ways to supply input signals:

1. No input signals given:

   (reg-sub state :query-id a-computation-fn) ;; (fn [db v] ... a-value)

   The node's input signal defaults to app-db, and the value within app-db is is given as the 1st argument to the computation function.

2. A signal function is supplied:

   (reg-sub state :query-id signal-fn ;; <-- here computation-fn)

   When a node is created from the template, the signal-fn will be called and it is expected to return the input signal(s) as either a singleton, if there is only one, or a sequence if there are many, or a map with the signals as the values.

   The values from the nominated signals will be supplied as the 1st argument to the computation function - either a singleton, sequence or map of them, paralleling the structure returned by the signal function.

   Here, is an example signal-fn, which returns a vector of input signals.

   (fn [query-vec dynamic-vec] [(subscribe [:a-sub]) (subscribe [:b-sub])])

   For that signal function, the computation function must be written to expect a vector of values for its first argument. (fn [[a b] _] ....)

   If the signal function was simpler and returned a singleton, like this: (fn [query-vec dynamic-vec] (subscribe [:a-sub]))

   then the computation function must be written to expect a single value as the 1st argument:

   (fn [a _] ...)

3. Syntax Sugar

   (reg-sub state :a-b-sub :<- [:a-sub] :<- [:b-sub] (fn [[a b] [_]] {:a a :b b}))

This 3rd variation is syntactic sugar for the 2nd. Pairs are supplied instead of an input signals functions. Each pair starts with a :<- and a subscription vector follows.

For further understanding, read /docs, and look at the detailed comments in /examples/todomvc/src/subs.cljs

subscribe clj/s

(subscribe state query)

(subscribe state query dynv)

Given a re-frame state and a query, returns a Reagent reaction which, over time, reactively delivers a stream of values. So in FRP-ish terms, it returns a Signal.

To obtain the returned Signal/Stream's current value, it must be derefed.

state is a re-frame state created with the re-frame-lib.core/new-state fn.

query is a vector of at least one element. The first element is the query-id, typically a namespaced keyword. The rest of the vector's elements are optional, additional values which parameterise the query performed.

dynv is an optional 3rd argument, `which is a vector of further input signals (atoms, reactions, etc), NOT values. This argument exists for historical reasons and is borderline deprecated these days.

Example Usage:

(subscribe state [:items]) (subscribe state [:items "blue" :small]) (subscribe state [:items {:colour "blue" :size :small}])

Note: for any given call to subscribe there must have been a previous call to reg-sub, registering the query handler (function) for the query-id given.

Hint

When used in a view function BE SURE to deref the returned value. In fact, to avoid any mistakes, some prefer to define:

(def <sub (comp deref (partial re-frame-lib.core/subscribe state)))

And then, within their views, they call (<sub [:items :small]) rather than using subscribe directly.

De-duplication

XXX

to-seq clj/s

(to-seq x)

Coerces x to a seq if it isn't one already