0
# Primitives and Basic Types
1

2
Core type checking for JavaScript primitive values and basic type detection functionality. Provides both type detection and boolean validation for all primitive types.
3

4
## Capabilities
5

6
### Type Detection
7

8
The main `is()` function returns the type name of any value as a string. Primitives are returned as lowercase strings, object types as camelcase.
9

10
```typescript { .api }
11
/**
12
 * Returns the type of value as a string
13
 * @param value - Any value to detect type of
14
 * @returns Type name string (primitives lowercase, objects camelcase)
15
 */
16
function is(value: unknown): TypeName;
17

18
// Also available as named export
19
function detect(value: unknown): TypeName;
20

21
type TypeName = ObjectTypeName | PrimitiveTypeName;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import is from '@sindresorhus/is';
28

29
is('hello'); // => 'string'
30
is(42); // => 'number'
31
is(true); // => 'boolean'
32
is(null); // => 'null'
33
is(undefined); // => 'undefined'
34
is(Symbol('test')); // => 'symbol'
35
is(123n); // => 'bigint'
36
is(new Date()); // => 'Date'
37
is([]); // => 'Array'
38
is({}); // => 'Object'
39
```
40

41
### String Type Checking
42

43
Check if a value is a string primitive.
44

45
```typescript { .api }
46
/**
47
 * Check if value is a string primitive
48
 * @param value - Value to check
49
 * @returns True if value is string
50
 */
51
function isString(value: unknown): value is string;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import is from '@sindresorhus/is';
58

59
is.string('hello'); // => true
60
is.string(123); // => false
61
is.string(new String('hello')); // => false (throws error for object wrappers)
62

63
// Type guard usage
64
function processText(input: unknown) {
65
  if (is.string(input)) {
66
    // input is now typed as string
67
    return input.toUpperCase();
68
  }
69
}
70
```
71

72
### Number Type Checking
73

74
Check if a value is a number primitive. Note that `NaN` returns `false` to provide user-friendly behavior.
75

76
```typescript { .api }
77
/**
78
 * Check if value is a number primitive (excludes NaN)
79
 * @param value - Value to check
80
 * @returns True if value is number and not NaN
81
 */
82
function isNumber(value: unknown): value is number;
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import is from '@sindresorhus/is';
89

90
is.number(42); // => true
91
is.number(3.14); // => true
92
is.number(NaN); // => false (intentionally excludes NaN)
93
is.number('42'); // => false
94
is.number(Infinity); // => true
95
is.number(-Infinity); // => true
96
```
97

98
### Boolean Type Checking
99

100
Check if a value is a boolean primitive.
101

102
```typescript { .api }
103
/**
104
 * Check if value is a boolean primitive
105
 * @param value - Value to check
106
 * @returns True if value is boolean
107
 */
108
function isBoolean(value: unknown): value is boolean;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import is from '@sindresorhus/is';
115

116
is.boolean(true); // => true
117
is.boolean(false); // => true
118
is.boolean(1); // => false
119
is.boolean('true'); // => false
120
```
121

122
### Symbol Type Checking
123

124
Check if a value is a symbol primitive.
125

126
```typescript { .api }
127
/**
128
 * Check if value is a symbol primitive
129
 * @param value - Value to check
130
 * @returns True if value is symbol
131
 */
132
function isSymbol(value: unknown): value is symbol;
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import is from '@sindresorhus/is';
139

140
is.symbol(Symbol('test')); // => true
141
is.symbol(Symbol.iterator); // => true
142
is.symbol('symbol'); // => false
143
```
144

145
### BigInt Type Checking
146

147
Check if a value is a bigint primitive.
148

149
```typescript { .api }
150
/**
151
 * Check if value is a bigint primitive
152
 * @param value - Value to check
153
 * @returns True if value is bigint
154
 */
155
function isBigint(value: unknown): value is bigint;
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
import is from '@sindresorhus/is';
162

163
is.bigint(123n); // => true
164
is.bigint(BigInt(456)); // => true
165
is.bigint(123); // => false
166
is.bigint('123n'); // => false
167
```
168

169
### Null Type Checking
170

171
Check if a value is null.
172

173
```typescript { .api }
174
/**
175
 * Check if value is null
176
 * @param value - Value to check
177
 * @returns True if value is null
178
 */
179
function isNull(value: unknown): value is null;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import is from '@sindresorhus/is';
186

187
is.null(null); // => true
188
is.null(undefined); // => false
189
is.null(0); // => false
190
is.null(''); // => false
191
```
192

193
### Undefined Type Checking
194

195
Check if a value is undefined.
196

197
```typescript { .api }
198
/**
199
 * Check if value is undefined
200
 * @param value - Value to check
201
 * @returns True if value is undefined
202
 */
203
function isUndefined(value: unknown): value is undefined;
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import is from '@sindresorhus/is';
210

211
is.undefined(undefined); // => true
212
is.undefined(null); // => false
213

214
let uninitialized;
215
is.undefined(uninitialized); // => true
216
```
217

218
### Combined Null or Undefined
219

220
Check if a value is either null or undefined.
221

222
```typescript { .api }
223
/**
224
 * Check if value is null or undefined
225
 * @param value - Value to check
226
 * @returns True if value is null or undefined
227
 */
228
function isNullOrUndefined(value: unknown): value is null | undefined;
229
```
230

231
**Usage Examples:**
232

233
```typescript
234
import is from '@sindresorhus/is';
235

236
is.nullOrUndefined(null); // => true
237
is.nullOrUndefined(undefined); // => true
238
is.nullOrUndefined(0); // => false
239
is.nullOrUndefined(''); // => false
240
```
241

242
### Primitive Type Checking
243

244
Check if a value is any JavaScript primitive type.
245

246
```typescript { .api }
247
/**
248
 * Check if value is a primitive type
249
 * @param value - Value to check
250
 * @returns True if value is primitive
251
 */
252
function isPrimitive(value: unknown): value is Primitive;
253

254
type Primitive = null | undefined | string | number | boolean | symbol | bigint;
255
```
256

257
**Usage Examples:**
258

259
```typescript
260
import is from '@sindresorhus/is';
261

262
is.primitive('hello'); // => true
263
is.primitive(42); // => true
264
is.primitive(null); // => true
265
is.primitive({}); // => false
266
is.primitive([]); // => false
267
is.primitive(() => {}); // => false
268
```
269

270
### NaN Detection
271

272
Check if a value is NaN (Not-a-Number).
273

274
```typescript { .api }
275
/**
276
 * Check if value is NaN
277
 * @param value - Value to check
278
 * @returns True if value is NaN
279
 */
280
function isNan(value: unknown): value is number;
281
```
282

283
**Usage Examples:**
284

285
```typescript
286
import is from '@sindresorhus/is';
287

288
is.nan(NaN); // => true
289
is.nan(Number('invalid')); // => true
290
is.nan(42); // => false
291
is.nan('NaN'); // => false
292
```
293

294
## Notes
295

296
- The library throws an error if you try to pass object-wrapped primitives (e.g., `new String('foo')`)
297
- `is.number()` intentionally excludes `NaN` for user-friendliness, use `is.nan()` to check for NaN specifically
298
- All primitive checks work with TypeScript type guards for compile-time type narrowing
299
- Tree-shakable named exports are available: `import { isString, isNumber } from '@sindresorhus/is'`