@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/orchestration/README.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-Orchestration 模块提供围绕执行单元编排（orchestration）的基础建模能力，用于把多个执行单元之间的创建、组织、调度、等待、放行、推进、收束以及整体协作关系表达为稳定且可复用的公共语义。
+Orchestration 模块提供围绕执行单元编排（orchestration）的基础建模能力，用于把多个执行单元之间的创建、组织、调度、分派、等待、放行、推进、收束以及整体协作关系表达为稳定且可复用的公共语义。
 
 它关注的不是某个具体框架、某个具体队列系统或某个具体工作流引擎的宿主接口，而是“多个执行单元如何被组织为可理解、可组合、可控制、可持续演化的编排结构”这一更一般的问题。因此，这个模块不应被理解为仅仅承载互斥锁、信号量或栅栏的协调原语集合；这些内容只是当前实现中更基础的一层，而不是 Orchestration 这个词所指向的全部问题域。
 
@@ -10,13 +10,14 @@ Orchestration 模块提供围绕执行单元编排（orchestration）的基础
 
 理解 Orchestration 模块时，应先把它看作“执行单元组织关系”的建模层，而不是一组彼此孤立的小工具。它要解决的问题，不只是多个异步流程怎样竞争资源、怎样等待同步点，也包括执行单元该如何被表达、如何被组合成更大的结构、流程阶段该如何被推进，以及这些结构之间应该暴露什么样的稳定公共语义。
 
-因此，Orchestration 更适合被理解为一个分层的问题域：较底层是 coordination，用于表达进入控制、等待约束、同步点和资源占用；再往上则可以逐步生长出更接近编排结构本身的能力，用于表达单个执行单元、执行单元之间的关系、阶段推进、依赖收敛、生命周期以及整体执行边界。未来这些能力的形态可能会落在 task、job、workflow 或其它更合适的抽象上，但 coordination 只是这些能力可复用的基础，并不等同于整个 orchestration 模块。
+因此，Orchestration 更适合被理解为一个分层的问题域：较底层是 coordination，用于表达进入控制、等待约束、同步点和资源占用；在其之上还可以有 dispatching，用于表达一组候选执行目标如何被选择、如何按上下文形成选择视图，以及反馈如何影响后续分派；再往上则可以逐步生长出更接近编排结构本身的能力，用于表达单个执行单元、执行单元之间的关系、阶段推进、依赖收敛、生命周期以及整体执行边界。未来这些能力的形态可能会落在 task、job、workflow 或其它更合适的抽象上，但 coordination 与 dispatching 都只是这些能力可复用的基础层，不等同于整个 orchestration 模块。
 
 理解这个模块时，还应守住几条边界原则：
 
 - Orchestration 模块表达的是编排语义与协调语义，但不应直接承担某个业务系统专属的流程定义语言、运营规则或领域状态机。
 - 它可以吸收一切稳定且通用的编排概念，但这些概念应以模型形式出现，而不是某个具体平台配置格式、DSL 或产品术语的直接翻版。
 - coordination 适合表达进程内、运行时内的基础协作约束；更高层的编排能力即使依赖这些约束，也不应把自己退化成底层锁语义的别名。
+- dispatching 适合表达一组候选目标之间的运行时分派、反馈驱动选择与局部选择视图，但不应直接退化成只面向某类网络节点的负载均衡器别名。
 - 它可以为重试、取消、阶段推进、依赖关系或执行计划等语义提供抽象空间，但不应把监控、持久化、分布式共识、租约续期或平台运维策略直接混入核心公共 API。
 
 ## For Using
@@ -26,18 +27,19 @@ Orchestration 模块提供围绕执行单元编排（orchestration）的基础
 从使用角度看，当前模块中的能力大致可以分为三类：
 
 - 底层协调能力：用于表达互斥进入、限量并发、阶段会合、闭锁等待、资源占用句柄以及超时和中止等等待约束。
