@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/route/README.md

@@ -0,0 +1,105 @@
+# Route
+
+## Description
+
+Route 模块提供围绕命中入口表达、地址片段归一化、路由历史推进以及宿主桥接的基础建模能力。
+
+它关注的不是某个框架路由器的页面约定，也不是对浏览器 `location`、`history` 或某个导航 API 的临时封装，而是“一个系统中的当前位置或目标入口，如何被表达为稳定、可比较、可派生、可推进的公共语义”这一更一般的问题。浏览器 URL 是 route 的典型形态，但不是唯一形态。只要某个系统里存在“某个输入命中某个稳定入口，并伴随一组可解释片段或参数”的过程，就存在 route 语义。因此，这个模块更适合被理解为路由领域的基础模型集合，而不是浏览器导航工具箱、前端框架路由方案或零散的 URL 处理函数集合。
+
+## For Understanding
+
+理解 Route 模块时，应优先把它看作“当前命中入口及其变化过程”的建模层，而不是把它缩窄成页面跳转工具。这个模块当前表达的核心问题有三层：一是地址片段如何被归一化为稳定表示；二是当前路由如何作为一个可读取、可比较、可派生的对象存在；三是路由历史如何被推进、替换、漫游、回退，并以清楚语义向上层暴露。
+
+这里的 route 不必被限制在浏览器页面地址中。更一般地说，只要某个系统存在“命中入口”的过程，就可以出现 route 语义。例如浏览器应用中的页面或视图入口、服务端系统中的路径分发入口、CLI 中的命令入口，以及任务系统中的某个目标节点入口，本质上都在回答“输入如何命中某个稳定目标，以及这个目标如何和片段、参数、历史一起被组织起来”这一问题。Route 模块关心的是这个抽象层，而不是某一种宿主上的具体表现。
+
+从当前目录结构看，这个模块由三个子边界构成：
+
+- `uri`：负责 `pathname`、`search`、`hash` 等片段的归一化、转换与比较语义。
+- `router`：负责 `Route`、`Router`、历史记录以及各类导航动作的模型化表达。
+- `adapter`：负责把 Route 模型接到具体宿主上，例如浏览器环境或响应式消费面。
+
+理解这个模块时，还应守住几条边界：
+
+- Route 模块表达的是“入口及其历史”的基础模型，不负责替代页面渲染系统、框架路由约定、服务端业务编排、CLI 参数解析器或权限体系。
+- 它可以和浏览器、服务端、CLI 或响应式系统对接，但不应让某个宿主的临时 API 细节反过来定义模块公共语义。
+- 它适合承载入口片段、标准化路由记录、历史动作以及宿主同步边界，但不应直接承担组件装载、数据预取、业务参数解释、命令执行副作用或框架专属生命周期。
+- `adapter` 更适合作为桥接层理解。它的职责是把既有 Route 模型接入宿主，而不是把宿主细节直接提升为父模块语义。
+
+## For Using
+
+当你希望在应用或库中复用一套不依赖具体页面结构、能够稳定表达“当前命中入口”和“入口历史”的基础能力时，可以使用 Route 模块。
+
+从使用角度看，这个模块大致可以分为三类能力：
+
+- 地址片段能力：把 `pathname`、`search`、`hash` 等结构收束成稳定表示，并支持统一的转换、包含与比较语义。
+- 路由模型能力：把当前地址、标准化记录、历史链路以及导航动作组织为一套清楚的对象模型。
+- 宿主桥接能力：把内部 Router 与浏览器历史或响应式消费面连接起来，使上层系统能够围绕统一的 Route 语义工作。
+
+更合适的接入方式，通常是先判断你的问题是否真的属于 route 边界。如果你需要的是：
+
+- 让地址片段形成稳定且可比较的统一表示；
+- 把当前地址收束到一个可复用的路由对象和标准化记录中；
+- 明确区分 navigate、redirect、replace、go、roaming 等历史动作的语义；
+- 将内部 Router 同浏览器历史或响应式消费面连接起来；
+
+那么这个模块就是合适的边界。
+
+相反，如果你的需求主要是页面组件树装载、业务参数校验、访问权限决策、SEO 约定、框架页面生命周期、命令执行副作用或服务端领域逻辑分派，那么这些通常不应直接成为 Route 模块本身的职责，而应放在更外层系统或具体框架集成层中。
+
+## For Contributing
+
+为 Route 模块贡献内容时，优先判断新增能力是否真的在澄清“入口如何表达、如何标准化、如何形成历史、如何与宿主同步”这一稳定问题域，而不是只是在给某个当前宿主补一层便捷封装。这个模块应长期服务于入口片段、路由对象、历史语义与桥接边界这几个方向，而不是退化成浏览器导航工具目录或某个框架的外围辅助层。
+
+扩展时应特别警惕两类偏差。一类是把 `uri` 层做成只对某组业务参数、某条服务路径或某套 CLI 选项成立的临时工具，导致公共语义不稳定；另一类是让 `adapter` 下沉过多桥接之外的职责，例如页面装载、业务状态解释、命令执行、副作用编排或框架专属生命周期。更稳妥的做法，是先确认新增能力究竟属于片段语义、路由历史语义，还是宿主桥接语义，再把它放到对应子边界中。
+
+当前 `adapter` 下的能力更适合被理解为桥接层，因此不要求为其编写单元测试。这并不是说这些代码永远不可测试，而是因为它们主要依赖浏览器事件或响应式系统等宿主前提；在当前模块边界下，优先保证 `uri` 与 `router` 这些环境中立、语义稳定的核心部分被充分测试，通常比为桥接细节重复编写单元测试更有价值。如果未来某个适配器逐渐沉淀出脱离宿主也成立的稳定公共语义，再考虑为其引入单元测试。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/route/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 route 相关的实现应优先围绕入口片段语义、路由对象、历史推进动作和宿主桥接边界组织，避免把页面装载、服务端业务处理、CLI 命令执行、业务专属参数解释或框架专属生命周期直接提升为 Route 的长期公共语义。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的路由语义，而不是某段浏览器实现细节、宿主桥接细节或业务约定的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/route`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/route/<sub-module-name>`。
+- `adapter` 目录当前无需编写单元测试，并应在模块文档中明确说明这是因为它主要承担宿主桥接职责，核心语义应优先由 `uri` 与 `router` 层测试覆盖。
+- 对这个模块来说，测试应优先覆盖入口片段归一化、Route 标准化记录、Router 的历史推进与替换语义、回退与漫游边界，以及关键动作产生的历史记录与事件行为。

