0
# Iteration Module
1

2
Internal iteration system providing type-level arithmetic infrastructure used by the Number module and other utilities requiring iterative operations.
3

4
## Capabilities
5

6
### Core Iteration Type
7

8
The fundamental iteration type used for type-level arithmetic operations.
9

10
```typescript { .api }
11
/**
12
 * Iteration type representing a step in type-level arithmetic
13
 * Tuple format: [value: number, sign: '-'|'0'|'+', prev: IterationKey, next: IterationKey, oppo: IterationKey]
14
 */
15
type Iteration = [number, '-' | '0' | '+', IterationKey, IterationKey, IterationKey];
16

17
/**
18
 * Key type for iteration mapping (supports range -100 to 100)
19
 */
20
type Key = string;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { I } from "ts-toolbelt";
27

28
// Iteration represents a position in arithmetic operations
29
// Internal structure: [current_value, sign, previous_key, next_key, opposite_key]
30

31
// This is typically used internally by Number module operations
32
// Users generally don't interact with Iteration directly
33
```
34

35
### Iteration Conversion
36

37
Convert between numbers and iteration representations.
38

39
```typescript { .api }
40
/**
41
 * Convert number to iteration type for arithmetic operations
42
 * @param N - Number to convert (must be in supported range -100 to 100)
43
 * @returns Iteration representation of the number
44
 */
45
type IterationOf<N extends number> = IterationOfImpl<N>;
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { I, N } from "ts-toolbelt";
52

53
// Convert numbers to iteration form (used internally)
54
type Iter5 = I.IterationOf<5>; // Internal iteration representation of 5
55
type IterNeg3 = I.IterationOf<-3>; // Internal iteration representation of -3
56
type Iter0 = I.IterationOf<0>; // Internal iteration representation of 0
57

58
// This enables the Number module to perform arithmetic
59
type Addition = N.Add<5, 3>; // Uses I.IterationOf<5> and I.IterationOf<3> internally
60
```
61

62
### Iteration Navigation
63

64
Navigate through iterations for sequential operations.
65

66
```typescript { .api }
67
/**
68
 * Get the next iteration in sequence
69
 * @param I - Current iteration
70
 * @returns Next iteration in sequence
71
 */
72
type Next<I extends Iteration> = NextImpl<I>;
73

74
/**
75
 * Get the previous iteration in sequence
76
 * @param I - Current iteration
77
 * @returns Previous iteration in sequence
78
 */
79
type Prev<I extends Iteration> = PrevImpl<I>;
80

81
/**
82
 * Get the position/value from iteration
83
 * @param I - Iteration to extract position from
84
 * @returns Position value as number
85
 */
86
type Pos<I extends Iteration> = PosImpl<I>;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { I } from "ts-toolbelt";
93

94
// These operations work with iteration types internally
95
// Used by Number module for incrementing/decrementing
96

97
// Example conceptual usage (actual types are complex internal structures)
98
type CurrentIter = I.IterationOf<5>;
99
type NextIter = I.Next<CurrentIter>; // Represents iteration for 6
100
type PrevIter = I.Prev<CurrentIter>; // Represents iteration for 4
101

102
type Position = I.Pos<CurrentIter>; // 5
103

104
// Chain operations for multi-step arithmetic
105
type TwoStepsForward = I.Next<I.Next<CurrentIter>>; // Represents iteration for 7
106
type BackAndForth = I.Prev<I.Next<CurrentIter>>; // Back to original (5)
107
```
108

109
### Implementation Details
110

111
The iteration system provides the foundation for type-level arithmetic.
112

113
**Usage Examples:**
114

