@lukekaalim/act-recon 3.0.0-alpha.3 → 3.0.0

package/docs/lifecycle_of_an_update.md

@@ -0,0 +1,465 @@
+# Lifecycle of an Update
+
+Journey with us as we go through the code to see which
+systems are responsible for the various parts of
+managing an Act Tree inside `@lukekaalim/act-recon`.
+
+We'll start at a button onclick handler, and end up
+where we submit a packet of changes to our renderer.
+
+> This description of these processes is a little simplified to skip some of the
+> more complicated edge cases - so example code here does not 1-1 match
+> the actual library code.
+
+  1. [Clicking the Button](#1-clicking-the-button)
+  2. [Inside the Reconciler](#2-inside-the-reconciler)
+  3. [Queuing a new WorkTask](#3-queuing-a-new-work-task)
+  4. [Working in the Thread](#4-working-in-the-thread)
+  5. [Learning the History](#5-learning-the-history)
+  6. [Running the Component](#6-running-the-component)
+  7. [Generating the Diff](#7-generating-the-diff)
+  8. [Handling the Output](#8-handling-the-output)
+  9. [Submitting the Delta](#9-submitting-the-delta)
+  10. [Conclusion](#10-conclusion)
+
+## 1. Clicking the Button
+
+Typically, a user will interact with an application in some way - click a button,
+type some text. Something like:
+
+```ts
+const [count, setCount] = useState(0)
+
+function onClick() {
+  setCount(count + 1)
+}
+
+return h('button', { onClick }, `Clicked ${count} times!`);
+
+```
+Our "setCount" call is the function that starts everything off! Otherwise
+referred to as the `setState` function.
+
+The setState function generated by `useState()` has captured a few variables
+internally when it was created:
+  - A ["CommitRef2"](/Reconciler#@lukekaalim/act-recon.CommitRef2) to a specific
+    part of our Act Tree where the calling component lives.
+  - A "ComponentState" - a mutable instance that stores all the variables relevant
+    for rendering a component, including such things as a map of
+    literal values of each `useState` call.
+  - The ["Reconciler"](/Reconciler#@lukekaalim/act-recon.Reconciler2) to which this entire app belongs.
+
+So, to kick off our update, we need to two things: we need to update the internal
+state of our component to use the new value provided to setState, and we need
+to re-render the component. For the second one, we just ask the reconciler, and give it
+that `ref` we had from before
+
+
+```ts
+// somewhere
+const ref: CommitRef2 = ...;
+const componentState: ComponentState = ...;
+const reconciler: Reconciler2 = ...;
+
+// the second return value from useState
+// e.g.
+// [state, setState] = useState();
+setState(newValue) {
+  // update our component state
+  componentState.values.set(hookId, newValue);
+  // then request our component be re-rendered
+  reconciler.render(ref);
+}
+```
+
+## 2. Inside the Reconciler
+
+Next stop: the reconciler. It's received a request
+to re-render a specific component. It's mainly going
+to delegate to it's [WorkThread](/Reconciler#@lukekaalim/act-recon.WorkThread2),
+but while it does it will also tell the **Scheduler** that it should
+get itself ready to do some work.
+
+```ts
+// somewhere
+const scheduler: Scheduler = ...;
+const thread: WorkThread2 = ...;
+
+render(ref: CommitRef2) {
+  thread.queue(ref);
+  scheduler.requestCallback();
+}
+```
+
+## 3. Queuing a new WorkTask
+
+Inside the WorkThread, it does a few checks before actually
+promising to do any work:
+  - Am I already in the middle of a render? If so:
+    - Do I already have an update for this commit specifically?
+      If so, I don't actually need to do anything.
+    - Have I already rendered this Commit? I'm only allowed
+      to render a commit once per "pass", so I'll add this to my
+      "missed" queue, and I'll get started on it next pass.
+    - Am I currently rendering any of this commit's parents?
+      If so, just mark all the bits in-between as "MustVisit",
+      and that other update will handle the re-render.
+  
+If none of those conditions are met, the thread will add a
+new [WorkTask](/Reconciler#@lukekaalim/act-recon.WorkTask) to it's queue.
+
+To add this work task, we need to turn the CommitRef into the
+actual commit it references - we can do this by just asking
+the commit tree (which the WorkThread has access to)! We can
+just pass the commit to once of the WorkTask constructors
+to tell it what kind of operation we want to perform.
+
+In this case, all we want is for the task to visit that node,
+which should cause a re-render (thus updating our component).
+
+```ts
+const tree: CommitTree2 = ...;
+
+const missed = new Set<CommitID>();
+const mustVisit = new Set<CommitID>();
+const mustRender = new Set<CommitID>();
+const visited = new Set<CommitID>();
+
+const tasks: WorkTask[] = [];
+
+queue(ref) {
+  if (mustRender.has(ref.id))
+    return;
+
+  if (visited.has(ref.id)) {
+    missed.add(ref);
+    return;
+  }
+
+  if (ref.path.find(ancestorId => tasks.find(task => task.ref.id === ancestorId))) {
+    ref.path.forEach(ancestorId => mustVisit.add(ancestorId))
+    return;
+  }
+
+  mustRender.add(ref.id);
+  mustVisit.add(ref.id);
+  const commit = tree.commits.get(ref.id) as Commit2;
+  tasks.push(WorkTask.visit(commit));
+}
+
+```
+
+## 4. Working in the Thread
+
+After adding a new tasks to the queue, nothing immediately happens. But
+remember previously, when we called `scheduler.requestCallback`? At
+some point later, the callback we requested will trigger, sending us back to the
+reconciler.
+
+The reconciler asks the thread if there is work to do (the thread checks it's tasks,
+which we might have just added to). If there is, the reconciler asks the thread to work!
+
+Kicking things off here, our thread just pops off the first task off it's task queue.
+It does a few more checks to see if it can skip out on doing work, such as:
+  - Does this task just ask be to visit this node? If so:
+    - Is this node on my MustVisit list? Skip it not.
+    - Is this node something I have to directly render? If not
+      (aka I need to visit this node, but I don't need to render it),
+      just queue up some tasks to visit this node's children.
+
+Otherwise, it will commit to doing the work - it's going to start
+by asking the tree to process the commit we have inside the WorkTask.
+
+The tree will give us an output object, which we will use later.
+
+```ts
+const tree: CommitTree2 = ...;
+
+work() {
+  const task = tasks.pop();
+
+  if (task.isVisiting()) {
+    if (!mustVisit.has(task.ref.id))
+      return;
+
+    if (!mustRender.has(task.ref.id)) {
+      const visits = task.commit.children
+        .map(child => WorkTask.visit(child));
+      tasks.push(visits);
+      return;
+    }
+  }
+
+  const output = tree.processElement(task.commit.element, task.commit)
+  // more later
+}
+```
+
+## 5. Learning the History
+
+A "Visit" task is actually just an instance of a generic task where the
+"prev" element and the "next" element are the same - we know that our
+component's special internal state has changed, not it's external props.
+
+> Other types of Tasks often describe a specific change - the addition
+> of more props or the changing of a value.
+
+When a element is "processed" (like a component or "div"), it should
+return some children, which should create additional tasks to process.
+
+We want to make sure that children generated in the past are matched up
+to the return values of the component, so when a component renders a second
+time we can match up it's old children to it's new children.
+
+Our tree's processing has a few tasks: first, it checks our commit's
+history to see who our old children were, then figure out what kind
+of element we are. There are some special cases for Providers and Boundaries,
+but the one we care about is the "Component", or
+`typeof element.type === 'function'` case.
+
+The tree loads the previous children, and the components current state, before
+passing it to the ElementOutput, telling it to process the component. The tree
+also has a reference to the reconciler, which it passes along too.
+
+```ts
+const reconciler: Reconciler2 = ...;
+const componentStates: Map<CommitID, ComponentState> = ...;
+
+processElement(element: Element, commit: CommitRef2) {
+  const output = new ElementOutput2()
+  output.prevChildren = commit.children.map(childRef => commits.get(childRef.id));
+
+  switch (typeof element.type) {
+    case 'function':
+      const state = componentStates.get(ref.id);
+
+      output.processComponent(commit.ref, element.type, element, reconciler, state);
+      return output;
+  }
+}
+
+```
+
+## 6. Running the Component
+
+The ElementOutput is finally responsible for determining all the things
+that will change when the component is processed. First thing it
+does it is sets up the Hook Globals - assigning implementations to
+the hooks imported from `@lukekaalim/act`;
+
+> This is actually where,
+> from the first chapter, those variables like ComponentState and Reconciler
+> are captured by our hooks.
+
+Once everything is set up, we actually call our component function (finally!).
+
+The results of the function (the element actually returned by our component)
+is passed to our calculateDiff function, which uses the history we have from
+our previous children, and our new result, the identify what nodes should
+be created, updated, or destroyed.
+
+```ts
+
+processComponent(ref, component, element, reconciler, componentState) {
+  // make hooks and set them up
+  hookImplementation.useState = function useState() {
+    const hookId = state.hookIndex++;
+
+    function setState(newValue) {
+      // update our component state
+      componentState.values.set(hookId, newValue);
+      // then request our component be re-rendered
+      reconciler.render(ref);
+    }
+    // ...blah
+    return [value, setState]
+  }
+  // and do so for useEffect & useContext...
+
+  // reset the hook counter, used to give
+  // each "call" of a hook a unique identifier
+  state.hookIndex = 0;
+
+  // run the component!
+  const result = component(element.props);
+
+  this.diff = this.calculateDiff(result);
+}
+
+```
+## 7. Generating the Diff
+
+We want to essentially learn four things:
+  - Stuff was there before but isn't now (Deleted)
+  - Stuff wasn't there before but is there now (Created)
+  - Stuff that moved around (Moved)
+  - Stuff that stayed the same (Persisted)
+
+We'll call all these facts a "ChangeReport". We can actually compact 
+the representation a little into just two arrays: "transform" and "removed".
+
+Element in transform are just array indices for where an element "was" in the previous
+state. If the index is `-1`, that's the special case for when an element didn't exist before.
+
+Element in the "removed" array are just elements that _were_ in the prev state, but not in the new
+one.
+
+We have some criteria to tell if something is considered "the same" (evaluated in this order):
+  1. Are they the same "type" of element? If not, they aren't the same.
+  2. Does either element have a key? If once of them does have a key,
+    and they don't match, then they aren't the same.
+  3. Do they appear in the same index? Then they are the same!
+  4. Otherwise, they are not the same.
+
+We call this the `EqualityTest`, which we can represent as a function.
+
+To combo all this up, we just run through both lists, marking stuff as visited
+and add it to either "transform" or "removed" lists depending on
+how it handles the equality test. Then, we take a look
+through those lists, and create WorkTasks for each new change.
+
+```ts
+const tasks: WorkTask[] = [];
+const newChildren: CommitRef[] = []
+
+calculateDiff(result) {
+  // prevChildren was given to us by the Tree
+  const changeReport = generateChangeReport(this.prevChildren, result)
+
+  for (/* loop through "transform" */) {
+    newChildren.push(child.ref);
+
+    if (moved) {
+      tasks.push(WorkTask.moved(child))
+    } else if (created) {
+      tasks.push(WorkTask.fresh(child))
+    } else {
+      tasks.push(WorkTask.update(child))
+    }
+  }
+  for (/* loop through "removed" */) {
+    tasks.push(WorkTask.remove(child))
+  }
+}
+
+generateChangeReport(prevs, nexts) {
+  const visited = new Set();
+  const transform = [];
+  const removed = [];
+
+  for (let nextIndex = 0; nextIndex < nexts.length; nextIndex++) {
+    const next = nexts[nextIndex];
+    const prevIndex = prevs.findIndex((prev, prevIndex) => equalityTest(prev, next, prevIndex, nextIndex));
+    transform.push(prevIndex);
+    if (prevIndex !== -1)
+      visited.add(prevIndex);
+  }
+  for (let i = 0; i < prevs.length; i++) {
+    if (!visited.has(i))
+      removed.push(i);
+  }
+
+  return { transform, removed };
+}
+```
+
+## 8. Handling the Output
+
+As you saw, the ElementOutput object bubbles all the way back up
+to the Thread, and now we'll tackle the other half of the thread code
+in the `work` function.
+
+We update a few systems with the new output, such as:
+  - The Commit for the component is updated to reflect it's (possibly)
+    new children.
+  - The "previous" element, before the update, and the updated commit
+    are passed to a "Delta".
+  - The additional work tasks created are appended to the "tasks" array,
+    so our Thread will recursively keep following these instructions until
+    it "walks" through the entire affect tree.
+
+```ts
+const tree: CommitTree2 = ...;
+
+work() {
+
+  // ...as seen previously
+  const output = tree.processElement(task.commit.element, task.commit)
+  
+  const oldElement = commit.element;
+  commit.update(element, output.newChildren);
+
+  this.delta.update(oldElement, commit);
+
+  this.tasks.push(...output.tasks);
+}
+```
+
+## 9. Submitting the Delta
+
+The "Delta" object that our thread updates represents all
+the changes that a thread has recorded - containing
+the "previous" and "next" state of any commit in a map. This structure
+will be passed to the renderer when the thread runs out of tasks to do.
+
+If a thread makes multiple changes to a single commit, only the final
+change is recorded and sent to the renderer.
+
+The thread discarded and a new one is created after it's delta is sent
+to the renderer.
+
+```ts
+// inside delta
+updates: Map<CommitID, { prev: Element, next: Commit2 }>
+
+update(prev: Element, next: Commit2, moved: boolean) {
+  const change = this.changed.get(next.ref.id);
+  if (change) {
+    change.next = next;
+  } else {
+    this.changed.set(next.ref.id, { prev, next, moved });
+  }
+}
+
+// inside reconciler
+onTasksComplete() {
+  // store the old thread
+  const currentThread = this.thread;
+
+  // Start a new thread
+  this.thread = new WorkThread2(this.tree);
+
+  // send delta
+  this.renderer.render(currentThread.delta);
+}
+```
+
+## 10. Conclusion
+
+And with that, our renderer receives a lovely
+package of a "Delta", which it will
+then use to modify the existing DOM
+to update our button's text.
+
+You can see that our Component visit task
+probably created a few more Update tasks
+of it's own - so our reconciler will be
+working for a few cycles until it runs out of
+tasks and submits our delta.
+
+We didn't cover all topics, such as:
+  - **How do you start the process?** The "mount" process is really
+  just a special case of the "update" process, where there is just
+  no previous history, and everything is a `WorkTask.create`.
+  "unmount" is also similar, where there is history but no future state.
+  - **What happens to "missed" updates?** We mentions that
+  a thread never repeats a node if it's already rendered it, saving it
+  for another pass and marking it missed.
+  Essentially, when our renderer finishes all it's current tasks,
+  it checks it's "missed" array, and if there are entries there, it
+  just converts them to tasks and starts again from the top, clearing
+  its internal state (except for it's "Delta", which accumulates over
+  these passes). Only when both "missed" and "tasks" is empty is a thread
+  considered "done".
+  - **What happens after the Delta is sent to the renderer?** This
+  is better covered in the [Lifecycle of a Render](/)