feat: add round function

[shan-shaji]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

The round function is designed to round a given number to a specified precision.

Related issue, if any:

sodiray/radash#61

What kind of change does this PR introduce?

Feature

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

No

[aleclarson]

How can we verify these precision limits to be correct?

Interestingly, Lodash does this:

precision = precision == null 
  ? 0 
  : (precision >= 0 
    ? Math.min(precision, 292) 
    : Math.max(precision, -292))

[shan-shaji]

@aleclarson I added that check inspired from them.

[shan-shaji]

Also i found an issue related with this: lodash/lodash#4232

[aleclarson]

Here's what Claude Sonnet 3.5 says on the matter:

You're right to question this. Lodash's choice of 292 is indeed intentional and has a specific reason. Let me explain:

1. Precision: While JavaScript can theoretically represent numbers up to 308 decimal places, it doesn't maintain full precision for all of those digits.

2. Reliable accuracy: Lodash uses 292 as a more conservative limit to ensure reliable and consistent results across different JavaScript engines and environments.

3. IEEE 754 standard: This limit is related to the IEEE 754 double-precision floating-point format, which guarantees about 15-17 decimal digits of precision.

4. Safety margin: 292 provides a safety margin, avoiding potential rounding errors or inconsistencies that might occur when pushing to the absolute limits of JavaScript's number representation.

So, while 308 is technically the maximum exponent, Lodash's choice of 292 is a pragmatic one, prioritizing consistent and reliable results over the theoretical maximum. For most practical applications, this limit is more than sufficient and helps prevent subtle bugs that could arise from pushing the boundaries of floating-point precision.

I will push an update, along with the Lodash test suite and a reimplementation to support the edge cases that lodash.round does.

[shan-shaji]

Thanks @aleclarson for the explanation. So they chose 292 to ensure results are reliable and consistent across different JavaScript engines (e.g., V8 in Chrome, SpiderMonkey in Firefox) and environments (e.g., browsers, Node.js).

[aleclarson]

I tracked down the original commit:
lodash/lodash@68ae6fc

Not much justification is given. If we can use technically “more correct” limits, we should as long as NaN is avoided. If someone reports misbehavior in some JS engine, we'll consider a breaking change then, but considering such large precision values are probably very rare in Javascript code, that won't happen anytime soon. Besides, the caller can always wrap/fork Radashi round to clamp the precision to 292 if necessary.

[shan-shaji]

So to be on the safe side shall we stick with 292 then?

[aleclarson]

After some testing, I found that 292 is the upper limit that prevents NaN in all cases, while -323 works fine as a lower limit in all cases.

[aleclarson]

Thanks for the contribution! Hope to see more from you in the future.

[github-actions]

A new beta version 12.2.0-beta.af936c4 has been published to NPM. 🚀

To install:

pnpm add radashi@12.2.0-beta.af936c4

The radashi@beta tag also includes this PR.