@lukekaalim/act-recon 1.0.0

package/algorithms.ts

@@ -0,0 +1,46 @@
+import { MagicError } from "@lukekaalim/act";
+
+export type ChangeReport = {
+  /** Index for Next that didnt exist in Prev */
+  created: number[],
+  /** Index for Prev that didnt exist in Next */
+  removed: number[],
+  
+  /** Index for elements that are the same previously and next */
+  nextToPrev: number[],
+};
+
+export type ChangeEqualityTest<Prev, Next> = (prev: Prev, next: Next, prevIndex: number, nextIndex: number) => boolean;
+
+export const calculateChangedElements = <Prev, Next>(
+  prevs: Prev[],
+  nexts: Next[],
+  isEqual: ChangeEqualityTest<Prev, Next>,
+): ChangeReport => {
+  const report: ChangeReport = {
+    created: [],
+    removed: [],
+    nextToPrev: [],
+  }
+  report.nextToPrev = nexts.map((next, nextIndex) => {
+    const prevIndex = prevs.findIndex((prev, prevIndex) => isEqual(prev, next, prevIndex, nextIndex));
+    if (prevIndex === -1)
+      report.created.push(nextIndex);
+    return prevIndex;
+  });
+  report.removed = prevs
+    .map((_, index) => {
+      return report.nextToPrev.indexOf(index) !== -1 ? -1 : index;
+    })
+    .filter((index) => index !== -1)
+  
+  return report;
+}
+
+export type SortedChangeReport = ChangeReport & {
+  /** Index for elements that moved around, but were equal */
+  moved: [number, number][],
+};
+export const calculateSortedChangedElements = (): SortedChangeReport => {
+  throw new MagicError();
+}

package/commit.ts

@@ -0,0 +1,69 @@
+import { createId, Element, OpaqueID } from "@lukekaalim/act";
+
+/**
+ * A single consistent id representing a commit in the act tree.
+ * Does not change.
+ */
+export type CommitID = OpaqueID<"CommitID">;
+/**
+ * A array of **CommitID**'s, starting at the "root" id and "descending"
+ * until reaching (including) the subject's ID. Useful for efficiently
+ * descending the tree to find a specific change.
+ * Does not change.
+ */
+export type CommitPath = readonly CommitID[];
+/**
+ * A ID for a particular _state_ a **Commit** is in - every time it or its
+ * children change, a commit with the same Id but a new CommitVersion
+ * is added to the tree, replacing the previous.
+ */
+export type CommitVersion = OpaqueID<"CommitVersion">;
+
+/**
+ * Structure for quick lookup and identification of a commit
+ */
+export type CommitRef = {
+  id: CommitID;
+  path: CommitPath;
+};
+export const CommitRef = {
+  new(path: CommitPath = []) {
+    const id = createId<'CommitID'>();
+    return {
+      path: [...path, id],
+      id,
+    }
+  }
+}
+
+/**
+ * Representing an entry in the act "Tree"
+ */
+export type Commit = CommitRef & {
+  version: CommitVersion;
+  element: Element;
+  children: CommitRef[];
+};
+
+export const updateCommit = (
+  ref: CommitRef,
+  element: Element,
+  children: CommitRef[]
+): Commit => ({
+  ...ref,
+  element,
+  children,
+  version: createId(),
+});
+
+export const Commit = {
+  new(element: Element, path: CommitPath = [], children: CommitRef[] = []): Commit {
+    return {
+      ...CommitRef.new(path),
+      version: createId(),
+      children,
+      element,
+    }
+  },
+  update: updateCommit,
+}

package/component.ts

@@ -0,0 +1,24 @@
+import { CommitRef } from "./commit";
+import { ContextManager, createContextManager } from "./context"
+import { createEffectManager, EffectManager } from "./effects"
+import { createStateManager, StateManager } from "./state"
+
+export type ComponentService = {
+  state: StateManager,
+  effect: EffectManager,
+  context: ContextManager,
+};
+
+export const ComponentService = {
+  create: (requestRender: (ref: CommitRef) => unknown): ComponentService => {
+    const effect = createEffectManager();
+    const context = createContextManager();
+    const state = createStateManager(effect, requestRender, context);
+
+    return {
+      effect,
+      context,
+      state,
+    }
+  }
+}

