@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/basic/README.md

@@ -1,144 +1,95 @@
 # Basic
 
-Runtime utilities for JavaScript primitives and built-in objects. This module focuses on safe, predictable helpers and type guards that you can use in everyday code.
+## Description
 
-## For Users
+Basic 模块提供面向 JavaScript 运行时值（runtime value）的通用基础能力，用于围绕基础类型、内建对象、常见容器与轻量流程控制建立稳定、可组合、低假设的公共语义。
 
-This module provides runtime utilities organized by domain so you can quickly locate the right tool for a specific problem.
+它关注的不是某个具体业务领域，而是那些可以长期复用的值级操作：判断、转换、裁剪、组合、格式化、调度、异步组织，以及与少量宿主无关接口的桥接。
 
-### 1. Domain Areas
+## For Understanding
 
-1. Helper: Shared runtime helpers used across other domains.
-2. Is: Runtime predicates and type guards (primitives, objects, iterables, DOM/browser targets, and more).
-3. String: String generation, casing conversion, slicing, splitting, and truncation helpers.
-4. Number: Numeric normalization, range constraint, parity checks, and randomization helpers.
-5. Boolean: Boolean conversion and logical operation helpers.
-6. BigInt: BigInt-oriented helpers.
-7. Symbol: Symbol creation, inspection, and conversion helpers.
-8. Array: Array-oriented helpers and transformations.
-9. Object: Object field selection/exclusion, Date-field timestamp conversion, and object utility helpers.
-10. Function: Function composition and execution-control helpers (once, debounce, throttle, memoize, etc.).
-11. Temporal: Date/time formatting, relative-time, and humanization helpers.
-12. Error: Error detection and exception-stringify helpers.
-13. RegExp: RegExp-based validation helpers.
-14. Promise: Promise control-flow, queueing, retry, interval, and forever-loop helpers.
-15. Stream: ReadableStream construction, consumption, and transform helpers.
-16. Enhance: Runtime enhancement helpers (for example, BigInt JSON serialization support).
+理解 Basic 模块时，首先要把握它的核心边界：这里承载的是“值如何被稳定处理”，而不是“宿主环境如何被接入和驱动”。只要某项能力的主要价值在于处理字符串、数字、布尔值、BigInt、符号（Symbol）、数组、对象、函数、Promise、Error、正则表达式（regular expression）、时间值、流（stream）等运行时值，它通常就有机会属于 Basic。
 
-For a full list of exports, see the domain files (Helper, Is, String, Number, Boolean, BigInt, Symbol, Array, Object, Function, Temporal, Error, RegExp, Promise, Stream, Enhance).
+反过来说，如果某项能力的重点已经变成注册全局监听器、驱动宿主生命周期、读取运行时上下文、感知平台能力，或消费宿主级事件源，那么它通常就不再属于 Basic，即使它最后处理的对象仍然表现为某种值。Basic 关心的是值级语义，而不是环境级语义。
 
-## For Contributors
+这也意味着 Basic 不是“随手工具箱”。一个能力只有在满足以下条件时，才适合进入这个模块：
 
-This guide documents the conventions and best practices for implementing runtime utilities in this module. All implementations should follow these patterns for consistency and maintainability.
+- 它表达的是稳定、清楚、可复用的值级问题域。
+- 它对调用方前提的假设足够少，能在不同项目中长期成立。
+- 它适合通过清楚的输入输出语义被组合，而不是依赖隐式上下文或宿主副作用。
 
-### 1. Documentation and Comments
+## For Using
 
-#### 1.1 JSDoc Comment Format
+当你需要把分散在业务代码中的基础判断、值转换、容器处理和轻量流程控制整理成稳定能力时，可以使用这个模块。它适合放在业务逻辑与语言原生能力之间，作为一层更可复用、也更可测试的基础模型层。
 
-Every exported function should have a JSDoc comment following this structure:
+当前公共能力大致可以按以下几类理解：
 
-```typescript
-/**
- * Brief one-line description of what the function does.
- *
- * @example
- * ```
- * // Expect: true
- * const example1 = isString("hello")
- * // Expect: false
- * const example2 = isString(123)
- * ```
- * 
- * @see {@link https://……}
- */
-export const isString = (value: unknown): value is string => {
-	...
-}
-```
+- 值判断与基础守卫：例如 primitive、对象、数组、空值、数字特征等运行时判断，用于减少重复的分支代码。
+- 基础值处理：例如字符串、数字、布尔值、BigInt、符号等常见值类型的转换、裁剪、计算与格式化。
+- 容器处理：例如数组与对象的筛选、映射、分区、裁剪、合并、字段选择与标准化，适合在进入业务模型前先整理数据形态。
+- 函数与流程控制：例如一次性调用、防抖、节流、组合、管道、记忆化、条件执行等轻量控制能力。
+- 异步与流处理：例如 Promise 队列、重试、轮询、失败结果表达，以及围绕 `ReadableStream` 的基础消费与转换。
+- 时间、错误与正则辅助：例如时间格式化、异常字符串化、常见模式判断等值级辅助能力。
+- 显式增强能力：如果某个能力会对内建对象做增强，它必须保持显式调用、行为可审查，并且不应成为其它公共能力成立的隐含前提。
 
