number-kit

Modern toolkit for JavaScript and TypeScript numeric semantics

The Problem: JavaScript's Surprising Numeric Behavior

JavaScript has several behaviors around numbers that can be confusing:

typeof NaN === "number"           // true - NaN is a number?
Number("") === 0                  // true - empty string becomes 0?
Number([]) === 0                  // true - array becomes 0?
Number("123abc") === 123          // true - "123abc" becomes 123?
Object.is(-0, 0) === false        // true - -0 and 0 are different?
typeof 42n === "bigint"           // true - BigInt is not number
Number("1_000") === 1000          // true - underscore separators work?

Features

TypeScript-first — Full type narrowing with type predicates

Zero dependencies — Tiny bundle size with excellent tree-shaking

ESM + CommonJS — Works everywhere (Node.js, Bun, Deno, browsers)

Safe parsing — No silent coercion of invalid strings like "123abc"

Explicit semantics — Clear separation between "is a number" and "represents a number"

Comprehensive — Handles NaN, Infinity, -0, BigInt, numeric strings, and more

Installation

npm install number-kit.js

Quick Start

import { 
  isNumber, 
  isNumeric, 
  isFiniteNumber, 
  isInteger,
  isSafeInteger,
  isNaNValue,
  isInfinity,
  isNegativeZero,
  isBigInt,
  parseNumber,
  analyzeNumber
} from 'number-kit';

// Strict type checking
isNumber(42)       // true
isNumber(NaN)      // true - NaN is typeof "number"
isNumber("42")     // false
isNumber(42n)      // false

// Semantic checking (strings that represent numbers)
isNumeric("42")    // true
isNumeric("42.5")  // true
isNumeric("1e10")  // true
isNumeric("0xFF")  // true - hexadecimal
isNumeric("0b101") // true - binary
isNumeric("123abc")// false - no silent coercion!
isNumeric("")      // false

// More specific checks
isFiniteNumber(42)        // true
isFiniteNumber(Infinity)  // false
isInteger(42)             // true
isInteger(42.5)           // false
isSafeInteger(42)         // true
isNaNValue(NaN)           // true
isInfinity(Infinity)      // true
isNegativeZero(-0)        // true
isBigInt(42n)             // true

// Safe parsing
parseNumber("123")       // 123
parseNumber("123.45")    // 123.45
parseNumber("1e5")       // 100000
parseNumber("0xFF")      // 255
parseNumber("0b101")     // 5
parseNumber("1_000")     // 1000 - underscore separators
parseNumber("123abc")    // null - no silent coercion!
parseNumber("")          // null
parseNumber(null)        // null

// Detailed analysis for debugging
analyzeNumber(42)
// {
//   isValid: true,
//   type: "number",
//   isNumeric: true,
//   value: 42,
//   isInteger: true,
//   isFinite: true,
//   isSafeInteger: true,
//   isNaN: false,
//   isInfinity: false,
//   isNegativeZero: false,
//   isBigInt: false
// }

analyzeNumber("42")
// {
//   isValid: false,
//   type: "string",
//   isNumeric: true,
//   value: 42,
//   isInteger: true,
//   isFinite: true,
//   isSafeInteger: true,
//   ...
// }