package/context.ts

@@ -0,0 +1,60 @@
+import { Context, ContextID, Element, providerNodeType } from "@lukekaalim/act";
+import { CommitID, CommitRef, Commit } from "./commit.ts";
+import { WorkThread } from "./thread.ts";
+
+export type ContextManager = ReturnType<typeof createContextManager>;
+
+export type ContextState<T> = {
+  id: CommitID,
+  contextId: ContextID,
+  consumers: Map<CommitID, CommitRef>,
+  value: T,
+}
+
+export const createContextManager = () => {
+  const contextStates = new Map<CommitID, ContextState<unknown>>();
+
+  return {
+    /**
+     * Take an element+commit, and if a change is detected,
+     * the context value is updated and the consumers are returned.
+     */
+    processContextElement(element: Element, commitId: CommitID) {
+      if (element.type !== providerNodeType)
+        return;
+      const prevState: ContextState<unknown> = contextStates.get(commitId) || {
+        id: commitId,
+        contextId: element.props.id as ContextID,
+        consumers: new Map(),
+        value: element.props.value,
+      };
+
+      if (prevState.value !== element.props.value || !contextStates.has(commitId)) {
+        contextStates.set(commitId, { ...prevState, value: element.props.value })
+        return [...prevState.consumers.values()];
+      }
+      return [];
+    },
+    subscribeContext<T>(ref: CommitRef, context: Context<T>): T {
+      const contextsInPath = ref.path.map(id => contextStates.get(id)).reverse();
+      
+      const closestContextOfType = contextsInPath.find(cState => cState && cState.contextId === context.id);
+      if (!closestContextOfType)
+        return context.defaultValue;
+      closestContextOfType.consumers.set(ref.id, ref);
+
+      return closestContextOfType.value as T;
+    },
+    unsubscribeContext(ref: CommitRef, context: Context<unknown>) {
+      const contextsInPath = ref.path.map(id => contextStates.get(id)).reverse();
+      
+      const closestContextOfType = contextsInPath.find(cState => cState && cState.contextId === context.id);
+      if (!closestContextOfType)
+        return;
+      closestContextOfType.consumers.delete(ref.id);
+    },
+    deleteContextValue(ref: CommitRef) {
+      contextStates.delete(ref.id);
+    }
+  };
+};

package/delta.test.ts

@@ -0,0 +1,108 @@
+import { noop } from 'lodash-es';
+
+import { describe, it } from "node:test";
+import { CommitTree } from "./tree";
+import { WorkThread } from "./thread";
+import { ComponentService } from "./component";
+import { applyUpdate } from "./delta";
+import { Update } from "./update";
+import { Commit, CommitRef } from "./commit";
+import { h } from "@lukekaalim/act";
+import { equal } from "node:assert/strict";
+
+describe('delta library', () => {
+
+  describe('generated deltas', () => {
+    it('should make a create delta if there is no prev', () => {
+      const tree = CommitTree.new();
+      const comp = ComponentService.create(noop);
+
+      const thread = WorkThread.new();
+      const element = h('test-element');
+      const ref = CommitRef.new();
+      const update = Update.fresh(ref, element);
+
+      applyUpdate(tree, comp, thread, update);
+
+      equal(thread.deltas.created.length, 1);
+      const delta = thread.deltas.created[0];
+      equal(delta.next.element, element);
+      equal(delta.next.id, ref.id);
+      equal(delta.next.path, ref.path);
+    })
+    it('should not make any deltas if the prev and next are the same (and there is no targets)', () => {
+      const tree = CommitTree.new();
+      const comp = ComponentService.create(noop);
+
+      const thread = WorkThread.new();
+      const element = h('test-element');
+      const prev = Commit.new(element);
+      const update = Update.existing(prev, element);
+      tree.commits.set(prev.id, prev);
+
+      applyUpdate(tree, comp, thread, update);
+
+      equal(thread.deltas.created.length, 0);
+      equal(thread.deltas.updated.length, 0);
+      equal(thread.deltas.removed.length, 0);
+      equal(thread.deltas.skipped.length, 0);
+    })
+    it('should make a skip delta if the prev and the next are the same, but there is a target', () => {
+      const tree = CommitTree.new();
+      const comp = ComponentService.create(noop);
+
+      const thread = WorkThread.new();
+      const element = h('test-element');
+      const prev = Commit.new(element);
+      // an imaginary child
+      const target = CommitRef.new(prev.path);
+
+      const update = Update.existing(prev, element);
+      update.targets.push(target);
+      tree.commits.set(prev.id, prev);
+
+      applyUpdate(tree, comp, thread, update);
+
+      equal(thread.deltas.skipped.length, 1);
+    })
+  })
+
+  it('should create a delta for a new id, and queue its children for creation', () => {
+    const tree = CommitTree.new();
+    const comp = ComponentService.create(noop);
+    const thread = WorkThread.new();
+    const childA = h('child-element-a');
+    const childB = h('child-element-b');
+    const element = h('new-element', {}, [childA, childB]);
+
+    const update = Update.fresh(Commit.new(element), element);
+    applyUpdate(tree, comp, thread, update);
+
+    equal(thread.deltas.created.length, 1);
+    equal(thread.pendingUpdates.length, 2);
+    
+    const delta = thread.deltas.created[0];
+    const updateA = thread.pendingUpdates[0];
+    const updateB = thread.pendingUpdates[1];
+
+    equal(delta.next.element, element);
+    equal(updateA.next, childA);
+    equal(updateB.next, childB);
+  })
+  it('should create a delete delta for a node, and queue its children to be deleted', () => {
+    const tree = CommitTree.new();
+    const comp = ComponentService.create(noop);
+    const thread = WorkThread.new();
+
+    const prev = Commit.new(h('element'))
+
+    tree.commits.set(prev.id, prev);
+
+    const update = Update.remove(prev);
+
+    applyUpdate(tree, comp, thread, update);
+
+    equal(thread.deltas.removed.length, 1);
+  })
+
+})