+- 分派能力：用于表达多个候选执行目标之间如何被选择、如何基于调用上下文形成可复用的 selector，以及失败或恢复反馈如何影响后续选择。
 - 更高层编排能力：用于表达单个执行单元的边界、多个执行单元之间的关系、阶段推进、失败传播、取消语义、执行计划以及整体完成条件。这部分目前还不是主实现重心，但属于该模块未来合理的组成方向。
 - 结构化执行能力：用于把一组原本零散的异步动作收束为可以理解、组合与扩展的执行结构。未来它可能体现为 task、job、workflow，也可能体现为其它更贴切的抽象，但都不应退化成业务代码里对底层 Promise 的随意组合。
 
 更合适的接入方式，是先判断你的问题属于哪一层：如果你的核心诉求是某个时刻能否进入、是否需要排队、何时统一继续，那么你更接近 coordination；如果你的核心诉求已经开始涉及执行单元如何被声明、取消、组合、计划、收束或被纳入更大的执行结构，那么你已经进入更高层的 orchestration 语义。
 
-当前对外已经落地的主要是 `coordination` 子模块，因此现阶段使用时更多是在处理互斥、信号量、读写锁、闭锁与栅栏这类问题；但理解这个模块时不应把它局限为“并发锁工具箱”。更合适的看法是：coordination 先提供底层编排积木，而 orchestration 的整体职责会继续向更完整的执行组织与流程编排语义扩展。
+当前对外已经落地的主要是 `coordination` 与 `dispatching` 子模块，因此现阶段使用时既可以处理互斥、信号量、读写锁、闭锁与栅栏这类问题，也可以处理一组候选目标之间的 selector 构造、目标选择与反馈驱动分派；但理解这个模块时仍不应把它局限为“并发锁工具箱”或“负载均衡工具箱”。更合适的看法是：coordination 与 dispatching 先提供底层编排积木，而 orchestration 的整体职责会继续向更完整的执行组织与流程编排语义扩展。
 
 ## For Contributing
 
 为 Orchestration 模块贡献内容时，优先判断新增能力是否真的在澄清某种稳定的编排语义，而不是只是在补一个局部业务流程的便捷封装。这个模块应长期服务于“执行单元如何被表达”“多个执行单元如何组成更大的结构”“流程如何推进与结束”“等待与放行如何成为可复用原语”这几类问题。如果一个能力只有在绑定特定平台、特定产品流程或特定部署环境时才成立，那么它通常不应直接成为该模块的公共组成部分。
 
-扩展这个模块时，应特别警惕以下倾向：把 orchestration 退化成一堆零散锁工具；把某个具体工作流引擎的配置模型直接照搬进公共 API；把重试、补偿、优先级、监控或持久化策略无差别地下沉到所有层级；把调用方的一次性业务约定固化为模块语义；或者为了某个实现细节而暴露内部等待队列、内部状态节点与临时调度结构。文档应说明哪些编排边界是长期成立的，以及为什么这些边界成立，而不是复述当前版本的局部实现技巧。
+扩展这个模块时，应特别警惕以下倾向：把 orchestration 退化成一堆零散锁工具；把 dispatching 退化成只对某一类 upstream 节点成立的网络负载均衡器包装；把某个具体工作流引擎的配置模型直接照搬进公共 API；把重试、补偿、优先级、监控或持久化策略无差别地下沉到所有层级；把调用方的一次性业务约定固化为模块语义；或者为了某个实现细节而暴露内部等待队列、内部状态节点、候选集快照与临时调度结构。文档应说明哪些编排边界是长期成立的，以及为什么这些边界成立，而不是复述当前版本的局部实现技巧。
 
 ### JSDoc 注释格式要求
 
@@ -68,14 +70,14 @@ Orchestration 模块提供围绕执行单元编排（orchestration）的基础
 - 子模块不需要有自己的 `README.md`。
 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
