source: trip-planner-front/node_modules/is-what/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.5 KB
Line 
1# is What? 🙉
2
3Very simple &amp; small JS type check functions. It's fully TypeScript supported!
4
5```
6npm i is-what
7```
8
9Or for deno available at: `"deno.land/x/is_what"`
10
11## Motivation
12
13I built is-what because the existing solutions were all too complex or too poorly built.
14
15I was looking for:
16- A simple way to check any kind of type (including non-primitives)
17- Be able to check if an object is a plain object `{}` or a special object (like a class instance) ‼️
18- Let TypeScript automatically know what type a value is when checking
19
20And that's exactly what `is-what` is! (what a great wordplay 😃)
21
22## Usage
23
24is-what is really easy to use, and most functions work just like you'd expect.
25
26```js
27// import functions you want to use like so:
28import { isString, isDate, isPlainObject } from 'is-what'
29```
30
311. First I'll go over the simple functions available. Only `isNumber` and `isDate` have special treatment.
322. After that I'll talk about working with Objects (plain objects vs class instances etc.).
333. Lastly I'll talk about TypeScript implementation
34
35### Simple type check functions
36
37```js
38// strings
39isString('') // true
40isEmptyString('') // true
41isFullString('') // false
42
43// numbers
44isNumber(0) // true
45isNumber(NaN) // false
46
47// dates
48isDate(new Date()) // true
49isDate(new Date('invalid date')) // false
50
51// others
52isBoolean(false) // true
53isFunction(function () {}) // true
54isArray([]) // true
55isUndefined(undefined) // true
56isNull(null) // true
57isRegExp(/\s/gi) // true
58isSymbol(Symbol()) // true
59isBlob(new Blob()) // true
60isFile(new File([''], '', { type: 'text/html' })) // true
61
62// primitives
63isPrimitive('') // true
64// true for any of: boolean, null, undefined, number, string, symbol
65```
66
67### Getting and checking for specific types
68
69You can check for specific types with `getType` and `isType`:
70
71```js
72import { getType, isType } from 'is-what'
73
74getType('') // returns 'String'
75// pass a Type as second param:
76isType('', String) // returns true
77```
78
79### isPlainObject vs isAnyObject
80
81Checking for a JavaScript object can be really difficult. In JavaScript you can create classes that will behave just like JavaScript objects but might have completely different prototypes. With is-what I went for this classification:
82
83- `isPlainObject` will only return `true` on plain JavaScript objects and not on classes or others
84- `isAnyObject` will be more loose and return `true` on regular objects, classes, etc.
85
86```js
87// define a plain object
88const plainObject = {hello: 'I am a good old object.'}
89
90// define a special object
91class SpecialObject {
92 constructor (somethingSpecial) {
93 this.speciality = somethingSpecial
94 }
95}
96const specialObject = new SpecialObject('I am a special object! I am a class instance!!!')
97
98// check the plain object
99isPlainObject(plainObject) // returns true
100isAnyObject(plainObject) // returns true
101getType(plainObject) // returns 'Object'
102
103// check the special object
104isPlainObject(specialObject) // returns false !!!!!!!!!
105isAnyObject(specialObject) // returns true
106getType(specialObject) // returns 'Object'
107```
108
109> Please note that `isPlainObject` will only return `true` for normal plain JavaScript objects.
110
111## TypeScript
112
113is-what makes TypeScript know the type during if statements. This means that a check returns the type of the payload for TypeScript users.
114
115```ts
116function isNumber (payload: any): payload is number {
117 // return boolean
118}
119// As you can see above, all functions return a boolean for JavaScript, but pass the payload type to TypeScript.
120
121// usage example:
122function fn (payload: string | number): number {
123 if (isNumber(payload)) {
124 // ↑ TypeScript already knows payload is a number here!
125 return payload
126 }
127 return 0
128}
129```
130
131`isPlainObject` and `isAnyObject` with TypeScript will declare the payload to be an object type with any props:
132
133```ts
134function isPlainObject (payload: any): payload is {[key: string]: any}
135function isAnyObject (payload: any): payload is {[key: string]: any}
136// The reason to return `{[key: string]: any}` is to be able to do
137if (isPlainObject(payload) && payload.id) return payload.id
138// if isPlainObject() would return `payload is object` then it would give an error at `payload.id`
139```
140
141### isObjectLike
142
143If you want more control over which kind of objects are allowed you can use `isObjectLike<T>`:
144
145```ts
146import { isObjectLike } from 'is-what'
147// usage examples:
148isObjectLike<{specificKey: string}>(payload)
149isObjectLike<object>(payload)
150// you can pass a specific type for TS to check on.
151```
152
153`isObjectLike<T>` works like this under the hood:
154
155```ts
156function isObjectLike<T extends object> (payload: any): payload is T {
157 return isAnyObject(payload)
158}
159```
160
161## Meet the family
162
163- [is-what 🙉](https://github.com/mesqueeb/is-what)
164- [merge-anything 🥡](https://github.com/mesqueeb/merge-anything)
165- [filter-anything ⚔️](https://github.com/mesqueeb/filter-anything)
166- [find-and-replace-anything 🎣](https://github.com/mesqueeb/find-and-replace-anything)
167- [compare-anything 🛰](https://github.com/mesqueeb/compare-anything)
168- [copy-anything 🎭](https://github.com/mesqueeb/copy-anything)
169- [flatten-anything 🏏](https://github.com/mesqueeb/flatten-anything)
170
171## Source code
172
173It's litterally just these functions:
174
175```js
176function getType (payload) {
177 return Object.prototype.toString.call(payload).slice(8, -1)
178}
179function isUndefined (payload) {
180 return getType(payload) === 'Undefined'
181}
182function isString (payload) {
183 return getType(payload) === 'String'
184}
185function isAnyObject (payload) {
186 return getType(payload) === 'Object'
187}
188// etc...
189```
190
191See the full source code [here](https://github.com/mesqueeb/is-what/blob/master/src/index.ts).
Note: See TracBrowser for help on using the repository browser.