0
# Number Module
1

2
Type-level arithmetic operations using an internal iteration system supporting mathematical operations from -100 to 100 with full type safety.
3

4
## Capabilities
5

6
### Basic Arithmetic
7

8
Core mathematical operations implemented at the type level.
9

10
```typescript { .api }
11
/**
12
 * Add two numbers at type level
13
 * @param N1 - First number to add
14
 * @param N2 - Second number to add
15
 * @returns Sum of N1 and N2
16
 */
17
type Add<N1 extends number, N2 extends number> = AddImpl<N1, N2>;
18

19
/**
20
 * Subtract second number from first at type level
21
 * @param N1 - Number to subtract from
22
 * @param N2 - Number to subtract
23
 * @returns Difference of N1 minus N2
24
 */
25
type Sub<N1 extends number, N2 extends number> = SubImpl<N1, N2>;
26

27
/**
28
 * Get absolute value of number
29
 * @param N - Number to get absolute value of
30
 * @returns Absolute value of N
31
 */
32
type Absolute<N extends number> = AbsoluteImpl<N>;
33

34
/**
35
 * Negate a number (multiply by -1)
36
 * @param N - Number to negate
37
 * @returns Negated value of N
38
 */
39
type Negate<N extends number> = NegateImpl<N>;
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { N } from "ts-toolbelt";
46

47
// Basic arithmetic
48
type Sum = N.Add<5, 3>; // 8
49
type Difference = N.Sub<10, 4>; // 6
50
type AbsValue = N.Absolute<-15>; // 15
51
type Negated = N.Negate<7>; // -7
52

53
// With negative numbers
54
type NegativeSum = N.Add<-5, 3>; // -2
55
type NegativeDiff = N.Sub<-10, -4>; // -6
56

57
// Edge cases
58
type Zero = N.Add<0, 0>; // 0
59
type Identity = N.Sub<42, 0>; // 42
60
type AbsOfZero = N.Absolute<0>; // 0
61
```
62

63
### Comparison Operations
64

65
Compare numbers and determine relationships between them.
66

67
```typescript { .api }
68
/**
69
 * Check if first number is greater than second
70
 * @param N1 - First number to compare
71
 * @param N2 - Second number to compare
72
 * @returns 1 if N1 > N2, 0 otherwise
73
 */
74
type Greater<N1 extends number, N2 extends number> = GreaterImpl<N1, N2>;
75

76
/**
77
 * Check if first number is greater than or equal to second
78
 * @param N1 - First number to compare
79
 * @param N2 - Second number to compare
80
 * @returns 1 if N1 >= N2, 0 otherwise
81
 */
82
type GreaterEq<N1 extends number, N2 extends number> = GreaterEqImpl<N1, N2>;
83

84
/**
85
 * Check if first number is lower than second
86
 * @param N1 - First number to compare
87
 * @param N2 - Second number to compare
88
 * @returns 1 if N1 < N2, 0 otherwise
89
 */
90
type Lower<N1 extends number, N2 extends number> = LowerImpl<N1, N2>;
91

92
/**
93
 * Check if first number is lower than or equal to second
94
 * @param N1 - First number to compare
95
 * @param N2 - Second number to compare
96
 * @returns 1 if N1 <= N2, 0 otherwise
97
 */
98
type LowerEq<N1 extends number, N2 extends number> = LowerEqImpl<N1, N2>;
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { N } from "ts-toolbelt";
105

106
// Greater than comparisons
107
type IsGreater1 = N.Greater<10, 5>; // 1
108
type IsGreater2 = N.Greater<3, 8>; // 0
109
type IsGreater3 = N.Greater<5, 5>; // 0
110

111
// Greater than or equal
112
type IsGreaterEq1 = N.GreaterEq<10, 5>; // 1
113
type IsGreaterEq2 = N.GreaterEq<5, 5>; // 1
114
type IsGreaterEq3 = N.GreaterEq<3, 8>; // 0
115

116
// Less than comparisons
117
type IsLower1 = N.Lower<3, 8>; // 1
118
type IsLower2 = N.Lower<10, 5>; // 0
119
type IsLower3 = N.Lower<5, 5>; // 0
120

121
// Less than or equal
122
type IsLowerEq1 = N.LowerEq<3, 8>; // 1
123
type IsLowerEq2 = N.LowerEq<5, 5>; // 1
124
type IsLowerEq3 = N.LowerEq<10, 5>; // 0
125

126
// With negative numbers
127
type NegComparison1 = N.Greater<-5, -10>; // 1 (true, -5 > -10)
128
type NegComparison2 = N.Lower<-2, 3>; // 1 (true, -2 < 3)
129
```
130

131
### Number Classification
132

133
Utility operations to classify and check properties of numbers.
134

