@planet-matrix/mobius-model 0.4.0 → 0.6.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 { BaseEvents, 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 interface RemainingManagerEvents<ExpirationName extends string> extends BaseEvents {
+  /**
+   * 在剩余时间快照发生变化时发出最新结果。
+   */
+  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"