com.fulcrologic.fulcro.raw.application — com.fulcrologic/fulcro 3.5.15

abort! clj/s

(abort! app-ish abort-id)

Attempt to abort the send queue entries with the given abort ID.

NOTE: This can be redefined on an application. If you change your transaction processing routing, then the built-in version will not work, and this docstring does not apply.

Will notify any aborted operations (e.g. result-handler will be invoked, remote-error? will be used to decide if you consider that an error, etc.). The result map from an abort will include {::txn/aborted? true}, but will not include :status-code or :body.

This function affects both started and non-started items in the send queues, but will not affect submissions that have not yet made it to the network processing layer (things still in top-level transaction submission queue).

So the sequence of calls:

(comp/transact! this `[(f)] {:abort-id :a})
(app/abort! this :a)

will cancel anything active with abort id :a, but since you've held the thread the entire time the submission of mutation (f) is still on the submission queue and will not be aborted.

• app-ish: Anything that can be coerced to an app with comp/any->app.
• abort-id: The abort ID of the operations to be aborted.

add-component! clj/s

(add-component! app
                component
                {:keys [receive-props initialize? keep-existing? initial-params]
                 :as options})

Use a component (that has initial state) as a subtree managed by Fulcro. This establishes props updates to non-React UI, and is not rendered by normal Fulcro rendering.

The component should be a real Fulcro component or a generated normalizing component from nc (or similar) that has initial state. .

The options map can contain:

• :initialize? - Pass true if you want the initial state of component to be merged into app state.
• :keep-existing? - Only valid if initialize? is true. When true, indicates initialize should only be done if there isn't already state at the component's ident in the database.
• :initial-params - The parameters to pass to the component's get-initial-state when initializing.
• :receive-props - REQUIRED: The function to call when the props change in the Fulcro state. This is a (fn [props] ) where the props will be the component props.
• :ident - Only needed if you are NOT initializing state, AND the component has a dynamic ident.
• :listener-id - The ID used for the render listener that is added by this function. Defaults to component ident, but you can override it with this option. If you do override, use remove-render-listener! instead of remove-component! to remove the listener.

add-render-listener! clj/s

(add-render-listener! app nm listener)

Add (or replace) a render listener named nm. listener is a (fn [app options] ) that will be called after each render.

See the :batch-notifications option of the application, which can be set when using certain verions of React to improve performance and reduce over-rendering.

add-root! clj/s

(add-root! app
           root-key
           component
           {:keys [receive-props initialize? keep-existing? initial-params]
            :as options})

Use a root key and component as a subtree managed by Fulcro. This establishes props updates to non-React UI, and is not rendered by normal Fulcro rendering. You can integrate with React using use-root from the hooks ns.

The root-key must be a unique (namespace recommended) key among all keys used within the application, since the root of the database is where it will live.

The component should be a real Fulcro component or a generated normalizing component from nc (or similar).

The options map can contain:

• :initialize? - Pass true if you want the initial state of component to be merged into app state.
• :keep-existing? - Only valid if initialize? is true. When true, indicates initialize should only be done if there isn't already state at the component's ident in the database.
• :initial-params - The parameters to pass to the component's get-initial-state when initializing.
• :receive-props - REQUIRED: The function to call when the props change in the Fulcro state. This is a (fn [props] ) where the props will be the component props (sans the root-key).
• :listener-id - The ID used for the render listener that is added by this function. Defaults to the root-key, but you can override it with this option.

NOTE: This function tracks prior props and is capable of a very fast staleness check. It will not call your callback unless it detects an actual change to the data of interest to your UI.

basis-t clj/s

(basis-t app)

Return the current basis time of the app.

current-state clj/s

(current-state app-or-component)

Get the current value of the application state database. If called without arguments it will attempt to find the app in the dynamically-bound comp/app, which is bound during render.

default-global-eql-transform clj/s

(default-global-eql-transform ast)

The default query transform function. It makes sure the following items on a component query are never sent to the server:

• Props whose namespace is ui
• Any prop or join that is namespaced to com.fulcrologic.fulcro*
• Any ident (as a prop or join) whose table name is namespaced ui or com.fulcrologic.fulcro*

Takes an AST and returns the modified AST.

default-remote-error? clj/s

(default-remote-error? {:keys [status-code]})

Default detection of network errors. Returns true if the status-code of the given result map is not 200.

default-tx! clj/s deprecated

fulcro-app clj/s

(fulcro-app)

(fulcro-app {:keys [props-middleware global-eql-transform global-error-action
                    default-result-action! core-render! optimized-render!
                    batch-notifications render-root! hydrate-root! unmount-root!
                    submit-transaction! abort-transaction! render-middleware
                    initial-db client-will-mount client-did-mount remote-error?
                    remotes query-transform-default load-marker-default
                    load-mutation root-class shared external-config
                    refresh-component! shared-fn]
             :as options})

Create a new Fulcro application. See com.fulcrologic.fulcro.application/fulcro-app for the React-based initializer.

This version creates an app that is not attached to React, and has no default root or optimized render. The map of initial options is the same except that react-centric options are obviously ignore, and also:

• :optimized-render! - A (fn ([app]) ([app txn-options])) that can analyze the state of the application and optimally refresh the screen. Defaults to a no-op. This function is normally called from core-render!, and therefore is useless unless you define a core-render! that calls it.
• :core-render! - A (fn [app txn-options] side-effect) that is called by schedule render. If you fail to supply this on a raw app, then NO rendering will happen; however, render listeners will still be called.
• :batch-notifications - A side-effecting function (fn [notify-all]) that can surround a batch of render notifiations with a context. The only argument to this function is notify-all, which is a function that will do the actual notifications. This is useful when using render notifications with React hooks, and need to tell React that a bunch of state changes need to happen together. The normal setting for this (if you're using hooks and render listeners) is (fn [render!] (react-dom/unstable_batchedUpdates render!)) or (fn [render!] (react-native/unstable_batchedUpdates render!)).
• :refresh-component! - A (fn [component]) that is used by synchronous transactions to attempt to refresh the UI of component. This has no definition for non-react applications, and cannot work without you defining this.

Note that raw apps are not mounted, but are instead ready to be used immediately. If you want to use inspect, then you must call (inspect/client-started! app) yourself.

Indexing is available, but normally runs from React lifecycle, so unless you're using this with React indexes will be non-managed.

fulcro-app? clj/s

(fulcro-app? x)

Returns true if the given x is a Fulcro application.

get-root-subtree-props clj/s

(get-root-subtree-props app root-key component prior-props)

Uses fdn/traced-db->tree to get the props of the subtree at root-key. If prior-props are not stale, those are returned instead.

headless-synchronous-app clj/s

(headless-synchronous-app faux-root)

(headless-synchronous-app faux-root options)

Returns a new instance from fulcro-app that is pre-configured to use synchronous transaction processing and no rendering. This is particularly useful when you want to write integration tests around a Fulcro app so that the tests need no async support. The faux-root must be a component (which need have no body).

The returned application will be properly initialized, and will have the initial state declared in faux-component already merged into the app's state (i.e. the returned app is ready for operations).

options can be anything from fulcro-app, but :submit-transaction!, :render-root!, and :optimized-render! are ignored.

initialize-state! clj/s

(initialize-state! app root)

Initialize the app state using root component's app state. This will deep merge against any data that is already in the state atom of the app. Can be called before mount!, in which case you should tell mount not to (re) initialize state.

maybe-merge-new-component! clj/s

(maybe-merge-new-component! app
                            component
                            component-data
                            {:keys [keep-existing? initialize?]
                             :or {initialize? true}})

Helper for add-component! and similar. Populates the component state depending on initialize? and keep-existing?.

app - The app component - A component (e.g. from nc) component-data - A tree of data that matches the shape of the component's query. initialize? is true by default. :keep-existing? - A boolean (default false). If true, then the state of the component will not be initialized if there is already data at the component's ident (which will be computed using the initial entity provided).

maybe-merge-new-root! clj/s

(maybe-merge-new-root! app
                       root-key
                       component
                       {:keys [keep-existing? initial-params initialize?]
                        :or {initial-params {}}})

A helper for add-root! and similar. Populates the initial state for a subtree depending on initialize? and keep-existing?

:keep-existing? - A boolean. If true, then the state will not be initialized if there is already data at the root-key.

remove-component! clj/s

(remove-component! app component)

Remove a root key managed subtree from Fulcro. Does not GC the state, just stops sending props updates on render.

remove-render-listener! clj/s

(remove-render-listener! app nm)

Remove the render listener named nm.

remove-root! clj/s

(remove-root! app root-key)

Remove a root key managed subtree from Fulcro. Does not garbage collect, just stops updating the callback.

render! clj/s

(render! app)

(render! app {:keys [force-root?] :as options})

Render the application immediately. Prefer schedule-render!, which will ensure no more than 60fps.

This is the central processing for render and cannot be overridden. schedule-render! will always invoke this function. The optimized render is called by this function, which does extra bookkeeping and other supporting features common to all rendering.

Options include:

• force-root?: boolean. When true disables all optimizations and forces a full root re-render.
• anything your selected rendering optization system allows. Shared props are updated via shared-fn only on force-root? and when (shallow) root props change.

root-props-changed? clj/s

(root-props-changed? app)

Returns true if the props queries directly by the root component of the app (if mounted) have changed since the last render. This is a shallow analysis such that, for example, a join from root (in a normalized db) will be checked as a difference of idents that the root prop points to. This can be used for determining if things like shared-fn need to be re-run, and if it would simply be quicker to keyframe render the entire tree.

This is a naivé algorithm that is essentially select-keys on the root props. It does not interpret the query in any way.

schedule-render! clj/s

(schedule-render! app)

(schedule-render! app options)

Schedule a render on the next animation frame.

set-remote! clj/s

(set-remote! app remote-name remote)

Add/replace a remote on the given app. remote-name is a keyword, and remote is a Fulcro remote (map containing at least transmit!).

This function is generally safe to call at any time. Requests that are in-flight on an old version of the remote will complete on that remote, and any that are queued will be processed by the new one; however, if the old remote supported abort operations then an abort on in-flight requests of the old remote will not work (since you're replaced the remote that the details about that request).

This function changes the content of the application's runtime atom so you do not need to capture the return value, which is the app you passed in.

tick! clj/s

(tick! app)

Move the basis-t forward one tick. For internal use in internal algorithms. Fulcro uses this to add metadata to props so it can detect the newer of two version of props.

update-shared! clj/s

(update-shared! {:com.fulcrologic.fulcro.application/keys [runtime-atom]
                 :as app})

Force shared props to be recalculated. This updates the shared props on the app, and future renders will see the updated values. This is a no-op if no shared-fn is defined on the app. If you're using React 16+ consider using Context instead of shared.