EP 002 Re-Frame Instances Concrete Design Proposal

[clyfe]

On 002-ReframeInstances.md.

Before I attempt a PR, I'd like feedback/approval of the design that follows.
It has no breaking changes to current public API.
How the frame is passed in Reagent is not in scope here.

A. Proposal

1. Frame

a). A "partial" frame has an app-db and an kind->id->handler registrar.
b). A "full" frame also has an EventQueue that has the partial frame. (See code samples below.)
c). The "default global frame" is a full frame instance: it's app-db is re-frame.db/app-db, registrar is
re-frame.registrar/kind->id->handler and has it's EventQueue is re-frame.router/event-queue.

2. The internal API

a) Is changed to pass (at least) a partial frame around, and to operate within that frame.
b) For dispatch/d-sync we pass the queue (or the full frame).

3. The public API

a) Has a new ns re-frame.frame. Mostly mirrors re-frame.core, fns take an extra 1st arg, a full frame.
c) "Old" re-frame.core API remains, but it's implementation delegates to re-frame.frame with the "default
global frame" frame.

4. EventQueue

a) Has an extra partial frame field.
b) Passes it on internal API calls.

B. Code Samples

1. Public Frame API

(ns my.re-frame.frame-api-sample
  (:require [re-frame.frame :as frame]))

(def frame (frame/make))

(frame/reg-event-db frame
  ::increment (fn [db _] (update db ::count (fnil inc 0))))

(frame/reg-sub frame
  ::count (fn [db _] (::count db 0)))

(defn main
  [:button {:on-click #(frame/dispatch frame [::increment])}
   "Increment: " @(frame/subscribe frame [::count])])

2. Frame Implementation

(ns re-frame.frame
  (:require
   [re-frame.fx] ;; base fxs
   [re-frame.db :as db]
   [re-frame.events :as events]
   [re-frame.router :as router]
   [re-frame.registrar :as registrar]
   [re-frame.interop :as interop]))

(def default ;; The default frame is "global re-frame"
  (let [partial-frame {:app-db            db/app-db
                       :kind->id->handler registrar/kind->id->handler}
        queue (router/make-event-queue partial-frame)]
    (assoc partial-frame :queue queue)))

(defn make
  "A Frame constructor, returns a new frame."
  []
  (let [partial-frame {:app-db            (interop/ratom {})
                       :kind->id->handler (atom @registrar/kind->id->handler)} ;; copy base fxs
        queue (router/make-event-queue partial-frame)]
    (assoc partial-frame :queue queue)))

;; Extra 1st arg: frame

(defn reg-event-db [frame id interceptors handler]
  (events/register frame id [... interceptors (db-handler->interceptor handler)]))

(defn reg-sub [frame query-id & args]
  (apply subs/reg-sub frame (into [query-id] args)))

(defn dispatch [frame event]
  (router/dispatch frame event))

(defn subscribe [frame query dynv]
  (subs/subscribe frame query dynv))

3. EventQueue(s)

(ns re-frame.router)

(deftype EventQueue [frame
                     ^:mutable fsm-state
                     ^:mutable queue
                     ^:mutable post-event-callback-fns]
  router/IEventQueue
  ...
  (-process-1st-event-in-queue
    [this]
    (let [event-v (peek queue)]
      (try
        (handle frame event-v)
        (set! queue (pop queue))
        (-call-post-event-callbacks this event-v)
        (catch :default ex
          (-fsm-trigger this :exception ex)))))
  ...)

(defn make-event-queue
  "An EventQueue constructor, returns a new EventQueue with the given frame."
  [frame]
  (->EventQueue frame :idle empty-queue {}))

(defn dispatch [event-queue event]
  (if (nil? event)
    (throw (ex-info "re-frame: you called \"dispatch\" without an event vector." {}))
    (push event-queue event))
  nil)

4. re-frame.core

(ns re-frame.core
  (:require [re-frame.frame :as frame]))

;; Calls into re-frame.frame with the "default global frame"

(defn reg-event-db [id interceptors handler]
  (frame/reg-event-db frame/default id interceptors handler]))

(defn reg-sub [query-id & args]
  (frame/reg-sub frame/default query-id args))

(defn dispatch [event]
  (frame/dispatch frame/default event))

(defn subscribe [query dynv]
  (frame/subscribe frame/default query dynv))

...

[clyfe]

Ok, looking at #137 and pure-frame I can tell I'm late at the party I thought was just starting.

[mike-thompson-day8]

The best (modern and maintained) fork I'm aware of is: https://github.com/nextjournal/freerange

[clyfe]

What's the current plan on EP 002? Do we want to do the above? Something else? Further pondering?