@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/timer/expiration/min-heap.ts

@@ -0,0 +1,208 @@
+/**
+ * 表示最小堆中的一个节点。
+ *
+ * `name` 用于在 `indexMap` 中快速定位节点，
+ * `endAt` 用作最小堆的排序键，值越小表示越早到期，优先级越高。
+ */
+interface HeapNode<Name extends string> {
+  name: Name
+  endAt: number
+}
+
+/**
+ * 提供一个按 `endAt` 升序排列的最小堆。
+ *
+ * 该实现同时维护：
+ * 1. `heap`：保存二叉堆结构本身，用于快速获取最小值。
+ * 2. `indexMap`：记录名称到数组索引的映射，用于按名称 $O(1)$ 定位节点，
+ *    从而支持高效的更新和删除。
+ *
+ * 这个堆特别适合“按时间先后触发”的场景，例如过期调度器。
+ */
+export class MinHeap<Name extends string> {
+  /**
+   * 使用数组存储完全二叉树结构。
+   * 父子节点关系遵循：
+   * - parent = Math.floor((index - 1) / 2)
+   * - left = index * 2 + 1
+   * - right = index * 2 + 2
+   */
+  private heap: Array<HeapNode<Name>> = []
+
+  /**
+   * 记录节点名称在 `heap` 数组中的当前位置。
+   *
+   * 这样删除指定名称的节点时，不需要线性扫描整个堆。
+   */
+  private indexMap = new Map<Name, number>()
+
+  /**
+   * 返回当前堆中的节点数量。
+   */
+  size(): number {
+    return this.heap.length
+  }
+
+  /**
+   * 查看堆顶节点但不移除。
+   *
+   * 堆顶始终是当前 `endAt` 最小的节点，也就是最早应被处理的节点。
+   */
+  peek(): HeapNode<Name> | undefined {
+    return this.heap[0]
+  }
+
+  /**
+   * 向堆中插入一个新节点。
+   *
+   * 新节点会先追加到数组末尾，再通过上浮恢复最小堆性质。
+   */
+  push(node: HeapNode<Name>): void {
+    const index = this.heap.length
+    this.heap.push(node)
+    this.indexMap.set(node.name, index)
+    this.bubbleUp(index)
+  }
+
+  /**
+   * 按名称移除一个节点。
+   *
+   * 过程如下：
+   * 1. 借助 `indexMap` 找到目标节点位置。
+   * 2. 用最后一个节点填补被删除的位置。
+   * 3. 根据替换节点与父/子节点的大小关系，分别尝试下沉和上浮，恢复堆结构。
+   */
+  remove(name: Name): void {
+    const index = this.indexMap.get(name)
+    if (index === undefined) {
+      return
+    }
+
+    const last = this.heap.pop()!
+    this.indexMap.delete(name)
+
+    // 被删除节点本来就在数组末尾时，弹出后无需再做任何调整。
+    if (index === this.heap.length) {
+      return
+    }
+
+    this.heap[index] = last
+    this.indexMap.set(last.name, index)
+
+    // 替换进来的节点可能比子节点大，也可能比父节点小，
+    // 因此两个方向都尝试一次，以覆盖所有位置变化情况。
+    this.bubbleDown(index)
+    this.bubbleUp(index)
+  }
+
+  /**
+   * 移除并返回堆顶节点。
+   *
+   * 当堆为空时返回 `undefined`。
+   */
+  pop(): HeapNode<Name> | undefined {
+    if (this.heap.length === 0) {
+      return undefined
+    }
+
+    const top = this.heap[0]
+    if (top === undefined) {
+      return undefined
+    }
+
+    this.remove(top.name)
+    return top
+  }
+
+  /**
+   * 交换两个索引位置上的节点，并同步更新它们在 `indexMap` 中的记录。
+   */
+  private swap(i: number, j: number): void {
+    const a = this.heap[i]
+    const b = this.heap[j]
+
+    if (a === undefined || b === undefined) {
+      return
+    }
+
+    this.heap[i] = b
+    this.heap[j] = a
+
+    this.indexMap.set(a.name, j)
+    this.indexMap.set(b.name, i)
+  }
+
+  /**
+   * 让指定索引处的节点持续向上移动，直到满足最小堆性质。
+   *
+   * 适用于插入新节点，或某个节点的排序键变小之后的重排。
+   */
+  private bubbleUp(index: number): void {
+    let currentIndex = index
+
+    while (currentIndex > 0) {
+      const parent = Math.floor((currentIndex - 1) / 2)
+      const parentNode = this.heap[parent]
+      const currentNode = this.heap[currentIndex]
+
+      if (parentNode === undefined || currentNode === undefined) {
+        break
+      }
+
+      if (parentNode.endAt <= currentNode.endAt) {
+        break
+      }
+
+      this.swap(parent, currentIndex)
+      currentIndex = parent
+    }
+  }
+
+  /**
+   * 让指定索引处的节点持续向下移动，直到满足最小堆性质。
+   *
+   * 每次从当前节点与左右子节点中选出 `endAt` 最小者，
+   * 若最小者不是当前节点，则交换并继续向下检查。
+   */
+  private bubbleDown(index: number): void {
+    const length = this.heap.length
+    let currentIndex = index
+
+    while (true) {
+      let smallest = currentIndex
+      const left = currentIndex * 2 + 1
+      const right = currentIndex * 2 + 2
+      const smallestNode = this.heap[smallest]
+      const leftNode = this.heap[left]
+      const rightNode = this.heap[right]
+
+      if (smallestNode === undefined) {
+        break
+      }
+
+      // 先用左子节点与当前最小值比较。
+      if (left < length && leftNode !== undefined && leftNode.endAt < smallestNode.endAt) {
+        smallest = left
+      }
+
+      const nextSmallestNode = this.heap[smallest]
+
+      // 再基于最新的最小候选与右子节点比较。
+      if (
+        right < length &&
+        rightNode !== undefined &&
+        nextSmallestNode !== undefined &&
+        rightNode.endAt < nextSmallestNode.endAt
+      ) {
+        smallest = right
+      }
+
+      if (smallest === currentIndex) {
+        break
+      }
+
+      this.swap(currentIndex, smallest)
+      currentIndex = smallest
+    }
+  }
+}