package/src/route/adapter/browser.ts

@@ -0,0 +1,122 @@
+import { createRoute } from "../router/index.ts"
+import type { Route, Router } from "../router/index.ts"
+
+/**
+ * 创建浏览器路由适配器时需要的输入项。
+ */
+export interface CreateBrowserRouterOptions {
+  router: Router
+}
+
+/**
+ * 浏览器路由适配器返回的结果。
+ *
+ * `dispose` 用于释放当前适配器注册的订阅和浏览器事件监听器。
+ */
+export interface CreateBrowserRouterResult {
+  router: Router
+  dispose: () => void
+}
+
+/**
+ * 将 Router 和浏览器路由对接在一起，将 Router 作为唯一信源。
+ *
+ * 该适配器负责把 Router 产生的历史记录同步到浏览器 `history`，并在浏览器
+ * `popstate` 或 `hashchange` 发生时，把新的地址变化回灌到 Router。
+ *
+ * Tips:
+ *  - 浏览器 F5 刷新之后 `history.state` 不会丢失。
+ */
+export const createBrowserRouter = (options: CreateBrowserRouterOptions): CreateBrowserRouterResult => {
+  const { router } = options
+
+  interface State {
+    routeHistoryEntryId: string
+  }
+  const isState = (target: unknown): target is State => {
+    if (typeof target !== "object" || target === null) {
+      return false
+    }
+    if (("routeHistoryEntryId" in target) === false) {
+      return false
+    }
+    if (typeof target["routeHistoryEntryId"] !== "string") {
+      return false
+    }
+    return true
+  }
+  const insertState = (route: Route, state: State): void => {
+    const url = location.origin + route.getRecord().partialUrl
+    window.history.pushState(state, "", url)
+  }
+  const updateState = (route: Route, state: State): void => {
+    const url = location.origin + route.getRecord().partialUrl
+    window.history.replaceState(state, "", url)
+  }
+  const upsertState = (route: Route, state: State): void => {
+    const oldUrl = location.origin + createRoute(location.href).getRecord().partialUrl
+    const newUrl = location.origin + route.getRecord().partialUrl
+    if (oldUrl === newUrl) {
+      updateState(route, state)
+    } else {
+      insertState(route, state)
+    }
+  }
+
+  const subscriberEntry = router.eventManager.subscribe("history", (routeHistoryEntry) => {
+    upsertState(routeHistoryEntry.to.route, { routeHistoryEntryId: routeHistoryEntry.id })
+  })
+  const disposeRouterSubscriber = (): void => {
+    subscriberEntry.unsubscribe()
+  }
+
+  const popstateEventListener = (event: PopStateEvent): void => {
+    // 此事件触发的结果有两种：
+    // 1. 来到 Router 设置的路由，此时 state 可识别。
+    // 2. 来到非 Router 设置的路由，此时 state 不可识别。
+    //
+    // 对于 1，判断 state 中的 routeHistoryEntryId 是否与 router 的
+    // 最新的 routeHistoryEntry 的 id 相同，若相同，则说明此事件由 router
+    // 触发，不需要再次操作（否则会导致循环触发），若不同，则作为新路由同步至
+    // router。
+    // 对于 2，始终作为新路由同步至 router。
+
+    if (isState(event.state)) {
+      const currentRouteHistoryEntryId = router.getCurrentRouteHistoryEntryId()
+      if (event.state.routeHistoryEntryId === currentRouteHistoryEntryId) {
+        return
+      }
+    }
+
+    router.navigateTo({ url: location.href })
+  }
+  window.addEventListener("popstate", popstateEventListener)
+  const disposePopstateEventListener = (): void => {
+    window.removeEventListener("popstate", popstateEventListener)
+  }
+
+  const hashchangeEventListener = (event: HashChangeEvent): void => {
+    if (isState(history.state)) {
+      const currentRouteHistoryEntryId = router.getCurrentRouteHistoryEntryId()
+      if (history.state.routeHistoryEntryId === currentRouteHistoryEntryId) {
+        return
+      }
+    }
+    router.navigateTo({ url: event.newURL })
+  }
+  window.addEventListener("hashchange", hashchangeEventListener)
+  const disposeHashchangeEventListener = (): void => {
+    window.removeEventListener("hashchange", hashchangeEventListener)
+  }
+
+  const dispose = (): void => {
+    disposeRouterSubscriber()
+    disposePopstateEventListener()
+    disposeHashchangeEventListener()
+  }
+
+  return {
+    router,
+    dispose
+  }
+}

