0
# Primitive Type Validation
1

2
Comprehensive validation for JavaScript primitive types including strings, numbers, booleans, symbols, and special values with extensive chainable validation methods.
3

4
## Capabilities
5

6
### String Validation
7

8
Validation for string values with length, content, format, and pattern matching methods.
9

10
```typescript { .api }
11
/** String validation predicate */
12
interface StringPredicate extends BasePredicate<string> {
13
  // Length validation
14
  length(length: number): StringPredicate;
15
  minLength(length: number): StringPredicate;
16
  maxLength(length: number): StringPredicate;
17
  
18
  // Content validation
19
  matches(regex: RegExp): StringPredicate;
20
  startsWith(searchString: string): StringPredicate;
21
  endsWith(searchString: string): StringPredicate;
22
  includes(searchString: string): StringPredicate;
23
  oneOf(list: readonly string[]): StringPredicate;
24
  equals(expected: string): StringPredicate;
25
  
26
  // State validation
27
  readonly empty: StringPredicate;
28
  readonly nonEmpty: StringPredicate;
29
  readonly nonBlank: StringPredicate;
30
  
31
  // Format validation
32
  readonly alphanumeric: StringPredicate;
33
  readonly alphabetical: StringPredicate;
34
  readonly numeric: StringPredicate;
35
  readonly lowercase: StringPredicate;
36
  readonly uppercase: StringPredicate;
37
  readonly date: StringPredicate;
38
  readonly url: StringPredicate;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import ow from 'ow';
46

47
// Length validation
48
ow('hello', ow.string.minLength(3).maxLength(10));
49

50
// Content validation
51
ow('hello@example.com', ow.string.matches(/^.+@.+\..+$/));
52
ow('Hello World', ow.string.startsWith('Hello'));
53
ow('filename.txt', ow.string.endsWith('.txt'));
54
ow('JavaScript', ow.string.includes('Script'));
55
ow('red', ow.string.oneOf(['red', 'green', 'blue']));
56

57
// State validation
58
ow('', ow.string.empty);
59
ow('not empty', ow.string.nonEmpty);
60
ow('  not blank  ', ow.string.nonBlank);
61

62
// Format validation
63
ow('abc123', ow.string.alphanumeric);
64
ow('abc', ow.string.alphabetical);
65
ow('123', ow.string.numeric);
66
ow('hello', ow.string.lowercase);
67
ow('HELLO', ow.string.uppercase);
68
ow('2023-12-01', ow.string.date);
69
ow('https://example.com', ow.string.url);
70
```
71

72
### Number Validation
73

74
Validation for numeric values with range checking, type validation, and typed integer constraints.
75

76
```typescript { .api }
77
/** Number validation predicate */
78
interface NumberPredicate extends BasePredicate<number> {
79
  // Range validation
80
  inRange(start: number, end: number): NumberPredicate;
81
  greaterThan(number: number): NumberPredicate;
82
  greaterThanOrEqual(number: number): NumberPredicate;
83
  lessThan(number: number): NumberPredicate;
84
  lessThanOrEqual(number: number): NumberPredicate;
85
  equal(expected: number): NumberPredicate;
86
  oneOf(list: readonly number[]): NumberPredicate;
87
  
88
  // Type validation
89
  readonly integer: NumberPredicate;
90
  readonly finite: NumberPredicate;
91
  readonly infinite: NumberPredicate;
92
  readonly positive: NumberPredicate;
93
  readonly negative: NumberPredicate;
94
  readonly integerOrInfinite: NumberPredicate;
95
  
96
  // Typed integer validation
97
  readonly uint8: NumberPredicate;   // 0-255
98
  readonly uint16: NumberPredicate;  // 0-65535
99
  readonly uint32: NumberPredicate;  // 0-4294967295
100
  readonly int8: NumberPredicate;    // -128 to 127
101
  readonly int16: NumberPredicate;   // -32768 to 32767
102
  readonly int32: NumberPredicate;   // -2147483648 to 2147483647
103
}
104
```
105

106
**Usage Examples:**
107

