@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/type/README.md

@@ -1,330 +1,77 @@
 # Type
 
-Advanced TypeScript type utilities for string manipulation and type-level gymnastics.
+## Description
 
-## For Users
+Type 模块用于提供面向 TypeScript 类型系统（type system）的通用类型建模能力，主要承载类型判断、类型组合、类型转换以及类型结构重塑等公共语义。
 
-This module provides TypeScript type utilities that cover common type-level programming tasks. It is organized by domain and by capability so you can quickly locate the right tool for a specific problem.
+它并不是为了堆叠炫技式的类型体操，而是为了沉淀一组能够长期复用、命名稳定、语义清楚的类型层工具。这个模块关注的是“哪些静态约束值得被抽象为基础模型”，而不是让局部实现里的技巧性写法直接变成公共 API。
 
-### 1. Domain Areas
+## For Understanding
 
-1. Helper: Shared internal building blocks used across domains.
-2. Is: Generic predicates and basic type guards at the type level.
-3. Union: Utilities for building, filtering, and comparing union types.
-4. Intersection: Utilities for composing and analyzing intersection types.
-5. String: Validation, comparison, queries, slicing, and transformation for string literal types.
-6. Path: Parsing and access helpers for dot-path strings and object path navigation.
-7. Boolean: Logical composition and boolean collection helpers.
-8. Number: Numeric checks, comparisons, arithmetic, and range construction for number literal types.
-9. Object: Key/value queries, structural reshaping, and property-level composition.
-10. Function: Parameter and return extraction, comparisons, and function-shape transformations.
-11. Tuple: Tuple length, element access, mapping, and composition utilities.
-12. Class: Constructor and instance shape helpers for class-based typing.
-13. Iteration: Iterative helpers for building or traversing type-level sequences.
+理解 Type 模块时，应先区分它与运行时工具模块的职责差异。这里解决的问题发生在编译阶段：如何表达约束、如何描述结构关系、如何在类型层提前暴露不合法的使用方式、以及如何把一组复杂条件压缩成更稳定的公共类型语义。
 
-### 2. Capability Categories
+因此，这个模块适合放在公共 API 设计、库封装、复杂配置建模、框架适配和类型推导增强等边界中。只要某个问题的核心是“能否在编译阶段更早发现错误”或“能否把约束用类型表达而不是运行时代码表达”，Type 模块通常就比继续增加运行时判断更合适。
 
-These categories mirror the contributor groupings to keep terminology consistent across docs and source files.
+也正因为如此，本模块的边界不应被理解为“所有和 TypeScript 有关的东西”。仅当一个能力表达的是稳定、可复用的类型语义时，它才适合进入这里。某个局部实现专用的类型补丁、只为绕过编译器局限而存在的临时技巧、或者过度依赖当前文件上下文的辅助类型，都不应轻易加入公共导出。
 
-1. Helpers: Internal building blocks used by other types.
-2. Primitives: Core domain-specific primitives and base helpers.
-3. Validation: Presence checks, format checks, and equality checks.
-4. Comparison: Ordering, equality, and compatibility checks.
-5. Query: Length, count, index, and metadata queries.
-6. Generation: Creating new literal values, ranges, or repeated structures.
-7. Extraction: Pulling out segments, first/last elements, or subsets.
-8. Manipulation: Replacing, concatenating, mapping, and transforming shapes.
-9. Conversion: Converting between string/number/boolean or related domains.
+## For Using
 
-For a full list of types, see the domain files (String, Number, Function, Object, Path, etc.).
+当你需要在静态层面表达类型关系，而不是在运行时反复写守卫与转换逻辑时，可以使用这个模块。它适合那些需要提高公共 API 可读性、约束复杂输入结构、维护类型推导结果稳定性、或在库层提供更强静态保证的场景。
 
-## For Contributors
+从使用角度看，这个模块大致可以分为几类能力。第一类是基础判断与辅助能力，用于表达原始类型、对象、数组、函数、类等常见结构的静态条件。第二类是关系与运算能力，用于处理联合、交叉、字面量、路径等类型之间的组合与转换。第三类是结构重塑能力，用于在对象、数组、元组、函数签名等结构之间做映射、拆分、约束和重组。
 