package/src/route/adapter/driver.ts

@@ -0,0 +1,56 @@
+import type { Computed } from "#Source/reactor/index.ts"
+import { computed, signal } from "#Source/reactor/index.ts"
+import type { Route, RouteHistoryEntry, Router, RouteRecord } from "../router/index.ts"
+
+/**
+ * 创建路由驱动器时需要的输入项。
+ */
+export interface CreateRouteDriverOptions {
+  router: Router
+}
+
+/**
+ * 将 Router 暴露为响应式只读视图的驱动器。
+ *
+ * 该接口把当前历史记录、当前 Route 以及当前 RouteRecord 暴露为可追踪的计算值，
+ * 方便响应式系统消费。
+ */
+export interface RouteDriver {
+  router: Router
+  routeHistoryEntry: Computed<RouteHistoryEntry>
+  route: Computed<Route>
+  routeRecord: Computed<RouteRecord>
+}
+
+/**
+ * 基于 Router 创建一组可响应追踪的当前路由派生值。
+ *
+ * 返回结果中的计算值会随着 Router 的 `history` 事件自动更新。
+ */
+export const createRouteDriver = (options: CreateRouteDriverOptions): RouteDriver => {
+  const { router } = options
+
+  const internalCurrentRouteHistoryEntry = signal(() => {
+    return router.getCurrentRouteHistoryEntry()
+  })
+  router.eventManager.subscribe("history", (routeHistoryEntry) => {
+    internalCurrentRouteHistoryEntry.set(routeHistoryEntry)
+  })
+
+  const currentRouteHistoryEntry = computed(() => {
+    return internalCurrentRouteHistoryEntry.get()
+  })
+  const currentRoute = computed(() => {
+    return currentRouteHistoryEntry.get().to.route
+  })
+  const currentRouteRecord = computed(() => {
+    return currentRoute.get().getRecord()
+  })
+
+  return {
+    router,
+    routeHistoryEntry: currentRouteHistoryEntry,
+    route: currentRoute,
+    routeRecord: currentRouteRecord
+  }
+}

package/src/route/adapter/index.ts

@@ -0,0 +1,2 @@
+export * from "./driver.ts"
+export * from "./browser.ts"

package/src/route/index.ts

@@ -0,0 +1,3 @@
+export * from "./uri/index.ts"
+export * from "./router/index.ts"
+export * from "./adapter/index.ts"

package/src/route/router/index.ts

@@ -0,0 +1,2 @@
+export * from "./route.ts"
+export * from "./router.ts"