0
# Date Handling
1

2
Codecs for parsing and encoding dates from various formats including ISO strings, Unix timestamps, and millisecond timestamps. These codecs handle the common date representation formats used in APIs and data storage.
3

4
## Capabilities
5

6
### DateFromISOString
7

8
Converts ISO date strings to Date objects and vice versa, handling the standard ISO 8601 format commonly used in APIs.
9

10
```typescript { .api }
11
/**
12
 * Codec that parses ISO date strings to Date objects
13
 * Handles ISO 8601 format and encodes Date objects back to ISO strings
14
 */
15
interface DateFromISOStringC extends t.Type<Date, string, unknown> {}
16
const DateFromISOString: DateFromISOStringC;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { DateFromISOString } from "io-ts-types";
23

24
const result1 = DateFromISOString.decode("2023-12-25T10:30:00.000Z");
25
// Right(Date object representing December 25, 2023 at 10:30 AM UTC)
26

27
const result2 = DateFromISOString.decode("2023-12-25T10:30:00Z");
28
// Right(Date object) - also accepts without milliseconds
29

30
const result3 = DateFromISOString.decode("invalid-date");
31
// Left([ValidationError])
32

33
const result4 = DateFromISOString.decode("");
34
// Left([ValidationError])
35

36
// Encoding Date back to ISO string
37
const date = new Date("2023-12-25T10:30:00.000Z");
38
const encoded = DateFromISOString.encode(date);
39
// "2023-12-25T10:30:00.000Z"
40
```
41

42
### DateFromNumber
43

44
Converts millisecond timestamps (numbers) to Date objects, commonly used for JavaScript timestamp representations.
45

46
```typescript { .api }
47
/**
48
 * Codec that converts millisecond timestamps to Date objects
49
 * Handles JavaScript Date.getTime() format (milliseconds since epoch)
50
 */
51
interface DateFromNumberC extends t.Type<Date, number, unknown> {}
52
const DateFromNumber: DateFromNumberC;
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { DateFromNumber } from "io-ts-types";
59

60
const result1 = DateFromNumber.decode(1703505000000);
61
// Right(Date object representing December 25, 2023 at 10:30 AM UTC)
62

63
const result2 = DateFromNumber.decode(0);
64
// Right(Date object representing January 1, 1970 UTC)
65

66
const result3 = DateFromNumber.decode(-1);
67
// Right(Date object representing December 31, 1969 UTC)
68

69
// Encoding Date back to millisecond timestamp
70
const date = new Date("2023-12-25T10:30:00.000Z");
71
const encoded = DateFromNumber.encode(date);
72
// 1703505000000
73
```
74

75
### DateFromUnixTime
76

77
Converts Unix timestamps (seconds since epoch) to Date objects, commonly used in Unix systems and many APIs.
78

79
```typescript { .api }
80
/**
81
 * Codec that converts Unix timestamps to Date objects
82
 * Handles seconds since Unix epoch (January 1, 1970 UTC)
83
 */
84
interface DateFromUnixTimeC extends t.Type<Date, number, unknown> {}
85
const DateFromUnixTime: DateFromUnixTimeC;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { DateFromUnixTime } from "io-ts-types";
92

93
const result1 = DateFromUnixTime.decode(1703505000);
94
// Right(Date object representing December 25, 2023 at 10:30 AM UTC)
95

96
const result2 = DateFromUnixTime.decode(0);
97
// Right(Date object representing January 1, 1970 UTC)
98

99
const result3 = DateFromUnixTime.decode(-1);
100
// Right(Date object representing December 31, 1969 UTC)
101

102
// Encoding Date back to Unix timestamp
103
const date = new Date("2023-12-25T10:30:00.000Z");
104
const encoded = DateFromUnixTime.encode(date);
105
// 1703505000
106
```
107

108
### Date Validation
109

110
Validates values are Date instances using instanceof check, useful for runtime validation of Date objects.
111

112
```typescript { .api }
113
/**
114
 * Codec that validates values are Date instances
115
 * Uses instanceof check for runtime Date validation
116
 */
117
interface DateC extends t.Type<Date, Date, unknown> {}
118
const date: DateC;
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
import { date } from "io-ts-types";
125

126
const result1 = date.decode(new Date());
127
// Right(Date object)
128

129
const result2 = date.decode("2023-12-25");
130
// Left([ValidationError]) - string is not a Date instance
131

132
const result3 = date.decode(1703505000000);
133
// Left([ValidationError]) - number is not a Date instance
134

135
// Identity encoding (Date -> Date)
136
const dateObj = new Date();
137
const encoded = date.encode(dateObj);
138
// Same Date object
139
```
140

