re-frame

re-frame is a mature and stable ClojureScript framework designed for building user interfaces with a data-oriented, functional design. It focuses on high programmer productivity and scaling for large Single-Page Applications (SPAs).

Key architectural principles:

• Events are causal: State changes are driven by events.
• Views are purely reactive: Unlike many React-based patterns where views are causal (using hooks or lifecycle methods), re-frame views simply react to changes in the application state.
• React Integration: It leverages React (via Reagent) primarily as the rendering engine (the 'V' in MVC).

In re-frame, components are categorized by how they handle their Input/Output (I/O) requirements:

• Reagent Components (Widgets): Simple widgets representing a single value (e.g., an integer or string). They satisfy I/O requirements via positional arguments (e.g., a value and a callback-fn). They do not depend on re-frame internals.
• re-frame Components: Larger widget complexes, often representing an entire entity. They satisfy I/O requirements using re-frame primitives: subscribe for input and dispatch for output.

While Reagent provides the View (V) component of the MVC triad, it does not provide guidance for the Model (M) or Controller (C) components. As applications grow in complexity, developers face challenges regarding control logic, state management, websocket communication, and testability.

re-frame provides a pre-defined architecture to solve these challenges, whereas using Reagent alone requires you to design and implement your own architectural solutions for state and control logic.

re-frame follows a Data-Oriented Design pattern where data is code. In this paradigm, your application's logic is driven by a Domain-Specific Language (DSL) composed of Events.

Key concepts:

• Events as DSL: The set of events you design for your application acts as the 'assembly language' or instruction set of your system. They model user intent (e.g., clicks, drags, keypresses).
• Event Handlers as a Virtual Machine: The event handlers you register (using functions like reg-event-db) collectively form a 'virtual machine' that interprets and executes the event data.
• Execution Flow: One execution context (your application code) generates the data (the events), and another context (the re-frame runtime/event handlers) executes that data as instructions.

By designing a robust set of events, you are essentially defining the language your application speaks.

re-frame provides system architecture by managing the interconnections between functions (referred to as 'dominoes'). Instead of focusing solely on individual functions, re-frame focuses on how data 'flows' through them via composition.

re-frame uses different composition techniques depending on the context of the function pairs:

1. Queue/Router: Used for initial stages of data movement.
2. Interceptor Pipeline: Used for processing data through a sequence of steps.
3. Signal Graph: Used for managing complex data dependencies and flows.

Conceptually, re-frame acts as the 'transport' mechanism, similar to the water cycle, moving data through various 'forces' and phase changes within the system loop.

re-frame Enhancement Proposals (EPs) follow a lifecycle to indicate their maturity and readiness for implementation or discussion. When reading EPs, check their status to understand if they are stable or experimental:

• Placeholder: A skeleton/minimal entry.
• Drafting: Initial writing/thinking; may be incoherent or incorrect.
• UnderReview: Ready for general discussion in a dedicated repository Issue.
• Accepted or Rejected: The proposal has reached a decision.
• Released: The proposal has been implemented.

In re-frame, all application state is centralized in a single location called app-db.

Key concepts:

• app-db: An in-memory database (typically a Reagent atom containing a map) that serves as the single source of truth for the entire application.
• db: Refers to the actual value (the map) currently stored inside the app-db atom.
• Management: re-frame creates and manages the app-db for you; you do not need to declare it manually.

Treating app-db as an in-memory database rather than just a map in an atom allows you to perform CRUD operations, queries, and atomic transactions on your application state.

re-frame is implemented primarily in .cljc (Clojure Common) files rather than .cljs files. This design allows the library's tests to be executed on both the JVM and JS platforms.

If you need to access platform-specific interop logic, refer to the following files:

• interop.clj for JVM-specific interop.
• interop.cljs for JS-specific interop.

In re-frame, coeffects are external inputs (like a random number, GUID, current datetime, or LocalStore data) presented to an event handler as data.

There are two primary ways to register event handlers based on the data they need:

1. reg-event-db: Used when the handler only needs the application state. The handler signature is (fn [db event] ...).
2. reg-event-fx: Used when the handler needs application state PLUS other inputs (coeffects). The handler signature is (fn [cofx event] ...). In this case, cofx is a map containing a :db key (the application state) and other keys representing the injected coeffects.