package/delta.ts

@@ -0,0 +1,100 @@
+import { Commit, CommitID, CommitRef, updateCommit } from "./commit.ts";
+import { WorkThread } from "./thread.ts";
+import { Update, calculateUpdates, isDescendant } from "./update.ts";
+import { CommitTree } from "./tree.ts";
+import { ComponentService } from "./component.ts";
+
+export type CreateDelta = { ref: CommitRef, next: Commit };
+export type UpdateDelta = { ref: CommitRef, next: Commit, prev: Commit };
+export type RemoveDelta = { ref: CommitRef, prev: Commit };
+export type SkipDelta =   { ref: CommitRef, next: Commit };
+
+
+export type DeltaSet = {
+  created: CreateDelta[],
+  updated: UpdateDelta[],
+  skipped: SkipDelta[],
+  removed: RemoveDelta[],
+};
+
+
+/**
+ * Given an Update, compute if there is any
+ * change to the tree (a "Delta"), and if more updates
+ * are needed to complete this work, appending them to
+ * the work thread
+ * */
+export const applyUpdate = (
+  tree: CommitTree,
+  comp: ComponentService,
+  thread: WorkThread,
+  { next, prev, ref, targets }: Update
+) => {
+  /**
+   * A change is considered identical if the "next element"
+   * is the same as the "prev element" - its the same as there
+   * being no change at all.
+   * */
+  const identicalChange = (next && prev && next.id === prev.element.id);
+  /**
+   * If we're "on a target's path", then we have to continue rendering.
+   */
+  const requiredChange = !!targets.find(target => target.path.includes(ref.id));
+  const requiresRerender = targets.some(target => target.id === ref.id);
+
+  if (identicalChange && !requiredChange)
+    return;
+
+  const prevChildren = prev && prev.children
+    .map(c => tree.commits.get(c.id) as Commit) || [];
+
+  // If we have a "Next", then this is a request to either
+  // Create or Update a commit.
+  if (next) {
+
+    // skip the change
+    if (identicalChange && !requiresRerender) {
+      const updates = prevChildren.map(prev => ({ ref: prev, prev, next: prev.element, targets }));  
+      thread.pendingUpdates.push(...updates);
+      const commit = Commit.update(ref, prev.element, prev.children);
+      thread.deltas.skipped.push({ ref, next: commit });
+      return;
+    }
+
+    const contextTargets = comp.context.processContextElement(next, ref.id) || [];
+    const nextTargets = [...contextTargets, ...targets];
+
+    const childNode = comp.state.calculateCommitChildren(thread, next, ref);
+
+    const [childRefs, updates] = calculateUpdates(ref, prevChildren, childNode);
+    const finalUpdates = updates.map(update => ({
+      ...update,
+      targets: nextTargets.filter(t => isDescendant(update.ref, t))
+    }))
+
+    const commit = Commit.update(ref, next, childRefs);
+
+    if (prev)
+      thread.deltas.updated.push({ ref, prev, next: commit });
+    else
+      thread.deltas.created.push({ ref, next: commit });
+
+    thread.pendingUpdates.push(...finalUpdates);
+    return;
+  }
+  // If we have a prev, but no next, then this is a requets to
+  // delete this commit. We still have emit "delete" updates
+  // as well for all children of this node too.
+  else if (prev && !next) {
+    const [, updates] = calculateUpdates(ref, prevChildren, []);
+    comp.state.clearCommitState(thread, ref);
+    // No need to reclculate targets - no more re-rendering
+    // will happen on this set of updates.
+
+    thread.deltas.removed.push({ ref: prev, prev });
+    thread.pendingUpdates.push(...updates);
+    return;
+  } else {
+    throw new Error(`No prev, no next, did this commit ever exist?`)
+  }
+};

