@planet-matrix/mobius-model 0.1.1

package/src/signal-core/reactive-system.ts

@@ -0,0 +1,658 @@
+import type { Flags } from './flags'
+
+export interface Node {
+  /**
+   * 当前节点的上游连接链中的第一个连接。
+   */
+  headDepLink?: Link | undefined;
+  /**
+   * 当前节点的上游连接链中的最后一个连接。
+   */
+  tailDepLink?: Link | undefined;
+
+  /**
+   * 当前节点的下游连接链中的第一个连接。
+   */
+  headSubLink?: Link | undefined;
+  /**
+   * 当前节点的下游连接链中的最后一个连接。
+   */
+  tailSubLink?: Link | undefined;
+
+  /**
+   * 当前节点的标记。
+   */
+  flags: Flags;
+}
+/**
+ * 连接用于表示某个节点（下游节点）依赖了某个节点（上游节点）。
+ *
+ * 多个连接连在一起形成连接链，连接链只有两种情况：
+ *
+ * 1. 下游连接链：链中所有连接的上游节点相同，通过该链可以找到该上游节点的所有下游节点。
+ * 2. 上游连接链：链中所有连接的下游节点相同，通过该链可以找到该下游节点的所有上游节点。
+ */
+export interface Link {
+  /**
+   * 连接中的上游节点。
+   */
+  dep: Node;
+  /**
+   * 连接中的上游节点的下游连接链中的上一个连接。（下一个下游连接）
+   */
+  prevSubLink?: Link | undefined;
+  /**
+   * 连接中的上游节点的下游连接链中的下一个连接。（上一个下游连接）
+   */
+  nextSubLink?: Link | undefined;
+
+  /**
+   * 连接中的下游节点。
+   */
+  sub: Node;
+  /**
+   * 连接中的下游节点的上游连接链中的上一个连接。（上一个上游连接）
+   */
+  prevDepLink?: Link | undefined;
+  /**
+   * 连接中的下游节点的上游连接链中的下一个连接。（下一个上游连接）
+   */
+  nextDepLink?: Link | undefined;
+}
+
+export interface CreateReactiveSystemOptions {
+  /**
+   * 当节点的值需要更新时此回调会执行，返回值表示更新前后值是否变化。
+   */
+  update(sub: Node): boolean;
+  /**
+   * 当节点的上游节点的值发生变化后此回调会执行。
+   *
+   * 注意：只有包含 Watching 标记的节点会触发此方法。
+   */
+  notify(node: Node): void;
+  /**
+   * 当节点不再拥有任何下游节点时此回调会执行。
+   */
+  unwatched(node: Node): void;
+}
+export interface ReactiveSystem {
+  /**
+   * 判断连接是否是节点的上游连接。
+   */
+  isDepLinkOfNode(link: Link, node: Node): boolean;
+  /**
+   * 判断连接是否是节点的下游连接。
+   */
+  isSubLinkOfNode(link: Link, node: Node): boolean;
+  /**
+   * 获取两个节点之间的连接。
+   */
+  getLinkOfNodes(dep: Node, sub: Node): Link | undefined;
+  /**
+   * 判断两个节点之间是否存在连接。
+   */
+  isLinked(nodeA: Node, nodeB: Node): boolean;
+  /**
+   * 为两个节点建立连接。
+   */
+  linkNode(dep: Node, sub: Node): void;
+  /**
+   * 为两个节点解除连接。
+   */
+  unlinkNode(nodeA: Node, nodeB: Node): void;
+  /**
+   * 解除连接。
+   */
+  unlink(link: Link): void;
+  /**
+   * 为节点解除所有上游连接。
+   */
+  unlinkAllDepLinksOfNode(node: Node): void;
+  /**
+   * 为节点解除所有下游连接。
+   */
+  unlinkAllSubLinksOfNode(node: Node): void;
+
+
+  /**
+   * 获取当前正在进行依赖收集的节点。
+   */
+  getActiveNodeAsSub(): Node | undefined;
+  /**
+   * 设置当前正在进行依赖收集的节点。
+   */
+  setActiveNodeAsSub(nodeAsSub: Node): void;
+  /**
+   * 重置当前正在进行依赖收集的节点。
+   */
+  resetActiveNodeAsSub(): void;
+  /**
+   * 将指定节点作为当前正在进行依赖收集的节点执行指定函数。
+   */
+  withActiveNodeAsSub<T>(nodeAsSub: Node, fn: () => T): T;
+  /**
+   * 开始对节点（作为下游节点）进行依赖收集。
+   */
+  startTracking(node: Node): void;
+  /**
+   * 结束对节点（作为下游节点）进行依赖收集。
+   */
+  endTracking(node: Node): void;
+  /**
+   * 对节点（作为下游节点）进行依赖收集。
+   */
+  withTracking<T>(node: Node, fn: () => T): T;
+  /**
+   * 为两个节点建立连接（依赖收集优化版）。
+   */
+  linkNodeOptimizedForTracking(dep: Node, sub: Node): void;
+  /**
+   * 将节点作为当前正在进行依赖收集的节点的上游节点。
+   */
+  track(node: Node): void;
+
+  /**
+   * 当节点的值发生变化后，调用此方法更新直接下游节点的标记。
+   */
+  shallowPropagate(node: Node): void;
+  /**
+   * 当节点的值发生变化后，调用此方法更新所有下游节点的标记。
+   */
+  deeeeepPropagate(node: Node): void;
+  /**
+   * 解决节点的 Pending 标记。
+   */
+  resolvePending(node: Node): void;
+}
+export const createReactiveSystem = (options: CreateReactiveSystemOptions): ReactiveSystem => {
+  const { update, notify, unwatched } = options;
+
+  const isDepLinkOfNode = (link: Link, node: Node): boolean => {
+    let tailDepLinkOfNode = node.tailDepLink;
+    while (tailDepLinkOfNode !== undefined) {
+      if (tailDepLinkOfNode === link) {
+        return true;
+      }
+      tailDepLinkOfNode = tailDepLinkOfNode.prevDepLink;
+    }
+    return false;
+  }
+
+  const isSubLinkOfNode = (link: Link, node: Node): boolean => {
+    let tailSubLinkOfNode = node.tailSubLink;
+    while (tailSubLinkOfNode !== undefined) {
+      if (tailSubLinkOfNode === link) {
+        return true;
+      }
+      tailSubLinkOfNode = tailSubLinkOfNode.prevSubLink;
+    }
+    return false;
+  }
+
+  const getLinkOfNodes = (dep: Node, sub: Node): Link | undefined => {
+    let subToCheck = dep.tailSubLink;
+    while (subToCheck !== undefined) {
+      if (subToCheck.sub === sub) {
+        return subToCheck;
+      }
+      subToCheck = subToCheck.prevSubLink;
+    }
+    return undefined;
+  }
+
+  const isLinked = (nodeA: Node, nodeB: Node): boolean => {
+    const aIsDepOfB = getLinkOfNodes(nodeA, nodeB) !== undefined;
+    if (aIsDepOfB === true) {
+      return true;
+    }
+    const bIsDepOfA = getLinkOfNodes(nodeB, nodeA) !== undefined;
+    if (bIsDepOfA === true) {
+      return true;
+    }
+    return false;
+  }
+
+  const linkNode = (dep: Node, sub: Node): void => {
+    /**
+     * 检查是否存在重复连接。
+     */
+    const isLinked = getLinkOfNodes(dep, sub) !== undefined;
+    if (isLinked === true) {
+      return;
+    }
+
+    /**
+     * 建立新连接。
+     */
+    const newLink: Link = {
+      dep,
+      prevSubLink: undefined,
+      nextSubLink: undefined,
+
+      sub,
+      prevDepLink: undefined,
+      nextDepLink: undefined,
+    };
+
+    const tailDepLinkOfSub = sub.tailDepLink;
+    if (tailDepLinkOfSub !== undefined) {
+      tailDepLinkOfSub.nextDepLink = newLink;
+      newLink.prevDepLink = tailDepLinkOfSub;
+    } else {
+      sub.headDepLink = newLink;
+    }
+    sub.tailDepLink = newLink;
+
+    const tailSubLinkOfDep = dep.tailSubLink;
+    if (tailSubLinkOfDep !== undefined) {
+      tailSubLinkOfDep.nextSubLink = newLink;
+      newLink.prevSubLink = tailSubLinkOfDep;
+    } else {
+      dep.headSubLink = newLink;
+    }
+    dep.tailSubLink = newLink;
+  }
+
+  const unlinkNode = (nodeA: Node, nodeB: Node): void => {
+    const linkAB = getLinkOfNodes(nodeA, nodeB);
+    if (linkAB !== undefined) {
+      unlink(linkAB);
+    }
+    const linkBA = getLinkOfNodes(nodeB, nodeA);
+    if (linkBA !== undefined) {
+      unlink(linkBA);
+    }
+  }
+
+  const unlink = (link: Link): void => {
+    const prevDepLink = link.prevDepLink;
+    const dep = link.dep;
+    const nextDepLink = link.nextDepLink;
+    const prevSubLink = link.prevSubLink;
+    const sub = link.sub;
+    const nextSubLink = link.nextSubLink;
+
+    /**
+     * 处理上游连接链。
+     */
+
+    if (nextDepLink !== undefined) {
+      // 如果当前连接的下一个连接存在，则将当前连接的下一个连接的上一个连接指向当前连接的上一个连接
+      nextDepLink.prevDepLink = prevDepLink;
+    } else {
+      // 如果当前连接的下一个连接不存在，则将当前连接的上一个连接作为最后一个连接
+      sub.tailDepLink = prevDepLink;
+    }
+    if (prevDepLink !== undefined) {
+      // 如果当前连接的上一个连接存在，则将当前连接的上一个连接的下一个连接指向当前连接的下一个连接
+      prevDepLink.nextDepLink = nextDepLink;
+    } else {
+      // 如果当前连接的上一个连接不存在，则将当前连接的下一个连接作为第一个连接
+      sub.headDepLink = nextDepLink;
+    }
+
+    /**
+     * 处理下游连接链。
+     */
+
+    if (nextSubLink !== undefined) {
+      // 如果当前连接的下一个连接存在，则将当前连接的下一个连接的上一个连接指向当前连接的上一个连接
+      nextSubLink.prevSubLink = prevSubLink;
+    } else {
+      // 如果当前连接的下一个连接不存在，则将当前连接的上一个连接作为最后一个连接
+      dep.tailSubLink = prevSubLink;
+    }
+    if (prevSubLink !== undefined) {
+      // 如果当前连接的上一个连接存在，则将当前连接的上一个连接的下一个连接指向当前连接的下一个连接
+      prevSubLink.nextSubLink = nextSubLink;
+    } else {
+      // 如果当前连接的上一个连接不存在，则将当前连接的下一个连接作为第一个连接
+      dep.headSubLink = nextSubLink;
+    }
+
+    /**
+     * 处理完连接链之后，检查当前连接中的上游节点是否还有下游节点。
+     *
+     * - 如果有：什么都不做。
+     * - 如果没有：触发回调。
+     */
+    if (dep.headSubLink === undefined && dep.tailSubLink === undefined) {
+      unwatched(dep);
+    }
+
+    /**
+     * 彻底断引用，防止内存泄漏。
+     */
+    link.prevDepLink = undefined;
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    link.dep = undefined as unknown as Node; // type cast
+    link.nextDepLink = undefined;
+    link.prevSubLink = undefined;
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    link.sub = undefined as unknown as Node; // type cast
+    link.nextSubLink = undefined;
+  }
+
+  const unlinkAllDepLinksOfNode = (node: Node): void => {
+    let currentDepLink = node.headDepLink;
+    while (currentDepLink !== undefined) {
+      const nextDepLink = currentDepLink.nextDepLink;
+      unlink(currentDepLink);
+      currentDepLink = nextDepLink;
+    }
+  }
+
+  const unlinkAllSubLinksOfNode = (node: Node): void => {
+    let currentSubLink = node.headSubLink;
+    while (currentSubLink !== undefined) {
+      const nextSubLink = currentSubLink.nextSubLink;
+      unlink(currentSubLink);
+      currentSubLink = nextSubLink;
+    }
+  }
+
+  let prevActiveNodeAsSubStack: Array<Node | undefined> = [];
+  let activeNodeAsSub: Node | undefined = undefined;
+  const getActiveNodeAsSub = (): Node | undefined => {
+    return activeNodeAsSub;
+  }
+  const setActiveNodeAsSub = (nodeAsSub: Node): void => {
+    prevActiveNodeAsSubStack.push(activeNodeAsSub);
+    activeNodeAsSub = nodeAsSub;
+  }
+  const resetActiveNodeAsSub = (): void => {
+    activeNodeAsSub = prevActiveNodeAsSubStack.pop();
+  }
+  const withActiveNodeAsSub = <T>(nodeAsSub: Node, fn: () => T): T => {
+    setActiveNodeAsSub(nodeAsSub);
+    try {
+      return fn();
+    } finally {
+      resetActiveNodeAsSub();
+    }
+  }
+
+  const startTracking = (nodeAsSub: Node): void => {
+    setActiveNodeAsSub(nodeAsSub);
+
+    const flags = nodeAsSub.flags;
+    flags.unsetPending().unsetDirty().setTracking();
+  }
+  const endTracking = (nodeAsSub: Node): void => {
+    const flags = nodeAsSub.flags;
+    if (flags.hasTrackingReusing() === true) {
+      const firstRedundantDepLink = nodeAsSub?.tailDepLink?.nextDepLink;
+      if (firstRedundantDepLink !== undefined) {
+        let toRemove: Link | undefined = firstRedundantDepLink;
+        while (toRemove !== undefined) {
+          const nextToRemove: Link | undefined = toRemove.nextDepLink;
+          unlink(toRemove);
+          toRemove = nextToRemove;
+        }
+      }
+    }
+    flags.unsetTrackingReusing().unsetTracking();
+
+    resetActiveNodeAsSub();
+  }
+  const withTracking = <T>(node: Node, fn: () => T): T => {
+    startTracking(node);
+    try {
+      return fn();
+    } finally {
+      endTracking(node);
+    }
+  }
+  /**
+   * 依赖收集的目标是：在完成一次依赖收集之后，对于所有在依赖收集执行过程中被访问过的节点（上游节点），
+   * 都与进行依赖收集的节点（下游节点）建立且仅建立一个连接。
+   */
+  const linkNodeOptimizedForTracking = (dep: Node, sub: Node): void => {
+    let existingDepLinkToCompare: Link | undefined;
+
+    const subFlags = sub.flags;
+    if (subFlags.hasTracking() === true && subFlags.hasTrackingReusing() === false) {
+      subFlags.setTrackingReusing();
+      sub.tailDepLink = sub.headDepLink;
+      existingDepLinkToCompare = sub.tailDepLink
+    } else {
+      existingDepLinkToCompare = sub.tailDepLink?.nextDepLink;
+    }
+
+    /**
+     * 检查是否可以复用现存连接。
+     */
+    if (existingDepLinkToCompare !== undefined && existingDepLinkToCompare.dep === dep) {
+      return;
+    }
+
+    linkNode(dep, sub);
+  }
+  const track = (node: Node): void => {
+    const activeNodeAsSub = getActiveNodeAsSub();
+    if (activeNodeAsSub !== undefined) {
+      linkNodeOptimizedForTracking(node, activeNodeAsSub);
+    }
+  }
+
+  const shallowPropagate = (node: Node): void => {
+    // 从头到尾遍历目标节点下游连接链中的所有下游节点，更新其标记。
+
+    let currentSubLink: Link | undefined = node.headSubLink;
+    while (currentSubLink !== undefined) {
+      const sub = currentSubLink.sub;
+      const flags = sub.flags;
+      let isChangeToDirty = false;
+
+      if (flags.hasPending() === true && flags.hasDirty() === false) {
+        // 如果包含 Pending 标记，且不包含 Dirty 标记，为其添加 Dirty 标记，移除 Pending 标记
+        flags.setDirty().unsetPending();
+        isChangeToDirty = true;
+      } else {
+        // 如果是其它情况，则处理下一个连接
+        currentSubLink = currentSubLink.nextSubLink;
+        continue;
+      }
+
+      if (isChangeToDirty === true) {
+        // 如果检查过程中被标记为 Dirty，则酌情触发 notify 回调
+        const shouldNotify = flags.hasWatching() === true && flags.hasTracking() === false;
+        if (shouldNotify === true) {
+          notify(sub);
+        }
+      }
+
+      // 当前连接处理完成，处理下一个连接
+      currentSubLink = currentSubLink.nextSubLink;
+    }
+  }
+
+  interface InternalStack<T> {
+    value: T;
+    prev: InternalStack<T> | undefined;
+  }
+
+  const deeeeepPropagate = (node: Node): void => {
+    let currentSubLink = node.headSubLink;
+    let nextSubLink = currentSubLink?.nextSubLink;
+    let unhandledSubLinkStack: InternalStack<Link | undefined> | undefined = undefined;
+
+    while (currentSubLink !== undefined) {
+      const sub = currentSubLink.sub;
+
+      let flags = sub.flags;
+      let shouldNotify = flags.hasWatching();
+      let shouldDownward = flags.hasMutable();
+
+      if (flags.hasTracking() === false && flags.hasDirty() === false && flags.hasPending() === false) {
+        /**
+         * 进入此分支的 flags：
+         *  1. 不包含 Tracking 标记。
+         *  2. 不包含 Dirty 标记或 Pending 标记。
+         *
+         * 说明：上游节点的变更首次传递到该节点。
+         *
+         * 此时，添加 Pending 标记，根据其它标记决定是否需要 Notify，根据其它标记决定是否需要 Downward。
+         */
+        flags.setPending();
+        // shouldNotify = shouldNotify;
+        // shouldDownward = shouldDownward;
+      } else if (flags.hasTracking() === false) {
+        /**
+         * 进入此分支的 flags：
+         *  1. 不包含 Tracking 标记。
+         *  2. 包含 Dirty 标记或 Pending 标记。
+         *
+         * 说明：上游节点的变更已经传递到该节点。
+         *
+         * 此时，什么都不做，不需要修改标记，不需要 Notify，不需要 Downward。
+         */
+        // flags = flags;
+        shouldNotify = false;
+        shouldDownward = false;
+      } else if (flags.hasDirty() === false && flags.hasPending() === false) {
+        /**
+         * 进入此分支的 flags：
+         *  1. 包含 Tracking 标记。
+         *  2. 不包含 Dirty 标记或 Pending 标记。
+         *
+         * 说明：上游节点的变更首次传递到该节点，且该节点正在进行依赖收集。
+         *
+         * 此时，添加 Pending 标记，不需要 Notify，根据其它标记决定是否需要 Downward。
+         */
+        flags.setPending();
+        shouldNotify = false;
+        // shouldDownward = shouldDownward;
+      } else {
+        /**
+         * 进入此分支的 flags：
+         *  1. 包含 Tracking 标记。
+         *  2. 包含 Dirty 标记或 Pending 标记。
+         *
+         * 说明：上游节点的变更已经传递到该节点，且该节点正在进行依赖收集。
+         *
+         * 此时，不需要修改标记，不需要 Notify，不需要 Downward。
+         */
+        // flags = flags;
+        shouldNotify = false;
+        shouldDownward = false;
+      }
+
+      if (shouldNotify === true) {
+        notify(sub);
+      }
+
+      if (shouldDownward === true) {
+        const headSubLinkOfSub = sub.headSubLink;
+        if (headSubLinkOfSub !== undefined) {
+          currentSubLink = headSubLinkOfSub;
+          const nextSubLinkOfSub = headSubLinkOfSub.nextSubLink;
+          if (nextSubLinkOfSub !== undefined) {
+            unhandledSubLinkStack = { value: nextSubLink, prev: unhandledSubLinkStack };
+            nextSubLink = nextSubLinkOfSub;
+          }
+          continue;
+        }
+      }
+
+      currentSubLink = nextSubLink
+      if (currentSubLink !== undefined) {
+        nextSubLink = currentSubLink.nextSubLink;
+        continue;
+      }
+
+      if (unhandledSubLinkStack !== undefined) {
+        currentSubLink = unhandledSubLinkStack.value;
+        unhandledSubLinkStack = unhandledSubLinkStack.prev;
+        if (currentSubLink !== undefined) {
+          nextSubLink = currentSubLink.nextSubLink;
+        }
+      }
+    }
+  }
+
+  const resolvePending = (node: Node): void => {
+    let currentDepLink = node.headDepLink;
+    let unhandledDepLinkStack: InternalStack<Link> | undefined = undefined;
+
+    while (currentDepLink !== undefined) {
+      const currentSub: Node = currentDepLink.sub;
+      const currentDep: Node = currentDepLink.dep;
+      const subFlags = currentSub.flags;
+      const depFlags = currentDep.flags;
+
+      if (depFlags.hasMutable() === true && depFlags.hasDirty() === true) {
+        /**
+         * 当前下游节点不包含 Dirty 标记，当前上游节点包含 Dirty 标记。
+         *
+         * 更新当前上游节点，若值有变化，则将状态向直接下游节点传播。
+         */
+        const valueChanged = update(currentDep);
+        if (valueChanged === true) {
+          shallowPropagate(currentDep);
+        }
+      } else if (depFlags.hasMutable() === true && depFlags.hasPending() === true) {
+        /**
+         * 当前下游节点不包含 Dirty 标记，当前上游节点包含 Pending 标记。
+         *
+         * 继续检查当前上游节点的上游节点。
+         */
+        unhandledDepLinkStack = { value: currentDepLink, prev: unhandledDepLinkStack };
+        currentDepLink = currentDep.headDepLink;
+        continue;
+      }
+
+      if (subFlags.hasPending() === true) {
+        const nextDepLink = currentDepLink.nextDepLink;
+        if (nextDepLink !== undefined) {
+          currentDepLink = nextDepLink;
+          continue;
+        }
+      }
+
+      if (unhandledDepLinkStack !== undefined) {
+        currentDepLink = unhandledDepLinkStack.value;
+        unhandledDepLinkStack = unhandledDepLinkStack.prev;
+
+        /**
+         * 当一个连接先被存起来，后续又被取出来处理时，说明其所有上游节点都已经处理完成，
+         * 因此可以将其 Pending 标记移除。
+         */
+        currentDepLink.dep.flags.unsetPending();
+      } else {
+        /**
+         * 所有连接都处理完成，可以安全移除当前连接的下游节点的 Pending 标记。
+         */
+        currentDepLink.sub.flags.unsetPending();
+        break;
+      }
+    }
+  }
+
+  return {
+    isDepLinkOfNode,
+    isSubLinkOfNode,
+    getLinkOfNodes,
+    isLinked,
+    linkNode,
+    unlinkNode,
+    unlink,
+    unlinkAllDepLinksOfNode,
+    unlinkAllSubLinksOfNode,
+
+    getActiveNodeAsSub,
+    setActiveNodeAsSub,
+    resetActiveNodeAsSub,
+    withActiveNodeAsSub,
+    startTracking,
+    endTracking,
+    withTracking,
+    linkNodeOptimizedForTracking,
+    track,
+
+    shallowPropagate,
+    deeeeepPropagate,
+    resolvePending,
+  };
+}

package/src/signal-operators/index.ts

@@ -0,0 +1,19 @@
+import type { Signal } from "Source/index"
+import { effect, signal } from "Source/index"
+
+export const withHistory = <T>(orginal: Signal<T>): Signal<T[]> => {
+  const history: T[] = []
+  effect(() => {
+    history.push(orginal.get())
+  })
+  const result = signal<T[]>(history)
+  return result
+}
+
+export const zip = <T, U>(signal1: Signal<T>, signal2: Signal<U>): Signal<[T, U]> => {
+  const result = signal<[T, U]>([signal1.get(), signal2.get()])
+  effect(() => {
+    result.set([signal1.get(), signal2.get()])
+  })
+  return result
+}