0
# Primitive Types
1

2
Core type validators for JavaScript primitive values and special types. These are the building blocks for more complex validation schemas.
3

4
## Capabilities
5

6
### String
7

8
Validates that a value is a string.
9

10
```typescript { .api }
11
/**
12
 * Validates that a value is a string
13
 * @example String.check("hello") // "hello"
14
 * @example String.guard(123) // false
15
 */
16
const String: Runtype<string>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { String } from "runtypes";
23

24
// Basic validation
25
const name = String.check("Alice"); // "Alice"
26
String.check(123); // throws ValidationError
27

28
// Type guard usage
29
function processName(input: unknown) {
30
  if (String.guard(input)) {
31
    // input is now typed as string
32
    return input.toUpperCase();
33
  }
34
  throw new Error("Expected string");
35
}
36
```
37

38
### Number
39

40
Validates that a value is a number.
41

42
```typescript { .api }
43
/**
44
 * Validates that a value is a number
45
 * @example Number.check(42) // 42
46
 * @example Number.guard("42") // false
47
 */
48
const Number: Runtype<number>;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { Number } from "runtypes";
55

56
// Validation
57
const age = Number.check(25); // 25
58
const price = Number.parse("invalid"); // throws ValidationError
59

60
// With constraints
61
const PositiveNumber = Number.withConstraint(n => n > 0 || "Must be positive");
62
const count = PositiveNumber.check(5); // 5
63
```
64

65
### Boolean
66

67
Validates that a value is a boolean.
68

69
```typescript { .api }
70
/**
71
 * Validates that a value is a boolean
72
 * @example Boolean.check(true) // true
73
 * @example Boolean.guard("true") // false
74
 */
75
const Boolean: Runtype<boolean>;
76
```
77

78
### BigInt
79

80
Validates that a value is a bigint.
81

82
```typescript { .api }
83
/**
84
 * Validates that a value is a bigint
85
 * @example BigInt.check(123n) // 123n
86
 * @example BigInt.guard(123) // false
87
 */
88
const BigInt: Runtype<bigint>;
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { BigInt } from "runtypes";
95

96
const largeNumber = BigInt.check(9007199254740991n);
97
// For parsing from strings, combine with Parser
98
const BigIntFromString = BigInt.withParser(str => globalThis.BigInt(str));
99
```
100

101
### Symbol
102

103
Validates that a value is a symbol. Can optionally validate specific symbol descriptions.
104

105
```typescript { .api }
106
/**
107
 * Validates that a value is a symbol
108
 * @example Symbol.check(Symbol("test")) // Symbol(test)
109
 * @example Symbol("test").check(Symbol("test")) // Symbol(test)
110
 */
111
const Symbol: Runtype<symbol> & ((description?: string) => Runtype<symbol>);
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { Symbol } from "runtypes";
118

119
// Any symbol
120
const anySymbol = Symbol.check(Symbol("test"));
121

122
// Specific symbol description
123
const testSymbol = Symbol("test");
124
testSymbol.check(Symbol("test")); // passes
125
testSymbol.check(Symbol("other")); // throws ValidationError
126
```
127

128
### Null
129

130
Validates that a value is exactly null.
131

132
```typescript { .api }
133
/**
134
 * Validates that a value is exactly null
135
 * @example Null.check(null) // null
136
 * @example Null.guard(undefined) // false
137
 */
138
const Null: Runtype<null>;
139
```
140

141
### Undefined
142

143
Validates that a value is exactly undefined.
144

145
```typescript { .api }
146
/**
147
 * Validates that a value is exactly undefined
148
 * @example Undefined.check(undefined) // undefined
149
 * @example Undefined.guard(null) // false
150
 */
151
const Undefined: Runtype<undefined>;
152
```
153

154
### Void
155

156
Alias for Undefined, commonly used for function return types.
157

158
```typescript { .api }
159
/**
160
 * Validates that a value is exactly undefined (alias for Undefined)
161
 * @example Void.check(undefined) // undefined
162
 */
163
const Void: Runtype<undefined>;
164
```
165

166
### Unknown
167

168
Accepts any value (top type). Useful as a starting point for validation chains.
169

170
```typescript { .api }
171
/**
172
 * Accepts any value (top type)
173
 * @example Unknown.check(anything) // anything
174
 */
175
const Unknown: Runtype<unknown>;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { Unknown, String } from "runtypes";
182

183
// Accept any input, then narrow down
184
const validateInput = (input: unknown) => {
185
  Unknown.check(input); // Always passes
186
  
187
  if (String.guard(input)) {
188
    return { type: "string", value: input };
189
  }
190
  return { type: "other", value: input };
191
};
192
```
193

194
### Never
195

196
Rejects all values (bottom type). Useful for impossible cases and strict validation.
197

198
```typescript { .api }
199
/**
200
 * Rejects all values (bottom type)
201
 * @example Never.check(anything) // always throws ValidationError
202
 */
203
const Never: Runtype<never>;
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import { Never, Object } from "runtypes";
210

211
// Reject extra properties in exact objects
212
const StrictUser = Object({
213
  name: String,
214
  age: Number
215
}).exact(); // Uses Never internally for extra properties
216
```
217

218
### Nullish
219

220
Validates that a value is null or undefined (nullish values).
221

222
```typescript { .api }
223
/**
224
 * Validates that a value is null or undefined
225
 * @example Nullish.check(null) // null
226
 * @example Nullish.check(undefined) // undefined
227
 * @example Nullish.guard("") // false
228
 */
229
const Nullish: Runtype<null | undefined>;
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
import { Nullish, String, Union } from "runtypes";
236

237
// Optional string that can be nullish
238
const OptionalString = Union(String, Nullish);
239

240
// Or using the nullable/undefinedable methods
241
const NullableString = String.nullable(); // string | null
242
const UndefinableString = String.undefinedable(); // string | undefined  
243
const NullishString = String.nullishable(); // string | null | undefined
244
```
245

246
## Combination Examples
247

248
```typescript
249
import { String, Number, Boolean, Union, Object } from "runtypes";
250

251
// Mixed primitive validation
252
const MixedData = Object({
253
  id: Union(String, Number), // string or number
254
  name: String,
255
  active: Boolean,
256
  tags: Array(String),
257
  metadata: Unknown.optional() // any value, optional
258
});
259

260
type MixedDataType = Static<typeof MixedData>;
261
// {
262
//   id: string | number;
263
//   name: string;
264
//   active: boolean;
265
//   tags: string[];
266
//   metadata?: unknown;
267
// }
268
```