Glossary¶
Welcome to the lost-and-found. This is the page you keep open in a second tab — the one you flick to when a doc says "the cascade" or "a coeffect" and you want the one-line truth without re-reading a whole chapter. Every entry gives you the canonical word (re-frame2 is fussy about names, on purpose), a plain-English definition, a tiny snippet so you can see it in the wild, and a link to where it's taught for real. The snippets here are illustrative, not runnable — read them as sketches.
The objects¶
adapter — The concrete per-substrate binding value you hand to init! so the framework knows how to talk to your React layer. It is a value, not the layer itself.
See Views. (Keep distinct from substrate, the layer.)
app-db — Your app's single immutable state map; one per frame, the one source of truth your code owns.
See app-db.
coeffect — A declared input the framework injects into a handler so the handler can stay pure; the world enters only through these.
(rf/reg-event :order/place
{:rf.cofx/requires [:now]} ;; :now is a declared coeffect
(fn [{:keys [now db]} _] ...))
See Effects & Coeffects. The key-form is cofx.
effect — A described side-effect returned as data and run by the runtime, never performed by the handler itself.
See Effects & Coeffects. Reserve fx for the :fx key / fx-id.
effect map — The whole {:db … :fx …} value a handler returns; the closed top-level key set for app code is #{:db :fx}.
See Events & the cascade. Singular: effect map.
epoch — The before/after state record one cascade leaves behind; the unit of time-travel.
See Observability.
error record / :rf.error/* category — A failure surfaced as a structured map keyed by a reserved category keyword; branch on the category, never the human-readable :reason.
See Errors.
event — An inert data vector — a fact that something happened, shaped [id], [id scalar], or [id {map}].
See Events & the cascade.
flow — A pure derivation materialised into app-db so handlers can read it as plain state.
(rf/reg-flow
{:id :cart/total :inputs [[:cart :items]]
:derive (fn [items] (reduce + (map :price items)))
:output-path [:cart :total]})
See Flows.
frame — One isolated, running instance of your app, with its own app-db, event queue, and subscription cache.
See Frames. Frames isolate state, not registrations.
image — The selected, sealed set of registrations a frame resolves against; its resolved result is a generation.
See Images. Use image for the source, generation for the resolved set.
interceptor — A named, by-id context → context decorator that wraps a handler.
See Interceptors.
machine — A state machine registered as an event handler via reg-machine; its live value is a snapshot.
See Machines.
mutation — A declared server-state write whose cache consequences (what it invalidates) are declared once on the registration.
See Server state. The reply field is :value; the instance sub field is :result.
resource — A declared, cached server-state read registered with reg-resource; its :scope is a required leak boundary.
See Server state. "Server state" is the category, not the noun.
runtime-db — The framework-owned state partition beside app-db (machine snapshots, route slice, resource cache, mutation status); read-don't-write for app code.
See app-db. Paths: :rf.db/runtime, children :rf.runtime/*.
subscription — A named, registered, pure, cached, read-only derivation of state.
See Subscriptions. Casual "sub" is fine; not as a headword.
substrate — The React-family rendering layer your app runs on (Reagent / UIx / Helix / reagent-slim).
See Views.
view — A pure render function from subscription values to hiccup.
See Views. Use "component" for React-analogy callouts only.
The processes¶
commit — The single, deferred, all-or-nothing app-db write at the end of an event; no observer ever sees a half-written app-db.
See Events & the cascade.
dispatch — Send an event into a frame; returns immediately and never mutates inline.
See Events & the cascade.
drain / run-to-completion — The runtime drains the whole event queue to a fixed point before subscriptions recompute and views render.
See Events & the cascade. Hyphenate run-to-completion consistently.
elide — Compile dev-only code out of production via one flag (goog.DEBUG / -Dre-frame.debug).
See Observability. Name DCE once, then use elide.
the event cascade — The fixed, ordered run one dispatch sets off: handler → effect map → effects → derivations → view → DOM.
See Events & the cascade. Reserve "the loop" for the whole repeating machine, "the six dominoes" for the first-contact mnemonic, "epoch" for the record.
invalidate — A mutation declares, as data on its registration, which cached reads it makes stale.
{:invalidates (fn [{:keys [slug]} _result]
{:tags #{[:article slug]}})} ;; declared once, on the mutation
See Server state.
navigate — Change the route by dispatching navigation; the URL is an input, the route is a sub.
See Routing.
project (egress) — Run a value through redaction before it leaves the app, via project-egress; direct reads are not auto-projected.
See Keep secrets out of traces.
the reg-* registrars — The boot-time registration calls that name your handlers and machinery: reg-event, reg-sub, reg-view, reg-fx, reg-cofx, reg-interceptor, reg-machine, reg-flow, reg-resource, reg-mutation, reg-route, reg-app-schema.
See Events & the cascade. There is one reg-event — reg-event-db/-fx/-ctx are gone.
subscribe / derive — Read derived state by name through a subscription; @(subscribe …) both reads and subscribes.
See Subscriptions.
The big ideas¶
Effects are data — A handler returns a description of side-effects and the runtime performs them; a pure handler plus data effects is what makes replay, test, and trace possible.
See Effects & Coeffects.
Fail loud, not silent — A recognised input that can't be honoured raises a structured :rf.error/*, never a nil or no-op. Keep fail-loud (raise instead of swallow) distinct from fail-closed (deny by default at a boundary).
See Errors.
Frame identity is carried, not found — An operation reads its frame from its scope (provider / running handler / captured handle); the runtime never invents one. A rootless call is :rf.error/no-frame-context.
See Frames.
generation — The resolved registration set an image produces; what a frame actually runs against.
See Images.
The four homes (where state lives) — Subscription → flow → resource → machine: pick the cheapest that fits, decided by the where-state-lives router. Every other concept defers here for "which one do I use?".
See Where state lives.
snapshot — A machine's live value at any moment: which state it's in plus its :data, read through a subscription addressed by the machine's id.
See Machines.
The two partitions — A frame holds app-db (yours) and runtime-db (the framework's), addressed by the projection paths :rf.db/app and :rf.db/runtime; runtime subsystems live under :rf.runtime/*.
See app-db.
The uniform reply — Every managed async surface (HTTP, resources, mutations, route loaders, machine async) completes by dispatching an event carrying a reply map, never by an awaited value. The HTTP envelope's discriminator is :kind (:success/:failure); the resource view-model's :status (:ok/:partial/:error/:cancelled/:stale) is a different field, with :kind :success ≡ :status :ok.
See Managed HTTP.
Xray — The dev inspector: an in-app panel that reads the trace stream and per-frame epoch history so you debug the loop, not the DOM.
See Debug with Xray.