com.fulcrologic.fulcro.algorithms.merge — com.fulcrologic/fulcro 3.0.0-beta-15

Various algorithms that are used for merging trees of data into a normalized Fulcro database.

component-merge-query clj/s

(component-merge-query state-map component object-data)

Calculates the query that can be used to pull (or merge) a component with an ident to/from a normalized app database. Requires a tree of data that represents the instance of the component in question (e.g. ident will work on it)

is-ui-query-fragment? clj/s

(is-ui-query-fragment? kw)

Check the given keyword to see if it is in the :ui namespace.

mark-missing clj/s

(mark-missing result query)

Recursively walk the query and response marking anything that was asked for in the query but is not in the response as missing. The sweep-merge process (which happens later in the plumbing) uses these markers as indicators to remove any existing data in the target of the merge (i.e. your state database).

The naive approach to data merging (even recursive) would fail to remove such data.

Returns the result with missing markers in place (which are then used/removed in a later stage).

See the Developer Guide section on Fulcro's merge process for more information.

merge! clj/s

(merge! app data-tree query)

(merge! app data-tree query options)

Merge an arbitrary data-tree that conforms to the shape of the given query using Fulcro's standard merge and normalization logic.

app - A fulcro application to merge into. query - A query, derived from components, that can be used to normalized a tree of data. data-tree - A tree of data that matches the nested shape of query.

The options is a map containing:

• :remove-missing? If true (default false) then anything appearing in the query but not the result-tree will be removed from state-map.

NOTE: This function assumes you are merging against the root of the tree. See merge-component and merge-component! for relative merging.

See also merge*.

merge* clj/s

(merge* state-map query result-tree)

(merge* state-map query result-tree {:keys [remove-missing?] :as options})

Merge the query-result of a query using Fulcro's standard merge and normalization logic.

Typically used on the state atom as:

(swap! state merge* query-result query)

• state-map - The normalized database.
• query - The query that was used to obtain the query-result. This query will be treated relative to the root of the database.
• tree - The query-result to merge (a map).

The options is a map containing:

• :remove-missing? If true (default false) then anything appearing in the query but not the result-tree will be removed from state-map.

See merge-component and merge-component! for possibly more appropriate functions for your task.

Returns the new normalized database.

merge-alternate-union-elements clj/s

(merge-alternate-union-elements state-map root-component)

Just like merge-alternate-union-elements!, but usable from within mutations and on server-side rendering. Ensures that when a component has initial state it will end up in the state map, even if it isn't currently in the initial state of the union component (which can only point to one at a time).

merge-alternate-union-elements! clj/s

(merge-alternate-union-elements! app root-component)

Walks the query and initial state of root-component and merges the alternate sides of unions with initial state into the application state database. See also merge-alternate-union-elements, which can be used on a state map and is handy for server-side rendering. This function side-effects on your app, and returns nothing.

merge-alternate-unions clj/s

(merge-alternate-unions merge-fn root-component)

Walks the given query and calls (merge-fn parent-union-component union-child-initial-state) for each non-default element of a union that has initial app state. You probably want to use merge-alternate-union-elements[!] on a state map or app.

merge-component clj/s

(merge-component state-map component component-data & named-parameters)

Given a state map of the application database, a component, and a tree of component-data: normalizes the tree of data and merges the component table entries into the state, returning a new state map.

Since there is not an implied root, the component itself won't be linked into your graph (though it will remain correctly linked for its own consistency).

• state-map - The normalized database
• component - A component class
• component-data - A tree of data that matches the shape of the component's query.
• named-parameters - Parameters from targeting/integrate-ident* that will let you link the merged component into the graph. Named parameters may also include :remove-missing?, which will remove things that are queried for but do not appear in the data from the state.

See also targeting/integrate-ident*, and merge/merge-component!

merge-component! clj/s

(merge-component! app component object-data & named-parameters)

Normalize and merge a (sub)tree of application state into the application using a known UI component's query and ident.

This utility function obtains the ident of the incoming object-data using the UI component's ident function. Once obtained, it uses the component's query and ident to normalize the data and places the resulting objects in the correct tables. It is also quite common to want those new objects to be linked into lists in other spots in app state, so this function supports optional named parameters for doing this. These named parameters can be repeated as many times as you like in order to place the ident of the new object into other data structures of app state.

This function honors the data merge story for Fulcro: attributes that are queried for but do not appear in the data will be removed from the application. This function also uses the initial state for the component as a base for merge if there was no state for the object already in the database.

This function will also trigger re-renders of components that directly render object merged, as well as any components into which you integrate that data via the named-parameters.

This function is primarily meant to be used from things like server push and setTimeout/setInterval, where you're outside of the normal mutation story. Do not use this function within abstract mutations.

• app: Your application.
• component: The class of the component that corresponds to the data. Must have an ident.
• object-data: A map (tree) of data to merge. Will be normalized for you.
• named-parameter: Post-processing ident integration steps. see targeting/integrate-ident*. You may also include :remove-missing? true/false to indicate that data that is missing for the component's query should be removed from app state.

Any keywords that appear in ident integration steps will be added to the re-render queue.

See also fulcro.client.primitives/merge!.

merge-ident clj/s

(merge-ident app-state ident props)

merge-idents clj/s

(merge-idents tree query refs {:keys [remove-missing?] :as options})

Merge the given refs (a map from ident to props), query (a query that contains ident-joins), and tree:

returns a new tree with the data merged into the proper ident-based tables.

merge-mutation-joins clj/s

(merge-mutation-joins state query data-tree)

(merge-mutation-joins state
                      query
                      data-tree
                      {:keys [remove-missing?] :as options})

Merge all of the mutations that were joined with a query.

The options, if supplied, can include:

• :remove-missing?: (default false) If true then any items that appear in the query but not in the data-tree will be removed from state (if present).

merge-tree clj/s

(merge-tree target source)

Handle merging incoming data and sweep it of values that are marked missing. This function also ensures that raw mutation join results are ignored (they must be merged via merge-mutation-joins).

nilify-not-found clj/s

(nilify-not-found x)

Given x, return x value unless it's ::not-found (the mark/sweep missing marker), in which case it returns nil.

This is useful when you are pre-processing a tree that has been marked for missing data sweep (see mark-missing), but has not yet been swept. This is basically the same as a nil? check in this circumstance since the given value will be removed after the final sweep.

not-found? clj/s

(not-found? props k)

Returns true if the k in props is the sweep-merge not-found marker. This marker appears during merge, and can affect :pre-merge processing, since the data-tree will have these markers when the given data is missing.

pre-merge-transform clj/s

(pre-merge-transform state)

(pre-merge-transform state options)

Transform function that modifies data using component pre-merge hook.

remove-ident* clj/s

(remove-ident* 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.

sweep clj/s

(sweep m)

Remove all of the not-found keys (recursively) from m, stopping at marked leaves (if present). Requires m to have been pre-marked via mark-missing.

sweep-merge clj/s

(sweep-merge target source)

Do a recursive merge of source into target (both maps), but remove any target data that is marked as missing in the response.

Requires that the source has been marked via mark-missing.

The missing marker is generated in the source when something has been asked for in the query, but had no value in the response. This allows us to correctly remove 'empty' data from the database without accidentally removing something that may still exist on the server (in truth we don't know its status, since it wasn't asked for, but we leave it as our 'best guess').