108
```typescript
109
import ow from 'ow';
110

111
// Range validation
112
ow(5, ow.number.inRange(1, 10));
113
ow(15, ow.number.greaterThan(10));
114
ow(15, ow.number.greaterThanOrEqual(15));
115
ow(5, ow.number.lessThan(10));
116
ow(10, ow.number.lessThanOrEqual(10));
117
ow(42, ow.number.equal(42));
118
ow(3, ow.number.oneOf([1, 2, 3, 4, 5]));
119

120
// Type validation
121
ow(42, ow.number.integer);
122
ow(3.14, ow.number.finite);
123
ow(Infinity, ow.number.infinite);
124
ow(5, ow.number.positive);
125
ow(-5, ow.number.negative);
126
ow(42, ow.number.integerOrInfinite);
127

128
// Typed integer validation
129
ow(255, ow.number.uint8);
130
ow(65535, ow.number.uint16);
131
ow(4294967295, ow.number.uint32);
132
ow(-128, ow.number.int8);
133
ow(-32768, ow.number.int16);
134
ow(-2147483648, ow.number.int32);
135
```
136

137
### Boolean Validation
138

139
Validation for boolean values with specific true/false checking.
140

141
```typescript { .api }
142
/** Boolean validation predicate */
143
interface BooleanPredicate extends BasePredicate<boolean> {
144
  readonly true: BooleanPredicate;
145
  readonly false: BooleanPredicate;
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import ow from 'ow';
153

154
// Basic boolean validation
155
ow(true, ow.boolean);
156
ow(false, ow.boolean);
157

158
// Specific value validation
159
ow(true, ow.boolean.true);
160
ow(false, ow.boolean.false);
161
```
162

163
### BigInt Validation
164

165
Validation for BigInt values.
166

167
```typescript { .api }
168
/** BigInt validation predicate */
169
interface BigIntPredicate extends BasePredicate<bigint> {
170
  // Inherits only base predicate methods
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
import ow from 'ow';
178

179
// Basic bigint validation
180
ow(123n, ow.bigint);
181
ow(BigInt('123456789012345678901234567890'), ow.bigint);
182

183
// With custom validation
184
ow(42n, ow.bigint.is(value => value > 0n));
185
```
186

187
### Symbol Validation
188

189
Validation for Symbol values.
190

191
```typescript { .api }
192
/** Symbol validation predicate */
193
const symbol: Predicate<symbol>;
194
```
195

196
**Usage Examples:**
197

198
```typescript
199
import ow from 'ow';
200

201
// Basic symbol validation
202
ow(Symbol('test'), ow.symbol);
203
ow(Symbol.for('global'), ow.symbol);
204
```
205

206
### Special Value Validation
207

208
Validation for special JavaScript values including undefined, null, and NaN.
209

210
```typescript { .api }
211
/** Special value predicates */
212
const undefined: Predicate<undefined>;
213
const null: Predicate<null>;
214
const nullOrUndefined: Predicate<null | undefined>;
215
const nan: Predicate<number>;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import ow from 'ow';
222

223
// Special value validation
224
ow(undefined, ow.undefined);
225
ow(null, ow.null);
226
ow(null, ow.nullOrUndefined);
227
ow(undefined, ow.nullOrUndefined);
228
ow(NaN, ow.nan);
229
```
230

231
## Base Predicate Methods
232

233
All primitive predicates inherit these common validation methods:
234

235
```typescript { .api }
236
/** Base methods available on all predicates */
237
interface BasePredicate<T> {
238
  /** Inverts the following validator */
239
  readonly not: BasePredicate<T>;
240
  
241
  /** Custom validation function returning boolean or error string */
242
  is(validator: (value: T) => boolean | string): BasePredicate<T>;
243
  
244
  /** Custom validation with validator/message object */
245
  validate(customValidator: CustomValidator<T>): BasePredicate<T>;
246
  
247
  /** Override default error message */
248
  message(newMessage: string | MessageBuilder<T>): BasePredicate<T>;
249
}
250

251
interface CustomValidator<T> {
252
  validator: boolean;
253
  message: string | ((label?: string) => string);
254
}
255

256
type MessageBuilder<T> = (value: T, label?: string) => string;
257
```
258

259
**Usage Examples:**
260

261
```typescript
262
import ow from 'ow';
263

264
// Negation
265
ow(5, ow.number.not.negative);
266
ow('hello', ow.string.not.empty);
267

268
// Custom validation
269
ow(8, ow.number.is(x => x % 2 === 0 || 'Expected even number'));
270
ow('password123', ow.string.is(s => s.length >= 8 && /\d/.test(s)));
271

272
// Custom validation object
273
ow(10, ow.number.validate(value => ({
274
  validator: value > 5,
275
  message: `Expected number greater than 5, got ${value}`
276
})));
277

278
// Custom error messages
279
ow('hi', 'greeting', ow.string.minLength(5).message('Greeting too short'));
280
ow(3, ow.number.positive.message((value, label) => 
281
  `Expected positive ${label}, got ${value}`
282
));
283
```