com.fulcrologic.fulcro.algorithms.merge — com.fulcrologic/fulcro 3.0.0-alpha-18

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

-preprocess-merge clj/s

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

PRIVATE.

Does the steps necessary to honor the data merge technique defined by Fulcro with respect to data overwrites in the app 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)

component-pre-merge clj/s

(component-pre-merge class query state data)

integrate-ident* clj/s

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

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 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 defui components, that can be used to normalized a tree of data. data-tree - A tree of data that matches the nested shape of query.

See also merge*.

merge* clj/s

(merge* state-map query result-tree)

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.
• query-result - The query-result to merge (a map).

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). Therefore, this function is just for dropping normalized things into tables when they themselves have a recursive nature. This function is useful when you want to create a new component instance and put it in the database, but the component instance has recursive normalized state. This is a basically a thin wrapper around merge/tree->db.

See also integrate-ident, integrate-ident!, and 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 integrate-ident!

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-mutation-joins clj/s

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

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

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.

pre-merge-transform clj/s

(pre-merge-transform state)

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').