0
# Type Assertions
1

2
Methods for testing the type and class of values using JavaScript's built-in type system and constructor checking.
3

4
## Type Testing
5

6
### type()
7

8
Test the result of `typeof` operation.
9

10
```javascript { .api }
11
/**
12
 * Assert that typeof returns the specified type string
13
 * @param typeName - Expected type name ('string', 'number', 'boolean', etc.)
14
 * @param description - Optional error message
15
 * @returns This assertion for chaining
16
 */
17
type(typeName: string, description?: string): Assertion;
18
```
19

20
**Usage:**
21
```javascript
22
import should from 'should';
23

24
'hello'.should.have.type('string');
25
(42).should.have.type('number');
26
true.should.have.type('boolean');
27
undefined.should.have.type('undefined');
28
({}).should.have.type('object');
29
(() => {}).should.have.type('function');
30

31
// With description
32
const value = 'test';
33
value.should.have.type('string', 'Value should be a string');
34
```
35

36
### instanceof() / instanceOf()
37

38
Test if a value is an instance of a constructor function.
39

40
```javascript { .api }
41
/**
42
 * Assert that the value is an instance of the given constructor
43
 * @param constructor - Constructor function to test against
44
 * @param description - Optional error message
45
 * @returns This assertion for chaining
46
 */
47
instanceof(constructor: Function, description?: string): Assertion;
48
instanceOf(constructor: Function, description?: string): Assertion;
49
```
50

51
**Usage:**
52
```javascript
53
const date = new Date();
54
date.should.be.instanceof(Date);
55
date.should.be.instanceOf(Date);
56

57
const array = [1, 2, 3];
58
array.should.be.instanceof(Array);
59

60
const error = new Error('test');
61
error.should.be.instanceof(Error);
62

63
class CustomClass {}
64
const instance = new CustomClass();
65
instance.should.be.instanceof(CustomClass);
66

67
// With description
68
const regex = /test/;
69
regex.should.be.instanceof(RegExp, 'Should be a regular expression');
70
```
71

72
## Built-in Type Assertions
73

74
### Number()
75

76
Test that a value is a number.
77

78
```javascript { .api }
79
/**
80
 * Assert that the value is of type 'number'
81
 * @returns This assertion for chaining
82
 */
83
Number(): Assertion;
84
```
85

86
**Usage:**
87
```javascript
88
(42).should.be.a.Number();
89
(3.14).should.be.a.Number();
90
(-100).should.be.a.Number();
91
NaN.should.be.a.Number(); // NaN is still type 'number'
92
Infinity.should.be.a.Number();
93

94
// Chaining with other number assertions
95
(42).should.be.a.Number().and.be.above(0);
96
```
97

98
### String()
99

100
Test that a value is a string.
101

102
```javascript { .api }
103
/**
104
 * Assert that the value is of type 'string'
105
 * @returns This assertion for chaining
106
 */
107
String(): Assertion;
108
```
109

110
**Usage:**
111
```javascript
112
'hello'.should.be.a.String();
113
''.should.be.a.String();
114
`template`.should.be.a.String();
115

116
const message = 'test';
117
message.should.be.a.String().and.have.length(4);
118
```
119

120
### Boolean()
121

122
Test that a value is a boolean.
123

124
```javascript { .api }
125
/**
126
 * Assert that the value is of type 'boolean'  
127
 * @returns This assertion for chaining
128
 */
129
Boolean(): Assertion;
130
```
131

132
**Usage:**
133
```javascript
134
true.should.be.a.Boolean();
135
false.should.be.a.Boolean();
136

137
const isValid = true;
138
isValid.should.be.a.Boolean().and.be.true();
139
```
140

141
### Array()
142

143
Test that a value is an array.
144

145
```javascript { .api }
146
/**
147
 * Assert that the value is an Array instance
148
 * @returns This assertion for chaining
149
 */
150
Array(): Assertion;
151
```
152