package/src/timer/expiration/remaining-manager.ts

@@ -0,0 +1,241 @@
+import { EventManager } from "#Source/event/index.ts"
+
+import type { BuildEvents, SubscriberEntry } from "#Source/event/index.ts"
+import type { ExpirationManager, ExpirationManagerEvents } from "./expiration-manager.ts"
+
+/**
+ * 表示一个以秒为单位的剩余时长。
+ */
+export type RemainingTime = number
+
+/**
+ * 描述一组按名称索引的派生剩余时长字典。
+ */
+export type RemainingDict<ExpirationName extends string> = {
+  [K in ExpirationName]?: RemainingTime | undefined
+}
+
+/**
+ * 描述 `RemainingManager` 对外发出的事件表。
+ */
+export type RemainingManagerEvents<ExpirationName extends string> = BuildEvents<{
+  /**
+   * 在剩余时间快照发生变化时发出最新结果。
+   */
+  remaining: (remaining: RemainingDict<ExpirationName>) => void
+}>
+
+/**
+ * 描述创建 `RemainingManager` 时可用的配置项。
+ */
+export interface RemainingManagerOptions<ExpirationName extends string> {
+  /**
+   * 提供过期状态真相来源的过期管理器。
+   */
+  expirationManager: ExpirationManager<ExpirationName>
+
+  /**
+   * 控制是否在创建后立即启用周期性剩余时间检查。
+   */
+  enabled?: boolean | undefined
+}
+
+const isRemainingDictEqual = <ExpirationName extends string>(
+  left: RemainingDict<ExpirationName>,
+  right: RemainingDict<ExpirationName>,
+): boolean => {
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+
+  if (leftKeys.length !== rightKeys.length) {
+    return false
+  }
+
+  for (const key of leftKeys) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    const expirationName = key as ExpirationName
+
+    if (left[expirationName] !== right[expirationName]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * 管理基于 `ExpirationManager` 状态派生出的剩余时间查询与周期性通知。
+ *
+ * `RemainingManager` 不拥有独立的过期真相来源，而是始终从 `ExpirationManager`
+ * 读取当前过期状态，并在需要时把这些状态换算为以秒为单位的剩余值。
+ *
+ * 这里的 `enabled` 只影响内部的周期性检查是否运行，不影响过期状态变化时
+ * 立即触发的派生结果更新。
+ */
+export class RemainingManager<ExpirationName extends string = string> {
+  readonly expirationManager: ExpirationManager<ExpirationName>
+  readonly event: EventManager<RemainingManagerEvents<ExpirationName>>
+
+  private enabled: boolean
+  private lastEmittedRemainingSnapshot: RemainingDict<ExpirationName>
+  private timer: ReturnType<typeof setInterval> | null
+  private terminated: boolean
+  private readonly expirationStateSubscriberEntry: SubscriberEntry<
+    ExpirationManagerEvents<ExpirationName>,
+    "expirationState"
+  >
+
+  constructor(options: RemainingManagerOptions<ExpirationName>) {
+    const { expirationManager, enabled } = options
+
+    this.expirationManager = expirationManager
+    this.event = new EventManager()
+
+    this.enabled = enabled === true
+    this.lastEmittedRemainingSnapshot = {}
+    this.timer = null
+    this.terminated = false
+    this.expirationStateSubscriberEntry = this.expirationManager.event.subscribe(
+      "expirationState",
+      (): void => {
+        this.emit()
+      },
+    )
+
+    if (this.enabled === true) {
+      this.resume()
+    }
+  }
+
+  /**
+   * 返回某个具名过期项当前的秒级剩余时长。
+   *
+   * 当目标不存在，或其状态不是 `active` 时，返回 `undefined`。
+   */
+  getRemaining(name: ExpirationName): number | undefined {
+    const expirationState = this.expirationManager.getExpirationState(name)
+    if (expirationState === undefined) {
+      return undefined
+    }
+    if (expirationState.state !== "active") {
+      return undefined
+    }
+
+    return Math.max(0, Math.ceil((expirationState.endAt - this.expirationManager.getNow()) / 1_000))
+  }
+
+  /**
+   * 返回当前所有活跃过期项的秒级剩余时长快照。
+   */
+  getRemainingSnapshot(): RemainingDict<ExpirationName> {
+    const expirationDict = this.expirationManager.getExpirationSnapshot()
+    const result: RemainingDict<ExpirationName> = {}
+
+    for (const name in expirationDict) {
+      if (Object.hasOwn(expirationDict, name) === false) {
+        continue
+      }
+
+      const expirationName = name as ExpirationName
+      const remaining = this.getRemaining(expirationName)
+
+      if (remaining === undefined) {
+        continue
+      }
+
+      result[expirationName] = remaining
+    }
+
+    return result
+  }
+
+  /**
+   * 在剩余时间快照发生变化时发出一次 `remaining` 事件。
+   *
+   * 若当前实例已经终止，或新旧快照完全一致，则不会重复发出事件。
+   */
+  emit(): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    const remainingSnapshot = this.getRemainingSnapshot()
+    if (isRemainingDictEqual(this.lastEmittedRemainingSnapshot, remainingSnapshot) === true) {
+      return
+    }
+
+    this.lastEmittedRemainingSnapshot = remainingSnapshot
+    this.event.emit("remaining", remainingSnapshot)
+  }
+
+  /**
+   * 启用周期性剩余时间检查。
+   *
+   * 这不会跳过过期状态变更时本来就会触发的即时派生通知。
+   */
+  start(): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    this.enabled = true
+    this.resume()
+  }
+
+  /**
+   * 停止周期性剩余时间检查，并将启用标记设为关闭。
+   */
+  stop(): void {
+    this.enabled = false
+
+    if (this.timer === null) {
+      return
+    }
+
+    clearInterval(this.timer)
+    this.timer = null
+  }
+
+  /**
+   * 暂停当前周期性定时器，但保留启用标记。
+   *
+   * 这通常用于由外层过期管理器在暂停期间临时停止派生检查，
+   * 以便之后通过 `resume()` 继续运行。
+   */
+  pause(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+  }
+
+  /**
+   * 在实例已启用且尚未终止时恢复周期性剩余时间检查。
+   */
+  resume(): void {
+    if (this.terminated === true || this.enabled !== true || this.timer !== null) {
+      return
+    }
+
+    this.timer = setInterval(() => {
+      if (Object.keys(this.expirationManager.getExpirationSnapshot()).length === 0) {
+        return
+      }
+
+      this.emit()
+    }, 1_000)
+  }
+
+  /**
+   * 终止实例并释放订阅与定时器资源。
+   */
+  terminate(): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    this.terminated = true
+    this.expirationStateSubscriberEntry.unsubscribe()
+    this.stop()
+  }
+}