package/effects.ts

@@ -0,0 +1,49 @@
+import { EffectCleanup, EffectConstructor, OpaqueID } from "@lukekaalim/act";
+import { WorkThread } from "./thread.ts";
+
+export type EffectID = OpaqueID<"EffectID">;
+export type EffectTask = {
+  id: EffectID,
+  task: () => void,
+}
+
+export const createEffectManager = () => {
+  const cleanups = new Map<EffectID, EffectCleanup>();
+
+  const enqueueEffect = (
+    thread: WorkThread,
+    id: EffectID,
+    effect: EffectConstructor
+  ) => {
+    thread.pendingEffects.push({
+      id,
+      task() {
+        const cleanup = cleanups.get(id);
+        if (cleanup) {
+          cleanups.delete(id);
+          cleanup();
+        }
+        cleanups.set(id, effect());
+      }
+    });
+  };
+  const enqueueTeardown = (
+    thread: WorkThread,
+    id: EffectID,
+  ) => {
+    thread.pendingEffects.push({
+      id,
+      task() {
+        const cleanup = cleanups.get(id);
+        if (cleanup) {
+          cleanups.delete(id);
+          cleanup();
+        }
+      }
+    })
+  };
+
+  return { enqueueEffect, enqueueTeardown };
+};
+
+export type EffectManager = ReturnType<typeof createEffectManager>;

package/mod.ts

