Mostly I'm trying to estimate complexity in terms of the conceptual load we're introducing. Right now we have two types in the spec that hold a numerical value (number and bigint), and with Amount we're due to introduce a third one. The core pitch with Decimal (as I understand it) is to represent decimal numbers, i.e. ones coming from the real world. But don't those almost always have some implicit unit attached? Its stated primary use case is for monetary values, so why not include the currency code with the value? I would think that it would be a very positive feature for something like

new Amount(42, { currency: 'USD' }).add(new Amount(13, { currency: 'BTC' }))

to throw an error.

So from a JS developer point of view, I would think that it'd be simpler to understand a single Amount as being the thing to use for values coming from the real world, rather than needing to decide between an Amount and a Decimal, depending on what sort of operations might need to be done with the value.

Let's say I start with two values

const foo = new Amount(42, { currency: 'EUR' })
const bar = new Amount(13, { currency: 'EUR' })

With an amount that did decimal math, I could add those up as

foo.add(bar)

but if their values were Decimal instances, then I'd need to do

const sum = foo.value.add(bar.value)
new Amount(sum, { currency: foo.currency })

To me that seems clumsier, more verbose, and it skips all the validation fo the former about foo and bar being addable.

The compatibility check will need to take into account the operation type and possibly include a conversion; for instance, adding meter and centimeter should be allowed with a conversion of one into the other, while adding kilogram to meter-per-second should fail. Multiplying a kilogram with a meter-per-second should still work, resulting in a kilogram-meter-per-second. The -per- infix/divisor is already supported by Intl.NumberFormat, btw.

Similarly, adding a unitless value to one with a unit should fail, while multiplication ought to work. Currencies should not be considered convertible between different codes.

In general, operating on things that may include a unit/currency and a precision indicator in addition to a numerical value does add a little bit of work, but only when those fields are actually used. Beyond the compatibility check & possible conversion, we would need to apply some strategy to merging the precisions.

As a default strategy, the significant-figures approach should work: If either Amount has its precision as fraction digits, that number is converted to significant digits by adding Math.floor(Math.log10(n) + 1) to the value. if only one Amount has a precision set, that's applied on the result. If both have, then the smaller significant digits value is applied to the result. This same strategy can work for all arithmetic operations.

As a later step, it could be possible to customize the precision calculation strategy, similarly to how it's possible to consider different precision indicators to work next to fraction & significant digits (e.g. error bars).

The arithmetic operation on the value ought to be defined just as it is currently proposed for Decimal.

The arithmetic operation on the value ought to be defined just as it is currently proposed for Decimal.

How should this work, when the underlying value may be a Number or string, as you've also requested?