141
## Common Usage Patterns
142

143
### API Response with Mixed Date Formats
144

145
```typescript
146
import * as t from "io-ts";
147
import { DateFromISOString, DateFromUnixTime } from "io-ts-types";
148

149
const Event = t.type({
150
  id: t.number,
151
  title: t.string,
152
  createdAt: DateFromISOString,    // ISO format from modern APIs
153
  scheduledAt: DateFromUnixTime,   // Unix timestamp from legacy systems
154
  updatedAt: DateFromISOString
155
});
156

157
const eventData = {
158
  id: 1,
159
  title: "Team Meeting",
160
  createdAt: "2023-12-25T10:30:00.000Z",
161
  scheduledAt: 1703505000,  // Unix timestamp
162
  updatedAt: "2023-12-25T11:00:00.000Z"
163
};
164

165
const parsed = Event.decode(eventData);
166
// Right({ 
167
//   id: 1, 
168
//   title: "Team Meeting", 
169
//   createdAt: Date, 
170
//   scheduledAt: Date, 
171
//   updatedAt: Date 
172
// })
173
```
174

175
### Database Record Processing
176

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

181
const DatabaseRecord = t.type({
182
  id: t.string,
183
  created_at: DateFromNumber,     // Stored as millisecond timestamp
184
  expires_at: DateFromISOString,  // Stored as ISO string
185
  data: t.record(t.string, t.unknown)
186
});
187

188
const record = {
189
  id: "user_123",
190
  created_at: 1703505000000,
191
  expires_at: "2024-01-25T10:30:00.000Z",
192
  data: { preferences: { theme: "dark" } }
193
};
194

195
const parsed = DatabaseRecord.decode(record);
196
// Converts timestamps to proper Date objects
197
```
198

199
### Form Input Processing
200

201
```typescript
202
import * as t from "io-ts";
203
import { DateFromISOString } from "io-ts-types";
204

205
const EventForm = t.type({
206
  title: t.string,
207
  startDate: DateFromISOString,  // HTML date input provides ISO string
208
  endDate: DateFromISOString,
209
  description: t.string
210
});
211

212
// HTML form data (date inputs return ISO strings)
213
const formData = {
214
  title: "Conference",
215
  startDate: "2024-06-15T09:00:00.000Z",
216
  endDate: "2024-06-15T17:00:00.000Z", 
217
  description: "Annual tech conference"
218
};
219

220
const validated = EventForm.decode(formData);
221
// Right({ title: "Conference", startDate: Date, endDate: Date, description: "..." })
222
```
223

224
### Time Zone Handling
225

226
```typescript
227
import { DateFromISOString, DateFromUnixTime } from "io-ts-types";
228

229
// Unix timestamps are always UTC
230
const utcTime = DateFromUnixTime.decode(1703505000);
231
// Right(Date representing UTC time)
232

233
// ISO strings can include timezone information
234
const isoWithTz = DateFromISOString.decode("2023-12-25T10:30:00+02:00");
235
// Right(Date object automatically adjusted to local timezone)
236

237
const isoUtc = DateFromISOString.decode("2023-12-25T10:30:00.000Z");
238
// Right(Date object in UTC)
239
```
240

241
### Date Arithmetic and Comparison
242

243
```typescript
244
import * as t from "io-ts-types";
245
import { DateFromISOString } from "io-ts-types";
246

247
const DateRange = t.type({
248
  start: DateFromISOString,
249
  end: DateFromISOString
250
});
251

252
const range = {
253
  start: "2023-12-25T10:00:00.000Z",
254
  end: "2023-12-25T18:00:00.000Z"
255
};
256

257
const decoded = DateRange.decode(range);
258
if (decoded._tag === "Right") {
259
  const { start, end } = decoded.right;
260
  const durationMs = end.getTime() - start.getTime();
261
  const durationHours = durationMs / (1000 * 60 * 60);
262
  console.log(`Duration: ${durationHours} hours`); // Duration: 8 hours
263
}
264
```