115
```typescript
116
import { I, N } from "ts-toolbelt";
117

118
// The iteration system enables complex arithmetic operations
119
// All Number module operations use this internally
120

121
// Example: How N.Add<3, 2> works conceptually:
122
// 1. Convert 3 to I.IterationOf<3>
123
// 2. Navigate forward by 2 steps using I.Next
124
// 3. Extract final position using I.Pos
125
// Result: 5
126

127
// Range limitations
128
type MinSupported = I.IterationOf<-100>; // Minimum supported value
129
type MaxSupported = I.IterationOf<100>; // Maximum supported value
130

131
// Out of range numbers cannot be converted
132
// type OutOfRange = I.IterationOf<101>; // Would fail
133
// type TooNegative = I.IterationOf<-101>; // Would fail
134

135
// Practical usage through Number module
136
type Calculation1 = N.Add<10, 5>; // 15 (uses iteration internally)
137
type Calculation2 = N.Sub<20, 8>; // 12 (uses iteration internally)
138
type Comparison = N.Greater<7, 3>; // 1 (uses iteration internally)
139

140
// The iteration system provides:
141
// - Consistent arithmetic operations
142
// - Type-safe range checking
143
// - Sequential navigation
144
// - Bidirectional operations
145

146
// Performance considerations
147
// - Pre-computed lookup tables for efficiency
148
// - Bounded range prevents infinite recursion
149
// - Optimized for common arithmetic patterns
150
```
151

152
### Advanced Patterns
153

154
Complex iteration usage patterns for advanced operations.
155

156
**Usage Examples:**
157

158
```typescript
159
import { I, N, L } from "ts-toolbelt";
160

161
// Using iteration system for custom arithmetic
162
type CustomIncrement<N extends number> = I.Pos<I.Next<I.IterationOf<N>>>;
163
type Result1 = CustomIncrement<5>; // 6
164
type Result2 = CustomIncrement<-10>; // -9
165

166
// Multi-step operations
167
type AddThree<N extends number> = I.Pos<I.Next<I.Next<I.Next<I.IterationOf<N>>>>>;
168
type Result3 = AddThree<7>; // 10
169

170
// Conditional arithmetic using iteration
171
type SafeIncrement<N extends number> = N extends 100 
172
  ? N // At maximum, don't increment
173
  : I.Pos<I.Next<I.IterationOf<N>>>;
174

175
type SafeResult1 = SafeIncrement<99>; // 100
176
type SafeResult2 = SafeIncrement<100>; // 100 (unchanged)
177

178
// Integration with other modules
179
type CountElements<L extends readonly any[]> = L['length'] extends number
180
  ? L['length'] extends infer Len
181
    ? Len extends number
182
      ? Len extends 0
183
        ? 0
184
        : I.Pos<I.IterationOf<Len>>
185
      : never
186
    : never
187
  : never;
188

189
type ElementCount = CountElements<[1, 2, 3, 4, 5]>; // 5
190

191
// Range validation
192
type IsInRange<N extends number> = N extends number
193
  ? N extends -100 | -99 | -98 // ... (would list all valid values)
194
    ? true
195
    : N extends 98 | 99 | 100
196
    ? true  
197
    : false
198
  : false;
199

200
// Arithmetic validation
201
type CanAdd<A extends number, B extends number> = 
202
  N.Add<A, B> extends number ? true : false;
203

204
type ValidAddition = CanAdd<50, 30>; // true (80 is in range)
205
type InvalidAddition = CanAdd<90, 20>; // false (110 exceeds range)
206
```
207

208
## Implementation Notes
209

210
The Iteration module serves as the computational engine for ts-toolbelt's type-level arithmetic:
211

212
- **Range Support**: Operations from -100 to 100 for practical type-level computation
213
- **Tuple Structure**: Each iteration contains value, sign, navigation pointers
214
- **Lookup Tables**: Pre-computed mappings for performance optimization
215
- **Sequential Navigation**: Next/Previous operations for step-by-step arithmetic
216
- **Type Safety**: Bounded operations prevent infinite recursion and stack overflow
217

218
This module is primarily used internally by other modules and is rarely used directly by end users.
219

220
## Types
221

222
```typescript { .api }
223
// Core iteration types
224
type Iteration = [number, '-' | '0' | '+', IterationKey, IterationKey, IterationKey];
225
type Key = string; // Iteration key for mapping
226
type IterationKey = Key; // Alias for clarity
227
```