0
# is-number
1

2
Returns true if a number or string value is a finite number. Useful for regex matches, parsing, user input, etc.
3

4
## Package Information
5

6
- **Package Name**: is-number
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install is-number`
10

11
## Core Imports
12

13
```javascript
14
const isNumber = require('is-number');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const isNumber = require('is-number');
21

22
console.log(isNumber(5e3));      // true
23
console.log(isNumber('10'));     // true
24
console.log(isNumber(''));       // false
25
console.log(isNumber([]));       // false
26
console.log(isNumber(NaN));      // false
27
console.log(isNumber(Infinity)); // false
28
```
29

30
## Capabilities
31

32
### Number Validation
33

34
Returns true if the value is a finite number (including string representations of numbers), false otherwise.
35

36
```javascript { .api }
37
/**
38
 * Returns true if a number or string value is a finite number
39
 * @param {any} num - The value to test
40
 * @returns {boolean} - true if value is a finite number, false otherwise
41
 */
42
module.exports = function isNumber(num);
43
```
44

45
#### Behavior Details
46

47
**Returns `true` for:**
48
- Number primitives: `0`, `1`, `1.1`, `10`, `100`, `-100`, `0xff`, `5e3`
49
- String representations: `'0'`, `'1'`, `'1.1'`, `'10.10'`, `'0xff'`, `'5e3'`, `'012'`
50
- Mathematical constants: `Math.PI`, `Math.E`, `Math.LN2`, `Number.MAX_VALUE`, `Number.MIN_VALUE`
51
- Mathematical operations: `Math.abs(1)`, `Math.cos(1)`, `Math.pow(1, 2)`, etc.
52
- Parsed numbers: `parseInt('012')`, `parseFloat('012')`
53
- Whitespace-padded numbers: `'   56\r\n  '`
54
- Pre-converted numeric values: `+''`, `+[]`, `+false`, `+true`, `+null` (these are numbers when passed)
55

56
**Returns `false` for:**
57
- Infinite values: `Infinity`, `-Infinity`
58
- NaN values: `NaN`
59
- Empty/whitespace strings: `''`, `'   '`, `'\r\n\t'`
60
- Non-numeric strings: `'abc'`, `'3a'`, `'foo'`, `'null'`, `'true'`, `'false'`
61
- Arrays: `[]`, `[1]`, `[1, 2, 3]`
62
- Objects: `{}`, `{ a: 1 }`
63
- Functions: `function() {}`, `Math.sin`
64
- Primitives: `null`, `undefined`, `true`, `false`
65
- Date objects: `new Date()`
66
- Regular expressions: `/foo/`
67

68
#### Implementation Notes
69

70
- Uses `typeof` check for number primitives first for performance
71
- For strings, checks that the string is not empty or whitespace-only
72
- Uses `Number.isFinite` when available, falls back to `isFinite` for older environments
73
- Optimized for performance - 3x-4x faster than previous versions for non-string/non-number inputs
74
- Handles JavaScript's counterintuitive number coercion behaviors correctly
75
- Never throws exceptions - always returns a boolean value
76
- **Important**: Tests the actual value passed, not the original value before coercion
77

78
#### Usage Examples
79

80
```javascript
81
const isNumber = require('is-number');
82

83
// Numeric values
84
console.log(isNumber(42));           // true
85
console.log(isNumber(-17.5));        // true
86
console.log(isNumber(0xff));         // true (hexadecimal)
87
console.log(isNumber(5e3));          // true (scientific notation)
88

89
// String representations
90
console.log(isNumber('42'));         // true
91
console.log(isNumber('-17.5'));      // true
92
console.log(isNumber('0xff'));       // true
93
console.log(isNumber('5e3'));        // true
94
console.log(isNumber('012'));        // true (treated as decimal, not octal)
95

96
// Edge cases that return false
97
console.log(isNumber(''));           // false (empty string)
98
console.log(isNumber('   '));        // false (whitespace only)
99
console.log(isNumber('abc'));        // false (non-numeric)
100
console.log(isNumber('3a'));         // false (mixed alphanumeric)
101
console.log(isNumber([]));           // false (empty array)
102
console.log(isNumber({}));           // false (empty object)
103
console.log(isNumber(null));         // false
104
console.log(isNumber(undefined));    // false
105
console.log(isNumber(NaN));          // false
106
console.log(isNumber(Infinity));     // false
107
console.log(isNumber(-Infinity));    // false
108

109
// Parsed values
110
console.log(isNumber(parseInt('12', 10)));     // true
111
console.log(isNumber(parseFloat('12.34')));    // true
112

113
// Important distinction: pre-converted vs original values
114
console.log(isNumber(+'')); // true (+ converts to 0, which is a number)
115
console.log(isNumber(''));  // false (empty string)
116
console.log(isNumber(+[])); // true (+ converts to 0, which is a number)
117
console.log(isNumber([]));  // false (array)
118
console.log(isNumber(+null)); // true (+ converts to 0, which is a number)
119
console.log(isNumber(null));  // false (null)
120

121
// Whitespace handling
122
console.log(isNumber('  42  '));     // true (leading/trailing whitespace OK)
123
console.log(isNumber('4\n2'));       // false (internal whitespace/newlines)
124
```