0
# String and Number Transformations
1

2
Codecs for converting between string representations and typed values including numbers, integers, booleans, and big integers. These codecs are essential for parsing API responses, form data, and configuration files where numeric values are represented as strings.
3

4
## Capabilities
5

6
### NumberFromString
7

8
Converts strings to numbers with validation to ensure the result is not NaN and the input is not empty.
9

10
```typescript { .api }
11
/**
12
 * Codec that parses strings to numbers with NaN validation
13
 * Validates input is a non-empty string and result is not NaN
14
 */
15
interface NumberFromStringC extends t.Type<number, string, unknown> {}
16
const NumberFromString: NumberFromStringC;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { NumberFromString } from "io-ts-types";
23
import { isRight } from "fp-ts/lib/Either";
24

25
const result1 = NumberFromString.decode("42.5");
26
// Right(42.5)
27

28
const result2 = NumberFromString.decode("invalid");
29
// Left([ValidationError])
30

31
const result3 = NumberFromString.decode("");
32
// Left([ValidationError])
33

34
// Encoding back to string
35
const encoded = NumberFromString.encode(42.5);
36
// "42.5"
37
```
38

39
### IntFromString
40

41
Parses strings to integers with validation to ensure the result is a valid integer.
42

43
```typescript { .api }
44
/**
45
 * Codec that parses strings to integers with validation
46
 * Uses NumberFromString internally then validates result is an integer
47
 */
48
interface IntFromStringC extends t.Type<t.Int, string, unknown> {}
49
const IntFromString: IntFromStringC;
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { IntFromString } from "io-ts-types";
56

57
const result1 = IntFromString.decode("42");
58
// Right(42)
59

60
const result2 = IntFromString.decode("42.5");
61
// Left([ValidationError]) - not an integer
62

63
const result3 = IntFromString.decode("abc");
64
// Left([ValidationError]) - not a number
65
```
66

67
### BigIntFromString
68

69
Converts non-empty strings to BigInt values for handling large integers beyond JavaScript's Number.MAX_SAFE_INTEGER.
70

71
```typescript { .api }
72
/**
73
 * Codec that parses non-empty strings to BigInt values
74
 * Validates input is a non-empty trimmed string and can be converted to BigInt
75
 */
76
interface BigIntFromStringC extends t.Type<bigint, string, unknown> {}
77
const BigIntFromString: BigIntFromStringC;
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { BigIntFromString } from "io-ts-types";
84

85
const result1 = BigIntFromString.decode("12345678901234567890");
86
// Right(12345678901234567890n)
87

88
const result2 = BigIntFromString.decode("");
89
// Left([ValidationError]) - empty string
90

91
const result3 = BigIntFromString.decode("not-a-number");
92
// Left([ValidationError]) - invalid BigInt format
93

94
// Encoding back to string
95
const encoded = BigIntFromString.encode(12345678901234567890n);
96
// "12345678901234567890"
97
```
98

99
### BooleanFromString
100

101
Parses string literals "true" and "false" to boolean values.
102

103
```typescript { .api }
104
/**
105
 * Codec that parses string literals "true" and "false" to boolean values
106
 * Only accepts exact string matches (case-sensitive)
107
 */
108
interface BooleanFromStringC extends t.Type<boolean, string, unknown> {}
109
const BooleanFromString: BooleanFromStringC;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { BooleanFromString } from "io-ts-types";
116

117
const result1 = BooleanFromString.decode("true");
118
// Right(true)
119

120
const result2 = BooleanFromString.decode("false");
121
// Right(false)
122

123
const result3 = BooleanFromString.decode("True");
124
// Left([ValidationError]) - case sensitive
125

126
const result4 = BooleanFromString.decode("1");
127
// Left([ValidationError]) - only accepts "true"/"false"
128

129
// Encoding back to string
130
const encoded1 = BooleanFromString.encode(true);
131
// "true"
132
const encoded2 = BooleanFromString.encode(false);
133
// "false"
134
```
135

136
### BooleanFromNumber
137

138
Converts numbers to booleans using JavaScript's truthy/falsy semantics (0 = false, any other number = true).
139

140
```typescript { .api }
141
/**
142
 * Codec that converts numbers to booleans
143
 * 0 becomes false, any other number becomes true
144
 */
145
interface BooleanFromNumberC extends t.Type<boolean, number, unknown> {}
146
const BooleanFromNumber: BooleanFromNumberC;
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { BooleanFromNumber } from "io-ts-types";
153

154
const result1 = BooleanFromNumber.decode(0);
155
// Right(false)
156

157
const result2 = BooleanFromNumber.decode(1);
158
// Right(true)
159

160
const result3 = BooleanFromNumber.decode(-1);
161
// Right(true)
162

163
const result4 = BooleanFromNumber.decode(42.5);
164
// Right(true)
165

166
// Encoding back to number
167
const encoded1 = BooleanFromNumber.encode(false);
168
// 0
169
const encoded2 = BooleanFromNumber.encode(true);
170
// 1
171
```
172

173
## Common Usage Patterns
174

175
### API Response Parsing
176

177
```typescript
178
import * as t from "io-ts";
179
import { NumberFromString, BooleanFromString } from "io-ts-types";
180

181
const APIResponse = t.type({
182
  userId: NumberFromString,
183
  score: NumberFromString, 
184
  isActive: BooleanFromString,
185
  metadata: t.record(t.string, t.string)
186
});
187

188
// Parse API response with string values
189
const response = {
190
  userId: "123",
191
  score: "85.5",
192
  isActive: "true",
193
  metadata: { source: "web" }
194
};
195

196
const parsed = APIResponse.decode(response);
197
// Right({ userId: 123, score: 85.5, isActive: true, metadata: { source: "web" } })
198
```
199

200
### Form Data Processing
201

202
```typescript
203
import * as t from "io-ts";
204
import { IntFromString, BooleanFromString } from "io-ts-types";
205

206
const FormData = t.type({
207
  age: IntFromString,
208
  count: IntFromString,
209
  newsletter: BooleanFromString
210
});
211

212
// Process form data (all values come as strings from HTML forms)
213
const formFields = {
214
  age: "25",
215
  count: "3", 
216
  newsletter: "false"
217
};
218

219
const processed = FormData.decode(formFields);
220
// Right({ age: 25, count: 3, newsletter: false })
221
```
222

223
### Configuration File Parsing
224

225
```typescript
226
import * as t from "io-ts";
227
import { NumberFromString, BigIntFromString } from "io-ts-types";
228

229
const Config = t.type({
230
  port: NumberFromString,
231
  maxFileSize: BigIntFromString,
232
  timeout: NumberFromString
233
});
234

235
// Parse configuration where values might be strings
236
const configData = {
237
  port: "3000",
238
  maxFileSize: "9007199254740992", // Beyond Number.MAX_SAFE_INTEGER
239
  timeout: "30000"
240
};
241

242
const config = Config.decode(configData);
243
// Right({ port: 3000, maxFileSize: 9007199254740992n, timeout: 30000 })
244
```