153
**Usage:**
154
```javascript
155
[1, 2, 3].should.be.an.Array();
156
[].should.be.an.Array();
157

158
const items = ['a', 'b', 'c'];
159
items.should.be.an.Array().and.have.length(3);
160

161
// Arrays are also Objects in JavaScript
162
const arr = [1, 2, 3];
163
arr.should.be.an.Array().and.be.an.Object();
164
```
165

166
### Object()
167

168
Test that a value is an object.
169

170
```javascript { .api }
171
/**  
172
 * Assert that the value is of type 'object' (includes arrays, dates, etc.)
173
 * @returns This assertion for chaining
174
 */
175
Object(): Assertion;
176
```
177

178
**Usage:**
179
```javascript
180
({}).should.be.an.Object();
181
({ name: 'john' }).should.be.an.Object();
182

183
// Arrays, dates, and other objects are also Objects
184
[1, 2, 3].should.be.an.Object();
185
new Date().should.be.an.Object();
186
/regex/.should.be.an.Object();
187

188
const user = { name: 'john' };
189
user.should.be.an.Object().and.have.property('name');
190
```
191

192
### Function()
193

194
Test that a value is a function.
195

196
```javascript { .api }
197
/**
198
 * Assert that the value is of type 'function'
199
 * @returns This assertion for chaining
200
 */
201
Function(): Assertion;
202
```
203

204
**Usage:**
205
```javascript
206
(() => {}).should.be.a.Function();
207
function named() {}
208
named.should.be.a.Function();
209

210
class MyClass {}
211
MyClass.should.be.a.Function(); // Classes are functions
212

213
const callback = (x) => x * 2;
214
callback.should.be.a.Function();
215
```
216

217
### Date()
218

219
Test that a value is a Date instance.
220

221
```javascript { .api }
222
/**
223
 * Assert that the value is a Date instance
224
 * @returns This assertion for chaining
225
 */
226
Date(): Assertion;
227
```
228

229
**Usage:**
230
```javascript
231
new Date().should.be.a.Date();
232
new Date('2023-01-01').should.be.a.Date();
233

234
const timestamp = new Date();
235
timestamp.should.be.a.Date().and.be.instanceof(Date);
236
```
237

238
### Error()
239

240
Test that a value is an Error instance.
241

242
```javascript { .api }
243
/**
244
 * Assert that the value is an Error instance
245
 * @returns This assertion for chaining
246
 */
247
Error(): Assertion;
248
```
249

250
**Usage:**
251
```javascript
252
new Error().should.be.an.Error();
253
new TypeError().should.be.an.Error();
254
new RangeError().should.be.an.Error();
255

256
try {
257
  throw new Error('test error');
258
} catch (err) {
259
  err.should.be.an.Error().and.have.property('message', 'test error');
260
}
261
```
262

263
## Special Value Assertions
264

265
### null() / Null()
266

267
Test that a value is null.
268

269
```javascript { .api }
270
/**
271
 * Assert that the value is null
272
 * @returns This assertion for chaining
273
 */
274
null(): Assertion;
275
Null(): Assertion;
276
```
277

278
**Usage:**
279
```javascript
280
// Must use functional syntax since null has no properties
281
const should = require('should/as-function');
282

283
should(null).be.null();
284
should(null).be.Null();
285

286
let value = null;
287
should(value).be.null();
288
```
289

290
### undefined() / Undefined()
291

292
Test that a value is undefined.
293

294
```javascript { .api }
295
/**
296
 * Assert that the value is undefined
297
 * @returns This assertion for chaining
298
 */
299
undefined(): Assertion;
300
Undefined(): Assertion;
301
```
302

303
**Usage:**
304
```javascript
305
const should = require('should/as-function');
306

307
should(undefined).be.undefined();
308
should(undefined).be.Undefined();
309

310
let uninitialized;
311
should(uninitialized).be.undefined();
312

313
const obj = {};
314
should(obj.nonexistent).be.undefined();
315
```
316

