0
# @sindresorhus/is
1

2
@sindresorhus/is is a comprehensive TypeScript type checking library that provides runtime type validation with extensive TypeScript type guards and assertion methods. It offers both validation functions (returning boolean) and assertion functions (throwing errors), enabling reliable type checking for all JavaScript built-in types, web APIs, and Node.js specific objects.
3

4
## Package Information
5

6
- **Package Name**: @sindresorhus/is
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @sindresorhus/is`
10

11
## Core Imports
12

13
```typescript
14
import is from '@sindresorhus/is';
15
import { assert } from '@sindresorhus/is';
16
```
17

18
For tree-shakable imports:
19

20
```typescript
21
import { isString, isNumber, assertArray } from '@sindresorhus/is';
22
```
23

24
CommonJS:
25

26
```javascript
27
const is = require('@sindresorhus/is');
28
const { assert } = require('@sindresorhus/is');
29
```
30

31
Named export for type detection:
32

33
```typescript
34
import { detect } from '@sindresorhus/is';
35
// detect is the same as the default is function
36
```
37

38
## Basic Usage
39

40
```typescript
41
import is from '@sindresorhus/is';
42
import { assert } from '@sindresorhus/is';
43

44
// Type detection - returns string type name
45
is('hello'); // => 'string'
46
is(42); // => 'number'
47
is(new Map()); // => 'Map'
48

49
// Type validation - returns boolean
50
is.string('hello'); // => true
51
is.number('hello'); // => false
52

53
// Type assertions - throws if type doesn't match
54
assert.string('hello'); // passes
55
assert.number('hello'); // throws TypeError
56

57
// TypeScript type guards
58
function processValue(value: unknown) {
59
  if (is.string(value)) {
60
    // value is now typed as string
61
    return value.toUpperCase();
62
  }
63
  
64
  if (is.number(value)) {
65
    // value is now typed as number
66
    return value * 2;
67
  }
68
}
69

70
// Array validation with item assertion
71
const numbers = [1, 2, 3];
72
if (is.array(numbers, is.number)) {
73
  // numbers is typed as number[]
74
  console.log(numbers.map(n => n * 2));
75
}
76
```
77

78
## Architecture
79

80
@sindresorhus/is is built around several key components:
81

82
- **Type Detection**: Core `is()` function returns string type names for any value
83
- **Type Guards**: Boolean-returning methods that provide TypeScript type narrowing
84
- **Assertions**: Error-throwing methods for runtime type validation with custom messages
85
- **Tree Shaking**: All methods available as named exports for optimal bundle size
86
- **Generic Support**: Type-aware generics with runtime safety considerations
87
- **Comprehensive Coverage**: Support for all JavaScript built-ins, web APIs, and Node.js types
88

89
## Capabilities
90

91
### Primitives and Basic Types
92

93
Core type checking for JavaScript primitive values including string, number, boolean, symbol, bigint, null, and undefined.
94

95
```typescript { .api }
96
function is(value: unknown): TypeName;
97

