fix: harden input validation and edge-case handling in filesize() #343

Summary

The filesize() function has a broad set of unhandled edge cases in input validation, option handling, and formatting that produce silent wrong output, raw native errors, or inconsistent results between equivalent inputs. This issue inventories every confirmed edge case in one place at equal priority.

Edge Cases (Complete Inventory)

Every case below is confirmed against the live code. All are treated at equal priority.

Root Cause Analysis

• BigInt overflow: filesize() converts BigInt via Number(arg) at src/filesize.js:77-79 but skips the isFinite check at line 86 that the number path applies. An overflowing BigInt becomes Infinity and is never rejected.
• Float exponent: calculateExponent() at src/helpers.js:288-313 only handles e === -1/isNaN (line 289) and e < 0 (line 298). A positive non-integer exponent indexes the power lookup tables out of bounds, producing NaN.
• String exponent: resolveSymbol() at src/helpers.js:356-369 uses strict e === 1 (line 359) for the SI special case. String "1" fails strict equality and falls through to the JEDEC symbol.
• Negative fullform singular: the singular/plural check at src/helpers.js:445 uses numericValue === 1, which fails for -1.
• Sign loss on round-to-zero: neg is captured at src/filesize.js:94 before rounding. When a negative value rounds to 0, the sign is dropped in the non-precision path but preserved in the precision path (decorateResult line 409 prefixes the sign only for string values).
• Precision out of range: value.toPrecision(precision) at src/helpers.js:195 is called with no range validation; precision: 101 throws a raw native RangeError.
• Invalid output: formatOutput() at src/helpers.js:468-489 only checks output === ARRAY (line 469) and output === OBJECT (line 473); any other value silently falls through to string.
• Scientific notation leak: the precision path strips scientific notation but the non-precision path does not, so Number.MAX_VALUE leaks e+284.

Testing Strategy

• Add regression tests for every case in the table above to tests/unit/filesize.test.js.
• Add targeted helper tests in tests/unit/filesize-helpers.test.js for calculateExponent, resolveSymbol, applyRounding, and applyNumberFormatting.
• Verify with npm run test and npm run coverage (currently 100% line/branch/function coverage).

Security Considerations

• Input validation for exponent, precision, and output options prevents silent wrong output and unhandled native errors.
• No credential or sensitive-data handling is involved; this is pure input-validation hardening.

Fix Steps

1. Validate BigInt overflow — In src/filesize.js, after the BigInt conversion at line 77-79, apply the same isFinite check used at line 86 so overflowing BigInts throw TypeError.
2. Validate exponent — In src/helpers.js calculateExponent(), reject or clamp non-integer positive exponents before they index the power tables.
3. Normalize string exponent — In src/helpers.js resolveSymbol(), coerce e to a number before the strict e === 1 check so string "1" matches the SI special case.
4. Fix negative fullform singular — In src/helpers.js decorateResult(), use Math.abs(numericValue) === 1 for the singular/plural check so -1 uses the singular unit.
5. Preserve sign on round-to-zero — In src/filesize.js, ensure negative values that round to 0 keep their sign consistently across the precision and non-precision paths.
6. Validate precision range — In src/helpers.js, validate precision is 1-100 before calling toPrecision() at line 195, throwing a clean TypeError for out-of-range values.
7. Validate output option — In src/helpers.js formatOutput(), throw TypeError for invalid output values instead of silently falling through to string.
8. Strip scientific notation in non-precision path — Ensure Number.MAX_VALUE and similar large values don't leak e+ notation.
9. Document or validate coercion contract — Decide whether null, true, false, "", [1000], and hex/binary/octal strings are intended; if so, document them; if not, validate and throw.
10. Document option precedence — Lock in and document standard > base, fullform > symbols, locale > separator, and fullforms fallback behavior.
11. Add regression tests — Add cases to tests/unit/filesize.test.js and tests/unit/filesize-helpers.test.js for every case in the table above. Verify with npm run test and npm run coverage.