package/src/timer/index.ts

@@ -0,0 +1 @@
+export * from "./expiration/index.ts"

package/src/tube/README.md

@@ -0,0 +1,99 @@
+# Tube
+
+## Description
+
+Tube 模块提供围绕运行时数据通道（runtime data conduit）的通用建模能力，用于把一段会经历开启、启动、接收数据、出现错误、结束与关闭等生命周期的数据传递过程，组织为可观察、可组合且可选择重放历史记录的稳定公共语义。
+
+它关注的不是某个具体传输协议、宿主流实现或消息中间件接口本身，而是“当一段数据传递过程需要在运行时被明确建模为一个有生命周期、有事件面、可回放最近数据、并可与其它边界协作的通道对象时，应暴露什么样的长期语义”这一类更一般的问题。因此，这个模块更适合被理解为一组数据通道模型，而不是事件总线工具箱、Node.js Stream 包装层，或为了临时转发数据而拼接出来的便捷函数集合。
+
+## For Understanding
+
+理解 Tube 模块时，应先把它看作“有生命周期的数据通道”建模层，而不是把任何会发出事件或传递值的对象都简单归并到这里。它真正要表达的，不只是“某个值能不能被推送出去”，还包括一段通道是否已经打开、是否已经开始接收数据、是否已经变为非空、是否已经发生错误、是否已经结束，以及这些状态变化如何以清楚的事件面暴露给外部。
+
+Tube 的核心价值，在于把一段原本容易散落在回调、标志位和局部变量里的通道过程，收束为一份稳定模型。这样做的重点不是单纯提供一个 `pushData` 方法，而是让“生命周期顺序”“数据到达语义”“错误传播语义”“历史回放语义”“与其它通道或宿主流互转的边界”都可以被统一理解和长期维护。
+
+理解这个模块时，特别要守住几条边界：
+
+- Tube 模块表达的是运行时数据通道及其生命周期，而不是传输协议、Socket 连接、HTTP 请求、文件读取或浏览器流 API 本身。
+- 它适合描述通道何时开始可接收数据、何时真正进入流动状态、何时首次变为非空、何时结束以及如何对这些变化做出订阅。
+- 它可以与 `ReadableStream` 等宿主流结构互相转换，也可以连接上下游通道，但这些都应被理解为围绕通道模型发生的集成接点，而不是让宿主 API 细节反过来定义 Tube 的公共语义。
+- 它不应直接承担背压（backpressure）协商、传输重试、协议握手、序列化格式、连接保活、分布式消息确认或业务专属路由规则等职责。
+- 数据历史回放的价值，在于帮助新订阅者接入一个已经运行中的通道，而不是把 Tube 退化成无限责任的缓存容器；因此扩展时应优先围绕“通道中的历史视图”思考，而不是围绕“持久存储”思考。
+
+## For Using
+
+当你希望在应用内部表达一段真正有生命周期的数据传递过程，而不是把数据流转逻辑拆散到多个事件回调、Promise 链或宿主流对象的临时包装里时，可以使用 Tube 模块。
+
+从使用角度看，这个模块大致可以分为三类能力：
+
+- 生命周期控制能力：用于表达通道的打开、启动、结束、关闭以及错误发生后的自动联动行为，适合把一段通道过程收束为稳定状态机。
+- 事件与数据订阅能力：用于观察 `open`、`start`、`wet`、`error`、`end`、`close` 与数据到达本身，并根据需要为新订阅者重放最近的历史数据。
+- 集成辅助能力：用于连接上下游 Tube、把 Tube 收束为 Promise，或与 `ReadableStream` 等宿主流结构互相转换。
+
+更合适的接入方式，通常是先判断你的核心对象是不是“一段需要被长期观察和组合的数据通道过程”。如果你需要的是：
+
+- 某个生产者持续把数据推给多个订阅方，并且这些订阅方还需要感知通道生命周期；
+- 一个已经开始流动的通道要允许新接入者按需看到最近历史，而不是只看到未来数据；
+- 你希望把宿主流结构转换为一份带稳定生命周期语义的对象，再与其它模型协作；
+- 上下游两个处理阶段之间需要一个清楚的数据通道边界，而不是若干零散回调直接耦合；
+
+那么这个模块就是合适的边界。
+
+相反，如果你的需求只是宿主环境里某个具体流 API 的底层控制、传输协议细节、连接状态机、消息编码格式、流量控制或业务专属转发规则，那么这些通常不应直接落在 Tube 模块本身，而应放在对应宿主模块、适配层或更外层系统中。
+
+## For Contributing
+
+为 Tube 模块贡献内容时，优先判断新增能力是否真的在澄清“运行时数据通道如何被建模为稳定生命周期对象”这一问题，而不是只是在补一个临时好用的转发函数或宿主 API 包装。这个模块应长期服务于“通道状态如何表达”“数据与错误如何被送入并传播”“订阅者如何观察生命周期与数据”“历史如何被有边界地回放”“通道如何与其它模型形成集成接点”这几类问题。
+
+扩展这个模块时，应特别警惕以下倾向：把 Tube 退化成普通事件总线；把某个宿主流实现的局部行为直接暴露为公共承诺；把连接、协议、背压、重试、路由或业务缓存逻辑无差别地下沉到 Tube 内部；或者为了当前实现方便而公开内部状态结构。文档应说明哪些通道语义是长期成立的，以及为什么这些语义成立，而不是复述某个版本里恰好采用的局部实现技巧。
+
+当前已经落地的 `Tube` 应被理解为 Tube 模块下的核心通道模型，而 `connectTube`、`tubeToPromise`、`tubeToReadableStream` 与 `readableStreamToTube` 则是围绕这一模型形成的集成辅助函数。后续若增加子模块或更多辅助能力，应优先判断它们是否仍然服务于“清楚、稳定的数据通道语义”，而不是把其它更大的问题域误并到这个模块里。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/tube/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 tube 相关的实现应优先围绕生命周期、数据进入语义、错误传播、历史回放与集成接点组织，避免把协议细节、连接控制或宿主流底层策略直接混入模块公共边界。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的通道语义，而不是某段宿主实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/tube`。
+- 对这个模块来说，测试应优先覆盖生命周期切换、自动联动配置、历史回放、错误传播、订阅与退订行为，以及 Tube 与其它 Tube 或宿主 `ReadableStream` 之间的集成协同行为。

package/src/tube/helper.ts

@@ -0,0 +1,138 @@
+import { ReadableStream } from "node:stream/web"
+
+import { streamConsumeInMacroTask, toError } from "#Source/basic/index.ts"
+import { Tube } from "./tube.ts"
+
+/**
+ * 将上游 Tube 的生命周期、错误与数据转发到下游 Tube。
+ */
+export const connectTube = <D, E = Error>(
+  upstream: Tube<D, E>,
+  downstream: Tube<D, E>,
+): (() => void) => {
+  const openEventSubscriber = async (): Promise<void> => {
+    await downstream.open()
+  }
+  upstream.subscribeOpenEvent({ subscriber: openEventSubscriber })
+  const closeEventSubscriber = async (): Promise<void> => {
+    await downstream.close()
+  }
+  upstream.subscribeCloseEvent({ subscriber: closeEventSubscriber })
+  const startEventSubscriber = async (): Promise<void> => {
+    await downstream.start()
+  }
+  upstream.subscribeStartEvent({ subscriber: startEventSubscriber })
+  const endEventSubscriber = async (): Promise<void> => {
+    await downstream.end()
+  }
+  upstream.subscribeEndEvent({ subscriber: endEventSubscriber })
+  const errorEventSubscriber = async (error: E): Promise<void> => {
+    await downstream.pushError(error)
+  }
+  upstream.subscribeErrorEvent({ subscriber: errorEventSubscriber })
+  const dataSubscriber = async (data: D): Promise<void> => {
+    await downstream.pushData(data)
+  }
+  upstream.subscribeData({ subscriber: dataSubscriber })
+
+  return (): void => {
+    upstream.unsubscribeOpenEvent(openEventSubscriber)
+    upstream.unsubscribeCloseEvent(closeEventSubscriber)
+    upstream.unsubscribeStartEvent(startEventSubscriber)
+    upstream.unsubscribeEndEvent(endEventSubscriber)
+    upstream.unsubscribeErrorEvent(errorEventSubscriber)
+    upstream.unsubscribeData(dataSubscriber)
+  }
+}
+
+/**
+ * 把 Tube 收束为一个 Promise，并在通道关闭时以最后一条数据或最新错误结算。
+ */
+export const tubeToPromise = async <D, E = Error>(
+  tube: Tube<D, E>,
+): Promise<D> => {
+  const promise = new Promise<D>((resolve, reject) => {
+    const handle = (): void => {
+      if (tube.isError()) {
+        reject(toError(tube.safeGetLatestError()))
+        unsubscribe()
+      }
+      if (tube.hasClosed()) {
+        if (tube.isWet()) {
+          resolve(tube.safeGetLatestData())
+          unsubscribe()
+        }
+        else {
+          reject(new Error("No data available"))
+          unsubscribe()
+        }
+      }
+    }
+    const unsubscribe = tube.subscribeCloseEvent({
+      subscriber: () => {
+        handle()
+      },
+    })
+    // invoke once
+    handle()
+  })
+  return await promise
+}
+
+/**
+ * 把 Tube 暴露为一个 `ReadableStream`。
+ */
+export const tubeToReadableStream = <D, E = Error>(
+  tube: Tube<D, E>,
+): ReadableStream<D> => {
+  const readableStream = new ReadableStream<D>({
+    start(controller): void {
+      const closeEventSubscriber = (): void => {
+        controller.close()
+        unsubscribeAll()
+      }
+      const unsubscribeCloseEvent = tube.subscribeCloseEvent({ subscriber: closeEventSubscriber })
+      const errorEventSubscriber = (error: E): void => {
+        controller.error(error)
+      }
+      const unsubscribeErrorEvent = tube.subscribeErrorEvent({ subscriber: errorEventSubscriber })
+      const dataSubscriber = (data: D): void => {
+        controller.enqueue(data)
+      }
+      const unsubscribeDataSubscriber = tube.subscribeData({ subscriber: dataSubscriber })
+
+      const unsubscribeAll = (): void => {
+        unsubscribeCloseEvent()
+        unsubscribeErrorEvent()
+        unsubscribeDataSubscriber()
+      }
+    },
+  })
+  return readableStream
+}
+
+/**
+ * 把 `ReadableStream` 转换为一个立即开始消费上游数据的 Tube。
+ *
+ * 调用后会立刻开始消费 `ReadableStream`，并将数据推入返回的 Tube。
+ */
+export const readableStreamToTube = <D, E = Error>(
+  readableStream: ReadableStream<D>,
+): Tube<D, E> => {
+  const tube = new Tube<D, E>({
+    historyCount: Infinity,
+    replayHistory: true,
+  })
+
+  // NOTE: 这里确保 chunk 的消费和 Tube 的回调穿插在宏任务队列中执行，
+  //       而不是所有 chunk 都获取完毕之后才开始处理 Tube 回调。
+  streamConsumeInMacroTask({
+    readableStream,
+    onValue: async chunk => await tube.pushData(chunk),
+    onDone: async () => await tube.close(),
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    onError: async error => await tube.pushError(error as E),
+  })
+
+  return tube
+}

package/src/tube/index.ts

@@ -0,0 +1,2 @@
+export * from "./tube.ts"
+export * from "./helper.ts"