-- 与 orchestration 相关的实现应优先围绕执行单元边界、执行单元关系、等待约束、生命周期推进、阶段语义与可组合性组织；其中 coordination 子模块再单独关注占用句柄、队列调度、公平性与同步阶段语义，避免把具体业务流程或宿主运行时策略混入模块边界。
+- 与 orchestration 相关的实现应优先围绕执行单元边界、执行单元关系、等待约束、分派语义、生命周期推进、阶段语义与可组合性组织；其中 coordination 子模块再单独关注占用句柄、队列调度、公平性与同步阶段语义，dispatching 子模块再单独关注候选目标集合、selector 视图、选择策略与反馈驱动调整，避免把具体业务流程、网络拓扑假设或宿主运行时策略混入模块边界。
 
 ### 导出策略要求
 
 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
-- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的编排语义或协调语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的编排语义、协调语义或分派语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
 ### 测试要求
 
@@ -86,4 +88,4 @@ Orchestration 模块提供围绕执行单元编排（orchestration）的基础
 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。
 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
 - 模块的单元测试文件目录是 `./tests/unit/orchestration`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/orchestration/<sub-module-name>`。
-- 对这个模块来说，测试应按层覆盖：coordination 层优先覆盖资源获取与释放、等待队列的 FIFO 或公平性约束、超时与中止导致的失败语义、同步点完成或破坏时的整体行为，以及 permit 重复释放等误用路径；未来若引入更高层编排能力，则应优先覆盖生命周期推进、依赖关系收敛、失败传播、取消与重试边界，以及整体编排结果的确定性。
+- 对这个模块来说，测试应按层覆盖：coordination 层优先覆盖资源获取与释放、等待队列的 FIFO 或公平性约束、超时与中止导致的失败语义、同步点完成或破坏时的整体行为，以及 permit 重复释放等误用路径；dispatching 层优先覆盖 selector 复用与销毁、候选目标过滤、策略驱动的选择顺序、无可选目标与无可用目标的区分，以及反馈回写后对后续选择的影响；未来若引入更高层编排能力，则应优先覆盖生命周期推进、依赖关系收敛、失败传播、取消与重试边界，以及整体编排结果的确定性。

package/src/orchestration/dispatching/dispatcher.ts

@@ -0,0 +1,83 @@
+import type { LoggerFriendly, LoggerFriendlyOptions } from "#Source/log/index.ts"
+import { generateUuidV4FromUrl } from "#Source/identifier/index.ts"
+import { Logger } from "#Source/log/index.ts"
+
+import type { BaseSelector } from "./selector/index.ts"
+import { DownCountSelector } from "./selector/index.ts"
+
+interface ItemStates<Target> {
+  item: Target
+  available: boolean
+}
+
+export interface GetSelectorOptions<Target> {
+  id?: string | undefined
+  filter?: ((item: Target) => boolean) | undefined
+}
+
+export interface GetSelectorResult<Target> {
+  selector: BaseSelector<Target>
+  destroy: () => void
+}
+
+export interface DispatcherOptions<Target> extends LoggerFriendlyOptions {
+  itemList: Target[]
+}
+
+export class Dispatcher<Target> implements LoggerFriendly {
+  readonly logger: Logger
+
+  private itemStatesMap: Map<Target, ItemStates<Target>>
+  private selectorMap: Map<string, BaseSelector<Target>>
+
+  constructor(options: DispatcherOptions<Target>) {
+    this.logger = Logger.fromOptions(options).setDefaultName("Dispatcher")
+
+    this.itemStatesMap = new Map()
+    options.itemList.forEach((item) => {
+      this.itemStatesMap.set(item, {
+        item,
+        available: true,
+      })
+    })
+    this.selectorMap = new Map()
+  }
+
+  getSelector(options: GetSelectorOptions<Target>): GetSelectorResult<Target> {
+    const {
+      id = generateUuidV4FromUrl(),
+      filter = (): boolean => true,
+    } = options
+
+    const isInitialized = this.selectorMap.has(id)
+    if (isInitialized === false) {
+      const list = Array.from(this.itemStatesMap.values())
+        .filter((itemStates) => {
+          return itemStates.available === true && filter(itemStates.item) === true
+        })
+        .map((itemStates) => {
+          return itemStates.item
+        })
+      // TODO: 将 selector 的类型作为参数，从而实现不同的 dispatcher 策略
+      const selector = new DownCountSelector({
+        id,
+        itemList: list,
+        logger: Logger.derive(this.logger).setName(`Selector-${id}`),
+      })
+      this.selectorMap.set(id, selector)
+    }
+
+    const selector = this.selectorMap.get(id)!
+    const result = {
+      selector,
+      destroy: (): void => {
+        this.destroySelector(id)
+      },
+    }
+    return result
+  }
+
+  destroySelector(key: string): void {
+    this.selectorMap.delete(key)
+  }
+}

package/src/orchestration/dispatching/index.ts

@@ -0,0 +1,2 @@
+export * from "./selector/index.ts"
+export * from "./dispatcher.ts"

package/src/orchestration/dispatching/selector/base-selector.ts

@@ -0,0 +1,39 @@
+import type { LoggerFriendly, LoggerFriendlyOptions } from "#Source/log/index.ts"
+import type { Either } from "#Source/result/index.ts"
+
+import { Logger } from "#Source/log/index.ts"
+
+export interface GetItemLeft {
+  code: "NO_CHOICE" | "NO_AVAILABLE"
+}
+
+export interface GetItemRight<Target> {
+  item: Target
+  markAvailable: () => void
+  markUnavailable: () => void
+}
+
+export type GetItemResult<Target> = Either<GetItemLeft, GetItemRight<Target>>
+
+export interface BaseSelectorOptions<Target> extends LoggerFriendlyOptions {
+  id: string
+  itemList: Target[]
+}
+
+export abstract class BaseSelector<Target> implements LoggerFriendly {
+  readonly logger: Logger
+
+  private id: string
+
+  constructor(options: BaseSelectorOptions<Target>) {
+    this.logger = Logger.fromOptions(options).setDefaultName("BaseSelector")
+
+    this.id = options.id
+  }
+
+  getId(): string {
+    return this.id
+  }
+
+  abstract getItem(): Promise<GetItemResult<Target>>
+}

package/src/orchestration/dispatching/selector/down-count-selector.ts

@@ -0,0 +1,119 @@
+import type { LoggerFriendly, LoggerFriendlyOptions } from "#Source/log/index.ts"
+import { controllerFromEitherType } from "#Source/result/index.ts"
+
+import type { BaseSelectorOptions, GetItemResult } from "./base-selector.ts"
+import { BaseSelector } from "./base-selector.ts"
+
+interface ItemStates<Target> {
+  item: Target
+  downCount: number
+}
+
+export interface DownCountSelectorOptions<Target> extends BaseSelectorOptions<Target>, LoggerFriendlyOptions {
+  /**
+   * @default 1
+   */
+  maxDownCount?: number | undefined
+  /**
+   * @default true
+   */
+  resetAllWhenNoAvailable?: boolean | undefined
+}
+
+export class DownCountSelector<Target> extends BaseSelector<Target> implements LoggerFriendly {
+  private maxDownCount: number
+  private resetAllWhenNoAvailable: boolean
+
+  private itemStatesMap: Map<Target, ItemStates<Target>>
+
+  constructor(options: DownCountSelectorOptions<Target>) {
+    super(options)
+    this.logger.setDefaultName("DownCountSelector")
+
+    this.maxDownCount = options.maxDownCount ?? 1
+    this.resetAllWhenNoAvailable = options.resetAllWhenNoAvailable ?? true
+
+    this.itemStatesMap = new Map()
+    options.itemList.forEach((item) => {
+      this.itemStatesMap.set(item, {
+        item,
+        downCount: 0,
+      })
+    })
+  }
+
+  private markItemAvailable(item: Target): void {
+    const states = this.itemStatesMap.get(item)
+    if (states === undefined) {
+      throw new Error(`Item not found: ${String(item)}`)
+    }
+    states.downCount = 0
+  }
+
+  private markItemUnavailable(item: Target): void {
+    const states = this.itemStatesMap.get(item)
+    if (states === undefined) {
+      throw new Error(`Item not found: ${String(item)}`)
+    }
+    states.downCount = states.downCount + 1
+  }
+
+  private resetAllItem(): void {
+    this.itemStatesMap.forEach((states) => {
+      states.downCount = 0
+    })
+  }
+
+  private getAvailableItemList(): Target[] {
+    const availableItemList: Target[] = []
+    this.itemStatesMap.forEach((states) => {
+      if (states.downCount < this.maxDownCount) {
+        availableItemList.push(states.item)
+      }
+    })
+    return availableItemList
+  }
+
+  async getItem(): Promise<GetItemResult<Target>> {
+    const controller = controllerFromEitherType<GetItemResult<Target>>()
+
+    if (this.itemStatesMap.size === 0) {
+      return await controller.returnLeft({
+        code: "NO_CHOICE",
+      })
+    }
+
+    const availableItemList = this.getAvailableItemList()
+    if (availableItemList.length === 0) {
+      if (this.resetAllWhenNoAvailable === false) {
+        return await controller.returnLeft({
+          code: "NO_AVAILABLE",
+        })
+      }
+      else {
+        this.resetAllItem()
+        return await this.getItem()
+      }
+    }
+
+    availableItemList.sort((a, b) => {
+      const aStates = this.itemStatesMap.get(a)!
+      const bStates = this.itemStatesMap.get(b)!
+      if (aStates.downCount === bStates.downCount) {
+        return 0
+      }
+      return aStates.downCount - bStates.downCount
+    })
+    const item = availableItemList[0]!
+
+    return await controller.returnRight({
+      item,
+      markAvailable: () => {
+        this.markItemAvailable(item)
+      },
+      markUnavailable: () => {
+        this.markItemUnavailable(item)
+      },
+    })
+  }
+}

package/src/orchestration/dispatching/selector/index.ts

@@ -0,0 +1,2 @@
+export * from "./base-selector.ts"
+export * from "./down-count-selector.ts"

package/src/orchestration/index.ts

@@ -1 +1,3 @@
 export * from "./coordination/index.ts"
+export * from "./dispatching/index.ts"
+export * from "./scheduling/index.ts"

package/src/orchestration/scheduling/index.ts

@@ -0,0 +1,2 @@
+export * from "./task.ts"
+export * from "./scheduler.ts"

package/src/orchestration/scheduling/scheduler.ts

@@ -0,0 +1,103 @@
+import type { Task } from "./task.ts"
+
+export interface RunLogEntry {
+  name: string
+  time: Date
+}
+export interface ErrLogEntry {
+  name: string
+  time: Date
+  reason: string
+}
+export interface SchedulerOptions {
+  tasks: Task[]
+  maxLogNumber?: number | undefined
+}
+export class Scheduler {
+  protected options: SchedulerOptions
+
+  protected isRunning: boolean
+  protected maxLogNumber: number
+  protected timers: Set<ReturnType<typeof setTimeout>>
+  protected runLog: RunLogEntry[] = []
+  protected errLog: ErrLogEntry[] = []
+
+  constructor(options: SchedulerOptions) {
+    this.options = options
+
+    this.isRunning = false
+    this.maxLogNumber = options.maxLogNumber ?? 100
+    this.timers = new Set()
+  }
+
+  addTask(task: Task): void {
+    this.options.tasks.push(task)
+  }
+
+  addRunLog(runLog: RunLogEntry): void {
+    this.runLog.push(runLog)
+    if (this.runLog.length > this.maxLogNumber) {
+      this.runLog = this.runLog.slice(this.maxLogNumber * -1)
+    }
+  }
+
+  addErrLog(errLog: ErrLogEntry): void {
+    this.errLog.push(errLog)
+    if (this.errLog.length > this.maxLogNumber) {
+      this.errLog = this.errLog.slice(this.maxLogNumber * -1)
+    }
+  }
+
+  getRunLog(): RunLogEntry[] {
+    return this.runLog
+  }
+
+  getErrLog(): ErrLogEntry[] {
+    return this.errLog
+  }
+
+  protected scheduleTask(task: Task): void {
+    const nextRun = task.getCron().nextRun()
+    if (nextRun === undefined) {
+      return
+    }
+
+    const delay = Math.max(nextRun.getTime() - Date.now(), 0)
+    const timer = setTimeout(() => {
+      this.timers.delete(timer)
+      if (this.isRunning !== true) {
+        return
+      }
+
+      this.scheduleTask(task)
+      void task.run()
+        .catch((reason: unknown) => {
+          this.addErrLog({
+            name: task.getName(),
+            time: new Date(),
+            reason: String(reason),
+          })
+        })
+        .finally(() => {
+          this.addRunLog({
+            name: task.getName(),
+            time: new Date(),
+          })
+        })
+    }, delay)
+
+    this.timers.add(timer)
+  }
+
+  run(): void {
+    if (this.isRunning === true) {
+      throw new Error("Scheduler is already running")
+    } else {
+      this.isRunning = true
+    }
+
+    for (const task of this.options.tasks) {
+      this.scheduleTask(task)
+    }
+  }
+}

package/src/orchestration/scheduling/task.ts

@@ -0,0 +1,32 @@
+import { isCron, Cron } from "#Source/cron/index.ts"
+
+export interface TaskOptions {
+  name: string
+  cron: Cron | string | Date
+  run: (() => void) | (() => Promise<void>)
+}
+export class Task {
+  protected options: TaskOptions
+  protected cron: Cron
+
+  constructor(options: TaskOptions) {
+    this.options = options
+    if (isCron(options.cron) === true) {
+      this.cron = options.cron
+    } else {
+      this.cron = new Cron({ pattern: options.cron })
+    }
+  }
+
+  getName(): string {
+    return this.options.name
+  }
+
+  getCron(): Cron {
+    return this.cron
+  }
+
+  async run(): Promise<void> {
+    await this.options.run()
+  }
+}

package/src/random/README.md

@@ -2,31 +2,31 @@
 
 ## Description
 
-Random 模块用于提供随机值（random value）相关的基础能力，当前主要承载随机字符串生成语义。
+Random 模块用于提供随机值（random value）相关的基础能力，当前主要承载随机布尔值、随机字符串、随机数字与随机整数生成语义。
 
-它关注的是“如何生成一类通用、可复用、语义清楚的随机文本”，而不是各种标识格式校验、业务编码规则或安全承诺各异的随机机制集合。
+它关注的是“如何生成一类通用、可复用、语义清楚的随机值”，而不是各种标识格式校验、业务编码规则或安全承诺各异的随机机制集合。
 
 ## For Understanding
 
 理解 Random 模块时，应先把它放在应用边界附近。随机值通常意味着不可复现、带有环境依赖，或者会影响测试与调试行为，因此更合理的做法是把它看作边界输入的生成层，而不是让随机行为无约束地扩散到核心业务逻辑内部。
 
-当前这个模块的核心边界比较克制：它主要处理“随机字符串如何生成”这一类问题。也就是说，它更关心字符集、长度、结果格式和重复概率，而不再负责 UUID 这类已经具有明确标识语义的格式模型。
+当前这个模块的核心边界比较克制：它主要处理“随机布尔值如何生成”“随机字符串如何生成”“通用随机数字如何生成”与“通用随机整数如何生成”这一类问题。也就是说，它更关心 true 概率、字符集、长度、数值区间、整数边界、结果格式和重复概率，而不再负责 UUID 这类已经具有明确标识语义的格式模型。
 
 不适合放入本模块的能力，通常包括两类：一类是与密码学安全直接绑定、需要单独安全承诺的能力；另一类是已经形成稳定标识语义的格式模型，例如 UUID。前者应以更明确的安全语义单独建模，后者则应放入更贴近标识问题域的模块。
 
 ## For Using
 
-当你需要在应用或库的边界层生成临时标识、关联值、会话键或其它非业务主键用途的随机文本时，可以使用这个模块。它更适合被理解为“随机字符串生成接口”，而不是一个什么都往里塞的杂项工具箱。
+当你需要在应用或库的边界层生成随机布尔值、临时标识、关联值、会话键或其它非业务主键用途的随机值时，可以使用这个模块。它更适合被理解为“随机值生成接口”，而不是一个什么都往里塞的杂项工具箱。
 
-从使用角度看，当前公共能力主要围绕随机字符串生成展开。更合适的接入方式，是在边界层尽早生成这些随机文本，再把得到的结果作为普通输入传给后续模块，从而避免内部逻辑直接依赖随机过程本身。
+从使用角度看，当前公共能力主要围绕随机布尔值、随机字符串、随机数字与随机整数生成展开。更合适的接入方式，是在边界层尽早生成这些随机值，再把得到的结果作为普通输入传给后续模块，从而避免内部逻辑直接依赖随机过程本身。
 
 需要特别注意的是，本模块中的“随机”默认应被理解为通用应用层随机，而不是自动带有密码学强度承诺的安全随机。只要调用场景对安全性、可预测性、重复碰撞风险或跨环境一致性有更严格要求，就应先在设计上明确这些前提，而不要仅凭模块名称推断安全等级。
 
 ## For Contributing
 
-贡献 Random 模块时，应先确认新增能力表达的是稳定、清楚且可长期承诺的随机语义，而不是某种实现手段的直接暴露。对外公开的重点应该是“调用方需要什么随机字符串能力”，而不是“内部恰好如何生成这些值”。只要一个能力过度依赖当前实现细节，或者只在某个很窄的业务上下文中成立，就不适合进入这个模块。
+贡献 Random 模块时，应先确认新增能力表达的是稳定、清楚且可长期承诺的随机语义，而不是某种实现手段的直接暴露。对外公开的重点应该是“调用方需要什么随机值能力”，而不是“内部恰好如何生成这些值”。只要一个能力过度依赖当前实现细节，或者只在某个很窄的业务上下文中成立，就不适合进入这个模块。
 
-在扩展时，应特别警惕两个方向的边界漂移。其一，不要把安全领域的问题用模糊措辞塞进来，例如把需要明确密码学承诺的能力混入通用随机工具中。其二，不要把已经形成稳定标识语义的格式模型重新拉回 Random。Random 模块应尽量保持为面向广泛调用方的随机文本生成边界，而不是业务专用规则仓库。
+在扩展时，应特别警惕两个方向的边界漂移。其一，不要把安全领域的问题用模糊措辞塞进来，例如把需要明确密码学承诺的能力混入通用随机工具中。其二，不要把已经形成稳定标识语义的格式模型重新拉回 Random。Random 模块应尽量保持为面向广泛调用方的随机值生成边界，而不是业务专用规则仓库。
 
 ### JSDoc 注释格式要求
 
@@ -75,4 +75,5 @@ Random 模块用于提供随机值（random value）相关的基础能力，当
 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。
 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
 - 模块的单元测试文件目录是 `./tests/unit/random`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/random/<sub-module-name>`。