@@ -0,0 +1,10 @@
+export * from './commit.ts'
+export * from './delta.ts';
+export * from './state.ts';
+export * from './algorithms.ts';
+export * from './update.ts';
+export * from './thread.ts';
+export * from './tree.ts';
+export * from './effects.ts';
+
+export * from './reconciler.ts';

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@lukekaalim/act-recon",
+  "type": "module",
+  "version": "1.0.0",
+  "main": "mod.ts",
+  "dependencies": {
+    "@lukekaalim/act": "^3.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,3 @@
+# `@lukekaalim/act-recon`
+
+A node reconciliation library for `@lukekaalim/act`.

package/reconciler.ts

@@ -0,0 +1,36 @@
+
+import { createThreadManager, WorkThread } from "./thread";
+import { CommitTree } from "./tree";
+import { ComponentService } from "./component";
+import { DeltaSet } from "./delta";
+
+/**
+ * A reconciler links all the relevant subsystems together.
+ * 
+ * @param space 
+ * @param onAfterRender 
+ * @returns 
+ */
+export const createReconciler = (
+  render: (deltas: DeltaSet) => void,
+  requestWork: () => void,
+) => {
+  const tree = CommitTree.new();
+  const components = ComponentService.create(ref => {
+    threads.request(ref);
+  });
+
+  const threads = createThreadManager(components, tree, requestWork, (deltas, effects) => {
+    render(deltas);
+    
+    // immedialty execute all side effects
+    for (const effect of effects)
+      effect.task();
+  });
+
+  return {
+    threads,
+    components,
+    tree,
+  }
+}

package/state.ts

@@ -0,0 +1,118 @@
+import { CommitRef, CommitID } from "./commit.ts";
+import { ContextManager } from "./context.ts";
+import * as act from '@lukekaalim/act';
+import { EffectManager, EffectID } from "./effects.ts";
+import { WorkThread } from "./thread.ts";
+
+export type ComponentState = {
+  ref: CommitRef;
+
+  values:   Map<number, unknown>;
+  deps:     Map<number, act.Deps>;
+  effects:  Map<number, EffectID>;
+  contexts:  Map<number, act.Context<unknown>>;
+};
+
+export const createStateManager = (
+  effectManager: EffectManager,
+  rerender: (ref: CommitRef) => unknown,
+  contextManager: ContextManager | null = null
+) => {
+  const states = new Map<CommitID, ComponentState>();
+
+  const createState = (ref: CommitRef): ComponentState => {
+    const state = {
+      ref,
+      values: new Map(),
+      effects: new Map(),
+      deps: new Map(),
+      contexts: new Map(),
+    };
+    states.set(ref.id, state);
+    return state;
+  };
+
+  const loadHookImplementation = (thread: WorkThread, ref: CommitRef) => {
+    const createHookImplementation = (): act.HookImplementation => {
+      const state = states.get(ref.id) || createState(ref);
+      let index = 0;
+      return {
+        useContext<T>(context: act.Context<T>): T {
+          if (!contextManager)
+            throw new act.MagicError();
+
+          state.contexts.set(index, context as act.Context<unknown>);
+          return contextManager.subscribeContext(ref, context);
+        },
+        useState<T>(initialValue: act.ValueOrCalculator<T>) {
+          const stateIndex = index++;
+          if (!state.values.has(stateIndex))
+            state.values.set(stateIndex, act.calculateValue(initialValue));
+
+          const value = state.values.get(stateIndex) as T;
+          const setValue: act.StateSetter<T> = (updater) => {
+            const prevValue = state.values.get(stateIndex) as T;
+            const nextValue = act.runUpdater(prevValue, updater);
+            state.values.set(stateIndex, nextValue);
+            rerender(ref);
+          };
+          return [value, setValue];
+        },
+        useEffect(effect, deps = null) {
+          const effectIndex = index++;
+          if (!state.effects.has(effectIndex))
+            state.effects.set(effectIndex, act.createId());
+          const prevDeps = state.deps.get(effectIndex) || null;
+          const effectId = state.effects.get(effectIndex) as EffectID;
+          state.deps.set(effectIndex, deps);
+          const depsChanges = act.calculateDepsChange(prevDeps, deps)
+          if (depsChanges)
+            effectManager.enqueueEffect(thread, effectId, effect);
+          return;
+        },
+      };
+    };
+
+    const hooks = createHookImplementation();
+    act.hookImplementation.useContext = hooks.useContext;
+    act.hookImplementation.useState = hooks.useState;
+    act.hookImplementation.useEffect = hooks.useEffect;
+  };
+
+  const calculateCommitChildren = (
+    thread: WorkThread,
+    element: act.Element,
+    commit: CommitRef
+  ) => {
+    const component = typeof element.type === "function" && element.type;
+    if (!component) return element.children;
+
+    const children = element.children;
+
+    const props = {
+      ...element.props,
+      children,
+    } as Parameters<typeof component>[0];
+
+    loadHookImplementation(thread, commit);
+    const result = component(props);
+
+    return result;
+  };
+  const clearCommitState = (thread: WorkThread, ref: CommitRef) => {
+    const state = states.get(ref.id)
+    if (!state)
+      return;
+    const effects = [...state.effects.values()];
+    const contexts = [...state.contexts.values()];
+    for (const effect of effects)
+      effectManager.enqueueTeardown(thread, effect);
+    if (contextManager)
+      for (const context of contexts)
+        contextManager.unsubscribeContext(ref, context);
+  };
+
+  return { calculateCommitChildren, clearCommitState, states };
+};
+
+export type StateManager = ReturnType<typeof createStateManager>;

package/thread.ts

@@ -0,0 +1,142 @@
+import { convertNodeToElements, createId, Node } from "@lukekaalim/act";
+import { Commit, CommitID, CommitRef } from "./commit.ts";
+import { ComponentService } from "./component.ts";
+import { applyUpdate, DeltaSet } from "./delta.ts";
+import { EffectTask } from "./effects.ts";
+import { CommitTree } from "./tree.ts";
+import { Update } from "./update.ts";
+
+/**
+ * A WorkThread is a mutable data struture that
+ * represents a particular "Tree Travesal Task".
+ * 
+ * Its expected when you start rendering, you
+ * may start rendering more nodes due to updates.
+ */
+export type WorkThread = {
+  started: boolean,
+
+  pendingUpdates: Update[],
+  pendingEffects: EffectTask[],
+
+  deltas: DeltaSet,
+};
+export const WorkThread = {
+  new(): WorkThread {
+    return {
+      started: false,
+      pendingEffects: [],
+      pendingUpdates: [],
+      deltas: {
+        created: [],
+        updated: [],
+        removed: [],
+        skipped: [],
+      },
+    }
+  },
+}
+
+export const createThreadManager = (
+  comp: ComponentService,
+  tree: CommitTree,
+  requestWork: () => void,
+  onThreadComplete: (deltas: DeltaSet, effects: EffectTask[]) => unknown = _ => {},
+) => {
+  const pendingUpdateTargets = new Map<CommitID, CommitRef>();
+
+  let currentThread = WorkThread.new();
+
+  const run = () => {
+    const update = currentThread.pendingUpdates.pop();
+    if (update) {
+      applyUpdate(tree, comp, currentThread, update);
+    }
+  }
+
+  const work = (test: () => boolean) => {
+    let tick = 0;
+
+    while (currentThread.pendingUpdates.length > 0) {
+      run()
+      tick++;
+
+      if (currentThread.pendingUpdates.length === 0) {
+        apply();
+      }
+
+      // only test every 10 ticks
+      if ((tick % 10 === 0) && test()) {
+        // early exit
+        return false;
+      }
+    }
+    // completed all work
+    return true;
+  }
+
+  const apply = () => {
+    // Update the tree.
+    for (const delta of currentThread.deltas.created)
+      tree.commits.set(delta.ref.id, delta.next);
+    
+    for (const delta of currentThread.deltas.skipped)
+      tree.commits.set(delta.ref.id, delta.next);
+    
+    for (const delta of currentThread.deltas.updated)
+      tree.commits.set(delta.ref.id, delta.next);
+    
+    for (const delta of currentThread.deltas.removed)
+      tree.commits.delete(delta.ref.id);
+
+    // Notify external
+    onThreadComplete(currentThread.deltas, currentThread.pendingEffects);
+
+    // clear the thread
+    currentThread = WorkThread.new();
+
+    // add any pending work that couldnt be completed last thread
+    if (pendingUpdateTargets.size > 0) {
+      const roots = CommitTree.getRootCommits(tree);
+      const targets = [...pendingUpdateTargets.values()];
+      for (const root of roots) {
+        currentThread.pendingUpdates.push(Update.distant(root, targets));
+      }
+      
+      pendingUpdateTargets.clear();
+    }
+  }
+
+  const request = (target: CommitRef) => {
+    if (currentThread.started) {
+      // TODO: add new requests to the current thread
+      // if they are compatible instead of scheduling another
+      // thread.
+      pendingUpdateTargets.set(target.id, target);
+    } else {
+      const roots = CommitTree.getRootCommits(tree);
+      for (const root of roots) {
+        currentThread.started = true;
+        currentThread.pendingUpdates.push(Update.distant(root, [target]));
+      }
+    }
+
+    requestWork();
+  }
+
+  const mount = (root: Node) => {
+    const elements = convertNodeToElements(root);
+    for (const element of elements) {
+      const id = createId<"CommitID">();
+      const ref = { id, path: [id] };
+      tree.roots.add(ref);
+      currentThread.pendingUpdates.push(Update.fresh(ref, element));
+    }
+
+    requestWork();
+  }
+
+  return { work, request, mount }
+};
+
+export type ThreadManager = ReturnType<typeof createThreadManager>;

package/tree.ts

@@ -0,0 +1,16 @@
+import { Commit, CommitID, CommitRef } from "./commit.ts";
+
+export type CommitTree = {
+  commits: Map<CommitID, Commit>,
+  roots: Set<CommitRef>,
+}
+
+export const CommitTree = {
+  new: (): CommitTree => ({
+    commits: new Map(),
+    roots: new Set(),
+  }),
+  getRootCommits: (tree: CommitTree) => {
+    return [...tree.roots].map(ref => tree.commits.get(ref.id) as Commit)
+  }
+}

package/update.ts

@@ -0,0 +1,121 @@
+import { convertNodeToElements, createId, Element, Node } from "@lukekaalim/act";
+import { calculateChangedElements, ChangeEqualityTest } from "./algorithms.ts";
+import { Commit, CommitID, CommitRef } from "./commit.ts";
+
+export type Update = {
+  /**
+   * The commit that should evaluate this
+   * update (if this commit does not exist,
+   * it should use this as it's ID and Path).
+   * */
+  ref: CommitRef;
+
+  /** If null, this update should cause
+   * this commit to be created */
+  prev: null | Commit;
+  /** If null, this update should cause
+   * this commit to be removed
+   */
+  next: null | Element;
+
+  /**
+   * List of commits that _must_ re-render as a
+   * concequence of this update.
+   */
+  targets: CommitRef[];
+};
+
+export const Update = {
+  fresh: (ref: CommitRef, next: Element): Update => ({
+    ref, next, prev: null, targets: []
+  }),
+  existing: (prev: Commit, next: Element): Update => ({
+    ref: prev, next, prev, targets: [],
+  }),
+  remove: (prev: Commit): Update => ({
+    ref: prev, next: null, prev, targets: [],
+  }),
+  distant: (root: Commit, targets: CommitRef[]): Update => ({
+    ref: root, next: root.element, prev: root, targets,
+  })
+}
+
+/** 
+ * Create an update for a single commit and node pair.
+ */
+export const calculateFastUpdate = (
+  parentRef: CommitRef,
+  prevCommit: null | Commit,
+  element: Element,
+): [CommitRef[], Update[]] => {
+  const compatible = prevCommit && prevCommit.element.type === element.type;
+
+  const updates: Update[] = [];
+  const refs: CommitRef[] = [];
+
+  if (!compatible) {
+    const id = createId<"CommitID">();
+    const path = [...parentRef.path, id];
+    const ref = { id, path };
+    updates.push(Update.fresh(ref, element));
+
+    refs.push(ref);
+    if (prevCommit)
+      updates.push(Update.remove(prevCommit));
+  } else if (prevCommit) {
+    refs.push(prevCommit);
+    updates.push(Update.existing(prevCommit, element));
+  }
+
+  return [refs, updates];
+};
+
+
+const simpleElementEqualityTest: ChangeEqualityTest<Commit, Element> = (prev, next, prev_index, next_index) =>
+  prev.element.type === next.type && prev_index === next_index;
+
+/**
+ * Returns a list of all updates that should
+ * occur -- given a set of commits and a
+ * new node that represents the next state of
+ * those commits.
+ *
+ * Also returns as part of it's tuple the next
+ * canonical list of refs, taking into account
+ * new commits and removed commits.
+ */
+export const calculateUpdates = (
+  parentRef: CommitRef,
+  commits: Commit[],
+  node: Node
+): [CommitRef[], Update[]] => {
+  const elements = convertNodeToElements(node);
+
+  // Fast exit if there is only one node
+  if (commits.length <= 1 && elements.length == 1)
+    return calculateFastUpdate(parentRef, commits[0], elements[0])
+
+  const change_report = calculateChangedElements(commits, elements, simpleElementEqualityTest);
+
+  const newOrPersisted = elements.map((next, index) => {
+    const prevIndex = change_report.nextToPrev[index];
+    const prev = prevIndex !== -1 ? commits[prevIndex] : null;
+
+    if (!prev)
+      return Update.fresh(CommitRef.new(parentRef.path), next);
+    
+    return Update.existing(prev, next);
+  });
+  const removed = change_report.removed.map((index) => {
+    const prev = commits[index];
+    return Update.remove(prev);
+  });
+  const updates = [...newOrPersisted, ...removed];
+
+  const refs = newOrPersisted.map((p) => p.ref);
+  return [refs, updates];
+};
+
+export const isDescendant = (anscestor: CommitRef, descendant: CommitRef) => {
+  return descendant.path.includes(anscestor.id);
+}