Performance: add function is slow for large numbers

[colinhacks]

The add function in index.js doesn't handle very large numbers efficiently. We should consider using BigInt for numbers above Number.MAX_SAFE_INTEGER.

[pullfrog]

Analysis

Issue #4 requests BigInt support for large numbers exceeding Number.MAX_SAFE_INTEGER (9,007,199,254,740,991). The current add function uses plain JavaScript number addition, which loses precision beyond this threshold.

Actionability: ✅ Well-scoped and actionable, but requires API design decisions.

---

Key Design Challenge

JavaScript BigInt and Number types are incompatible:

1n + 1  // ❌ TypeError: Cannot mix BigInt and other types

This means we need to decide:

1. Return type: Always BigInt? Always Number? Mixed based on input?
2. Input handling: Accept both types? Auto-convert?

---

Proposed Approach

Option A: Auto-convert when needed (Recommended)

• Detect when inputs exceed Number.MAX_SAFE_INTEGER
• Automatically use BigInt arithmetic, return BigInt
• Otherwise use normal numbers

function add(a, b) {
  const threshold = Number.MAX_SAFE_INTEGER;
  if (Math.abs(a) > threshold || Math.abs(b) > threshold) {
    return BigInt(a) + BigInt(b);
  }
  return a + b;
}

Tradeoffs:

• ✅ Backward compatible (small numbers still return Number)
• ✅ Handles large numbers automatically
• ⚠️ Inconsistent return type (Number vs BigInt)
• ⚠️ May surprise callers expecting consistent types

Option B: Always use BigInt

function add(a, b) {
  return BigInt(a) + BigInt(b);
}

Tradeoffs:

• ✅ Consistent return type
• ❌ Breaking change (all callers must handle BigInt)
• ❌ Cannot handle decimals (BigInt(1.5) throws)

---

Recommendation

Option A for add(), with the same treatment for subtract() for consistency. Both functions have identical structure and face the same precision issues with large numbers.

---

Implementation Plan

1. Modify index.js:

   • Update add(a, b) with threshold-based BigInt logic
   • Update subtract(a, b) identically (consistency)

2. Update test.js:

   // Existing tests still pass
   assert.strictEqual(add(1, 2), 3);
   
   // New large number tests
   assert.strictEqual(
     add(Number.MAX_SAFE_INTEGER, 1),
     9007199254740992n  // BigInt result
   );
   
   assert.strictEqual(
     subtract(Number.MAX_SAFE_INTEGER + 1000, 1000),
     9007199254740991n
   );

3. Documentation (if README exists):

   • Note return type behavior (Number for small, BigInt for large)

---

Questions for Clarification

1. Breaking changes acceptable? Should we prioritize backward compatibility (Option A) or type consistency (Option B)?
2. Decimal support needed? BigInt cannot represent decimals (1.5, 3.14, etc.). Should we handle this edge case or assume integer-only inputs for large numbers?
3. Subtract too? Should subtract() get the same treatment for consistency, even though the issue only mentions add()?

Let me know which approach you prefer and I'll implement it.

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ Using Claude Code ｜ Triggered by Pullfrog ｜ pullfrog.com ｜ 𝕏}