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:

// 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:

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

(npm/yarn) (install/add) compare-shield

API Reference

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

// Prevent currency comparison errors
if (compare(transaction.amount, "<=", account.balance)) {
  processPayment(transaction);
}

Data Validation

// Reliable input validation
const isValid = compare(userAge, ">=", 18) && compare(userAge, "<=", 120);

API Response Processing

// Safe handling of external data
const results = apiResponse.items.filter((item) =>
  compare(item.score, ">", threshold)
);

Sorting and Filtering

// 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