317
### arguments() / Arguments()
318

319
Test that a value is an arguments object.
320

321
```javascript { .api }
322
/**
323
 * Assert that the value is an arguments object
324
 * @returns This assertion for chaining
325
 */
326
arguments(): Assertion;
327
Arguments(): Assertion;
328
```
329

330
**Usage:**
331
```javascript
332
function testFunction() {
333
  arguments.should.be.arguments();
334
  arguments.should.be.Arguments();
335
}
336

337
testFunction(1, 2, 3);
338

339
// Arguments objects are array-like but not arrays
340
function compare() {
341
  arguments.should.be.arguments();
342
  arguments.should.not.be.an.Array();
343
}
344
```
345

346
## Advanced Type Testing
347

348
### class() / Class()
349

350
Test that a value has a specific class name via `Object.prototype.toString`.
351

352
```javascript { .api }
353
/**
354
 * Assert that the value has the specified class name
355
 * @param className - Expected class name from Object.prototype.toString
356
 * @returns This assertion for chaining
357
 */
358
class(className: string): Assertion;
359
Class(className: string): Assertion;
360
```
361

362
**Usage:**
363
```javascript
364
[].should.have.class('Array');
365
{}.should.have.class('Object');
366
new Date().should.have.class('Date');
367
/regex/.should.have.class('RegExp');
368
'string'.should.have.class('String');
369
(42).should.have.class('Number');
370

371
// Custom class names  
372
class CustomClass {}
373
const instance = new CustomClass();
374
instance.should.have.class('Object'); // Custom classes show as 'Object'
375
```
376

377
### iterable()
378

379
Test that a value is iterable (has Symbol.iterator).
380

381
```javascript { .api }
382
/**
383
 * Assert that the value is iterable (implements Symbol.iterator)
384
 * @returns This assertion for chaining
385
 */
386
iterable(): Assertion;
387
```
388

389
**Usage:**
390
```javascript
391
[1, 2, 3].should.be.iterable();
392
'hello'.should.be.iterable();
393
new Set([1, 2, 3]).should.be.iterable();
394
new Map().should.be.iterable();
395

396
// Objects are not iterable by default
397
({}).should.not.be.iterable();
398
```
399

400
### iterator()
401

402
Test that a value is an iterator (has next method).
403

404
```javascript { .api }
405
/**
406
 * Assert that the value is an iterator (has next method)
407
 * @returns This assertion for chaining
408
 */
409
iterator(): Assertion;
410
```
411

412
**Usage:**
413
```javascript
414
const arr = [1, 2, 3];
415
const iter = arr[Symbol.iterator]();
416
iter.should.be.iterator();
417

418
const set = new Set([1, 2, 3]);
419
const setIter = set.values();
420
setIter.should.be.iterator();
421
```
422

423
### generator()
424

425
Test that a value is a generator object.
426

427
```javascript { .api }
428
/**
429
 * Assert that the value is a generator object
430
 * @returns This assertion for chaining
431
 */
432
generator(): Assertion;
433
```
434

435
**Usage:**
436
```javascript
437
function* generatorFunc() {
438
  yield 1;
439
  yield 2;
440
}
441

442
const gen = generatorFunc();
443
gen.should.be.generator();
444

445
// Generator functions themselves are not generators
446
generatorFunc.should.not.be.generator();
447
generatorFunc.should.be.a.Function();
448
```
449

450
## Negation and Chaining
451

452
All type assertions can be negated and chained:
453

454
```javascript
455
const value = 'hello';
456
value.should.not.be.a.Number();
457
value.should.be.a.String().and.not.be.empty();
458

459
const obj = { count: 5 };
460
obj.should.be.an.Object().and.not.be.an.Array();
461
obj.count.should.be.a.Number().and.not.be.a.String();
462
```