compare-shield
Version:
A coercion-free numeric comparison utility for <, <=, >, >= within JavaScript's safe integer range.
141 lines (102 loc) • 4.05 kB
Markdown
# compare-shield
**Production-ready numeric comparisons that eliminate JavaScript's most dangerous pitfalls.**
JavaScript's comparison operators are a source of critical bugs in production applications. Type coercion, special value handling, and precision issues cause silent failures that are expensive to debug and fix. `compare-shield` provides strict, predictable numeric comparisons with zero tolerance for ambiguous inputs.
**The cost of comparison bugs:**
- Silent data corruption in financial calculations
- Incorrect sorting and filtering in user interfaces
- Security vulnerabilities from type confusion attacks
- Hours of debugging time tracking down coercion issues
**The solution:** Explicit validation with guaranteed behavior. Every comparison either succeeds with valid finite numbers or fails fast with a clear `false` result.
## Critical JavaScript Comparison Problems
JavaScript's native comparison operators create unpredictable behavior that ships bugs to production:
```js
// Type coercion creates logic errors
"10" > 5 // true (string coerced to number)
"10" > "5" // false (lexicographic comparison)
[] < 1 // true (empty array coerced to 0)
[2] < 1 // false (array coerced to 2)
// Special values produce inconsistent results
null >= 0 // true (null coerced to 0)
null > 0 // false
null == 0 // false
undefined >= 0 // false (undefined coerced to NaN)
NaN < NaN // false
NaN >= NaN // false
// Precision loss with large numbers
9007199254740993 > 9007199254740992 // false (precision loss)
// Object coercion unpredictability
{} > 0 // false
{} >= 0 // true (both coerced to NaN)
[1,2] > 0 // false (coerced to NaN)
```
## Safe, Predictable Comparisons
`compare-shield` eliminates these issues with strict validation and explicit failure handling:
```js
import { compare } from "compare-shield";
// Type safety - rejects non-numeric inputs
compare("10", ">", 5); // false (string rejected)
compare([], "<", 1); // false (array rejected)
compare({}, ">=", 0); // false (object rejected)
// Consistent special value handling
compare(null, ">=", 0); // false (null rejected)
compare(undefined, "<", 5); // false (undefined rejected)
compare(NaN, ">=", NaN); // false (NaN rejected)
compare(Infinity, ">", 1000); // false (Infinity rejected)
// Only valid numeric comparisons succeed
compare(10, ">", 5); // true
compare(3.14, "<=", 3.14); // true
compare(-100, "<", 0); // true
```
## Installation
```bash
(npm/yarn) (install/add) compare-shield
```
## API Reference
```typescript
function compare(
a: number | null | undefined,
operator: "<" | "<=" | ">" | ">=",
b: number | null | undefined
): boolean;
```
### Parameters
- **a**: First operand (must be a finite number)
- **operator**: Comparison operator (`"<"`, `"<="`, `">"`, `">="`)
- **b**: Second operand (must be a finite number)
### Return Value
Returns `true` only when both operands are valid finite numbers and the comparison condition is met.
Returns `false` for any invalid input:
- Non-numeric values (strings, objects, arrays, null, undefined)
- Special numeric values (NaN, Infinity, -Infinity)
- Invalid operators
## Production Use Cases
### Financial Calculations
```js
// Prevent currency comparison errors
if (compare(transaction.amount, "<=", account.balance)) {
processPayment(transaction);
}
```
### Data Validation
```js
// Reliable input validation
const isValid = compare(userAge, ">=", 18) && compare(userAge, "<=", 120);
```
### API Response Processing
```js
// Safe handling of external data
const results = apiResponse.items.filter((item) =>
compare(item.score, ">", threshold)
);
```
### Sorting and Filtering
```js
// Predictable data operations
const sorted = data.sort((a, b) => {
if (compare(a.value, "<", b.value)) return -1;
if (compare(a.value, ">", b.value)) return 1;
return 0;
});
```
## License
MIT © wolf-software