+- 对随机布尔值相关能力，应优先测试概率边界、结果类型与极端输入语义，而不要把测试建立在脆弱的统计分布断言之上。
 - 对随机字符串相关能力，应优先测试长度约束、字符集边界与结果特征，而不要把测试建立在脆弱的精确随机输出之上。

package/src/random/base.ts

@@ -0,0 +1,66 @@
+// Uint32 的取值空间大小为 2^32。
+// Random 模块中的基础随机换算都会用到这一个范围常量。
+const internalRandomUint32Range = 0x1_0000_0000
+
+/**
+ * 取得一个随机 Uint32 值。
+ *
+ * 当运行时提供 `crypto.getRandomValues` 时，使用该随机源生成结果；否则回退到 `Math.random`。
+ * 该函数适合作为 Random 模块内外共享的基础随机整数入口。
+ *
+ * @example
+ * ```
+ * const value = getRandomUint32()
+ * // Expect: true
+ * const example1 = Number.isInteger(value) && value >= 0 && value < 0x1_0000_0000
+ * ```
+ */
+export const getRandomUint32 = (): number => {
+  if (globalThis.crypto !== undefined && typeof globalThis.crypto.getRandomValues === "function") {
+    const buffer = new Uint32Array(1)
+    globalThis.crypto.getRandomValues(buffer)
+    return buffer[0]!
+  }
+
+  return Math.floor(Math.random() * internalRandomUint32Range)
+}
+
+/**
+ * 取得一个 `0` 到 `1` 之间的随机小数，包含下界，不包含上界。
+ *
+ * 该函数基于统一的 Uint32 随机源换算得到，适合作为随机数字与随机整数逻辑的公共基础。
+ *
+ * @example
+ * ```
+ * const value = getRandomUnitValue()
+ * // Expect: true
+ * const example1 = value >= 0 && value < 1
+ * ```
+ */
+export const getRandomUnitValue = (): number => {
+  return getRandomUint32() / internalRandomUint32Range
+}
+
+/**
+ * 将随机整数均匀映射为索引。
+ *
+ * 若直接对 `alphabetLength` 取模，在长度不能整除 `2^32` 时会产生轻微偏差，因此这里使用拒绝采样，丢弃落在尾部残余区间的随机值。
+ *
+ * @example
+ * ```
+ * const index = getRandomIndex(3)
+ * // Expect: true
+ * const example1 = Number.isInteger(index) && index >= 0 && index < 3
+ * ```
+ */
+export const getRandomIndex = (length: number): number => {
+  const limit = internalRandomUint32Range - (internalRandomUint32Range % length)
+
+  while (true) {
+    const value = getRandomUint32()
+
+    if (value < limit) {
+      return value % length
+    }
+  }
+}