-This guide documents the conventions and best practices for implementing type utilities in this module. All implementations should follow these patterns for consistency and maintainability.
+更合理的使用方式，是先从你要表达的语义出发，再选取最接近该语义的类型工具，而不是把它们当作纯技巧库随意拼接。只要类型声明开始主要服务于“让编译器刚好不报错”，而不是帮助调用方理解边界，那通常意味着抽象方向已经偏离了这个模块的目标。
 
-### 1. File Organization and Grouping
+## For Contributing
 
-#### 1.1 Group Structure
+贡献 Type 模块时，应先回答两个问题：新增能力解决的是不是一个可长期复用的类型建模问题，以及它是否能以清楚、稳定、可读的形式向外承诺。只有在这两个问题的答案都足够明确时，一个新类型才值得被公开导出。
 
-Each type utility file should be organized into logical groups using section headers:
+在实现层面，应优先保证语义清晰和调用方面向的可读性，再考虑技巧性。复杂递归、分布式条件类型、累加器模式或品牌类型等写法本身并不构成价值；真正的价值在于它们是否帮助调用方稳定地理解某个约束。若一个类型只是在内部为另一个公开类型服务，就应优先把它保留为内部辅助项，而不是公开成新的通用工具。
 
-```typescript
-// ============================================================================
-// Group Name
-// ============================================================================
-```
+### JSDoc 注释格式要求
 
-**Group Header Rules:**
-- Use exactly 76 equal signs (to reach column 80).
-- Group name should be descriptive and use Title Case.
-- Add one blank line before the header block and one blank line after.
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
 
-#### 1.2 Grouping Logic and Order
+### 实现规范要求
 
-Groups should follow a logical progression from **simple to complex** and **general to specific**:
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/type/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 对复杂条件类型、递归类型、累加器模式或分布式条件类型，应优先让公开 API 保持最小、清晰、稳定的参数面，而不要把内部技巧直接暴露给调用方。
 
-1. Helpers: Common helper types within the module, such as `KeyOfBase`, `Cast`, `If`, `Try`, `IsEqual` in `Helper`, and internal helpers like `InternalBuildArray` in `Number`.
-2. Primitives: Types closely related to the module's core types, such as `NumberSign` and `NumberDigitCount` in `Number`, `StringAutoCompletable`, `UppercaseLetter`, `LowercaseLetter`, `DigitCharacter` in `String`, `FunctionNoop`, `FunctionIdentity`, `FunctionConstant` in `Function`, and `TupleEmpty`, `TupleSingleton` in `Tuple`.
-3. Validation: Types for validation or checking, such as `StringIsNumber`, `StringIsAlpha`, `StringIsEmpty`, `StringIsUpperCase` in `String`, `NumberIsZero`, `NumberIsPositive`, `NumberIsNegative`, `NumberIsEven` in `Number`, `FunctionIsAsync` in `Function`, `ClassIsConstructor` in `Class`.
-4. Comparison: Types for comparing values, such as `StringIsEqual`, `StringStartsWith`, `StringEndsWith` in `String`, `NumberIsEqual`, `NumberGreaterThan`, `NumberLessThan` in `Number`, `FunctionParametersEqual` in `Function`, `TupleIsEqual`, `TupleStartsWith`, `TupleEndsWith` in `Tuple`.
-5. Query: Types for querying information without transformation, such as `StringLength`, `StringCount`, `StringIndexOf` in `String`, `FunctionLength`, `FunctionArity` in `Function`, `TupleLength`, `TupleIndexOf` in `Tuple`, and `ClassConstructorArity` in `Class`.
-6. Generation: Types for creating new values from scratch, such as `StringRepeat` in `String`, `TupleRepeat`, `TupleRange`, `TupleCombinations` in `Tuple`.
-7. Extraction: Types for extracting partial content, such as `StringFirst`, `StringLast`, `StringAt` in `String`, `TupleHead`, `TupleTail`, `TupleAt` in `Tuple`.
-8. Manipulation: Types for modifying values, such as `StringTakeFirst`, `StringReplaceAll`, `StringTrim`, `StringSplit`, `StringJoin` in `String`, `NumberAdd`, `NumberSubtract`, `NumberMultiply` in `Number`, `FunctionBind`, `FunctionInsertParameter`, `FunctionRemoveParameter` in `Function`, `ObjectMerge`, `ObjectAssign`, `ObjectOverwrite` in `Object`, and `TupleMap`, `TupleFilter`, `TupleAppend` in `Tuple`.
-9. Conversion: Types for converting between different domains, such as `NumberToString`, `NumberToBoolean` in `Number`, `BooleanToNumber`, `BooleanToString` in `Boolean`, `TupleToUnion`, `TupleToObject`, `TupleToArray`, `TupleToString` in `Tuple`, `UnionToIntersection`, `UnionToTuple` in `Union`, `ObjectToFunction` in `Object`, and `ClassConstructorToFunction` or `FunctionToClassConstructor` in `Class`/`Function`.
+### 导出策略要求
 
