@planet-matrix/mobius-model 0.3.0 → 0.5.0

package/src/type/README.md

@@ -0,0 +1,330 @@
+# Type
+
+Advanced TypeScript type utilities for string manipulation and type-level gymnastics.
+
+## For Users
+
+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.
+
+### 1. Domain Areas
+
+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.
+
+### 2. Capability Categories
+
+These categories mirror the contributor groupings to keep terminology consistent across docs and source files.
+
+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 a full list of types, see the domain files (String, Number, Function, Object, Path, etc.).
+
+## 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
+
+#### 1.1 Group Structure
+
+Each type utility file should be organized into logical groups using section headers:
+
+```typescript
+// ============================================================================
+// Group Name
+// ============================================================================
+```
+
+**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.
+
+#### 1.2 Grouping Logic and Order
+
+Groups should follow a logical progression from **simple to complex** and **general to specific**:
+
+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
+
+#### 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.

package/src/type/array.ts

@@ -0,0 +1,5 @@
+/**
+ * A type that represents an array with a fixed number of elements of
+ * specific types, followed by any number of additional elements of any type.
+ */
+export type ArrayLoose<T extends unknown[]> = [...T, ...unknown[]]