0
# Number Operations
1

2
Safe number operations with precision handling, random number generation, and validation for JavaScript's safe integer limits to prevent precision loss and overflow issues.
3

4
## Capabilities
5

6
### Safe Integer Constants
7

8
JavaScript safe integer limits and string representations for precision validation.
9

10
```typescript { .api }
11
const MAX_SAFE_INTEGER: number;      // 9007199254740991 or 2^53 - 1
12
const MIN_SAFE_INTEGER: number;      // -9007199254740991
13
const MAX_SAFE_INTEGER_STR: string;  // "9007199254740991"
14
```
15

16
**Usage Examples:**
17

18
```typescript
19
import { MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_SAFE_INTEGER_STR, isSafeNumberString, toSafeNumber } from "utility";
20

21
// Using constants for validation
22
const userInput = "9007199254740991";
23
if (parseInt(userInput) <= MAX_SAFE_INTEGER) {
24
  console.log("Safe to convert to number");
25
}
26

27
// Compare against limits
28
console.log(MAX_SAFE_INTEGER);     // 9007199254740991
29
console.log(MIN_SAFE_INTEGER);     // -9007199254740991
30
console.log(MAX_SAFE_INTEGER_STR); // "9007199254740991"
31

32
// Validation using string constant
33
const isMaxSafe = isSafeNumberString(MAX_SAFE_INTEGER_STR);
34
// Result: true
35

36
// Beyond safe limits
37
const tooLarge = (MAX_SAFE_INTEGER + 1).toString();
38
const isUnsafe = isSafeNumberString(tooLarge);
39
// Result: false
40

41
// Practical usage with API input validation
42
function processNumericInput(value: string): number | string {
43
  if (value.length > MAX_SAFE_INTEGER_STR.length) {
44
    return value; // Too long, keep as string
45
  }
46
  return toSafeNumber(value);
47
}
48
```
49

50
### Safe Number String Validation
51

52
Validate if a number string can be safely converted to JavaScript Number.
53

54
```typescript { .api }
55
/**
56
 * Detect if a number string can safely convert to JavaScript Number
57
 * @param s - Number format string
58
 * @returns True if string represents a safe number
59
 */
60
function isSafeNumberString(s: string): boolean;
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { isSafeNumberString, MAX_SAFE_INTEGER } from "utility";
67

68
// Safe numbers
69
const safe1 = isSafeNumberString("123456789");
70
// Result: true
71

72
const safe2 = isSafeNumberString("-1000");
73
// Result: true
74

75
const safeMax = isSafeNumberString("9007199254740991");
76
// Result: true
77

78
// Unsafe numbers (too large)
79
const unsafe1 = isSafeNumberString("9007199254740992");
80
// Result: false
81

82
const unsafe2 = isSafeNumberString("123456789012345678901234567890");
83
// Result: false
84

85
// Negative numbers
86
const safeNeg = isSafeNumberString("-9007199254740991");
87
// Result: true
88
```
89

90
### Safe Number Conversion
91

92
Convert string to Number only if within safe integer range.
93

94
```typescript { .api }
95
/**
96
 * Convert string to Number if string is in safe Number scope
97
 * @param s - Number format string or existing number
98
 * @returns Number if safe conversion possible, otherwise returns original string
99
 */
100
function toSafeNumber(s: string | number): number | string;
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { toSafeNumber } from "utility";
107

108
// Safe conversions
109
const num1 = toSafeNumber("12345");
110
// Result: 12345 (number)
111

112
const num2 = toSafeNumber("-9007199254740991");
113
// Result: -9007199254740991 (number)
114

115
// Already a number
116
const num3 = toSafeNumber(42);
117
// Result: 42 (number)
118

119
// Unsafe conversions (returns original string)
120
const str1 = toSafeNumber("9007199254740992");
121
// Result: "9007199254740992" (string)
122

123
const str2 = toSafeNumber("123456789012345678901234567890");
124
// Result: "123456789012345678901234567890" (string)
125

126
// Floating point numbers
127
const float1 = toSafeNumber("123.456");
128
// Result: 123.456 (number)
129
```
130

131
### Random Number Generation
132

133
Generate random integers within specified bounds with automatic bound swapping.
134

135
```typescript { .api }
136
/**
137
 * Produces a random integer between inclusive bounds
138
 * @param lower - Lower bound (or upper bound if upper not provided)
139
 * @param upper - Upper bound (optional)
140
 * @returns Random integer within bounds
141
 */
142
function random(lower?: number, upper?: number): number;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { random } from "utility";
149

150
// No parameters - returns 0
151
const zero = random();
152
// Result: 0
153

154
// Single parameter - random between 0 and parameter
155
const dice = random(6);
156
// Result: 0, 1, 2, 3, 4, or 5
157

158
// Two parameters - random between bounds (inclusive)
159
const percentage = random(1, 100);
160
// Result: integer between 1 and 100
161

162
// Automatic bound swapping
163
const swapped = random(10, 1);
164
// Result: integer between 1 and 10 (bounds automatically swapped)
165

166
// Negative numbers
167
const negative = random(-10, -1);
168
// Result: integer between -10 and -1
169

170
// Mixed bounds
171
const mixed = random(-5, 5);
172
// Result: integer between -5 and 5
173
```