package/src/random/index.ts

@@ -1 +1,5 @@
-export * from "./string.ts"
+export * from "./base.ts"
+export * from "./random-boolean.ts"
+export * from "./random-integer.ts"
+export * from "./random-number.ts"
+export * from "./random-string.ts"

package/src/random/random-boolean.ts

@@ -0,0 +1,40 @@
+import { getRandomUnitValue } from "./base.ts"
+
+// 默认 true 概率为 0.5。
+// 当调用方未传入参数时，randomBoolean 会生成一个均匀分布的随机布尔值。
+const internalDefaultRandomBooleanProbability = 0.5
+
+// Step 1: 校验 true 概率。
+//
+// randomBoolean 只接受 0 到 1 之间的有限数值，避免把无效概率带入比较逻辑。
+const internalAssertRandomBooleanProbability = (value: number): void => {
+  if (Number.isFinite(value) === false) {
+    throw new TypeError(`Expected probability to be a finite number, got: ${value}`)
+  }
+
+  if (value < 0 || value > 1) {
+    throw new RangeError(`Expected probability to be between 0 and 1 inclusive, got: ${value}`)
+  }
+}
+
+/**
+ * 生成随机布尔值，并可选指定返回 `true` 的概率。
+ *
+ * 当未传入参数时，`true` 与 `false` 的概率各为一半；当传入 `probability` 时，会将其解释为返回 `true` 的概率，其中 `0` 表示恒为 `false`，`1` 表示恒为 `true`。
+ *
+ * @example
+ * ```
+ * const sample1 = randomBoolean()
+ * // Expect: true
+ * const example1 = typeof sample1 === "boolean"
+ * // Expect: false
+ * const example2 = randomBoolean(0)
+ * // Expect: true
+ * const example3 = randomBoolean(1)
+ * ```
+ */
+export const randomBoolean = (probability: number = internalDefaultRandomBooleanProbability): boolean => {
+  internalAssertRandomBooleanProbability(probability)
+
+  return getRandomUnitValue() < probability
+}