1 | # is [![Build Status](https://travis-ci.org/sindresorhus/is.svg?branch=master)](https://travis-ci.org/sindresorhus/is)
|
2 |
|
3 | > Type check values: `is.string('🦄') //=> true`
|
4 |
|
5 | <img src="header.gif" width="182" align="right">
|
6 |
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```
|
11 | $ npm install @sindresorhus/is
|
12 | ```
|
13 |
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```js
|
18 | const is = require('@sindresorhus/is');
|
19 |
|
20 | is('🦄');
|
21 | //=> 'string'
|
22 |
|
23 | is(new Map());
|
24 | //=> 'Map'
|
25 |
|
26 | is.number(6);
|
27 | //=> true
|
28 | ```
|
29 |
|
30 | When using `is` together with TypeScript, [type guards](http://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types) are being used to infer the correct type inside if-else statements.
|
31 |
|
32 | ```ts
|
33 | import is from '@sindresorhus/is';
|
34 |
|
35 | const padLeft = (value: string, padding: string | number) => {
|
36 | if (is.number(padding)) {
|
37 | // `padding` is typed as `number`
|
38 | return Array(padding + 1).join(' ') + value;
|
39 | }
|
40 |
|
41 | if (is.string(padding)) {
|
42 | // `padding` is typed as `string`
|
43 | return padding + value;
|
44 | }
|
45 |
|
46 | throw new TypeError(`Expected 'padding' to be of type 'string' or 'number', got '${is(padding)}'.`);
|
47 | }
|
48 |
|
49 | padLeft('🦄', 3);
|
50 | //=> ' 🦄'
|
51 |
|
52 | padLeft('🦄', '🌈');
|
53 | //=> '🌈🦄'
|
54 | ```
|
55 |
|
56 |
|
57 | ## API
|
58 |
|
59 | ### is(value)
|
60 |
|
61 | Returns the type of `value`.
|
62 |
|
63 | Primitives are lowercase and object types are camelcase.
|
64 |
|
65 | Example:
|
66 |
|
67 | - `'undefined'`
|
68 | - `'null'`
|
69 | - `'string'`
|
70 | - `'symbol'`
|
71 | - `'Array'`
|
72 | - `'Function'`
|
73 | - `'Object'`
|
74 |
|
75 | Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice. For example `new String('foo')`.
|
76 |
|
77 | ### is.{method}
|
78 |
|
79 | All the below methods accept a value and returns a boolean for whether the value is of the desired type.
|
80 |
|
81 | #### Primitives
|
82 |
|
83 | ##### .undefined(value)
|
84 | ##### .null(value)
|
85 | ##### .string(value)
|
86 | ##### .number(value)
|
87 | ##### .boolean(value)
|
88 | ##### .symbol(value)
|
89 |
|
90 | #### Built-in types
|
91 |
|
92 | ##### .array(value)
|
93 | ##### .function(value)
|
94 | ##### .buffer(value)
|
95 | ##### .object(value)
|
96 |
|
97 | Keep in mind that [functions are objects too](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions).
|
98 |
|
99 | ##### .regExp(value)
|
100 | ##### .date(value)
|
101 | ##### .error(value)
|
102 | ##### .nativePromise(value)
|
103 | ##### .promise(value)
|
104 |
|
105 | Returns `true` for any object with a `.then()` and `.catch()` method. Prefer this one over `.nativePromise()` as you usually want to allow userland promise implementations too.
|
106 |
|
107 | ##### .generator(value)
|
108 |
|
109 | Returns `true` for any object that implements its own `.next()` and `.throw()` methods and has a function definition for `Symbol.iterator`.
|
110 |
|
111 | ##### .generatorFunction(value)
|
112 |
|
113 | ##### .asyncFunction(value)
|
114 |
|
115 | Returns `true` for any `async` function that can be called with the `await` operator.
|
116 |
|
117 | ```js
|
118 | is.asyncFunction(async () => {});
|
119 | // => true
|
120 |
|
121 | is.asyncFunction(() => {});
|
122 | // => false
|
123 | ```
|
124 |
|
125 | ##### .boundFunction(value)
|
126 |
|
127 | Returns `true` for any `bound` function.
|
128 |
|
129 | ```js
|
130 | is.boundFunction(() => {});
|
131 | // => true
|
132 |
|
133 | is.boundFunction(function () {}.bind(null));
|
134 | // => true
|
135 |
|
136 | is.boundFunction(function () {});
|
137 | // => false
|
138 | ```
|
139 |
|
140 | ##### .map(value)
|
141 | ##### .set(value)
|
142 | ##### .weakMap(value)
|
143 | ##### .weakSet(value)
|
144 |
|
145 | #### Typed arrays
|
146 |
|
147 | ##### .int8Array(value)
|
148 | ##### .uint8Array(value)
|
149 | ##### .uint8ClampedArray(value)
|
150 | ##### .int16Array(value)
|
151 | ##### .uint16Array(value)
|
152 | ##### .int32Array(value)
|
153 | ##### .uint32Array(value)
|
154 | ##### .float32Array(value)
|
155 | ##### .float64Array(value)
|
156 |
|
157 | #### Structured data
|
158 |
|
159 | ##### .arrayBuffer(value)
|
160 | ##### .sharedArrayBuffer(value)
|
161 | ##### .dataView(value)
|
162 |
|
163 | #### Miscellaneous
|
164 |
|
165 | ##### .directInstanceOf(value, class)
|
166 |
|
167 | Returns `true` if `value` is a direct instance of `class`.
|
168 |
|
169 | ```js
|
170 | is.directInstanceOf(new Error(), Error);
|
171 | //=> true
|
172 |
|
173 | class UnicornError extends Error {};
|
174 |
|
175 | is.directInstanceOf(new UnicornError(), Error);
|
176 | //=> false
|
177 | ```
|
178 |
|
179 | ##### .urlInstance(value)
|
180 |
|
181 | Returns `true` if `value` is an instance of the [`URL` class](https://developer.mozilla.org/en-US/docs/Web/API/URL).
|
182 |
|
183 | ```js
|
184 | const url = new URL('https://example.com');
|
185 |
|
186 | is.urlInstance(url);
|
187 | //=> true
|
188 | ```
|
189 |
|
190 | ##### .truthy(value)
|
191 |
|
192 | Returns `true` for all values that evaluate to true in a boolean context:
|
193 |
|
194 | ```js
|
195 | is.truthy('🦄');
|
196 | //=> true
|
197 |
|
198 | is.truthy(undefined);
|
199 | //=> false
|
200 | ```
|
201 |
|
202 | ##### .falsy(value)
|
203 |
|
204 | Returns `true` if `value` is one of: `false`, `0`, `''`, `null`, `undefined`, `NaN`.
|
205 |
|
206 | ##### .nan(value)
|
207 | ##### .nullOrUndefined(value)
|
208 | ##### .primitive(value)
|
209 |
|
210 | JavaScript primitives are as follows: `null`, `undefined`, `string`, `number`, `boolean`, `symbol`.
|
211 |
|
212 | ##### .integer(value)
|
213 |
|
214 | ##### .safeInteger(value)
|
215 |
|
216 | Returns `true` if `value` is a [safe integer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).
|
217 |
|
218 | ##### .plainObject(value)
|
219 |
|
220 | An object is plain if it's created by either `{}`, `new Object()`, or `Object.create(null)`.
|
221 |
|
222 | ##### .iterable(value)
|
223 | ##### .asyncIterable(value)
|
224 | ##### .class(value)
|
225 |
|
226 | Returns `true` for instances created by a ES2015 class.
|
227 |
|
228 | ##### .typedArray(value)
|
229 |
|
230 | ##### .arrayLike(value)
|
231 |
|
232 | A `value` is array-like if it is not a function and has a `value.length` that is a safe integer greater than or equal to 0.
|
233 |
|
234 | ```js
|
235 | is.arrayLike(document.forms);
|
236 | //=> true
|
237 |
|
238 | function () {
|
239 | is.arrayLike(arguments);
|
240 | //=> true
|
241 | }
|
242 | ```
|
243 |
|
244 | ##### .inRange(value, range)
|
245 |
|
246 | Check if `value` (number) is in the given `range`. The range is an array of two values, lower bound and upper bound, in no specific order.
|
247 |
|
248 | ```js
|
249 | is.inRange(3, [0, 5]);
|
250 | is.inRange(3, [5, 0]);
|
251 | is.inRange(0, [-2, 2]);
|
252 | ```
|
253 |
|
254 | ##### .inRange(value, upperBound)
|
255 |
|
256 | Check if `value` (number) is in the range of `0` to `upperBound`.
|
257 |
|
258 | ```js
|
259 | is.inRange(3, 10);
|
260 | ```
|
261 |
|
262 | ##### .domElement(value)
|
263 |
|
264 | Returns `true` if `value` is a DOM Element.
|
265 |
|
266 | ##### .nodeStream(value)
|
267 |
|
268 | Returns `true` if `value` is a Node.js [stream](https://nodejs.org/api/stream.html).
|
269 |
|
270 | ```js
|
271 | const fs = require('fs');
|
272 | is.nodeStream(fs.createReadStream('unicorn.png'));
|
273 | //=> true
|
274 | ```
|
275 |
|
276 | ##### .observable(value)
|
277 |
|
278 | Returns `true` if `value` is an `Observable`.
|
279 |
|
280 | ```js
|
281 | const {Observable} = require('rxjs');
|
282 | is.observable(new Observable());
|
283 | //=> true
|
284 | ```
|
285 |
|
286 | ##### .infinite(value)
|
287 |
|
288 | Check if `value` is `Infinity` or `-Infinity`.
|
289 |
|
290 | ##### .even(value)
|
291 |
|
292 | Returns `true` if `value` is an even integer.
|
293 |
|
294 | ##### .odd(value)
|
295 |
|
296 | Returns `true` if `value` is an odd integer.
|
297 |
|
298 | ##### .empty(value)
|
299 |
|
300 | Returns `true` if `value` is falsy or an empty string, array, object, map, or set.
|
301 |
|
302 | ##### .emptyOrWhitespace(value)
|
303 |
|
304 | Returns `true` if `is.empty(value)` or a string that is all whitespace.
|
305 |
|
306 | ##### .any(predicate, ...values)
|
307 |
|
308 | Returns `true` if **any** of the input `values` returns true in the `predicate`:
|
309 |
|
310 | ```js
|
311 | is.any(is.string, {}, true, '🦄');
|
312 | //=> true
|
313 |
|
314 | is.any(is.boolean, 'unicorns', [], new Map());
|
315 | //=> false
|
316 | ```
|
317 |
|
318 | ##### .all(predicate, ...values)
|
319 |
|
320 | Returns `true` if **all** of the input `values` returns true in the `predicate`:
|
321 |
|
322 | ```js
|
323 | is.all(is.object, {}, new Map(), new Set());
|
324 | //=> true
|
325 |
|
326 | is.all(is.string, '🦄', [], 'unicorns');
|
327 | //=> false
|
328 | ```
|
329 |
|
330 |
|
331 | ## FAQ
|
332 |
|
333 | ### Why yet another type checking module?
|
334 |
|
335 | There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:
|
336 |
|
337 | - Includes both type methods and ability to get the type
|
338 | - Types of primitives returned as lowercase and object types as camelcase
|
339 | - Covers all built-ins
|
340 | - Unsurprising behavior
|
341 | - Well-maintained
|
342 | - Comprehensive test suite
|
343 |
|
344 | For the ones I found, pick 3 of these.
|
345 |
|
346 | The most common mistakes I noticed in these modules was using `instanceof` for type checking, forgetting that functions are objects, and omitting `symbol` as a primitive.
|
347 |
|
348 |
|
349 | ## Related
|
350 |
|
351 | - [ow](https://github.com/sindresorhus/ow) - Function argument validation for humans
|
352 | - [is-stream](https://github.com/sindresorhus/is-stream) - Check if something is a Node.js stream
|
353 | - [is-observable](https://github.com/sindresorhus/is-observable) - Check if a value is an Observable
|
354 | - [file-type](https://github.com/sindresorhus/file-type) - Detect the file type of a Buffer/Uint8Array
|
355 | - [is-ip](https://github.com/sindresorhus/is-ip) - Check if a string is an IP address
|
356 | - [is-array-sorted](https://github.com/sindresorhus/is-array-sorted) - Check if an Array is sorted
|
357 | - [is-error-constructor](https://github.com/sindresorhus/is-error-constructor) - Check if a value is an error constructor
|
358 | - [is-empty-iterable](https://github.com/sindresorhus/is-empty-iterable) - Check if an Iterable is empty
|
359 | - [is-blob](https://github.com/sindresorhus/is-blob) - Check if a value is a Blob - File-like object of immutable, raw data
|
360 | - [has-emoji](https://github.com/sindresorhus/has-emoji) - Check whether a string has any emoji
|
361 |
|
362 |
|
363 | ## Created by
|
364 |
|
365 | - [Sindre Sorhus](https://github.com/sindresorhus)
|
366 | - [Giora Guttsait](https://github.com/gioragutt)
|
367 | - [Brandon Smith](https://github.com/brandon93s)
|
368 |
|
369 |
|
370 | ## License
|
371 |
|
372 | MIT
|