com.fulcrologic.fulcro.algorithms.normalized-state — com.fulcrologic/fulcro 3.1.20

Functions that can be used against a normalized Fulcro state database. This namespace also includes some handy aliases to useful functions that work on normalized state from other namespaces.

dissoc-in clj/s

(dissoc-in m [k & ks :as keys])

Dissociates an entry from a nested associative structure returning a new nested structure. keys is a sequence of keys. Any empty maps that result will not be present in the new structure.

The ks is not ident-aware. This function is here simply because it is often needed, and clojure.core does not supply it.

get-in-graph clj/s

(get-in-graph state-map path)

(get-in-graph state-map path not-found)

Like clojure.core/get-in, but as it traverses the path it will follow idents in the state-map. This makes it similar to a very targeted db->tree, but allows you to get something along a particular path without needing to parse a query.

Returns the data at the path, not-found (if specified) if nothing is found; otherwise nil.

See also tree-path->db-path.

integrate-ident clj/s

[state ident & named-parameters]

Integrate an ident into any number of places in the app state. This function is safe to use within mutation implementations as a general helper function.

The named parameters can be specified any number of times. They are:

• append: A vector (path) to a list in your app state where this new object's ident should be appended. Will not append the ident if that ident is already in the list.
• prepend: A vector (path) to a list in your app state where this new object's ident should be prepended. Will not place the ident if that ident is already in the list.
• replace: A vector (path) to a specific location in app-state where this object's ident should be placed. Can target a to-one or to-many. If the target is a vector element then that element must already exist in the vector.

NOTE: ident does not have to be an ident if you want to place denormalized data. It can really be anything.

Returns the updated state map.

remove-entity clj/s

(remove-entity state-map ident)

(remove-entity state-map ident cascade)

Remove the given entity at the given ident. Also scans all tables and removes any to-one or to-many idents that are found that match ident (removes dangling pointers to the removed entity).

The optional cascade parameter is a set of keywords that represent edges that should cause recursive deletes (i.e. it indicates edge names that own something, indicating it is safe to remove those entities as well).

Returns the new state map with the entity(ies) removed.

remove-ident clj/s

[state-map ident path-to-idents]

Removes an ident, if it exists, from a list of idents in app state. This function is safe to use within mutations.

sort-idents-by clj/s

(sort-idents-by state-map vector-of-idents sortkey-fn)

(sort-idents-by state-map vector-of-idents sortkey-fn comp-fn)

Returns the sorted version of the provided vector of idents.

Intended to be used as

(sort-idents-by people-idents :person/name)

NOTE: The order of parameters is different from clojure.core/sort-by to facilitate:

(swap! state update-in [:person/id 1 :person/children]
  (partial sort-idents-by @state) :person/first-name)

(update-caller!

You can optionally pass a comp-fn which is as-described in sort-by.

swap!-> clj/s macro

(swap!-> atom & forms)

A useful macro for threading multiple operations together on an atom (e.g. state atom in mutation)

Equivalent to:

(swap! atom (fn [s] (-> s ...forms...)))

For example

(swap!-> (:state env)
  (merge/merge-component ...)
  (integrate-ident* ...))

tree-path->db-path clj/s

(tree-path->db-path state path)

Convert a 'denormalized' path into a normalized one by walking the path in state treating ident-based edges as jumps back to that location in state-map.

For example, one might find this to be true for a normalized db:

state => {:person/id {1 {:person/id 1 :person/spouse [:person/id 3]}
                      3 {:person/id 3 :person/first-name ...}}}

(tree-path->db-path state [:person/id 1 :person/spouse :person/first-name])
=> [:person/id 3 :person/first-name]

ui->props clj/s

(ui->props this)

(ui->props state-map component-class ident)

Obtain a tree of props for a UI instance from the current application state. Useful in mutations where you want to denormalize an entity from the state database. this can often be obtained from the mutation env at the :component key.

update-caller! clj/s

(update-caller! {:keys [state ref]} & args)

Runs clojure.core/update on the table entry in the state database that corresponds to the mutation caller (which can be explicitly set via :ref when calling transact!).

Equivalent to

(apply swap! (:state env) update-in (:ref env) ...)

update-caller-in! clj/s

(update-caller-in! {:keys [state ref] :as mutation-env} path & args)

Like swap! but starts at the ref from env, adds in supplied path elements (resolving across idents if necessary). Finally runs an update-in on that resultant path with the given args.

Equivalent to:

(swap! (:state env) update-in (tree-path->db-path @state (into (:ref env) path)) args)

with a small bit of additional sanity checking.