0
# Ow
1
2
## Overview
3
4
Ow is a TypeScript function argument validation library for humans that provides expressive, chainable APIs for validating JavaScript and TypeScript values. It offers comprehensive validation for all JavaScript types including primitives, built-in types, typed arrays, and complex structured data with automatic label inference and TypeScript type guards.
5
6
## Package Information
7
8
- **Package Name**: ow
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install ow`
12
13
## Core Imports
14
15
```typescript
16
import ow from 'ow';
17
```
18
19
For CommonJS:
20
21
```javascript
22
const ow = require('ow');
23
```
24
25
Development-only imports (automatically shimmed in production):
26
27
```typescript
28
import ow from 'ow/dev-only';
29
```
30
31
Type utilities:
32
33
```typescript
34
import ow, { Infer, ArgumentError } from 'ow';
35
```
36
37
## Basic Usage
38
39
```typescript
40
import ow from 'ow';
41
42
// Basic validation with automatic label inference
43
const validateUser = (input) => {
44
ow(input, ow.object.exactShape({
45
name: ow.string.minLength(2),
46
age: ow.number.integer.positive,
47
email: ow.optional.string.matches(/^.+@.+\..+$/)
48
}));
49
};
50
51
// With custom label
52
ow('hello', 'greeting', ow.string.minLength(10));
53
// => ArgumentError: Expected string `greeting` to have a minimum length of `10`, got `hello`
54
55
// Boolean validation instead of throwing
56
if (ow.isValid(42, ow.string)) {
57
console.log('Never runs');
58
}
59
60
// Create reusable validators
61
const checkPassword = ow.create('password', ow.string.minLength(8));
62
checkPassword('weak');
63
// => ArgumentError: Expected string `password` to have a minimum length of `8`, got `weak`
64
```
65
66
## Architecture
67
68
Ow is built around several key components:
69
70
- **Core Validation Functions**: `ow()` for assertions, `ow.isValid()` for boolean checks, `ow.create()` for reusable validators
71
- **Predicate System**: Chainable validation objects for each JavaScript type with specialized methods
72
- **Base Predicate Methods**: Common validation methods (`.not`, `.is()`, `.validate()`, `.message()`) available on all predicates
73
- **Type System**: Full TypeScript integration with type guards and type inference utilities
74
- **Modifier System**: Optional predicates that allow undefined values alongside the main type
75
76
## Capabilities
77
78
### Core Validation Functions
79
80
Main validation functions and utilities for creating validators and checking values.
81
82
```typescript { .api }
83
/** Test if value matches predicate, throws ArgumentError on failure */
84
function ow<T>(value: unknown, predicate: BasePredicate<T>): asserts value is T;
85
86
/** Test with custom label for error messages */
87
function ow<T>(value: unknown, label: string, predicate: BasePredicate<T>): asserts value is T;
88
89
/** Returns boolean instead of throwing, provides type guards */
90
function isValid<T>(value: unknown, predicate: BasePredicate<T>): value is T;
91
92
/** Create reusable validator function */
93
function create<T>(predicate: BasePredicate<T>): ReusableValidator<T>;
94
function create<T>(label: string, predicate: BasePredicate<T>): ReusableValidator<T>;
95
96
/** Returns predicate that passes if any of the provided predicates match */
97
function any<T1>(p1: BasePredicate<T1>): AnyPredicate<T1>;
98
function any<T1, T2>(p1: BasePredicate<T1>, p2: BasePredicate<T2>): AnyPredicate<T1 | T2>;
99
// ... supports up to 10 predicates
100
101
type ReusableValidator<T> = (value: unknown, label?: string) => void;
102
```
103
104
### Primitive Type Validation
105
106
Validation for JavaScript primitive types including strings, numbers, booleans, and symbols with extensive chainable methods.
107
108
```typescript { .api }
109
const string: StringPredicate;
110
const number: NumberPredicate;
111
const boolean: BooleanPredicate;
112
const bigint: BigIntPredicate;
113
const symbol: Predicate<symbol>;
114
const undefined: Predicate<undefined>;
115
const null: Predicate<null>;
116
const nullOrUndefined: Predicate<null | undefined>;
117
const nan: Predicate<number>;
118
```
119
120
[Primitive Type Validation](./primitive-types.md)
121
122
### Object and Array Validation
123
124
Advanced validation for objects and arrays including shape validation, property checking, and element type validation.
125
126
```typescript { .api }
127
const object: ObjectPredicate;
128
const array: ArrayPredicate;
129
130
interface ObjectPredicate {
131
exactShape<S>(shape: S): ObjectPredicate;
132
partialShape<S>(shape: S): ObjectPredicate;
133
hasKeys(...keys: string[]): ObjectPredicate;
134
// ... more methods
135
}
136
137
interface ArrayPredicate {
138
ofType<U>(predicate: BasePredicate<U>): ArrayPredicate;
139
length(length: number): ArrayPredicate;
140
includes(...searchElements: T[]): ArrayPredicate;
141
// ... more methods
142
}
143
```
144
145
[Object and Array Validation](./object-array-validation.md)
146
147
### Built-in Type Validation
148
149
Validation for JavaScript built-in types like Date, Error, RegExp, Promise, Function, and Buffer.
150
151
```typescript { .api }
152
const date: DatePredicate;
153
const error: ErrorPredicate;
154
const regExp: Predicate<RegExp>;
155
const promise: Predicate<Promise<unknown>>;
156
const function: Predicate<Function>;
157
const buffer: Predicate<Buffer>;
158
```
159
160
[Built-in Type Validation](./builtin-types.md)
161
162
### Collection Type Validation
163
164
Validation for JavaScript collection types including Map, Set, WeakMap, and WeakSet with size and content validation.
165
166
```typescript { .api }
167
const map: MapPredicate;
168
const set: SetPredicate;
169
const weakMap: WeakMapPredicate;
170
const weakSet: WeakSetPredicate;
171
const iterable: Predicate<Iterable<unknown>>;
172
```
173
174
[Collection Type Validation](./collection-types.md)
175
176
### Typed Array Validation
177
178
Comprehensive validation for all typed array types with length and byte length validation methods.
179
180
```typescript { .api }
181
const typedArray: TypedArrayPredicate<TypedArray>;
182
const int8Array: TypedArrayPredicate<Int8Array>;
183
const uint8Array: TypedArrayPredicate<Uint8Array>;
184
const uint8ClampedArray: TypedArrayPredicate<Uint8ClampedArray>;
185
const int16Array: TypedArrayPredicate<Int16Array>;
186
const uint16Array: TypedArrayPredicate<Uint16Array>;
187
const int32Array: TypedArrayPredicate<Int32Array>;
188
const uint32Array: TypedArrayPredicate<Uint32Array>;
189
const float32Array: TypedArrayPredicate<Float32Array>;
190
const float64Array: TypedArrayPredicate<Float64Array>;
191
const arrayBuffer: ArrayBufferPredicate<ArrayBuffer>;
192
const sharedArrayBuffer: ArrayBufferPredicate<SharedArrayBuffer>;
193
const dataView: DataViewPredicate;
194
```
195
196
[Typed Array Validation](./typed-arrays.md)
197
198
### Advanced Features
199
200
Optional predicates, custom validation, error handling, and TypeScript type utilities.
201
202
```typescript { .api }
203
/** Make any predicate optional (allows undefined) */
204
const optional: {
205
string: StringPredicate & BasePredicate<string | undefined>;
206
number: NumberPredicate & BasePredicate<number | undefined>;
207
// ... all other predicates as optional
208
};
209
210
/** Extract TypeScript type from predicate */
211
type Infer<P> = P extends BasePredicate<infer T> ? T : never;
212
213
/** Error thrown when validation fails */
214
class ArgumentError extends Error {
215
name: 'ArgumentError';
216
}
217
218
/** Base interface for all predicates */
219
interface BasePredicate<T> {
220
not: BasePredicate<T>;
221
is(validator: (value: T) => boolean | string): BasePredicate<T>;
222
validate(customValidator: CustomValidator<T>): BasePredicate<T>;
223
message(newMessage: string | MessageBuilder<T>): BasePredicate<T>;
224
}
225
```
226
227
[Advanced Features](./advanced-features.md)
228
229
## Type System
230
231
### Core Types
232
233
```typescript { .api }
234
/** Extract TypeScript type from predicate */
235
type Infer<P> = P extends BasePredicate<infer T> ? T : never;
236
237
/** Base interface for all predicates */
238
interface BasePredicate<T> {
239
// Base predicate methods available on all predicates
240
}
241
242
/** Reusable validator function created with ow.create() */
243
type ReusableValidator<T> = (value: unknown, label?: string) => void;
244
245
/** Type assertion version of reusable validator */
246
type AssertingValidator<T> = (value: unknown, label?: string) => asserts value is T;
247
248
/** Error thrown when validation fails */
249
class ArgumentError extends Error {
250
name: 'ArgumentError';
251
}
252
```
253
254
### Usage Examples
255
256
```typescript
257
import ow, { Infer } from 'ow';
258
259
// Extract types from predicates
260
const userPredicate = ow.object.exactShape({
261
name: ow.string,
262
age: ow.number.integer.positive,
263
email: ow.optional.string
264
});
265
266
type User = Infer<typeof userPredicate>;
267
// Result: { name: string; age: number; email?: string | undefined }
268
269
// Type guards in action
270
function processValue(input: unknown) {
271
ow(input, ow.string.minLength(5));
272
// TypeScript now knows input is string with length >= 5
273
return input.toUpperCase();
274
}
275
```