@planet-matrix/mobius-model 0.5.0 → 0.9.0

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

@@ -0,0 +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

@@ -1,109 +1,79 @@
 # Random
 
-Runtime utilities for generating random-oriented values with cross-runtime compatibility. This module currently focuses on UUID generation.
+## Description
 
-## For Users
+Random 模块用于提供随机值（random value）相关的基础能力，当前主要承载随机布尔值、随机字符串、随机数字与随机整数生成语义。
 
-This module provides lightweight helpers for random value generation scenarios.
+它关注的是“如何生成一类通用、可复用、语义清楚的随机值”，而不是各种标识格式校验、业务编码规则或安全承诺各异的随机机制集合。
 
-### 1. Domain Areas
+## For Understanding
 
-1. UUID: Generate RFC 4122 version-4 UUID strings with runtime-aware fallback behavior.
+理解 Random 模块时，应先把它放在应用边界附近。随机值通常意味着不可复现、带有环境依赖，或者会影响测试与调试行为，因此更合理的做法是把它看作边界输入的生成层，而不是让随机行为无约束地扩散到核心业务逻辑内部。
 
-Current public exports:
+当前这个模块的核心边界比较克制：它主要处理“随机布尔值如何生成”“随机字符串如何生成”“通用随机数字如何生成”与“通用随机整数如何生成”这一类问题。也就是说，它更关心 true 概率、字符集、长度、数值区间、整数边界、结果格式和重复概率，而不再负责 UUID 这类已经具有明确标识语义的格式模型。
 
-- `isUuid(input: string): boolean`
-- `assertUuid(input: string): void`
-- `getUuidVersion(input: string): number`
-- `generateUuid(): string`
+不适合放入本模块的能力，通常包括两类：一类是与密码学安全直接绑定、需要单独安全承诺的能力；另一类是已经形成稳定标识语义的格式模型，例如 UUID。前者应以更明确的安全语义单独建模，后者则应放入更贴近标识问题域的模块。
 
-## For Contributors
+## For Using
 
-This guide documents conventions and best practices for implementing random utilities in this module.
+当你需要在应用或库的边界层生成随机布尔值、临时标识、关联值、会话键或其它非业务主键用途的随机值时，可以使用这个模块。它更适合被理解为“随机值生成接口”，而不是一个什么都往里塞的杂项工具箱。
 
-### 1. Documentation and Comments
+从使用角度看，当前公共能力主要围绕随机布尔值、随机字符串、随机数字与随机整数生成展开。更合适的接入方式，是在边界层尽早生成这些随机值，再把得到的结果作为普通输入传给后续模块，从而避免内部逻辑直接依赖随机过程本身。
 
-#### 1.1 JSDoc Comment Format
+需要特别注意的是，本模块中的“随机”默认应被理解为通用应用层随机，而不是自动带有密码学强度承诺的安全随机。只要调用场景对安全性、可预测性、重复碰撞风险或跨环境一致性有更严格要求，就应先在设计上明确这些前提，而不要仅凭模块名称推断安全等级。
 
-Every exported function should include JSDoc in this form:
+## For Contributing
 
-```typescript
-/**
- * Brief one-line description of what the function does.
- *
- * @example
- * ```
- * const example1 = generateUuid()
- * // Expect: true
- * const example2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(example1)
- * ```
- */
-export const generateUuid = (): string => {
-	...
-}
-```
+贡献 Random 模块时，应先确认新增能力表达的是稳定、清楚且可长期承诺的随机语义，而不是某种实现手段的直接暴露。对外公开的重点应该是“调用方需要什么随机值能力”，而不是“内部恰好如何生成这些值”。只要一个能力过度依赖当前实现细节，或者只在某个很窄的业务上下文中成立，就不适合进入这个模块。
 
-**Documentation Rules:**
-- First line: Clear, concise description starting with a verb (Generate, Check, Convert, etc.)
-- Add a blank line after the description
-- Use `@example` tag followed by triple backticks
-- Include multiple cases showing different scenarios
-- Use comment format: `// Expect: <result>`
-- Assign example results to variables like `example1`, `example2` to keep examples readable
-- Place `@see`(if has) after the `@example` block, separated by a blank line
-- Prefer deterministic examples; avoid asserting exact random outputs
-- If a function returns a structured string, show expected format characteristics
+在扩展时，应特别警惕两个方向的边界漂移。其一，不要把安全领域的问题用模糊措辞塞进来，例如把需要明确密码学承诺的能力混入通用随机工具中。其二，不要把已经形成稳定标识语义的格式模型重新拉回 Random。Random 模块应尽量保持为面向广泛调用方的随机值生成边界，而不是业务专用规则仓库。
 
-### 2. Runtime Implementation Patterns
+### JSDoc 注释格式要求
 
-#### 2.1 Compatibility First
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
 
-- Prefer standard runtime APIs when available (for example, `crypto.randomUUID`).
-- Keep fallback logic for environments where modern APIs are unavailable.
+### 实现规范要求
 
-#### 2.2 Deterministic Interface
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/random/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与随机相关的实现应优先围绕结果格式、边界约束与调用方可理解的失败语义组织，不要把底层算法细节直接提升为公共承诺。
 
-- Public API shape should remain deterministic even if output values are random.
-- Return values should always conform to the documented output format.
+### 导出策略要求
 
-#### 2.3 Helper Placement
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的随机语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
-- Place local helper constants/functions immediately before the utility they support.
-- Prefix non-exported helpers with `internal`.
-- Never export internal helpers.
+### 测试要求
 
-#### 2.4 Spacing
-
-- Separate different utility functions with a single blank line.
-
-### 3. Naming Conventions
-
-#### 3.1 Function Name Format
-
-Use clear operation-oriented names in the `random` domain:
-
-- `isUuid` for UUID format validation checks
-- `assertUuid` for UUID validation that throws on malformed input
-- `getUuidVersion` for extracting UUID version numbers
-- `generateUuid` for UUID creation helpers
-
-Prefer names that clearly indicate output format and intent.
-
-### 4. Export Strategy
-
-- Export all public utilities from domain files.
-- Re-export them through `index.ts`.
-- Do not export internal helpers.
-
-### 5. Common Pitfalls to Avoid
-
-1. Do not assume browser-only APIs are always available.
-2. Do not couple random utilities to a specific runtime unless documented.
-3. Do not assert exact random results in tests.
-4. Do not mutate shared/global state permanently.
-
-### 6. Testing Requirements
-
-- Write one test per function.
-- If multiple cases are needed, include them within the same test.
-- For random outputs, validate shape/constraints instead of exact value.
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./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 "./uuid.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
+}