@planet-matrix/mobius-model 0.5.0 → 0.6.0

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

@@ -0,0 +1,594 @@
+import type { BaseEvents } from "#Source/event/index.ts"
+import { EventManager } from "#Source/event/index.ts"
+
+import { MinHeap } from "./min-heap.ts"
+import { RemainingManager } from "./remaining-manager.ts"
+
+const MAX_SCHEDULER_DELAY = 2_147_483_647
+
+/**
+ * 提供当前墙钟时间（wall-clock time）的毫秒值。
+ */
+export interface ExpirationManagerClock {
+  /**
+   * 返回当前时间戳，单位为毫秒。
+   */
+  now(): number
+}
+
+/**
+ * 表示一个以毫秒为单位的过期时点。
+ */
+export type ExpirationEndAt = number
+
+/**
+ * 描述一组按过期名称索引的过期时点字典。
+ */
+export type ExpirationDict<ExpirationName extends string> = {
+  [K in ExpirationName]?: ExpirationEndAt | undefined
+}
+
+/**
+ * 描述 `ExpirationManager` 对外发出的事件表。
+ *
+ * 当管理器处于暂停状态时，事件不会立即发出，而是延后并折叠为恢复时的最新快照。
+ */
+export interface ExpirationManagerEvents<ExpirationName extends string> extends BaseEvents {
+  /**
+   * 在保留的过期状态快照发生可观察变化时发出最新结果。
+   */
+  expirationState: (expirationState: ExpirationState<ExpirationName>) => void
+}
+
+/**
+ * Hold one coalesced emission payload derived from current manager state.
+ */
+interface ExpirationEmission<ExpirationName extends string> {
+  expirationState: ExpirationState<ExpirationName>
+}
+
+/**
+ * 描述一条被管理器保留的过期状态记录。
+ */
+export interface ExpirationStateItem<ExpirationName extends string> {
+  /**
+   * 该过期项的名称。
+   */
+  name: ExpirationName
+
+  /**
+   * 该过期项对应的绝对到期时点，单位为毫秒。
+   */
+  endAt: ExpirationEndAt
+
+  /**
+   * 该过期项当前的状态。
+   */
+  state: "active" | "expired" | "removed"
+}
+
+/**
+ * 描述一组按过期名称索引的保留状态字典。
+ */
+export type ExpirationState<ExpirationName extends string> = {
+  [K in ExpirationName]?: ExpirationStateItem<ExpirationName> | undefined
+}
+
+/**
+ * 描述创建 `ExpirationManager` 时可用的配置项。
+ */
+export interface ExpirationManagerOptions<ExpirationName extends string> {
+  /**
+   * 用于初始化管理器的过期项集合。
+   */
+  initialExpirations?: ExpirationDict<ExpirationName> | undefined
+
+  /**
+   * 控制是否同时启用派生剩余时间管理器的周期性检查。
+   */
+  enableRemainingManager?: boolean | undefined
+
+  /**
+   * 提供自定义时间来源；未提供时默认使用 `Date.now()`。
+   */
+  clock?: ExpirationManagerClock | undefined
+}
+
+/**
+ * 管理具名过期项的状态、事件与定时调度。
+ *
+ * `ExpirationManager` owns the source-of-truth expiration state dictionary and uses a `MinHeap`
+ * to keep the nearest `endAt` value at the top. That makes rescheduling efficient because
+ * the manager only needs to inspect the heap root to determine the next wake-up time,
+ * instead of scanning all expiration entries on every update.
+ *
+ * When the next expiration is farther away than the platform timer limit, scheduling is
+ * performed in bounded segments until the target timestamp becomes reachable.
+ *
+ * Pausing does not freeze time or reject writes. State updates may continue while paused,
+ * but expiration events and derived remaining events are deferred. Multiple paused-time
+ * state changes are coalesced into the latest snapshot and flushed after `resume()`.
+ *
+ * Remaining time is treated as derived state rather than primary state. The companion
+ * `RemainingManager` reads snapshots from `ExpirationManager`, computes second-based
+ * remaining values on demand, and can periodically emit those derived values without
+ * duplicating expiration ownership.
+ */
+export class ExpirationManager<ExpirationName extends string = string> {
+  private expirationState: ExpirationState<ExpirationName>
+
+  private clock: ExpirationManagerClock
+  private heap: MinHeap<ExpirationName>
+  private schedulerTimer: ReturnType<typeof setTimeout> | null
+  private paused: boolean
+  private terminated: boolean
+  private expirationEmissionQueue: Array<ExpirationEmission<ExpirationName>>
+  private flushingExpirationEmissionQueue: boolean
+
+  readonly event: EventManager<ExpirationManagerEvents<ExpirationName>>
+  readonly remainingManager: RemainingManager<ExpirationName>
+
+  constructor(options: ExpirationManagerOptions<ExpirationName>) {
+    const { initialExpirations, enableRemainingManager, clock } = options
+    const initialExpirationSource: ExpirationDict<ExpirationName> = initialExpirations ?? {}
+
+    this.expirationState = {}
+
+    this.clock = clock ?? {
+      now: (): number => Date.now()
+    }
+    this.heap = new MinHeap()
+    this.schedulerTimer = null
+    this.paused = false
+    this.terminated = false
+    this.expirationEmissionQueue = []
+    this.flushingExpirationEmissionQueue = false
+
+    this.event = new EventManager()
+    this.remainingManager = new RemainingManager<ExpirationName>({
+      expirationManager: this,
+      enabled: enableRemainingManager
+    })
+
+    this.updateExpirationBatch(initialExpirationSource)
+  }
+
+  /**
+    * 返回当前管理器使用的墙钟时间。
+   */
+  getNow(): number {
+    return this.clock.now()
+  }
+
+  /**
+    * 判断某个具名过期项当前是否仍有保留状态。
+    *
+    * 只要该名称当前处于 `active`、`expired` 或 `removed` 任一保留状态，就会返回 `true`。
+   */
+  hasExpiration(name: ExpirationName): boolean {
+    return this.expirationState[name] !== undefined
+  }
+
+  /**
+    * 返回某个具名过期项的状态快照。
+   */
+  getExpirationState(name: ExpirationName): ExpirationStateItem<ExpirationName> | undefined {
+    return structuredClone(this.expirationState[name])
+  }
+
+  /**
+    * 返回当前所有活跃过期项的绝对到期时点快照。
+   */
+  getExpirationSnapshot(): ExpirationDict<ExpirationName> {
+    const expirationDict: ExpirationDict<ExpirationName> = {}
+
+    for (const name of Object.keys(this.expirationState)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const expirationName = name as ExpirationName
+      const expirationState = this.expirationState[expirationName]
+
+      if (expirationState === undefined) {
+        continue
+      }
+      if (expirationState.state !== "active") {
+        continue
+      }
+
+      expirationDict[expirationName] = expirationState.endAt
+    }
+
+    return expirationDict
+  }
+
+  /**
+   * Check whether event emission is currently blocked.
+   */
+  private isEmissionBlocked(): boolean {
+    return this.terminated === true || this.paused === true
+  }
+
+  /**
+   * Flush queued state emissions in order until emission becomes blocked again.
+   */
+  private flushExpirationEmissionQueue(): void {
+    if (this.isEmissionBlocked() === true) {
+      return
+    }
+    if (this.flushingExpirationEmissionQueue === true) {
+      return
+    }
+
+    this.flushingExpirationEmissionQueue = true
+
+    try {
+      while (true) {
+        if (this.isEmissionBlocked() === true) {
+          return
+        }
+
+        const emission = this.expirationEmissionQueue.shift()
+        if (emission === undefined) {
+          return
+        }
+
+        this.event.emit("expirationState", emission.expirationState)
+      }
+    } finally {
+      this.flushingExpirationEmissionQueue = false
+    }
+  }
+
+  /**
+   * Build the latest event payload from current manager state.
+   */
+  private createExpirationEmission(): ExpirationEmission<ExpirationName> {
+    return {
+      expirationState: structuredClone(this.expirationState),
+    }
+  }
+
+  /**
+   * Replace any queued paused-time emission with the latest coalesced snapshot.
+   */
+  private replaceQueuedExpirationEmission(): void {
+    const emission = this.createExpirationEmission()
+    this.expirationEmissionQueue = [emission]
+  }
+
+  /**
+   * Queue an emission for the current state.
+   *
+   * While paused, the queue is collapsed to a single latest snapshot so `resume()`
+   * only flushes the final observable state.
+   */
+  private enqueueExpirationEmission(): void {
+    if (this.paused === true) {
+      this.replaceQueuedExpirationEmission()
+      return
+    }
+
+    const emission = this.createExpirationEmission()
+    this.expirationEmissionQueue.push(emission)
+    this.flushExpirationEmissionQueue()
+  }
+
+  /**
+   * Mark overdue active entries as expired when their stored timestamps are no longer in the future.
+   */
+  private updateExpired(now: number): boolean {
+    let changed = false
+
+    while (true) {
+      const top = this.heap.peek()
+      if (top === undefined || top.endAt > now) {
+        return changed
+      }
+
+      this.heap.pop()
+      const expiration = this.expirationState[top.name]
+      if (expiration === undefined) {
+        continue
+      }
+      if (expiration.state === "active" && expiration.endAt === top.endAt) {
+        this.expirationState[top.name] = { ...expiration, state: "expired" }
+        changed = true
+      }
+    }
+  }
+
+  private tick(): void {
+    if (this.terminated === true || this.paused === true) {
+      return
+    }
+
+    const changed = this.updateExpired(this.getNow())
+    if (changed === true) {
+      this.enqueueExpirationEmission()
+    }
+
+    this.schedule()
+  }
+
+  private schedule(): void {
+    if (this.terminated === true || this.paused === true) {
+      return
+    }
+
+    if (this.schedulerTimer !== null) {
+      clearTimeout(this.schedulerTimer)
+      this.schedulerTimer = null
+    }
+
+    const next = this.heap.peek()
+    if (next === undefined) {
+      return
+    }
+
+    const delay = Math.min(MAX_SCHEDULER_DELAY, Math.max(0, next.endAt - this.getNow()))
+    this.schedulerTimer = setTimeout(() => this.tick(), delay)
+  }
+
+  private validateExpirationEndAt(endAt: number): void {
+    if (Number.isFinite(endAt) !== true || endAt < 0) {
+      throw new RangeError("Expiration endAt must be a finite timestamp greater than or equal to 0.")
+    }
+  }
+
+  private internalUpsertExpiration(name: ExpirationName, endAt: number, now: number): boolean {
+    this.validateExpirationEndAt(endAt)
+
+    const oldState = this.expirationState[name]
+    const newState = { name, endAt, state: endAt <= now ? "expired" : "active" } as const
+
+    if (
+      oldState !== undefined &&
+      oldState.name === newState.name &&
+      oldState.endAt === newState.endAt &&
+      oldState.state === newState.state
+    ) {
+      return false
+    }
+
+    this.expirationState[name] = newState
+    this.heap.remove(name)
+    if (newState.state === "active") {
+      this.heap.push({ name, endAt })
+    }
+
+    return true
+  }
+
+  /**
+    * 使用毫秒级绝对时点设置或替换一个具名过期项。
+   */
+  upsertExpiration(name: ExpirationName, endAt: number): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    const changed = this.internalUpsertExpiration(name, endAt, this.getNow())
+    if (changed === true) {
+      this.enqueueExpirationEmission()
+
+      this.schedule()
+    }
+  }
+
+  /**
+    * 使用毫秒级绝对时点执行一次局部批量更新。
+   *
+    * 对于 `dict` 中每个被显式提供的键，行为如下：
+    * - 数值会把对应过期项设置或替换为给定的绝对 `endAt` 时点。
+    * - 显式的 `undefined` 只会在当前状态为 `active` 时把该项标记为 `removed`。
+    * - 当前已处于 `expired` 或 `removed` 的项，遇到显式 `undefined` 时保持不变。
+    * - `dict` 中未出现的键不会被处理，现有状态保持不变。
+   *
+    * 当至少有一项真实发生变化时，会在所有显式更新完成后统一发出一次状态变化通知。
+   */
+  updateExpirationBatch(dict: ExpirationDict<ExpirationName>): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    for (const name of Object.keys(dict)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const expirationName = name as ExpirationName
+      const endAt = dict[expirationName]
+
+      if (endAt === undefined) {
+        continue
+      }
+
+      this.validateExpirationEndAt(endAt)
+    }
+
+    let changed = false
+    const now = this.getNow()
+    for (const name of Object.keys(dict)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const expirationName = name as ExpirationName
+      const endAt = dict[expirationName]
+
+      if (endAt === undefined) {
+        const expiration = this.expirationState[expirationName]
+        if (expiration === undefined) {
+          continue
+        }
+        if (expiration.state === "active") {
+          this.expirationState[expirationName] = { ...expiration, state: "removed" }
+          this.heap.remove(expirationName)
+          changed = true
+        }
+
+        continue
+      }
+
+      changed = this.internalUpsertExpiration(expirationName, endAt, now) || changed
+    }
+
+    if (changed === true) {
+      this.enqueueExpirationEmission()
+
+      this.schedule()
+    }
+  }
+
+  /**
+    * 将一个当前处于活跃状态的过期项标记为 `removed`。
+    *
+    * 已经处于 `expired` 或 `removed` 的项不会被再次修改。
+   */
+  removeExpiration(name: ExpirationName): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    const expiration = this.expirationState[name]
+    if (expiration === undefined) {
+      return
+    }
+    if (expiration.state !== "active") {
+      return
+    }
+
+    this.expirationState[name] = { ...expiration, state: "removed" }
+    this.heap.remove(name)
+
+    this.enqueueExpirationEmission()
+
+    this.schedule()
+  }
+
+  /**
+    * 清除所有当前状态为 `expired` 的保留项，并返回清除数量。
+   */
+  clearExpiredExpirations(): number {
+    if (this.terminated === true) {
+      return 0
+    }
+
+    let clearedCount = 0
+
+    for (const name of Object.keys(this.expirationState)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const expirationName = name as ExpirationName
+      const expirationState = this.expirationState[expirationName]
+      if (expirationState === undefined) {
+        continue
+      }
+      if (expirationState.state !== "expired") {
+        continue
+      }
+
+      this.heap.remove(expirationName)
+      delete this.expirationState[expirationName]
+      clearedCount = clearedCount + 1
+    }
+
+    if (clearedCount > 0) {
+      this.enqueueExpirationEmission()
+    }
+
+    return clearedCount
+  }
+
+  /**
+    * 清除所有当前状态为 `removed` 的保留项，并返回清除数量。
+   */
+  clearRemovedExpirations(): number {
+    if (this.terminated === true) {
+      return 0
+    }
+
+    let clearedCount = 0
+
+    for (const name of Object.keys(this.expirationState)) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const expirationName = name as ExpirationName
+      const expirationState = this.expirationState[expirationName]
+      if (expirationState === undefined) {
+        continue
+      }
+      if (expirationState.state !== "removed") {
+        continue
+      }
+
+      this.heap.remove(expirationName)
+      delete this.expirationState[expirationName]
+      clearedCount = clearedCount + 1
+    }
+
+    if (clearedCount > 0) {
+      this.enqueueExpirationEmission()
+    }
+
+    return clearedCount
+  }
+
+  /**
+    * 暂停过期调度与事件发出。
+    *
+    * 这不会冻结绝对到期时点，也不会阻止状态写入。暂停期间时间仍会继续流逝，
+    * 只是过期推进与事件通知会延后到后续恢复时再统一处理。
+   */
+  pause(): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    this.paused = true
+
+    if (this.schedulerTimer !== null) {
+      clearTimeout(this.schedulerTimer)
+      this.schedulerTimer = null
+    }
+
+    this.remainingManager.pause()
+  }
+
+  /**
+    * 恢复过期调度，并刷新暂停期间积累的最新状态通知。
+    *
+    * 在暂停期间已经越过其绝对 `endAt` 的项，可能会在恢复后立即转为 `expired`。
+    * 若暂停期间发生过多次状态变更，对外只会发出折叠后的最新快照。
+   */
+  resume(): void {
+    if (this.terminated === true) {
+      return
+    }
+    if (this.paused !== true) {
+      return
+    }
+
+    this.paused = false
+
+    const changed = this.updateExpired(this.getNow())
+    if (changed === true) {
+      this.replaceQueuedExpirationEmission()
+    }
+
+    this.schedule()
+    this.remainingManager.resume()
+    this.flushExpirationEmissionQueue()
+  }
+
+  /**
+    * 终止当前管理器及其派生剩余时间管理器，并释放它们拥有的定时资源。
+   */
+  terminate(): void {
+    if (this.terminated === true) {
+      return
+    }
+
+    this.terminated = true
+    this.paused = true
+
+    if (this.schedulerTimer !== null) {
+      clearTimeout(this.schedulerTimer)
+      this.schedulerTimer = null
+    }
+
+    this.expirationEmissionQueue = []
+    this.remainingManager.terminate()
+  }
+}

package/src/timer/expiration/index.ts

@@ -0,0 +1,3 @@
+export * from "./min-heap.ts"
+export * from "./remaining-manager.ts"
+export * from "./expiration-manager.ts"