0
# Data Types
1

2
Comprehensive data type system with database-specific mappings and validation rules for model attributes.
3

4
## Capabilities
5

6
### String Types
7

8
Data types for textual data with various length constraints.
9

10
```typescript { .api }
11
/**
12
 * Variable length string
13
 * @param length - Maximum length (default varies by dialect)
14
 */
15
STRING(length?: number): DataType;
16

17
/**
18
 * Fixed length string
19
 * @param length - Fixed length
20
 */
21
CHAR(length?: number): DataType;
22

23
/**
24
 * Large text field for long strings
25
 */
26
TEXT: DataType;
27

28
/**
29
 * Case-insensitive text (PostgreSQL only)
30
 */
31
CITEXT: DataType;
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
class User extends Model {}
38
User.init({
39
  username: DataTypes.STRING(50),     // VARCHAR(50)
40
  code: DataTypes.CHAR(10),           // CHAR(10)
41
  description: DataTypes.TEXT,        // TEXT
42
  bio: DataTypes.CITEXT              // CITEXT (PostgreSQL)
43
});
44
```
45

46
### Numeric Types
47

48
Data types for numeric values with various precision and scale options.
49

50
```typescript { .api }
51
/**
52
 * Integer number
53
 */
54
INTEGER: DataType;
55

56
/**
57
 * Big integer for large numbers
58
 */  
59
BIGINT: DataType;
60

61
/**
62
 * Floating point number
63
 */
64
FLOAT: DataType;
65

66
/**
67
 * Real number
68
 */
69
REAL: DataType;
70

71
/**
72
 * Double precision floating point
73
 */
74
DOUBLE: DataType;
75

76
/**
77
 * Fixed-point decimal number
78
 * @param precision - Total number of digits
79
 * @param scale - Number of digits after decimal point
80
 */
81
DECIMAL(precision?: number, scale?: number): DataType;
82

83
/**
84
 * Alias for DECIMAL
85
 */
86
NUMERIC(precision?: number, scale?: number): DataType;
87

88
/**
89
 * Tiny integer (-128 to 127)
90
 */
91
TINYINT: DataType;
92

93
/**
94
 * Small integer (-32768 to 32767) 
95
 */
96
SMALLINT: DataType;
97

98
/**
99
 * Medium integer (-8388608 to 8388607)
100
 */
101
MEDIUMINT: DataType;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
class Product extends Model {}
108
Product.init({
109
  id: DataTypes.INTEGER,
110
  quantity: DataTypes.SMALLINT,
111
  price: DataTypes.DECIMAL(10, 2),    // 10 digits, 2 after decimal
112
  weight: DataTypes.FLOAT,
113
  largeNumber: DataTypes.BIGINT,
114
  rating: DataTypes.TINYINT
115
});
116

117
// With additional options
118
class User extends Model {}
119
User.init({
120
  id: {
121
    type: DataTypes.INTEGER,
122
    primaryKey: true,
123
    autoIncrement: true
124
  },
125
  balance: {
126
    type: DataTypes.DECIMAL(15, 2),
127
    defaultValue: 0.00
128
  }
129
});
130
```
131

132
### Numeric Type Variants
133

134
Data types with additional options and variants.
135

136
```typescript { .api }
137
/**
138
 * Unsigned integers (positive values only)
139
 */
140
INTEGER.UNSIGNED: DataType;
141
BIGINT.UNSIGNED: DataType;
142
TINYINT.UNSIGNED: DataType;
143
SMALLINT.UNSIGNED: DataType;
144
MEDIUMINT.UNSIGNED: DataType;
145

146
/**
147
 * Zero-filled integers (pad with leading zeros)
148
 */
149
INTEGER.ZEROFILL: DataType;
150
BIGINT.ZEROFILL: DataType;
151

152
/**
153
 * Binary strings (affects collation)
154
 */
155
STRING.BINARY: DataType;
156
CHAR.BINARY: DataType;
157

158
/**
159
 * Number type (general purpose numeric)
160
 */
161
NUMBER: DataType;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
class Statistics extends Model {}
168
Statistics.init({
169
  // Unsigned integers for counts/IDs
170
  userId: {
171
    type: DataTypes.INTEGER.UNSIGNED,
172
    allowNull: false
173
  },
174
  
175
  // Zero-filled display
176
  orderNumber: {
177
    type: DataTypes.INTEGER.ZEROFILL,
178
    // Displays as 0000001234
179
  },
180
  
181
  // Binary string comparison
182
  token: {
183
    type: DataTypes.STRING.BINARY,
184
    // Case-sensitive comparison
185
  },
186
  
187
  // General numeric
188
  score: DataTypes.NUMBER
189
});
190
```
191

