/
data_fetch.cljc
331 lines (294 loc) · 18.4 KB
/
data_fetch.cljc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
(ns com.fulcrologic.fulcro.data-fetch
"Functions for issuing loads of subgraphs of data for your application. The primary functions of interest are
`load!` and `load-field!`. Fulcro's composed queries and idents allow these loads to automatically be normalized
and merged into your database. The data targeting support allows you to then *join* that new subgraph to the
existing UI data graph. This process is the central topic to understand in Fulcro, and it is to your advantage
to study the concepts of Fulcro idents and query composition carefully."
(:refer-clojure :exclude [load])
(:require
[clojure.walk :refer [walk prewalk]]
[com.fulcrologic.fulcro.algorithms.do-not-use :as futil]
[com.fulcrologic.fulcro.algorithms.data-targeting :as targeting]
[com.fulcrologic.fulcro.algorithms.tx-processing :as txn]
[com.fulcrologic.fulcro.algorithms.merge :as merge]
[com.fulcrologic.fulcro.raw.components :as rc]
[com.fulcrologic.fulcro.mutations :as m]
[clojure.spec.alpha :as s]
[com.fulcrologic.guardrails.core :refer [>defn =>]]
[edn-query-language.core :as eql]
[taoensso.timbre :as log]
[com.fulcrologic.fulcro.algorithms.lookup :as ah]))
(>defn data-state?
"Is the given parameter a load marker?"
[state]
[any? => boolean?]
(and (map? state) (contains? state :status)))
(>defn load-marker?
"Is the given parameter a load marker?"
[x]
[any? => boolean?]
(data-state? x))
(>defn ready? "Is the given load marker ready for loading?" [marker]
[(s/nilable map?) => boolean?]
(= :loading (:status marker)))
(>defn loading? "Is the given load marker loading?" [marker]
[(s/nilable map?) => boolean?]
(= :loading (:status marker)))
(>defn failed?
"Is the given load marker indicate failed?
WARNING: This function is current unimplemented and will be removed. The new way of dealing with failure is to
define an `error-action` for the load in question and modify your own state. You can also override"
[marker]
[(s/nilable map?) => boolean?]
(= :failed (:status marker)))
(def marker-table
"The name of the table in which fulcro load markers are stored. You must query for this via a link query
`[df/marker-table '_]` in any component that needs to use them (and refresh) during loads."
:ui.fulcro.client.data-fetch.load-markers/by-id)
(defn elide-ast-nodes
"Remove items from a query (AST) that have a key that returns true for the elision-predicate"
[{:keys [key union-key children] :as ast} elision-predicate]
(let [union-elision? (elision-predicate union-key)]
(when-not (or union-elision? (elision-predicate key))
(when (and union-elision? (<= (count children) 2))
(log/warn "Unions are not designed to be used with fewer than two children. Check your calls to Fulcro
load functions where the :without set contains " (pr-str union-key) "See https://book.fulcrologic.com/#warn-union-needs-more-children"))
(let [new-ast (update ast :children (fn [c] (vec (keep #(elide-ast-nodes % elision-predicate) c))))]
(if (seq (:children new-ast))
new-ast
(dissoc new-ast :children))))))
(defn elide-query-nodes
"Remove items from a query when the query element where the (node-predicate key) returns true. Commonly used with
a set as a predicate to elide specific well-known UI-only paths."
[query node-predicate]
(-> query eql/query->ast (elide-ast-nodes node-predicate) eql/ast->query))
(defn load-params*
"Internal function to validate and process the parameters of `load` and `load-action`."
[app server-property-or-ident class-or-factory {:keys [target params marker post-mutation post-mutation-params without
fallback focus ok-action post-action error-action remote
abort-id update-query]
:or {remote :remote marker false}}]
{:pre [(or (nil? target) (vector? target))
(or (nil? post-mutation) (symbol? post-mutation))
(or (nil? post-mutation-params) (map? post-mutation-params))
(or (nil? params) (map? params))
(or (eql/ident? server-property-or-ident) (keyword? server-property-or-ident))]}
(let [state-map (-> app :com.fulcrologic.fulcro.application/state-atom deref)
transformed-query (if class-or-factory
(cond-> (rc/get-query class-or-factory state-map)
(set? without) (elide-query-nodes without)
focus (eql/focus-subquery focus)
update-query update-query)
nil)
query (cond
(and class-or-factory (map? params)) `[({~server-property-or-ident ~transformed-query} ~params)]
class-or-factory [{server-property-or-ident transformed-query}]
(map? params) [(list server-property-or-ident params)]
:else [server-property-or-ident])
marker (if (true? marker)
(do
(log/warn "Boolean load marker no longer supported. See https://book.fulcrologic.com/#warn-boolean-marker-not-supported")
false)
marker)]
(when (and target (not (targeting/special-target? target)) (= 2 (count target)))
(log/warn "Data load targets of two elements imply that you are targeting a table entry. That is probably"
"incorrect. Normalization targets tables. Targeting is for creating missing edges, which are usually 3-tuples. See https://book.fulcrologic.com/#warn-data-load-targets-table"))
{:query query
:source-key server-property-or-ident
:remote remote
:target target
:ok-action ok-action
:error-action error-action
:post-action post-action
:post-mutation post-mutation
:post-mutation-params post-mutation-params
:fallback fallback
:marker marker
:abort-id abort-id}))
(defn set-load-marker!
"Adds a load marker at the given `marker` id to df/marker-table with the given status.
NOTE: You must query for the marker table in any component that wants to show activity."
[app marker status]
(when marker
(let [{:com.fulcrologic.fulcro.application/keys [state-atom]} app
render! (ah/app-algorithm app :schedule-render!)]
(log/debug "Setting load marker")
(swap! state-atom assoc-in [marker-table marker] {:status status})
;; FIXME: Test refresh for this without the force root...it should work without it if ppl properly query for the marker table.
(render! app {:force-root? true}))))
(defn remove-load-marker!
"Removes the load marker with the given `marker` id from the df/marker-table."
[app marker]
(when marker
(let [{:com.fulcrologic.fulcro.application/keys [state-atom]} app]
(log/debug "Removing load marker")
(swap! state-atom update marker-table dissoc marker))))
(defn finish-load!
"Default processing when a load finishes successfully (called internally).
Removes any load marker, then either:
- Runs the `ok-action` (if defined).
- Does normal post-processing (if the was no ok-action):
- Merges the load result
- Processes desired targets
- Runs the post-mutation (if defined)
- Runs the post-action (if defined)"
[{:keys [app result transmitted-ast] :as env} {:keys [query ok-action post-mutation post-mutation-params
post-action target marker source-key] :as params}]
(remove-load-marker! app marker)
(let [env (assoc env :load-params params)]
(if (fn? ok-action)
(do
(log/debug "Skipping default merge and calling user-supplied ok-action.")
(ok-action env))
(let [{:keys [body transaction]} result
mark-query (or transaction (futil/ast->query transmitted-ast))
body (merge/mark-missing body mark-query)
{:com.fulcrologic.fulcro.application/keys [state-atom]} app]
(swap! state-atom (fn [s]
(cond-> (merge/merge* s query body)
target (targeting/process-target source-key target))))
(when (symbol? post-mutation)
(log/debug "Doing post mutation " post-mutation)
(rc/transact! app `[(~post-mutation ~(or post-mutation-params {}))]))
(when (fn? post-action)
(log/debug "Doing post action")
(post-action env))))))
(defn load-failed!
"The normal internal processing of a load that has failed (error returned true).
Sets the load marker, if present, to :failed.
If an `error-action` was desired, it is used to process the rest of the failure.
The `env` will include the network `:result` and the original load options as `:load-params`.
*Otherwise*, this function will:
- Trigger the global error action (if defined on the app) (arg is env as described above)
- Trigger any fallback for the load. (params are the env described above)
"
[{:keys [app] :as env} {:keys [error-action marker fallback] :as params}]
(log/debug "Running load failure logic.")
(set-load-marker! app marker :failed)
(let [env (assoc env :load-params params)]
(if (fn? error-action)
(do
(log/debug "Skipping default load error action")
(error-action env))
(do
(when-let [global-error-action (ah/app-algorithm app :global-error-action)]
(global-error-action env))
(when (symbol? fallback)
(rc/transact! app `[(~fallback ~env)]))))))
(defmethod m/mutate `internal-load! [{:keys [ast] :as env}]
(let [params (get ast :params)
{:keys [remote query marker]} params
remote-key (or remote :remote)]
(log/debug "Loading " remote " query:" query)
(cond-> {:action (fn [{:keys [app]}] (set-load-marker! app marker :loading))
:result-action (fn [{:keys [result app] :as env}]
(let [remote-error? (ah/app-algorithm app :remote-error?)]
(if (remote-error? result)
(load-failed! env params)
(finish-load! env params))))
remote-key (fn [_]
(eql/query->ast query))})))
(defn load!
"Load data from the server.
This function triggers a server interaction and normalizes the server response into your app state database. During
operation it also adds (by default) fetch markers into the app state so you can show busy indicators on the UI
components that are waiting for data. The `:target` parameter can be used to place the data somewhere besides app
state root (which is the default).
The server will receive a query of the form: [({server-property (comp/get-query class-or-factory)} params)], which
a Fulcro parser will correctly parse as a join on server-property with the given subquery and params. See the AST and
instructions on parsing queries in the developer's guide.
Parameters:
- `app-or-comp` : A component instance or Fulcro application
- `server-property-or-ident` : A keyword or ident that represents the root of the query to send to the server. If this is an ident
you are loading a specific entity from the database into a local app db table. A custom target will be ignored.
- `class-or-factory` : A component that implements IQuery, or a factory for it (if using dynamic queries). This will be combined with `server-property` into a join for the server query. Needed to normalize results.
class-or-factory can be nil, in which case the resulting server query will not be a join.
- `config` : A map of load configuration parameters.
Config (all optional):
- `target` - An assoc-in path at which to put the result of the Subquery (as an edge (normalized) or value (not normalized)).
Can also be special targets (multiple-targets, append-to,
prepend-to, or replace-at). If you are loading by keyword (into root), then this relocates the result (ident or value) after load.
When loading an entity (by ident), then this option will place additional idents at the target path(s) that point to that entity.
- `initialize` - REMOVED. Use component pre-merge instead.
- `remote` - Optional. Keyword name of the remote that this load should come from.
- `params` - Optional parameters to add to the generated query
- `marker` - ID of marker. Normalizes a load marker into app state so you can see progress.
- `refresh` - A list of things in the UI to refresh. Depends on rendering optimization.
- `focus` - Focus the query along a path. See eql/focus-subquery.
- `without` - A set of keys to remove (recursively) from the query.
- `update-query` - A general-purpose function that can transform the component query before sending to remote. See also
the application's `:global-eql-transform` option.
For example, to focus a subquery using update-query: `{:update-query #(eql/focus-subquery % [:my {:sub [:query]}])}`
Removing properties (like previous :without option): `{:update-query #(df/elide-query-nodes % #{:my :elisions})}`
- `abort-id` - Set a unique key. If supplied, then the load can be cancelled via that abort ID.
- `parallel` - Send the load out-of-order (immediately) without waiting for other loads in progress.
- `post-mutation` - A mutation (symbol) to run *after* the data is merged. Note, if target is supplied be sure your post mutation
should expect the data at the targeted location. The `env` of that mutation will be the env of the load (if available), but will also include `:load-request`.
- `post-mutation-params` - An optional map that will be passed to the post-mutation when it is called.
- `post-action` - A lambda that will get a mutation env parameter `(fn [env] ...)`. Called after success, like post-mutation
(and after post-mutation if also defined). `env` will include the original `:load-params` and raw network layer `:result`. If you
want the post behavior to act as a top-level mutation, then prefer `post-mutation`. The action can also call `transact!`.
- `fallback` - A mutation (symbol) to run if there is a server/network error. The `env` of the fallback will be like a mutation `env`, and will
include a `:result` key with the real result from the server, along with the original `:load-params`.
Special-purpose config options:
The config options can also include the following things that completely override behaviors of other (respons-processing) options,
and should only be used in very advanced situations where you know what you are doing:
- `ok-action` - WARNING: OVERRIDES ALL DEFAULT OK BEHAVIOR (except load marker removal)! A lambda that will receive an env parameter `(fn [env] ...)` that
includes the `:result` and original `:load-params`.
- `error-action` - WARNING: OVERRIDES ALL DEFAULT ERROR BEHAVIOR (except load marker update). A lambda that will receive an `env`
that includes the `:result` and original `:load-params`.
"
([app-or-comp server-property-or-ident class-or-factory] (load! app-or-comp server-property-or-ident class-or-factory {}))
([app-or-comp server-property-or-ident class-or-factory config]
(let [app (rc/any->app app-or-comp)
txn-options (get config ::txn/options {})
{:keys [load-marker-default query-transform-default load-mutation]} (-> app :com.fulcrologic.fulcro.application/config)
{:keys [parallel refresh] :as config} (merge
(cond-> {:marker load-marker-default :parallel false :refresh [] :without #{}}
query-transform-default (assoc :update-query query-transform-default))
config)
load-sym (or load-mutation `internal-load!)
mutation-args (load-params* app server-property-or-ident class-or-factory config)
abort-id (:abort-id mutation-args)]
(when query-transform-default
(log/warn "Query-transform-default is a dangerous option that can break general merge behaviors. Do not use it. See https://book.fulcrologic.com/#warn-dont-use-query-transform-default"))
(rc/transact! app `[(~load-sym ~mutation-args)]
(cond-> txn-options
(seq refresh) (assoc :refresh refresh)
(boolean? parallel) (assoc :parallel? parallel)
abort-id (assoc ::txn/abort-id abort-id))))))
(defn load-field!
"Load a field of the current component. Runs `prim/transact!`.
Parameters
- `component`: The component (**instance**, not class). This component MUST have an Ident.
- `field`: A field on the component's query that you wish to load. If `field` is a *vector* of keywords then
this function will load all of the fields specified.
- `options` : A map of load options. See `load`.
WARNING: If you're using dynamic queries, you won't really know what factory your parent is using,
nor can you pass it as a parameter to this function. Therefore, it is not recommended to use load-field from within
a component that has a dynamic query unless you can base it on the original static query.
"
[component field-or-fields options]
(let [app (rc/any->app component)
{:keys [parallel update-query]} options
ident (rc/get-ident component)
update-query (fn [q]
(cond-> (eql/focus-subquery q (if (vector? field-or-fields)
field-or-fields
[field-or-fields]))
update-query (update-query)))
params (load-params* app ident component (assoc options
:update-query update-query
:source-key (rc/get-ident component)))
abort-id (:abort-id params)]
(rc/transact! app [(list `internal-load! params)]
(cond-> {}
(boolean? parallel) (assoc :parallel? parallel)
abort-id (assoc ::txn/abort-id abort-id)))))
(defn refresh!
([component load-options]
(load! component (rc/get-ident component) component load-options))
([component]
(load! component (rc/get-ident component) component)))
(def load "DEPRECATED. Use `load!`" load!)
(def load-field "DEPRECATED. Use `load-field!`" load-field!)