README.md
1<h1 align=center>
2 <a href="http://chaijs.com" title="Chai Documentation">
3 <img alt="ChaiJS" src="http://chaijs.com/img/chai-logo.png"/> type-detect
4 </a>
5</h1>
6<br>
7<p align=center>
8 Improved typeof detection for <a href="http://nodejs.org">node</a> and the browser.
9</p>
10
11<p align=center>
12 <a href="./LICENSE">
13 <img
14 alt="license:mit"
15 src="https://img.shields.io/badge/license-mit-green.svg?style=flat-square"
16 />
17 </a>
18 <a href="https://github.com/chaijs/type-detect/releases">
19 <img
20 alt="tag:?"
21 src="https://img.shields.io/github/tag/chaijs/type-detect.svg?style=flat-square"
22 />
23 </a>
24 <a href="https://travis-ci.org/chaijs/type-detect">
25 <img
26 alt="build:?"
27 src="https://img.shields.io/travis/chaijs/type-detect/master.svg?style=flat-square"
28 />
29 </a>
30 <a href="https://coveralls.io/r/chaijs/type-detect">
31 <img
32 alt="coverage:?"
33 src="https://img.shields.io/coveralls/chaijs/type-detect/master.svg?style=flat-square"
34 />
35 </a>
36 <a href="https://www.npmjs.com/packages/type-detect">
37 <img
38 alt="npm:?"
39 src="https://img.shields.io/npm/v/type-detect.svg?style=flat-square"
40 />
41 </a>
42 <a href="https://www.npmjs.com/packages/type-detect">
43 <img
44 alt="dependencies:?"
45 src="https://img.shields.io/npm/dm/type-detect.svg?style=flat-square"
46 />
47 </a>
48 <a href="">
49 <img
50 alt="devDependencies:?"
51 src="https://img.shields.io/david/chaijs/type-detect.svg?style=flat-square"
52 />
53 </a>
54 <br/>
55 <table>
56 <tr><th colspan=6>Supported Browsers</th></tr> <tr>
57 <th align=center><img src="https://camo.githubusercontent.com/ab586f11dfcb49bf5f2c2fa9adadc5e857de122a/687474703a2f2f73766773686172652e636f6d2f692f3278532e737667" alt=""> Chrome</th>
58 <th align=center><img src="https://camo.githubusercontent.com/98cca3108c18dcfaa62667b42046540c6822cdac/687474703a2f2f73766773686172652e636f6d2f692f3279352e737667" alt=""> Edge</th>
59 <th align=center><img src="https://camo.githubusercontent.com/acdcb09840a9e1442cbaf1b684f95ab3c3f41cf4/687474703a2f2f73766773686172652e636f6d2f692f3279462e737667" alt=""> Firefox</th>
60 <th align=center><img src="https://camo.githubusercontent.com/728f8cb0bee9ed58ab85e39266f1152c53e0dffd/687474703a2f2f73766773686172652e636f6d2f692f3278342e737667" alt=""> Safari</th>
61 <th align=center><img src="https://camo.githubusercontent.com/96a2317034dee0040d0a762e7a30c3c650c45aac/687474703a2f2f73766773686172652e636f6d2f692f3279532e737667" alt=""> IE</th>
62 </tr><tr>
63 <td align=center>✅</td>
64 <td align=center>✅</td>
65 <td align=center>✅</td>
66 <td align=center>✅</td>
67 <td align=center>9, 10, 11</td>
68 </tr>
69 </table>
70 <br>
71 <a href="https://chai-slack.herokuapp.com/">
72 <img
73 alt="Join the Slack chat"
74 src="https://img.shields.io/badge/slack-join%20chat-E2206F.svg?style=flat-square"
75 />
76 </a>
77 <a href="https://gitter.im/chaijs/chai">
78 <img
79 alt="Join the Gitter chat"
80 src="https://img.shields.io/badge/gitter-join%20chat-D0104D.svg?style=flat-square"
81 />
82 </a>
83</p>
84
85## What is Type-Detect?
86
87Type Detect is a module which you can use to detect the type of a given object. It returns a string representation of the object's type, either using [`typeof`](http://www.ecma-international.org/ecma-262/6.0/index.html#sec-typeof-operator) or [`@@toStringTag`](http://www.ecma-international.org/ecma-262/6.0/index.html#sec-symbol.tostringtag). It also normalizes some object names for consistency among browsers.
88
89## Why?
90
91The `typeof` operator will only specify primitive values; everything else is `"object"` (including `null`, arrays, regexps, etc). Many developers use `Object.prototype.toString()` - which is a fine alternative and returns many more types (null returns `[object Null]`, Arrays as `[object Array]`, regexps as `[object RegExp]` etc).
92
93Sadly, `Object.prototype.toString` is slow, and buggy. By slow - we mean it is slower than `typeof`. By buggy - we mean that some values (like Promises, the global object, iterators, dataviews, a bunch of HTML elements) all report different things in different browsers.
94
95`type-detect` fixes all of the shortcomings with `Object.prototype.toString`. We have extra code to speed up checks of JS and DOM objects, as much as 20-30x faster for some values. `type-detect` also fixes any consistencies with these objects.
96
97## Installation
98
99### Node.js
100
101`type-detect` is available on [npm](http://npmjs.org). To install it, type:
102
103 $ npm install type-detect
104
105### Browsers
106
107You can also use it within the browser; install via npm and use the `type-detect.js` file found within the download. For example:
108
109```html
110<script src="./node_modules/type-detect/type-detect.js"></script>
111```
112
113## Usage
114
115The primary export of `type-detect` is function that can serve as a replacement for `typeof`. The results of this function will be more specific than that of native `typeof`.
116
117```js
118var type = require('type-detect');
119```
120
121#### array
122
123```js
124assert(type([]) === 'Array');
125assert(type(new Array()) === 'Array');
126```
127
128#### regexp
129
130```js
131assert(type(/a-z/gi) === 'RegExp');
132assert(type(new RegExp('a-z')) === 'RegExp');
133```
134
135#### function
136
137```js
138assert(type(function () {}) === 'function');
139```
140
141#### arguments
142
143```js
144(function () {
145 assert(type(arguments) === 'Arguments');
146})();
147```
148
149#### date
150
151```js
152assert(type(new Date) === 'Date');
153```
154
155#### number
156
157```js
158assert(type(1) === 'number');
159assert(type(1.234) === 'number');
160assert(type(-1) === 'number');
161assert(type(-1.234) === 'number');
162assert(type(Infinity) === 'number');
163assert(type(NaN) === 'number');
164assert(type(new Number(1)) === 'Number'); // note - the object version has a capital N
165```
166
167#### string
168
169```js
170assert(type('hello world') === 'string');
171assert(type(new String('hello')) === 'String'); // note - the object version has a capital S
172```
173
174#### null
175
176```js
177assert(type(null) === 'null');
178assert(type(undefined) !== 'null');
179```
180
181#### undefined
182
183```js
184assert(type(undefined) === 'undefined');
185assert(type(null) !== 'undefined');
186```
187
188#### object
189
190```js
191var Noop = function () {};
192assert(type({}) === 'Object');
193assert(type(Noop) !== 'Object');
194assert(type(new Noop) === 'Object');
195assert(type(new Object) === 'Object');
196```
197
198#### ECMA6 Types
199
200All new ECMAScript 2015 objects are also supported, such as Promises and Symbols:
201
202```js
203assert(type(new Map() === 'Map');
204assert(type(new WeakMap()) === 'WeakMap');
205assert(type(new Set()) === 'Set');
206assert(type(new WeakSet()) === 'WeakSet');
207assert(type(Symbol()) === 'symbol');
208assert(type(new Promise(callback) === 'Promise');
209assert(type(new Int8Array()) === 'Int8Array');
210assert(type(new Uint8Array()) === 'Uint8Array');
211assert(type(new UInt8ClampedArray()) === 'Uint8ClampedArray');
212assert(type(new Int16Array()) === 'Int16Array');
213assert(type(new Uint16Array()) === 'Uint16Array');
214assert(type(new Int32Array()) === 'Int32Array');
215assert(type(new UInt32Array()) === 'Uint32Array');
216assert(type(new Float32Array()) === 'Float32Array');
217assert(type(new Float64Array()) === 'Float64Array');
218assert(type(new ArrayBuffer()) === 'ArrayBuffer');
219assert(type(new DataView(arrayBuffer)) === 'DataView');
220```
221
222Also, if you use `Symbol.toStringTag` to change an Objects return value of the `toString()` Method, `type()` will return this value, e.g:
223
224```js
225var myObject = {};
226myObject[Symbol.toStringTag] = 'myCustomType';
227assert(type(myObject) === 'myCustomType');
228```
229
