0
# is-what
1

2
is-what is a comprehensive TypeScript-first type checking utility library that provides precise type validation functions designed to overcome the limitations of existing type checking solutions. It offers reliable type checking with automatic TypeScript type narrowing, special handling for edge cases like NaN, and proper distinction between plain objects and class instances.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { isString, isNumber, isPlainObject, getType } from "is-what";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { isString, isNumber, isPlainObject, getType } = require("is-what");
21
```
22

23
Import specific functions as needed:
24

25
```typescript
26
import { 
27
  isString, isNumber, isBoolean, isArray, 
28
  isPlainObject, isFunction, isPrimitive,
29
  isOneOf, isInstanceOf, getType 
30
} from "is-what";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { isString, isNumber, isPlainObject, isArray } from "is-what";
37

38
// Basic type checking with TypeScript type narrowing
39
if (isString(value)) {
40
  // TypeScript now knows value is string
41
  console.log(value.toUpperCase());
42
}
43

44
if (isNumber(value)) {
45
  // TypeScript now knows value is number (but not NaN)
46
  console.log(value.toFixed(2));
47
}
48

49
// Plain object detection (excludes class instances)
50
if (isPlainObject(obj)) {
51
  // obj is definitely a plain object {}
52
  console.log(Object.keys(obj));
53
}
54

55
// Array checking
56
if (isArray(list)) {
57
  console.log(list.length);
58
}
59
```
60

61
## Architecture
62

63
is-what is built around several key components:
64

65
- **Core Utility**: `getType()` function provides consistent type checking using `Object.prototype.toString`
66
- **Type Guards**: All functions are TypeScript type guards providing automatic type narrowing
67
- **Modular Design**: Each function in separate file for optimal tree-shaking
68
- **Edge Case Handling**: Special treatment for NaN, plain objects vs class instances
69
- **Zero Dependencies**: Self-contained implementation with no external dependencies
70

71
## Capabilities
72

73
### Basic Type Checking
74

75
Fundamental type checking functions for primitives and basic JavaScript types with TypeScript type guards.
76

77
```typescript { .api }
78
function isString(payload: unknown): payload is string;
79
function isNumber(payload: unknown): payload is number;
80
function isBoolean(payload: unknown): payload is boolean;
81
function isBigInt(payload: unknown): payload is bigint;
82
function isSymbol(payload: unknown): payload is symbol;
83
function isNull(payload: unknown): payload is null;
84
function isUndefined(payload: unknown): payload is undefined;
85
```
86

87
[Basic Types](./basic-types.md)
88

89
### Number Validation
90

91
Specialized number validation functions including NaN handling, positive/negative checks, and integer validation.
92

93
```typescript { .api }
94
function isNumber(payload: unknown): payload is number;
95
function isNaNValue(payload: unknown): payload is typeof Number.NaN;
96
function isInteger(payload: unknown): payload is number;
97
function isPositiveNumber(payload: unknown): payload is number;
98
function isNegativeNumber(payload: unknown): payload is number;
99
```
100

101
[Number Validation](./number-validation.md)
102

103
### Array Type Checking
104

105
Array validation functions including empty/full array checks and general array detection.
106

107
```typescript { .api }
108
function isArray(payload: unknown): payload is unknown[];
109
function isEmptyArray(payload: unknown): payload is [];
110
function isFullArray(payload: unknown): payload is unknown[];
111
```
112

113
[Array Types](./array-types.md)
114

115
### String Validation
116

117
String type checking including empty/full string validation and hexadecimal string detection.
118

119
```typescript { .api }
120
function isString(payload: unknown): payload is string;
121
function isEmptyString(payload: unknown): payload is "";
122
function isFullString(payload: unknown): payload is string;
123
function isHexDecimal(payload: unknown, length?: number): payload is string;
124
```
125

126
[String Types](./string-types.md)
127

128
### Object Type Checking
129

130
Comprehensive object type validation including plain object detection, empty/full object checks, and object-like detection.
131

132
```typescript { .api }
133
function isObject(payload: unknown): payload is PlainObject;
134
function isPlainObject(payload: unknown): payload is PlainObject;
135
function isAnyObject(payload: unknown): payload is PlainObject;
136
function isObjectLike<T extends PlainObject>(payload: unknown): payload is T;
137
function isEmptyObject(payload: unknown): payload is { [K in string | symbol | number]: never };
138
function isFullObject(payload: unknown): payload is PlainObject;
139

140
type PlainObject = { [key in string | number | symbol]: unknown };
141
```
142

143
[Object Types](./object-types.md)
144

145
### Built-in Object Detection
146

147
Type checking for JavaScript built-in objects and browser/Node.js specific types.
148

149
```typescript { .api }
150
function isDate(payload: unknown): payload is Date;
151
function isError(payload: unknown): payload is Error;
152
function isRegExp(payload: unknown): payload is RegExp;
153
function isMap(payload: unknown): payload is Map<unknown, unknown>;
154
function isSet(payload: unknown): payload is Set<unknown>;
155
function isWeakMap(payload: unknown): payload is WeakMap<object, unknown>;
156
function isWeakSet(payload: unknown): payload is WeakSet<object>;
157
function isPromise(payload: unknown): payload is Promise<unknown>;
158
function isBlob(payload: unknown): payload is Blob;
159
function isFile(payload: unknown): payload is File;
160
```
161

162
[Built-in Types](./builtin-types.md)
163

164
### Advanced Type Checking
165

166
Advanced utilities for function detection, primitive checking, and iterable validation.
167

168
```typescript { .api }
169
function isFunction(payload: unknown): payload is AnyFunction;
170
function isPrimitive(payload: unknown): payload is boolean | null | undefined | number | string | symbol | bigint;
171
function isIterable(payload: unknown): payload is Iterable<unknown>;
172

173
type AnyFunction = (...args: any[]) => any;
174
type AnyAsyncFunction = (...args: unknown[]) => Promise<unknown>;
175
```
176

177
[Advanced Types](./advanced-types.md)
178

179
### Generic Type Utilities
180

181
Generic type checking utilities including factory functions and instance validation.
182

183
```typescript { .api }
184
function getType(payload: unknown): string;
185
function isType<T extends AnyFunction | AnyClass>(payload: unknown, type: T): payload is T;
186
function isInstanceOf<T extends AnyClass>(value: unknown, class_: T): value is T;
187
function isOneOf<A, B extends A, C extends A>(
188
  a: TypeGuard<A, B>,
189
  b: TypeGuard<A, C>
190
): TypeGuard<A, B | C>;
191

192
type AnyClass = new (...args: unknown[]) => unknown;
193
```
194

195
[Generic Utilities](./generic-utils.md)