mercury

# The life cycles of a mercury app A well structure mercury app is reasonably deterministic about when certain code runs. There are a few main "phases" - Reacting to browser events from the event loop - Running application update logic - Running the rendering cycle in `requestAnimationFrame` ## Reacting to the event loop The only time JavaScript get's executed is when the event loop tells your code that a new thing happened. This includes the initial evaluation of your `browser.js` source code. On first evaluation you setup your state, render your view and insert it into the DOM. ### Reacting to DOM events All your handling of DOM events (i.e. `click`, `change`, ...) should go through `dom-delegator`. `dom-delegator` intercepts all events and sees if you have registered an event handler using the `ev-{{name}}` syntax in `h()` or have registered a global listener using `delegator.addGlobalEventListener()`. If it finds one it will invoke it. If you suspect there might be an issue or bug with an event not getting fired you should go into `node_modules/mercury/node_modules/dom-delegator` and edit your copy of dom-delegator to add print statements. One common issue might be that your event is not in the whitelist ( https://github.com/Raynos/dom-delegator/blob/master/index.js#L10-L16 ) you should call `delegator.listenTo(eventName)` to make sure the delegator registers a global event handler for it. ### Reacting to other entries from the event loop There are many other ways the event loop can notify you that something has changed. It's highly recommended that you take all other effects & entries to the event loop and wrap them in a `geval` interface. For example: - https://github.com/Raynos/mercury/blob/master/examples/todomvc/input.js#L15 - https://github.com/Raynos/mercury/blob/github-issues/examples/github-issues-viewer/input.js#L11-L12 The benefit is that once you've done this, you can now trace or debug `geval` to check all new events entering the event loop. The other benefit is isolating your actual core application logic that does not concern itself with effects from the code with side effects. If you put all the IO in one bucket and create a "seperate" part of your app that is just "on a geval event, run business logic and update state" then that second part is really simple to reason about and unit test. ## Running application logic ### `geval` event listeners Eventually a event from the event loop will trigger into a new discrete value being emitted on a `geval` Event instance. This discrete value should be a application specific value, you shouldn't have any dom events or raw xhr objects being emitted through geval but instead have already converted them into something specific to your application. ### Application logic At this point the listener to the `geval` Event is generally one of your applications `update` functions that has access to either the top level state or one of the nested states. This is your core application / business logic and you do some computation and update the state into a new state. ## The request animation frame rendering loop ### Scheduling a `requestAnimationFrame` Any time you do `state.set()` or `state.some.key.set()` the `main-loop` module will check if we have scheduled a rerender yet and if not will schedule a render on the next frame. If you suspect a `requestAnimationFrame` is not scheduled then add logging or tracing to `main-loop`. ### Entering a `requestAnimationFrame` The browser will enter the `main-loop` rendering phase on the next animation frame. #### Rendering the view to create a new virtual tree. `main-loop` will call the top level `render` function that you passed to `mercury.app(state, render)` and create a new virtual tree. One of the tricks that makes this fast is the fact that `mercury.partial` is used to avoid evaluating subtrees in `render` unless needed If you suspect this doesn't happen just add debug statements to your top level render function. #### Calling diff on the trees The next step is the diff phase, here `vtree` will diff the new and previous tree. At this point any `partial`'s that have actually changed will be evaluated and their respective rendering functions will be called. If you suspect anything is wrong here it's recommended you add a print to `main-loop` to inspect the `patches` returned by the `diff()` function and see if your expected changes are included. #### Calling patch on the DOM The final step is calling `patch()` on the actual DOM with your patches from `diff`. This is the only place in the life cycle of a mercury app where actual DOM manipulation happens. it happens at the end of any raf we have scheduled. Here all patches are applied and all hooks get called If you suspect something is wrong here it's recommended that you use DOM mutation observers with a helper like listenMutation ( https://github.com/Raynos/jsonml-stringify/blob/master/examples/lib/listen-mutation.js ) to inspect the actual mutations applied to the DOM and see if they are what you might expect.