com.fulcrologic.fulcro.offline.load-cache — com.fulcrologic/fulcro 3.7.6

Support for a loading system that supports keeping previously-seen query responses in a persistent cache. It supports the following features:

• Make a failed load return the last cached value. ** Support for a default value for the load in case you are offline and nothing is in the cache.
• Support for an eager/fast return from cache even when online. ** Indicating if the actual return should just go to cache, or both cache and app merge.

This support replaces the default definition of the internal-load mutation in your Fulcro app, and hooks cache control into the normal load options (open map). If no caching options are given in a load!, then it uses Fulcro's built-in implementation of load.

WARNING: Mixing this with durable mutations can be a problem. You should only use a load cache on items that cannot be modified by durable mutations unless you're willing to also update the load cache to reflect the mutation changes; otherwise the load cache can get out of sync with the durable mutations and cause all manner of havoc. This facility is primarily about making well-known data (e.g. inventory items, dropdown options, etc.) available even when the server is not responding.

Installation: See with-load-cache

Usage: Use the load! and load-eagerly! functions from this ns. Operations in data-fetch ns will continue to work in an unmodified fashion.

current-load-store clj/s

(current-load-store app)

Returns the EDN store that is currently being used to store cached loads.

internal-load! clj/s

load! clj/s

(load! app-ish query-key query-component default-value)

(load! app-ish
       query-key
       query-component
       default-value
       {:com.fulcrologic.fulcro.offline.load-cache/keys [on-cached-load]
        :as options})

Load data-fetch/load!, but enables load caching. The default mode always tries to fetch the data as normal, and only resorts to the cache on failure.

• app-ish - An app or component
• query-key - A keyword or ident to root the server query
• query-component - An optional (may be nil) component that will be used to derive the sub-graph query and normalization.
• default-value is required, and one or many of query-component instances.
• options is just like for data-fetch/load!. See that function for full details.

NOTE: The normal data-fetch/load! actions (e.g. post mutations, targeting) will always happen, since this function will essentially guarantee that some result is available (if nothing more than the default value). Thus, it is impossible to see that a low-level network error even happened when using this function.

As a result, you may supply a mutation via the options map as ::on-cached-load mutation. The mutation will be submitted if the load is satisfied by the cache, and will include the normalized load parameters (e.g. a map that includes :query).

Example:

;; The top-level key of the server remote result will be :inventory/items, but the default-value is just the value(s)
;; under that key.
(lc/load! SPA :inventory/items Item [{:item/id 1 :item/name "boo"}] {:target [:all-items]})

;; Loading by ident is fine, but the default value will then always be a map (the Item to default to in this case):
(lc/load! SPA [:item/id 2] Item {:item/id 2 :item/name "BAH"})

See also load-eagerly!.

load-eagerly! clj/s

(load-eagerly! app-ish query-key query-component default-value)

(load-eagerly! app-ish query-key query-component default-value options)

Just like load! from this same namespace, but this version will optimistically use a result from the cache if it exists (making startup very fast), and will only update the cache with the result returned from the remote when it arrives.

You can optionally choose to have the new network result merged with app state by passing ::merge-new-result? true in options.

Normal data-fetch/load! options (e.g. post mutations, targeting, etc.). are only triggered whenever merging to app state happens. Thus, a post-mutation can be run on the optimistic eager load, but it will only run for the network response if you've chosen to merge that with app state when it arrives.

load-store-options clj/s

(load-store-options app)

Returns the options that were passed when configuring the load cache.

with-load-cache clj/s

(with-load-cache app edn-store)

(with-load-cache app edn-store options)

Installs support for load caching to the provided app. Returns a new app, so it must be used like so:

(defonce app (-> (fulcro-app {})
               (with-load-cache edn-store)))

Currently options is unused.

Then you can leverage the caching using transaction options, or simply by calling the load! and load-eagerly! defined in this namespace.

The transaction options (under ::txn/options key in load parameter map) that are supported are:

• ::use-cache - Boolean. Use this caching support. When false, just does standard Fulcro load.
• ::default-value - A map or vector representing the default value to use if the load and cache both fail.
• ::on-cached-load - A mutation to run whenever the cache is used instead of a real response.
• ::eager? - Boolean. Should the cache be used optimistically?
• ::merge-new-result? - Boolean. Only applies if ::eager? was set to true: should the real network result be merged when it arrives? Default is false.

This and the load-eagerly! functions just make it easier (mostly unnecessary) to pass these additional options.