98
// Type guards for primitives
99
function isString(value: unknown): value is string;
100
function isNumber(value: unknown): value is number;
101
function isBoolean(value: unknown): value is boolean;
102
function isSymbol(value: unknown): value is symbol;
103
function isBigint(value: unknown): value is bigint;
104
function isNull(value: unknown): value is null;
105
function isUndefined(value: unknown): value is undefined;
106
```
107

108
[Primitives and Basic Types](./primitives.md)
109

110
### Objects and Built-in Types
111

112
Type checking for JavaScript built-in objects including arrays, functions, dates, regular expressions, maps, sets, and more.
113

114
```typescript { .api }
115
function isArray<T = unknown>(value: unknown, assertion?: (value: T) => value is T): value is T[];
116
function isFunction(value: unknown): value is Function;
117
function isObject(value: unknown): value is object;
118
function isDate(value: unknown): value is Date;
119
function isRegExp(value: unknown): value is RegExp;
120
function isMap<Key = unknown, Value = unknown>(value: unknown): value is Map<Key, Value>;
121
function isSet<T = unknown>(value: unknown): value is Set<T>;
122
```
123

124
[Objects and Built-in Types](./objects.md)
125

126
### Collections and Emptiness
127

128
Specialized checks for empty and non-empty collections including arrays, objects, strings, maps, and sets.
129

130
```typescript { .api }
131
function isEmptyArray(value: unknown): value is never[];
132
function isNonEmptyArray<T = unknown, Item = unknown>(value: T | Item[]): value is [Item, ...Item[]];
133
function isEmptyObject<Key extends keyof any = string>(value: unknown): value is Record<Key, never>;
134
function isNonEmptyObject<Key extends keyof any = string, Value = unknown>(value: unknown): value is Record<Key, Value>;
135
function isEmptyString(value: unknown): value is '';
136
function isNonEmptyString(value: unknown): value is NonEmptyString;
137
```
138

139
[Collections and Emptiness](./collections.md)
140

141
### Async and Promises
142

143
Type checking for promises, async functions, generators, and iterables including both sync and async variants.
144

145
```typescript { .api }
146
function isPromise<T = unknown>(value: unknown): value is Promise<T>;
147
function isNativePromise<T = unknown>(value: unknown): value is Promise<T>;
148
function isAsyncFunction<T = unknown>(value: unknown): value is ((...arguments_: any[]) => Promise<T>);
149
function isAsyncGenerator(value: unknown): value is AsyncGenerator;
150
function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T>;
151
function isGenerator(value: unknown): value is Generator;
152
function isIterable<T = unknown>(value: unknown): value is Iterable<T>;
153
```
154

155
[Async and Promises](./async.md)
156

157
### Typed Arrays and Binary Data
158

159
Type checking for typed arrays, array buffers, and binary data structures including all variants of typed arrays.
160

161
```typescript { .api }
162
function isTypedArray(value: unknown): value is TypedArray;
163
function isArrayBuffer(value: unknown): value is ArrayBuffer;
164
function isSharedArrayBuffer(value: unknown): value is SharedArrayBuffer;
165
function isDataView(value: unknown): value is DataView;
166
function isInt8Array(value: unknown): value is Int8Array;
167
function isUint8Array(value: unknown): value is Uint8Array;
168
function isFloat32Array(value: unknown): value is Float32Array;
169
function isFloat64Array(value: unknown): value is Float64Array;
170
```
171

172
[Typed Arrays and Binary Data](./typed-arrays.md)
173

174
### Numbers and Math
175

176
Specialized number validation including integers, safe integers, positive/negative numbers, even/odd checks, and range validation.
177

178
```typescript { .api }
179
function isInteger(value: unknown): value is number;
180
function isSafeInteger(value: unknown): value is number;
181
function isPositiveNumber(value: unknown): value is number;
182
function isNegativeNumber(value: unknown): value is number;
183
function isEvenInteger(value: unknown): value is number;
184
function isOddInteger(value: unknown): value is number;
185
function isInfinite(value: unknown): value is number;
186
function isInRange(value: number, range: number | [number, number]): value is number;
187
```
188

189
[Numbers and Math](./numbers.md)
190

191
### Strings and Text
192

193
String-specific validation including empty strings, whitespace detection, numeric strings, URL strings, and text content validation.
194

195
```typescript { .api }
196
function isEmptyString(value: unknown): value is '';
197
function isEmptyStringOrWhitespace(value: unknown): value is '' | Whitespace;
198
function isNonEmptyStringAndNotWhitespace(value: unknown): value is NonEmptyString;
199
function isNumericString(value: unknown): value is `${number}`;
200
function isUrlString(value: unknown): value is string;
201
function isWhitespaceString(value: unknown): value is Whitespace;
202
```
203

204
[Strings and Text](./strings.md)
205

206
### Web APIs and DOM
207

208
Type checking for web-specific APIs including DOM elements, form data, URL objects, and browser-specific types.
209

210
```typescript { .api }
211
function isHtmlElement(value: unknown): value is HTMLElement;
212
function isBlob(value: unknown): value is Blob;
213
function isFormData(value: unknown): value is FormData;
214
function isUrlInstance(value: unknown): value is URL;
215
function isUrlSearchParams(value: unknown): value is URLSearchParams;
216
```
217

218
[Web APIs and DOM](./web-apis.md)
219

220
### Validation and Logic
221

222
Multi-value validation, logical operations, and specialized validation patterns including predicate testing and enum checking.
223

224
```typescript { .api }
225
function isAll(predicate: Predicate, ...values: unknown[]): boolean;
226
function isAny(predicate: Predicate | Predicate[], ...values: unknown[]): boolean;
227
function isTruthy<T>(value: T | Falsy): value is T;
228
function isFalsy(value: unknown): value is Falsy;
229
function isEnumCase<T = unknown>(value: unknown, targetEnum: T): value is T[keyof T];
230
function isDirectInstanceOf<T>(instance: unknown, class_: Class<T>): instance is T;
231
```
232

233
[Validation and Logic](./validation.md)
234

235
### Assertions
236

237
Error-throwing assertion methods corresponding to all type checking functions, with optional custom error messages.
238

239
```typescript { .api }
240
interface Assert {
241
  string: (value: unknown, message?: string) => asserts value is string;
242
  number: (value: unknown, message?: string) => asserts value is number;
243
  array: <T = unknown>(value: unknown, assertion?: (element: unknown) => asserts element is T, message?: string) => asserts value is T[];
244
  all: (predicate: Predicate, ...values: unknown[]) => void | never;
245
  any: (predicate: Predicate | Predicate[], ...values: unknown[]) => void | never;
246
}
247

248
const assert: Assert;
249
```
250

251
[Assertions](./assertions.md)
252

253
## Types
254

255
```typescript { .api }
256
type TypeName = ObjectTypeName | PrimitiveTypeName;
257
type AssertionTypeDescription = string;
258

259
type Primitive = null | undefined | string | number | boolean | symbol | bigint;
260
type Class<T, Arguments extends unknown[] = any[]> = Constructor<T, Arguments> & {prototype: T};
261
type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
262
type ObservableLike = {
263
  subscribe(observer: (value: unknown) => void): void;
264
  [Symbol.observable](): ObservableLike;
265
};
266
type Falsy = false | 0 | 0n | '' | null | undefined;
267
type ArrayLike<T> = {
268
  readonly [index: number]: T;
269
  readonly length: number;
270
};
271
type NodeStream = {
272
  pipe<T extends NodeJS.WritableStream>(destination: T, options?: {end?: boolean}): T;
273
} & NodeJS.EventEmitter;
274
type Predicate = (value: unknown) => boolean;
275
type NonEmptyString = string & {0: string};
276
type Whitespace = ' ';
277
```