0
# io-ts-types
1
2
io-ts-types is a comprehensive collection of runtime type validation codecs and combinators designed to work seamlessly with the io-ts library. It extends io-ts functionality by offering specialized codecs for common data transformations, validations, and functional programming patterns with excellent TypeScript integration.
3
4
## Package Information
5
6
- **Package Name**: io-ts-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install io-ts-types`
10
11
## Core Imports
12
13
```typescript
14
import {
15
NumberFromString,
16
DateFromISOString,
17
option,
18
either,
19
NonEmptyString,
20
UUID
21
} from "io-ts-types";
22
```
23
24
For CommonJS:
25
26
```javascript
27
const {
28
NumberFromString,
29
DateFromISOString,
30
option,
31
either,
32
NonEmptyString,
33
UUID
34
} = require("io-ts-types");
35
```
36
37
## Basic Usage
38
39
```typescript
40
import * as t from "io-ts";
41
import { NumberFromString, DateFromISOString, option, NonEmptyString } from "io-ts-types";
42
43
// Define a user codec with transformations
44
const User = t.type({
45
id: t.number,
46
name: NonEmptyString,
47
age: NumberFromString,
48
birthDate: DateFromISOString,
49
avatar: option(t.string)
50
});
51
52
// Decode user data from JSON
53
const userData = {
54
id: 1,
55
name: "Alice",
56
age: "25",
57
birthDate: "1998-01-15T00:00:00Z",
58
avatar: { _tag: "Some", value: "avatar.jpg" }
59
};
60
61
const result = User.decode(userData);
62
// Result contains: { id: 1, name: "Alice", age: 25, birthDate: Date, avatar: Some("avatar.jpg") }
63
```
64
65
## Architecture
66
67
io-ts-types is built around several key concepts:
68
69
- **Transformation Codecs**: Convert between string/number representations and typed values
70
- **Branded Types**: Add compile-time safety to primitive values (UUID, NonEmptyString)
71
- **Functional Programming Types**: Serialize/deserialize Option and Either types to/from JSON
72
- **Collection Codecs**: Handle arrays, sets, and maps with proper encoding/decoding
73
- **Codec Utilities**: Functions to create, modify, and compose codecs
74
- **Type Safety**: Full TypeScript integration with proper type inference and branded types
75
76
## Dependencies
77
78
io-ts-types requires the following peer dependencies:
79
80
- `fp-ts` ^2.0.0 - Functional programming utilities
81
- `io-ts` ^2.0.0 - Runtime type validation library
82
- `monocle-ts` ^2.0.0 - Optics library for immutable data manipulation
83
- `newtype-ts` ^0.3.2 - Newtype implementation for TypeScript
84
85
## Capabilities
86
87
### String and Number Transformations
88
89
Codecs for converting between string representations and typed values including numbers, integers, booleans, and big integers.
90
91
```typescript { .api }
92
const NumberFromString: t.Type<number, string, unknown>;
93
const IntFromString: t.Type<t.Int, string, unknown>;
94
const BigIntFromString: t.Type<bigint, string, unknown>;
95
const BooleanFromString: t.Type<boolean, string, unknown>;
96
const BooleanFromNumber: t.Type<boolean, number, unknown>;
97
```
98
99
[String and Number Transformations](./string-number-transformations.md)
100
101
### Date Handling
102
103
Codecs for parsing and encoding dates from various formats including ISO strings, Unix timestamps, and millisecond timestamps.
104
105
```typescript { .api }
106
const DateFromISOString: t.Type<Date, string, unknown>;
107
const DateFromNumber: t.Type<Date, number, unknown>;
108
const DateFromUnixTime: t.Type<Date, number, unknown>;
109
const date: t.Type<Date, Date, unknown>;
110
```
111
112
[Date Handling](./date-handling.md)
113
114
### Branded Types and Validation
115
116
Branded types that add compile-time safety and runtime validation for special string formats and constraints.
117
118
```typescript { .api }
119
type NonEmptyString = t.Branded<string, NonEmptyStringBrand>;
120
const NonEmptyString: t.Type<NonEmptyString, string, unknown>;
121
122
type UUID = t.Branded<string, UUIDBrand>;
123
const UUID: t.Type<UUID, string, unknown>;
124
125
const regexp: t.Type<RegExp, RegExp, unknown>;
126
```
127
128
[Branded Types and Validation](./branded-types-validation.md)
129
130
### Functional Programming Types
131
132
Codecs for fp-ts Option and Either types with JSON serialization support, enabling functional programming patterns in API communication.
133
134
```typescript { .api }
135
function option<C extends t.Mixed>(codec: C, name?: string): OptionC<C>;
136
function either<L extends t.Mixed, R extends t.Mixed>(
137
leftCodec: L,
138
rightCodec: R,
139
name?: string
140
): EitherC<L, R>;
141
142
function optionFromNullable<C extends t.Mixed>(
143
codec: C,
144
name?: string
145
): OptionFromNullableC<C>;
146
```
147
148
[Functional Programming Types](./functional-programming-types.md)
149
150
### Collection Codecs
151
152
Codecs for working with arrays, sets, and maps including non-empty arrays and proper serialization of complex collection types.
153
154
```typescript { .api }
155
function nonEmptyArray<C extends t.Mixed>(
156
codec: C,
157
name?: string
158
): NonEmptyArrayC<C>;
159
160
function setFromArray<C extends t.Mixed>(
161
codec: C,
162
O: Ord<t.TypeOf<C>>,
163
name?: string
164
): SetFromArrayC<C>;
165
166
function mapFromEntries<K extends t.Mixed, V extends t.Mixed>(
167
keyCodec: K,
168
KO: Ord<t.TypeOf<K>>,
169
valueCodec: V,
170
name?: string
171
): MapFromEntriesC<K, V>;
172
```
173
174
[Collection Codecs](./collection-codecs.md)
175
176
### Utility Functions and Codec Modifiers
177
178
Utility functions for creating, modifying, and composing codecs including fallback values, custom validation, and lens generation.
179
180
```typescript { .api }
181
function withFallback<C extends t.Any>(
182
codec: C,
183
a: t.TypeOf<C>,
184
name?: string
185
): C;
186
187
function withMessage<C extends t.Any>(
188
codec: C,
189
message: (i: t.InputOf<C>, c: t.Context) => string
190
): C;
191
192
function fromRefinement<A>(
193
name: string,
194
is: (u: unknown) => u is A
195
): t.Type<A, A, unknown>;
196
197
function getLenses<C extends HasLenses>(
198
codec: C
199
): { [K in keyof t.TypeOf<C>]: Lens<t.TypeOf<C>, t.TypeOf<C>[K]> };
200
```
201
202
[Utility Functions and Codec Modifiers](./utility-functions-codec-modifiers.md)
203
204
### JSON Handling
205
206
Comprehensive JSON parsing and validation with proper type definitions for all JSON value types.
207
208
```typescript { .api }
209
type Json = boolean | number | string | null | JsonArray | JsonRecord;
210
const Json: t.Type<Json>;
211
const JsonFromString: t.Type<Json, string, string>;
212
```
213
214
[JSON Handling](./json-handling.md)
215
216
## Types
217
218
### Core Interface Types
219
220
```typescript { .api }
221
interface NonEmptyStringBrand {
222
readonly NonEmptyString: unique symbol;
223
}
224
225
interface UUIDBrand {
226
readonly UUID: unique symbol;
227
}
228
229
interface JsonRecord {
230
readonly [key: string]: Json;
231
}
232
233
interface JsonArray extends ReadonlyArray<Json> {}
234
235
interface ReadonlyNonEmptyArray<A> extends ReadonlyArray<A> {
236
readonly 0: A;
237
}
238
```
239
240
### Codec Interface Types
241
242
```typescript { .api }
243
interface EitherC<L extends t.Mixed, R extends t.Mixed>
244
extends t.Type<Either<t.TypeOf<L>, t.TypeOf<R>>, EitherOutput<t.OutputOf<L>, t.OutputOf<R>>, unknown> {}
245
246
interface OptionC<C extends t.Mixed>
247
extends t.Type<Option<t.TypeOf<C>>, OptionOutput<t.OutputOf<C>>, unknown> {}
248
249
interface NonEmptyArrayC<C extends t.Mixed>
250
extends t.Type<NonEmptyArray<t.TypeOf<C>>, NonEmptyArray<t.OutputOf<C>>, unknown> {}
251
```
252
253
### Output Types for Serialization
254
255
```typescript { .api }
256
type EitherOutput<L, R> = LeftOutput<L> | RightOutput<R>;
257
type LeftOutput<L> = { _tag: 'Left'; left: L };
258
type RightOutput<R> = { _tag: 'Right'; right: R };
259
260
type OptionOutput<A> = NoneOutput | SomeOutput<A>;
261
type SomeOutput<A> = { _tag: 'Some'; value: A };
262
type NoneOutput = { _tag: 'None' };
263
```