-**Documentation Rules:**
-- First line: Clear, concise description starting with a verb (Check, Get, 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 randomness or time-dependent output in docs
-- If a function returns a non-scalar, show the expected shape or key properties
+如果你的问题已经需要环境感知、平台能力探测、全局异常监听或更明确的领域语义，应优先考虑 Environment、Exception 或其它更贴近问题域的模块，而不是继续把能力堆进 Basic。
 
-### 2. Runtime Implementation Patterns
+## For Contributing
 
-#### 2.1 Prefer Type Predicates
+贡献 Basic 模块时，首要任务不是补齐一个方便函数，而是确认这项能力是否真的表达了稳定的值级语义。这里应长期承载的是对运行时值的清楚建模，而不是对某个调用点临时痛点的修补。
 
-Use type predicates for validation functions to maximize type safety:
+在扩展时，应优先遵守以下模块边界：
 
-```typescript
-export const isDate = (value: unknown): value is Date => {
-	return Object.prototype.toString.call(value) === "[object Date]"
-}
-```
+- 只收纳围绕运行时值本身展开的判断、转换、组合、格式化与轻量流程控制。
+- 不把环境探测、宿主监听、全局状态操纵或平台接入逻辑放入 Basic。
+- 不为了省几行调用代码而公开一次性便捷包装；只有值得长期承诺的公共语义才应进入模块。
+- 如果某项能力依赖显式增强内建对象，必须让增强保持可选，而不是让整个模块隐式建立在原型修改之上。
 
-#### 2.2 Accept `unknown`
+### JSDoc 注释格式要求
 
-Public utilities should accept `unknown` unless there is a strong reason to require a narrower input type.
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
 
-#### 2.3 Avoid Side Effects
+### 实现规范要求
 
-Helpers should be deterministic and should not mutate input values unless explicitly documented.
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/basic/internal.ts`；若当前没有必要，不必为了形式强行拆分。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- Basic 的实现应优先保证输入输出语义直接、低副作用、可组合，而不是追求隐式魔法或宿主绑定行为。
 
-#### 2.4 Helper Placement
+### 导出策略要求
 
-- If a utility function uses helper variables or helper functions, place those helpers immediately before the utility function.
-- Do not add blank lines between a helper and the utility function it supports.
-- Helper variables and functions must be prefixed with `internal`.
-- Helper variables and functions must never be exported.
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的值级语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
-#### 2.5 Spacing
+### 测试要求
 
-- Separate different utility functions with a single blank line.
-
-### 3. Naming Conventions
-
-#### 3.1 Function Name Format
-
-All functions should follow a consistent naming pattern:
-
-**Format:** `<domain><Operation><Qualifier>`
-
-- `is*` for predicates and checks (for example, `isPlainObject`, `isFiniteNumber`)
-- `string*` for string utilities (`stringRandom`, `stringTruncate`)
-- `number*` for number utilities (`numberClamp`, `numberInRange`)
-- `boolean*`, `date*`, `regexp*`, `error*`, `symbol*`, `bigint*` for other domains
-
-#### 3.2 Common Verb Prefixes
-
-- `is*` - Returns boolean for validation
-- `has*` - Returns boolean for existence checks
-- `get*` / `extract*` - Returns a value
-- `to*` - Conversion operations
-
-### 4. Export Strategy
-
-```typescript
-// Always export public functions
-export const publicFunction = () => {}
-
-// Never export internal helpers
-const internalHelper = () => {}
-```
-
-Keep domain exports in their files and re-export them via the barrel in `index.ts`.
-
-### 5. Common Pitfalls to Avoid
-
-1. Do not rely on `typeof` alone for objects (for example, `typeof null === "object"`).
-2. Do not confuse `NaN` with numbers that cannot be parsed.
-3. Do not treat boxed objects (`new String("x")`) as primitives without checks.
-4. Do not mutate inputs unless the function name and docs make it explicit.
-5. Do not introduce locale-dependent behavior without documenting it.
-
-### 6. Testing Requirements
-
-- Write one test per function.
-- If multiple cases are needed, include them within the same test.
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/basic`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/basic/<sub-module-name>`。
+- 对带有时间、随机、异步调度或流消费语义的能力，应显式控制前提，避免把不稳定行为写成稳定断言。

package/src/basic/function.ts

@@ -26,23 +26,28 @@ export const functionIife = <T extends AnyFunction>(
   return fn(...args)
 }
 
+/**
+ * 表示只会保留首次执行结果的一次性函数。
+ */
 export type FunctionOnce<T extends AnyFunction> =
   (...args: Parameters<T>) => ReturnType<T>
 /**
- * Generate a one-off function for a given function.
+ * 生成一个只在首次调用时真正执行的函数。
  *
  * @example
  * ```
- * const onceFn = functionOnce((x) => x * 2)
- * // Will return 10
- * const result1 = onceFn(5)
- * // Will still return 10, original function will not be called again
- * const result2 = onceFn(10)
- * // If timesSubscriber is provided, it will be called with the number of calls after the second call
+ * const exampleFn1 = functionOnce((x: number) => x * 2)
+ * // Expect: 10
+ * const example1 = exampleFn1(5)
+ * // Expect: 10
+ * const example2 = exampleFn1(10)
+ *
  * let callCount = 0
- * const onceFnWithSubscriber = functionOnce((x) => x * 2, (times) => { callCount = times })
- * onceFnWithSubscriber(5) // callCount is still 0
- * onceFnWithSubscriber(10) // callCount becomes 2
+ * const exampleFn2 = functionOnce((x: number) => x * 2, (times) => { callCount = times })
+ * exampleFn2(5)
+ * exampleFn2(10)
+ * // Expect: 2
+ * const example3 = callCount
  * ```
  */
 export const functionOnce = <T extends AnyFunction>(
@@ -67,20 +72,23 @@ export const functionOnce = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示简单防抖后的函数类型。
+ */
 export type FunctionDebouncedSimple<T extends AnyFunction> =
   (...args: Parameters<T>) => void
+
 /**
- * Generate a simple debounced function that delays invoking
- * the original function until after a specified wait time
- * has elapsed since the last time the debounced function was called.
+ * 生成一个简单防抖函数，在最后一次调用后的指定时间再触发原函数。
  *
  * @example
  * ```
- * const debouncedFn = functionDebounceSimple((x) => console.log(x), 100)
- * // Will log 5 after 100ms
- * debouncedFn(5)
- * // Will not log anything, will reset the timer
- * debouncedFn(10)
+ * const records: number[] = []
+ * const exampleFn1 = functionDebounceSimple((x: number) => { records.push(x) }, 10)
+ * exampleFn1(5)
+ * exampleFn1(10)
+ * // Expect: records.length === 0
+ * const example1 = records.length === 0
  * ```
  */
 export const functionDebounceSimple = <T extends AnyFunction>(
@@ -96,22 +104,23 @@ export const functionDebounceSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示返回 `Promise` 的防抖函数类型。
+ */
 export type FunctionDebounced<T extends AnyFunction>
   = (...args: Parameters<T>) => Promise<ReturnType<T>>
 /**
- * Generate a debounced function that returns a promise resolving
- * to the result of the original function. If the debounced function is called
- * multiple times within the debounce period, it will only execute the original
- * function once, and all calls will receive the same result.
+ * 生成一个返回 `Promise` 的防抖函数，并在防抖窗口内合并并发调用。
  *
  * @example
  * ```
- * const debouncedFn = debounce(async (x) => x * 2, 100)
- * // Will execute the original function after 100ms
- * const result1 = debouncedFn(5)
- * // Will not execute the original function, will receive the same result as result1
- * const result2 = debouncedFn(10)
- * // After 100ms, both result1 and result2 will resolve to 10
+ * const exampleFn1 = debounce(async (x: number) => x * 2, 10)
+ * const example1 = exampleFn1(5)
+ * const example2 = exampleFn1(10)
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const debounce = <T extends AnyFunction>(
@@ -139,25 +148,23 @@ export const debounce = <T extends AnyFunction>(
 }
 
 const THROTTLE_TYPE_ERROR = new TypeError("Throttle: fn must be a SyncFunction or AsyncFunction")
+/**
+ * 表示基于时间窗口的简单节流函数类型。
+ */
 export type FunctionThrottleTimeSimple<T extends AnyFunction> =
   (...args: Parameters<T>) => void
 /**
- * Generate a simple throttled function that only invokes the original function at most
- * once per every specified milliseconds. The throttled function will execute the original
- * function immediately on the first call, and then ignore subsequent calls until the
- * specified time has elapsed.
+ * 生成一个简单时间节流函数，在指定时间窗口内最多执行一次原函数。
  *
- * If `strict` is set to true, the throttled function will ensure that the window of time
- * during which the original function can be invoked is greater than the sum of the
- * specified milliseconds and the execution time of the original function.
+ * 当 `strict` 为 `true` 时，节流窗口会同时考虑等待时长与目标函数执行时长。
  *
  * @example
  * ```
  * let called = 0
- * const throttled = functionThrottleTimeSimple(() => { called += 1 }, 100)
- * throttled()
- * throttled()
- * // Expect: called === 1
+ * const exampleFn1 = functionThrottleTimeSimple(() => { called += 1 }, 100)
+ * exampleFn1()
+ * exampleFn1()
+ * // Expect: 1
  * const example1 = called
  * ```
  */
@@ -212,19 +219,21 @@ export const functionThrottleTimeSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示执行期间丢弃重复调用的简单节流函数类型。
+ */
 export type FunctionThrottleSimple<T extends AnyFunction> =
   (...args: Parameters<T>) => void
 /**
- * Generate a throttled function that only invokes the original function
- * when it is not currently executing.
+ * 生成一个在执行期间忽略重复调用的节流函数。
  *
  * @example
  * ```
  * let called = 0
- * const throttled = functionThrottleSimple(() => { called += 1 })
- * throttled()
- * throttled()
- * // Expect: called === 1
+ * const exampleFn1 = functionThrottleSimple(() => { called += 1 })
+ * exampleFn1()
+ * exampleFn1()
+ * // Expect: 1
  * const example1 = called
  * ```
  */
@@ -256,23 +265,25 @@ export const functionThrottleSimple = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示返回 `Promise` 的时间节流函数类型。
+ */
 export type FunctionThrottleTime<T extends AnyFunction> =
   (...args: Parameters<T>) => Promise<ReturnType<T>>
 /**
- * Generate a throttled function that returns a promise resolving to the result
- * of the original function. The throttled function will ensure that the original
- * function is invoked at most once per every specified milliseconds.
+ * 生成一个返回 `Promise` 的时间节流函数。
  *
- * If `strict` is set to true, the window of time during which the original function
- * can be invoked will be greater than the sum of the specified milliseconds and
- * the execution time of the original function.
+ * 当 `strict` 为 `true` 时，节流窗口会同时考虑等待时长与目标函数执行时长。
  *
  * @example
  * ```
- * const throttled = throttleTime(async (value: number) => value * 2, 100)
- * const result1 = throttled(2)
- * const result2 = throttled(3)
- * // Expect: result1 and result2 resolve to 4
+ * const exampleFn1 = throttleTime(async (value: number) => value * 2, 100)
+ * const example1 = exampleFn1(2)
+ * const example2 = exampleFn1(3)
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const throttleTime = <T extends AnyFunction>(
@@ -323,18 +334,23 @@ export const throttleTime = <T extends AnyFunction>(
   }
 }
 
+/**
+ * 表示合并并发调用的节流函数类型。
+ */
 export type FunctionThrottle<T extends AnyFunction> =
   (...args: Parameters<T>) => Promise<ReturnType<T>>
 /**
- * Generate a throttled function that returns a promise resolving to the result
- * of the original function and coalesces concurrent calls.
+ * 生成一个返回 `Promise` 的节流函数，并合并并发调用。
  *
  * @example
  * ```
- * const throttled = functionThrottle(async () => "ok")
- * const result1 = throttled()
- * const result2 = throttled()
- * // Expect: result1 and result2 resolve to "ok"
+ * const exampleFn1 = functionThrottle(async () => "ok")
+ * const example1 = exampleFn1()
+ * const example2 = exampleFn1()
+ * // Expect: example1 instanceof Promise
+ * const example3 = example1 instanceof Promise
+ * // Expect: example2 instanceof Promise
+ * const example4 = example2 instanceof Promise
  * ```
  */
 export const functionThrottle = <T extends AnyFunction>(
@@ -409,6 +425,9 @@ export const functionPipe = <Fns extends AnyFunction[]>(
   return functionCompose(...fns.toReversed()) as FunctionPipeAll<Fns>
 }
 
+/**
+ * 表示带参数缓存能力的记忆化函数类型。
+ */
 export type FunctionMemorized<T extends AnyFunction> =
   (...args: Parameters<T>) => ReturnType<T>
 // oxlint-disable-next-line no-explicit-any
@@ -434,7 +453,7 @@ const defaultMemorizeHasher = (...args: any[]): string => JSON.stringify(args)
  */
 export const functionMemorize = <T extends AnyFunction>(
   fn: T,
-  hashFunction?: (...args: Parameters<T>) => unknown
+  hashFunction?: (...args: Parameters<T>) => unknown | undefined
 ): FunctionMemorized<T> => {
   const cache = new Map()
   const hasher = hashFunction ?? defaultMemorizeHasher