-### 2. Documentation and Comments
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的类型语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
-#### 2.1 JSDoc Comment Format
+### 测试要求
 
-Every exported type must have a JSDoc comment following this structure:
-
-```typescript
-/**
- * Brief one-line description of what the type does.
- *
- * @example
- * ```
- * // Expect: <expected result>
- * type Example1 = TypeName<...>
- * // Expect: <expected result>
- * type Example2 = TypeName<...>
- * ```
- */
-export type TypeName<...> = ...
-```
-
-**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 example cases showing different scenarios
-- Use comment format: `// Expect: <result>`
-- Use descriptive example names: `Example1`, `Example2`, `Example3`, etc.
-- Include edge cases (empty values, single elements, etc.)
-
-#### 2.2 Example Writing Guidelines
-
-**Good Examples:**
-```typescript
-/**
- * Check if a string starts with a prefix.
- *
- * @example
- * ```
- * // Expect: true
- * type Example1 = StringStartsWith<'hello world', 'hello'>
- * // Expect: false
- * type Example2 = StringStartsWith<'hello world', 'world'>
- * // Expect: true
- * type Example3 = StringStartsWith<'', ''>
- * ```
- */
-```
-
-**Coverage Priority:**
-1. Typical use case (most common scenario)
-2. Edge cases (empty, single element, boundary conditions)
-3. Negative cases (when the operation fails or returns false)
-4. Complex cases (if applicable)
-
-### 3. Type Implementation Patterns
-
-#### 3.1 Internal Helper Types
-
-When a type requires a complex implementation with accumulator parameters or intermediate state, use an `Internal`-prefixed helper type:
-
-```typescript
-// Internal helper type - not exported
-type InternalStringLength<S extends string, Acc extends readonly unknown[]> = 
-  S extends `${string}${infer Rest}`
-    ? InternalStringLength<Rest, [...Acc, unknown]>
-    : Acc['length']
-
-/**
- * Get the length of a string literal type.
- *
- * @example
- * ```
- * // Expect: 5
- * type Example1 = StringLength<'hello'>
- * ```
- */
-export type StringLength<S extends string> = InternalStringLength<S, []>
-```
-
-**Internal Type Rules:**
-- Prefix with `Internal`
-- Do NOT export
-- Define immediately before the public type that uses it
-- NO blank line between the internal helper and the public type
-- Include all implementation details (accumulators, counters, flags)
-- The public API should hide complexity and provide clean, minimal parameters
-
-#### 3.2 Recursive Patterns
-
-Most type gymnastics use recursion. Common patterns:
-
-**Pattern 1: Tail Recursion with Accumulator**
-```typescript
-type InternalReverse<S extends string, Acc extends string = ''> =
-  S extends `${infer First}${infer Rest}`
-  ? InternalReverse<Rest, `${First}${Acc}`>
-  : Acc
-```
-
-**Pattern 2: Array/Tuple Length as Counter**
-```typescript
-type InternalRepeat<
-  S extends string,
-  N extends number,
-  Acc extends string,
-  Count extends readonly unknown[]
-> = Count['length'] extends N 
-  ? Acc 
-  : InternalRepeat<S, N, `${Acc}${S}`, [...Count, unknown]>
-```
-
-**Pattern 3: Distributed Conditional Types**
-```typescript
-type StringSplit<S extends string, Separator extends string> = 
-  S extends `${infer First}${Separator}${infer Rest}`
-  ? [First, ...StringSplit<Rest, Separator>]
-  : (S extends '' ? [] : [S])
-```
-
-**Pattern 4: Type Narrowing with Extends**
-```typescript
-export type BooleanAnd<T extends boolean, U extends boolean> = 
-  T extends true 
-    ? (U extends true ? true : false)
-    : false
-```
-
-**Ternary Formatting Rules:**
-
-When working with nested conditional types (ternary operations):
-
-1. **Single-level ternary**: Can be written inline if simple and readable
-   ```typescript
-   type Simple<T> = T extends string ? true : false
-   ```
-
-2. **Two or more levels of nesting**: **MUST** wrap the second level and beyond in parentheses
-   ```typescript
-   // ✅ Correct - nested ternary wrapped in parentheses
-   type Nested<T> = 
-     T extends string
-       ? (T extends '' ? 'empty' : 'non-empty')
-       : false
-   
-   // ❌ Wrong - missing parentheses on nested ternary
-   type Wrong<T> = 
-     T extends string
-       ? T extends '' ? 'empty' : 'non-empty'
-       : false
-   ```
-
-3. **Line breaks**: If the nested ternary can fit on one line and remain readable, keep it on one line. Only break into multiple lines when it improves clarity for complex expressions.
-
-4. **Readability**: If a ternary becomes too complex (3+ levels), consider extracting to helper types
-
-This ensures code clarity and makes the nesting structure immediately visible.
-
-#### 3.3 Parameter Constraints
-
-Always use proper constraints for type parameters:
-
-```typescript
-// String operations
-export type StringReverse<S extends string> = ...
-
-// Boolean operations
-export type BooleanAnd<T extends boolean, U extends boolean> = ...
-
-// Array/Tuple operations
-export type BooleanAll<T extends readonly boolean[]> = ...
-
-// Number constraints
-export type StringRepeat<S extends string, N extends number> = ...
-```
-
-**Key Points:**
-- Use `extends string`, `extends boolean`, `extends number` for primitive types
-- Use `extends readonly T[]` for immutable arrays/tuples
-- Use `extends unknown` for generic or any type parameters
-- Add default values when appropriate (e.g., `First extends boolean = true`)
-
-### 4. Naming Conventions
-
-#### 4.1 Type Name Format
-
-All types should follow a consistent naming pattern:
-
-**Format:** `<Domain><Operation><Qualifier>`
-
-- **Domain:** `String`, `Boolean`, `Number`, `Array`, `Object`, `Path`, etc.
-- **Operation:** Verb describing the action (Check, Get, Convert, Split, etc.)
-- **Qualifier:** Optional descriptor (First, Last, All, etc.)
-
-**Examples:**
-- `StringSplitToWords` - domain: String, operation: Split, qualifier: ToWords
-- `BooleanCountTrue` - domain: Boolean, operation: Count, qualifier: True
-- `StringIsEmpty` - domain: String, operation: Is, qualifier: Empty
-
-#### 4.2 Common Verb Prefixes
-
-- `Is*` - Returns boolean for validation or checking
-  - Examples: `IsEmpty`, `IsNumber`, `IsAlpha`, `IsEqual`
-- `Has*` - Returns boolean for existence checking
-  - Examples: `HasPrefix`, `HasSuffix`
-- `Get*` / `Extract*` - Returns a value
-  - Examples: `GetFirst`, `ExtractGroups`
-- `String*` / `Boolean*` / etc. - Domain-scoped operations
-  - Examples: `StringReverse`, `BooleanAnd`, `PathJoin`
-- `To*` - Conversion operations
-  - Examples: `ToString`, `ToNumber`, `ToBoolean`
-
-#### 4.3 Alias Types
-
-Provide intuitive aliases when appropriate:
-
-```typescript
-export type BooleanAll<T extends readonly boolean[]> = ...
-export type BooleanEvery<T extends readonly boolean[]> = BooleanAll<T>
-
-export type BooleanAny<T extends readonly boolean[]> = ...
-export type BooleanSome<T extends readonly boolean[]> = BooleanAny<T>
-```
-
-### 5. Export Strategy
-
-```typescript
-// Always export public types
-export type PublicType<T> = ...
-
-// Never export internal helpers
-type InternalHelper<T, Acc> = ...
-
-// Export commonly used aliases
-export type Alias<T> = PublicType<T>
-```
-
-### 6. Common Pitfalls to Avoid
-
-1. ❌ **Don't expose implementation details** in public APIs
-2. ❌ **Don't use ambiguous names** (prefer `StringLength` over `Length`)
-3. ❌ **Don't skip documentation** - every export needs JSDoc comments
-4. ❌ **Don't forget edge cases** in examples
-5. ❌ **Don't create circular dependencies** between types
-6. ❌ **Don't over-optimize** at the cost of readability
-7. ❌ **Don't use overly generic names** that might cause conflicts
-
-## Thanks
-
-This module is inspired by and borrows ideas from the following projects:
-
-- [ts-toolbelt](https://github.com/millsp/ts-toolbelt): 👷 TypeScript's largest type utility library.
-- [type-fest](https://github.com/sindresorhus/type-fest): A collection of essential TypeScript types.
-- [ts-essentials](https://github.com/ts-essentials/ts-essentials): All essential TypeScript types in one place 🤙
-- [type-challenges](https://github.com/type-challenges/type-challenges): Collection of TypeScript type challenges with online judge.
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 此模块暂时不需要任何测试，类型系统的测试通常需要特定的工具链支持，开发和维护成本较高，因此在没有明确需求的情况下，先保持模块的纯粹封装性质也是合理的。
+- 模块的单元测试文件目录是 `./tests/unit/type`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/type/<sub-module-name>`。

package/src/type/class.ts

@@ -15,7 +15,7 @@
  * type Example2 = ClassConstructor<Date>
  * ```
  */
-export type ClassConstructor<Instance = unknown, Args extends readonly unknown[] = []> =
+export type ClassConstructor<Instance = unknown, Args extends any[] = any[]> =
   new (...args: Args) => Instance
 
 /**
@@ -28,7 +28,7 @@ export type ClassConstructor<Instance = unknown, Args extends readonly unknown[]
  * type Example1 = ClassAbstractConstructor<Base>
  * ```
  */
-export type ClassAbstractConstructor<Instance = unknown, Args extends readonly unknown[] = []> =
+export type ClassAbstractConstructor<Instance = unknown, Args extends any[] = any[]> =
   abstract new (...args: Args) => Instance
 
 /**

package/src/type/index.ts

@@ -1,14 +1,14 @@
-export * from "./helper.ts"
-export * from "./is.ts"
-export * from "./union.ts"
-export * from "./intersection.ts"
-export * from "./string.ts"
-export * from "./path.ts"
-export * from "./boolean.ts"
-export * from "./number.ts"
-export * from "./object.ts"
-export * from "./function.ts"
-export * from "./tuple.ts"
-export * from "./array.ts"
-export * from "./class.ts"
-export * from "./iteration.ts"
+export type * from "./helper.ts"
+export type * from "./is.ts"
+export type * from "./union.ts"
+export type * from "./intersection.ts"
+export type * from "./string.ts"
+export type * from "./path.ts"
+export type * from "./boolean.ts"
+export type * from "./number.ts"
+export type * from "./object.ts"
+export type * from "./function.ts"
+export type * from "./tuple.ts"
+export type * from "./array.ts"
+export type * from "./class.ts"
+export type * from "./iteration.ts"