135
```typescript { .api }
136
/**
137
 * Check if number is zero
138
 * @param N - Number to check
139
 * @returns 1 if N is 0, 0 otherwise
140
 */
141
type IsZero<N extends number> = N extends 0 ? 1 : 0;
142

143
/**
144
 * Check if number is positive (greater than zero)
145
 * @param N - Number to check
146
 * @returns 1 if N > 0, 0 otherwise
147
 */
148
type IsPositive<N extends number> = IsPositiveImpl<N>;
149

150
/**
151
 * Check if number is negative (less than zero)
152
 * @param N - Number to check
153
 * @returns 1 if N < 0, 0 otherwise
154
 */
155
type IsNegative<N extends number> = IsNegativeImpl<N>;
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
import { N } from "ts-toolbelt";
162

163
// Zero checking
164
type CheckZero1 = N.IsZero<0>; // 1
165
type CheckZero2 = N.IsZero<5>; // 0
166
type CheckZero3 = N.IsZero<-3>; // 0
167

168
// Positive checking
169
type CheckPos1 = N.IsPositive<10>; // 1
170
type CheckPos2 = N.IsPositive<0>; // 0
171
type CheckPos3 = N.IsPositive<-5>; // 0
172

173
// Negative checking
174
type CheckNeg1 = N.IsNegative<-10>; // 1
175
type CheckNeg2 = N.IsNegative<0>; // 0
176
type CheckNeg3 = N.IsNegative<5>; // 0
177
```
178

179
### Range Operations
180

181
Generate ranges and sequences of numbers.
182

183
```typescript { .api }
184
/**
185
 * Generate a range of numbers from start to end
186
 * @param From - Starting number (inclusive)
187
 * @param To - Ending number (inclusive)
188
 * @returns Tuple containing range of numbers
189
 */
190
type Range<From extends number, To extends number> = RangeImpl<From, To>;
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
import { N } from "ts-toolbelt";
197

198
// Generate number ranges
199
type SmallRange = N.Range<1, 5>; // [1, 2, 3, 4, 5]
200
type NegativeRange = N.Range<-3, 2>; // [-3, -2, -1, 0, 1, 2]
201
type SingleNumber = N.Range<7, 7>; // [7]
202

203
// Practical usage with other utilities
204
type IndexRange = N.Range<0, 10>; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
205
type CountdownRange = N.Range<10, 0>; // [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
206
```
207

208
### Practical Examples
209

210
Real-world usage patterns combining number operations.
211

212
**Usage Examples:**
213

214
```typescript
215
import { N, L } from "ts-toolbelt";
216

217
// Calculate array indices
218
type ArrayLength = 5;
219
type LastIndex = N.Sub<ArrayLength, 1>; // 4
220
type ValidIndices = N.Range<0, LastIndex>; // [0, 1, 2, 3, 4]
221

222
// Pagination calculations
223
type PageSize = 10;
224
type PageNumber = 3;
225
type OffsetCalculation = N.Sub<N.Add<PageNumber, 1>, 1>; // Page index calculation
226
type StartIndex = N.Add<N.Sub<PageNumber, 1>, PageSize>; // Skip calculation
227

228
// Range validation
229
type MinValue = 0;
230
type MaxValue = 100;
231
type TestValue = 75;
232
type IsInRange = N.Greater<TestValue, MinValue> extends 1 
233
  ? N.Lower<TestValue, MaxValue> extends 1 
234
    ? 1 
235
    : 0 
236
  : 0; // 1 (true, 75 is between 0 and 100)
237

238
// Counter operations
239
type CurrentCount = 42;
240
type Increment = N.Add<CurrentCount, 1>; // 43
241
type Decrement = N.Sub<CurrentCount, 1>; // 41
242
type Reset = 0;
243

244
// Conditional arithmetic
245
type ConditionalAdd<A extends number, B extends number> = 
246
  N.IsZero<B> extends 1 ? A : N.Add<A, B>;
247

248
type Result1 = ConditionalAdd<5, 0>; // 5 (no addition when B is 0)
249
type Result2 = ConditionalAdd<5, 3>; // 8 (normal addition)
250
```
251

252
## Implementation Notes
253

254
The Number module uses an internal iteration system that supports operations within the range of -100 to 100. This is implemented through:
255

256
- **Iteration Types**: Internal tuple-based system for counting and arithmetic
257
- **Lookup Tables**: Pre-computed results for performance optimization  
258
- **Recursive Types**: Step-by-step computation for complex operations
259
- **Boundary Handling**: Proper handling of edge cases like zero and negative numbers
260

261
The module provides type-safe arithmetic that is evaluated at compile time, enabling mathematical operations in TypeScript's type system itself.
262

263
## Types
264

265
```typescript { .api }
266
// Core types are number literals within the supported range [-100, 100]
267
// All operations return number literal types when possible
268
```