192
### Date and Time Types
193

194
Data types for temporal data.
195

196
```typescript { .api }
197
/**
198
 * Date and time with timezone
199
 */
200
DATE: DataType;
201

202
/**
203
 * Date only (no time component)
204
 */
205
DATEONLY: DataType;
206

207
/**
208
 * Time only (no date component)
209
 */
210
TIME: DataType;
211

212
/**
213
 * Current timestamp default value
214
 */
215
NOW: DataType;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
class Event extends Model {}
222
Event.init({
223
  startDate: DataTypes.DATE,
224
  endDate: DataTypes.DATE,
225
  eventDay: DataTypes.DATEONLY,
226
  startTime: DataTypes.TIME,
227
  createdAt: {
228
    type: DataTypes.DATE,
229
    defaultValue: DataTypes.NOW
230
  }
231
});
232
```
233

234
### Boolean Type
235

236
Data type for true/false values.
237

238
```typescript { .api }
239
/**
240
 * Boolean true/false value
241
 */
242
BOOLEAN: DataType;
243
```
244

245
**Usage Example:**
246

247
```typescript
248
class User extends Model {}
249
User.init({
250
  isActive: {
251
    type: DataTypes.BOOLEAN,
252
    defaultValue: true
253
  },
254
  isVerified: DataTypes.BOOLEAN
255
});
256
```
257

258
### Binary Types
259

260
Data types for binary data.
261

262
```typescript { .api }
263
/**
264
 * Binary large object
265
 * @param length - Optional length specification
266
 */
267
BLOB(length?: 'tiny' | 'medium' | 'long'): DataType;
268
```
269

270
**Usage Example:**
271

272
```typescript
273
class File extends Model {}
274
File.init({
275
  data: DataTypes.BLOB,
276
  thumbnail: DataTypes.BLOB('tiny'),
277
  content: DataTypes.BLOB('medium')
278
});
279
```
280

281
### UUID Types
282

283
Data types for universally unique identifiers.
284

285
```typescript { .api }
286
/**
287
 * UUID string format
288
 */
289
UUID: DataType;
290

291
/**
292
 * UUID v1 generator (default value)
293
 */
294
UUIDV1: DataType;
295

296
/**
297
 * UUID v4 generator (default value)
298
 */
299
UUIDV4: DataType;
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
class User extends Model {}
306
User.init({
307
  id: {
308
    type: DataTypes.UUID,
309
    defaultValue: DataTypes.UUIDV4,
310
    primaryKey: true
311
  },
312
  sessionId: {
313
    type: DataTypes.UUID,
314
    defaultValue: DataTypes.UUIDV1
315
  }
316
});
317
```
318

319
### JSON Types
320

321
Data types for JSON data storage.
322

323
```typescript { .api }
324
/**
325
 * JSON data type
326
 */
327
JSON: DataType;
328

329
/**
330
 * Binary JSON (PostgreSQL only)
331
 */
332
JSONB: DataType;
333
```
334

335
**Usage Examples:**
336

337
```typescript
338
class User extends Model {}
339
User.init({
340
  preferences: DataTypes.JSON,
341
  metadata: DataTypes.JSONB,    // PostgreSQL only
342
  profile: {
343
    type: DataTypes.JSON,
344
    defaultValue: {}
345
  }
346
});
347

348
// Usage
349
const user = await User.create({
350
  preferences: {
351
    theme: 'dark',
352
    notifications: true
353
  }
354
});
355
```
356

357
### Array Types
358

359
Data types for array storage (PostgreSQL only).
360

361
```typescript { .api }
362
/**
363
 * Array of specified type
364
 * @param type - Element data type
365
 */
366
ARRAY(type: DataType): DataType;
367
```
368

369
**Usage Examples:**
370

371
```typescript
372
class User extends Model {}
373
User.init({
374
  tags: DataTypes.ARRAY(DataTypes.STRING),
375
  scores: DataTypes.ARRAY(DataTypes.INTEGER),
376
  coordinates: DataTypes.ARRAY(DataTypes.FLOAT)
377
});
378

379
// Usage
380
const user = await User.create({
381
  tags: ['developer', 'javascript', 'node.js'],
382
  scores: [95, 87, 92],
383
  coordinates: [40.7128, -74.0060]
384
});
385
```
386

387
### Enum Types
388

389
Data types for enumerated values.
390

391
```typescript { .api }
392
/**
393
 * Enumeration with predefined values
394
 * @param values - Allowed values
395
 */
396
ENUM(...values: string[]): DataType;
397
```
398

