README.md (11769B)
1 # kind-of [](https://www.npmjs.com/package/kind-of) [](https://npmjs.org/package/kind-of) [](https://npmjs.org/package/kind-of) [](https://travis-ci.org/jonschlinkert/kind-of) 2 3 > Get the native type of a value. 4 5 Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support. 6 7 ## Install 8 9 Install with [npm](https://www.npmjs.com/): 10 11 ```sh 12 $ npm install --save kind-of 13 ``` 14 15 Install with [bower](https://bower.io/) 16 17 ```sh 18 $ bower install kind-of --save 19 ``` 20 21 ## Why use this? 22 23 1. [it's fast](#benchmarks) | [optimizations](#optimizations) 24 2. [better type checking](#better-type-checking) 25 26 ## Usage 27 28 > es5, es6, and browser ready 29 30 ```js 31 var kindOf = require('kind-of'); 32 33 kindOf(undefined); 34 //=> 'undefined' 35 36 kindOf(null); 37 //=> 'null' 38 39 kindOf(true); 40 //=> 'boolean' 41 42 kindOf(false); 43 //=> 'boolean' 44 45 kindOf(new Buffer('')); 46 //=> 'buffer' 47 48 kindOf(42); 49 //=> 'number' 50 51 kindOf('str'); 52 //=> 'string' 53 54 kindOf(arguments); 55 //=> 'arguments' 56 57 kindOf({}); 58 //=> 'object' 59 60 kindOf(Object.create(null)); 61 //=> 'object' 62 63 kindOf(new Test()); 64 //=> 'object' 65 66 kindOf(new Date()); 67 //=> 'date' 68 69 kindOf([1, 2, 3]); 70 //=> 'array' 71 72 kindOf(/foo/); 73 //=> 'regexp' 74 75 kindOf(new RegExp('foo')); 76 //=> 'regexp' 77 78 kindOf(new Error('error')); 79 //=> 'error' 80 81 kindOf(function () {}); 82 //=> 'function' 83 84 kindOf(function * () {}); 85 //=> 'generatorfunction' 86 87 kindOf(Symbol('str')); 88 //=> 'symbol' 89 90 kindOf(new Map()); 91 //=> 'map' 92 93 kindOf(new WeakMap()); 94 //=> 'weakmap' 95 96 kindOf(new Set()); 97 //=> 'set' 98 99 kindOf(new WeakSet()); 100 //=> 'weakset' 101 102 kindOf(new Int8Array()); 103 //=> 'int8array' 104 105 kindOf(new Uint8Array()); 106 //=> 'uint8array' 107 108 kindOf(new Uint8ClampedArray()); 109 //=> 'uint8clampedarray' 110 111 kindOf(new Int16Array()); 112 //=> 'int16array' 113 114 kindOf(new Uint16Array()); 115 //=> 'uint16array' 116 117 kindOf(new Int32Array()); 118 //=> 'int32array' 119 120 kindOf(new Uint32Array()); 121 //=> 'uint32array' 122 123 kindOf(new Float32Array()); 124 //=> 'float32array' 125 126 kindOf(new Float64Array()); 127 //=> 'float64array' 128 ``` 129 130 ## Benchmarks 131 132 Benchmarked against [typeof](http://github.com/CodingFu/typeof) and [type-of](https://github.com/ForbesLindesay/type-of). 133 134 ```bash 135 # arguments (32 bytes) 136 kind-of x 17,024,098 ops/sec ±1.90% (86 runs sampled) 137 lib-type-of x 11,926,235 ops/sec ±1.34% (83 runs sampled) 138 lib-typeof x 9,245,257 ops/sec ±1.22% (87 runs sampled) 139 140 fastest is kind-of (by 161% avg) 141 142 # array (22 bytes) 143 kind-of x 17,196,492 ops/sec ±1.07% (88 runs sampled) 144 lib-type-of x 8,838,283 ops/sec ±1.02% (87 runs sampled) 145 lib-typeof x 8,677,848 ops/sec ±0.87% (87 runs sampled) 146 147 fastest is kind-of (by 196% avg) 148 149 # boolean (24 bytes) 150 kind-of x 16,841,600 ops/sec ±1.10% (86 runs sampled) 151 lib-type-of x 8,096,787 ops/sec ±0.95% (87 runs sampled) 152 lib-typeof x 8,423,345 ops/sec ±1.15% (86 runs sampled) 153 154 fastest is kind-of (by 204% avg) 155 156 # buffer (38 bytes) 157 kind-of x 14,848,060 ops/sec ±1.05% (86 runs sampled) 158 lib-type-of x 3,671,577 ops/sec ±1.49% (87 runs sampled) 159 lib-typeof x 8,360,236 ops/sec ±1.24% (86 runs sampled) 160 161 fastest is kind-of (by 247% avg) 162 163 # date (30 bytes) 164 kind-of x 16,067,761 ops/sec ±1.58% (86 runs sampled) 165 lib-type-of x 8,954,436 ops/sec ±1.40% (87 runs sampled) 166 lib-typeof x 8,488,307 ops/sec ±1.51% (84 runs sampled) 167 168 fastest is kind-of (by 184% avg) 169 170 # error (36 bytes) 171 kind-of x 9,634,090 ops/sec ±1.12% (89 runs sampled) 172 lib-type-of x 7,735,624 ops/sec ±1.32% (86 runs sampled) 173 lib-typeof x 7,442,160 ops/sec ±1.11% (90 runs sampled) 174 175 fastest is kind-of (by 127% avg) 176 177 # function (34 bytes) 178 kind-of x 10,031,494 ops/sec ±1.27% (86 runs sampled) 179 lib-type-of x 9,502,757 ops/sec ±1.17% (89 runs sampled) 180 lib-typeof x 8,278,985 ops/sec ±1.08% (88 runs sampled) 181 182 fastest is kind-of (by 113% avg) 183 184 # null (24 bytes) 185 kind-of x 18,159,808 ops/sec ±1.92% (86 runs sampled) 186 lib-type-of x 12,927,635 ops/sec ±1.01% (88 runs sampled) 187 lib-typeof x 7,958,234 ops/sec ±1.21% (89 runs sampled) 188 189 fastest is kind-of (by 174% avg) 190 191 # number (22 bytes) 192 kind-of x 17,846,779 ops/sec ±0.91% (85 runs sampled) 193 lib-type-of x 3,316,636 ops/sec ±1.19% (86 runs sampled) 194 lib-typeof x 2,329,477 ops/sec ±2.21% (85 runs sampled) 195 196 fastest is kind-of (by 632% avg) 197 198 # object-plain (47 bytes) 199 kind-of x 7,085,155 ops/sec ±1.05% (88 runs sampled) 200 lib-type-of x 8,870,930 ops/sec ±1.06% (83 runs sampled) 201 lib-typeof x 8,716,024 ops/sec ±1.05% (87 runs sampled) 202 203 fastest is lib-type-of (by 112% avg) 204 205 # regex (25 bytes) 206 kind-of x 14,196,052 ops/sec ±1.65% (84 runs sampled) 207 lib-type-of x 9,554,164 ops/sec ±1.25% (88 runs sampled) 208 lib-typeof x 8,359,691 ops/sec ±1.07% (87 runs sampled) 209 210 fastest is kind-of (by 158% avg) 211 212 # string (33 bytes) 213 kind-of x 16,131,428 ops/sec ±1.41% (85 runs sampled) 214 lib-type-of x 7,273,172 ops/sec ±1.05% (87 runs sampled) 215 lib-typeof x 7,382,635 ops/sec ±1.17% (85 runs sampled) 216 217 fastest is kind-of (by 220% avg) 218 219 # symbol (34 bytes) 220 kind-of x 17,011,537 ops/sec ±1.24% (86 runs sampled) 221 lib-type-of x 3,492,454 ops/sec ±1.23% (89 runs sampled) 222 lib-typeof x 7,471,235 ops/sec ±2.48% (87 runs sampled) 223 224 fastest is kind-of (by 310% avg) 225 226 # template-strings (36 bytes) 227 kind-of x 15,434,250 ops/sec ±1.46% (83 runs sampled) 228 lib-type-of x 7,157,907 ops/sec ±0.97% (87 runs sampled) 229 lib-typeof x 7,517,986 ops/sec ±0.92% (86 runs sampled) 230 231 fastest is kind-of (by 210% avg) 232 233 # undefined (29 bytes) 234 kind-of x 19,167,115 ops/sec ±1.71% (87 runs sampled) 235 lib-type-of x 15,477,740 ops/sec ±1.63% (85 runs sampled) 236 lib-typeof x 19,075,495 ops/sec ±1.17% (83 runs sampled) 237 238 fastest is lib-typeof,kind-of 239 240 ``` 241 242 ## Optimizations 243 244 In 7 out of 8 cases, this library is 2x-10x faster than other top libraries included in the benchmarks. There are a few things that lead to this performance advantage, none of them hard and fast rules, but all of them simple and repeatable in almost any code library: 245 246 1. Optimize around the fastest and most common use cases first. Of course, this will change from project-to-project, but I took some time to understand how and why `typeof` checks were being used in my own libraries and other libraries I use a lot. 247 2. Optimize around bottlenecks - In other words, the order in which conditionals are implemented is significant, because each check is only as fast as the failing checks that came before it. Here, the biggest bottleneck by far is checking for plain objects (an object that was created by the `Object` constructor). I opted to make this check happen by process of elimination rather than brute force up front (e.g. by using something like `val.constructor.name`), so that every other type check would not be penalized it. 248 3. Don't do uneccessary processing - why do `.slice(8, -1).toLowerCase();` just to get the word `regex`? It's much faster to do `if (type === '[object RegExp]') return 'regex'` 249 4. There is no reason to make the code in a microlib as terse as possible, just to win points for making it shorter. It's always better to favor performant code over terse code. You will always only be using a single `require()` statement to use the library anyway, regardless of how the code is written. 250 251 ## Better type checking 252 253 kind-of seems to be more consistently "correct" than other type checking libs I've looked at. For example, here are some differing results from other popular libs: 254 255 ### [typeof](https://github.com/CodingFu/typeof) lib 256 257 Incorrectly identifies instances of custom constructors (pretty common): 258 259 ```js 260 var typeOf = require('typeof'); 261 function Test() {} 262 console.log(typeOf(new Test())); 263 //=> 'test' 264 ``` 265 266 Returns `object` instead of `arguments`: 267 268 ```js 269 function foo() { 270 console.log(typeOf(arguments)) //=> 'object' 271 } 272 foo(); 273 ``` 274 275 ### [type-of](https://github.com/ForbesLindesay/type-of) lib 276 277 Incorrectly returns `object` for generator functions, buffers, `Map`, `Set`, `WeakMap` and `WeakSet`: 278 279 ```js 280 function * foo() {} 281 console.log(typeOf(foo)); 282 //=> 'object' 283 console.log(typeOf(new Buffer(''))); 284 //=> 'object' 285 console.log(typeOf(new Map())); 286 //=> 'object' 287 console.log(typeOf(new Set())); 288 //=> 'object' 289 console.log(typeOf(new WeakMap())); 290 //=> 'object' 291 console.log(typeOf(new WeakSet())); 292 //=> 'object' 293 ``` 294 295 ## About 296 297 <details> 298 <summary><strong>Contributing</strong></summary> 299 300 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 301 302 </details> 303 304 <details> 305 <summary><strong>Running Tests</strong></summary> 306 307 Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: 308 309 ```sh 310 $ npm install && npm test 311 ``` 312 313 </details> 314 315 <details> 316 <summary><strong>Building docs</strong></summary> 317 318 _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ 319 320 To generate the readme, run the following command: 321 322 ```sh 323 $ npm install -g verbose/verb#dev verb-generate-readme && verb 324 ``` 325 326 </details> 327 328 ### Related projects 329 330 You might also be interested in these projects: 331 332 * [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/micromatch/is-glob) | [homepage](https://github.com/micromatch/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet") 333 * [is-number](https://www.npmjs.com/package/is-number): Returns true if a number or string value is a finite number. Useful for regex… [more](https://github.com/jonschlinkert/is-number) | [homepage](https://github.com/jonschlinkert/is-number "Returns true if a number or string value is a finite number. Useful for regex matches, parsing, user input, etc.") 334 * [is-primitive](https://www.npmjs.com/package/is-primitive): Returns `true` if the value is a primitive. | [homepage](https://github.com/jonschlinkert/is-primitive "Returns `true` if the value is a primitive. ") 335 336 ### Contributors 337 338 | **Commits** | **Contributor** | 339 | --- | --- | 340 | 102 | [jonschlinkert](https://github.com/jonschlinkert) | 341 | 3 | [aretecode](https://github.com/aretecode) | 342 | 2 | [miguelmota](https://github.com/miguelmota) | 343 | 1 | [doowb](https://github.com/doowb) | 344 | 1 | [dtothefp](https://github.com/dtothefp) | 345 | 1 | [ianstormtaylor](https://github.com/ianstormtaylor) | 346 | 1 | [ksheedlo](https://github.com/ksheedlo) | 347 | 1 | [pdehaan](https://github.com/pdehaan) | 348 | 1 | [laggingreflex](https://github.com/laggingreflex) | 349 | 1 | [tunnckoCore](https://github.com/tunnckoCore) | 350 | 1 | [xiaofen9](https://github.com/xiaofen9) | 351 352 ### Author 353 354 **Jon Schlinkert** 355 356 * [GitHub Profile](https://github.com/jonschlinkert) 357 * [Twitter Profile](https://twitter.com/jonschlinkert) 358 * [LinkedIn Profile](https://linkedin.com/in/jonschlinkert) 359 360 ### License 361 362 Copyright © 2020, [Jon Schlinkert](https://github.com/jonschlinkert). 363 Released under the [MIT License](LICENSE). 364 365 *** 366 367 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on January 16, 2020._