399
**Usage Example:**
400

401
```typescript
402
class User extends Model {}
403
User.init({
404
  role: DataTypes.ENUM('admin', 'user', 'moderator'),
405
  status: {
406
    type: DataTypes.ENUM('active', 'inactive', 'pending'),
407
    defaultValue: 'pending'
408
  }
409
});
410
```
411

412
### Geometric Types
413

414
Data types for geometric data (PostgreSQL only).
415

416
```typescript { .api }
417
/**
418
 * Geometric data (points, lines, polygons)
419
 */
420
GEOMETRY: DataType;
421

422
/**
423
 * Geographic data with Earth model
424
 */
425
GEOGRAPHY: DataType;
426
```
427

428
**Usage Example:**
429

430
```typescript
431
class Location extends Model {}
432
Location.init({
433
  coordinates: DataTypes.GEOMETRY,
434
  area: DataTypes.GEOGRAPHY
435
});
436
```
437

438
### Network Types
439

440
Data types for network addresses (PostgreSQL only).
441

442
```typescript { .api }
443
/**
444
 * IP address (IPv4 or IPv6)
445
 */
446
INET: DataType;
447

448
/**
449
 * Network address with subnet mask
450
 */
451
CIDR: DataType;
452

453
/**
454
 * MAC address
455
 */
456
MACADDR: DataType;
457
```
458

459
**Usage Example:**
460

461
```typescript
462
class NetworkDevice extends Model {}
463
NetworkDevice.init({
464
  ipAddress: DataTypes.INET,
465
  subnet: DataTypes.CIDR,
466
  macAddress: DataTypes.MACADDR
467
});
468
```
469

470
### Other Specialized Types
471

472
Additional specialized data types.
473

474
```typescript { .api }
475
/**
476
 * Key-value store (PostgreSQL only)
477
 */
478
HSTORE: DataType;
479

480
/**
481
 * Range type (PostgreSQL only)
482
 * @param type - Range element type
483
 */
484
RANGE(type: DataType): DataType;
485

486
/**
487
 * Virtual computed field (not stored in database)
488
 */
489
VIRTUAL: DataType;
490

491
/**
492
 * Text search vector (PostgreSQL only)
493
 */
494
TSVECTOR: DataType;
495
```
496

497
**Usage Examples:**
498

499
```typescript
500
class Product extends Model {}
501
Product.init({
502
  // Key-value pairs
503
  attributes: DataTypes.HSTORE,
504
  
505
  // Date range
506
  availablePeriod: DataTypes.RANGE(DataTypes.DATE),
507
  
508
  // Virtual computed field
509
  fullName: {
510
    type: DataTypes.VIRTUAL,
511
    get() {
512
      return `${this.firstName} ${this.lastName}`;
513
    }
514
  },
515
  
516
  // Text search
517
  searchVector: DataTypes.TSVECTOR
518
});
519
```
520

521
### Data Type Options
522

523
Additional options available for all data types.
524

525
```typescript { .api }
526
interface DataTypeOptions {
527
  /** Allow null values */
528
  allowNull?: boolean;
529
  /** Default value */
530
  defaultValue?: any;
531
  /** Primary key */
532
  primaryKey?: boolean;
533
  /** Auto increment (numbers only) */
534
  autoIncrement?: boolean;
535
  /** Unique constraint */
536
  unique?: boolean | string;
537
  /** Column comment */
538
  comment?: string;
539
  /** Custom column name in database */
540
  field?: string;
541
  
542
  // String-specific options
543
  /** Binary string (affects collation) */
544
  binary?: boolean;
545
  /** Character set */
546
  charset?: string;
547
  /** Collation */
548
  collate?: string;
549
  
550
  // Numeric-specific options
551
  /** Unsigned integer */
552
  unsigned?: boolean;
553
  /** Zero fill */
554
  zerofill?: boolean;
555
}
556
```
557

558
**Usage Example with Options:**
559

560
```typescript
561
class User extends Model {}
562
User.init({
563
  id: {
564
    type: DataTypes.INTEGER,
565
    primaryKey: true,
566
    autoIncrement: true,
567
    unsigned: true
568
  },
569
  username: {
570
    type: DataTypes.STRING(50),
571
    allowNull: false,
572
    unique: true,
573
    comment: 'User login name'
574
  },
575
  email: {
576
    type: DataTypes.STRING,
577
    field: 'email_address',  // Different column name in DB
578
    defaultValue: null
579
  },
580
  balance: {
581
    type: DataTypes.DECIMAL(10, 2),
582
    unsigned: true,
583
    defaultValue: 0.00
584
  }
585
});
586
```