An exact decimal is a ZuDecimal

[tamnd]

The engine grew a decimal type at e617431: an integer of unscaled units and the scale that says how large a unit is. This client had no way to receive one and no way to send one, so a CAST to DECIMAL came back as something else or not at all. The pin moves to cfdc70f and the type arrives with it.

The shape

A class, because JavaScript has no exact number to be. A number is an IEEE double and a tenth is not a binary fraction, so 0.1 + 0.2 is not 0.3 and a price read into one is not the price. A bigint is exact and whole, which is half of what a decimal is. That is the same decision ZuDate is, for the same reason: the runtime has no type for the value, and inventing one that loses it would be worse than naming it.

const [row] = await conn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")
row.total.toString()   // '1.20'
row.total.scale        // 2
row.total.unscaled     // 120n
JSON.stringify(row)    // '{"total":"1.20"}'

await conn.query('RETURN $d AS d', { d: ZuDecimal.parse('-1234.5678') })

The scale rides on the value rather than only on the column it came from, because CAST('1.20' AS DECIMAL(5, 2)) in a RETURN has no column to ask and still has two places. ZuDecimal.parse reads the scale out of the text it was given, so 1.20 and 1.2 are the same number written with different care about how well it is known, and each prints back the way it was written. ZuDecimal.of(120n, 2) takes the pair for a caller who already has one.

toString() is the lossless spelling and is what JSON.stringify writes. toNumber() is the conversion offered rather than done.

What is refused

Both factories refuse what the carrier cannot hold, and they say which limit was reached. 38 digits is the widest decimal here and the widest DECIMAL(p, s) that may be declared. A NaN, an infinity and anything else that is not a number are refused at the call rather than turned into something, because an exact number is what a decimal is.

The parse checks the width itself rather than trusting the engine's. Decimal::parse takes a scale and does not compare the result against MAX_DIGITS, and 39 ones fit inside an i128, so a 39 digit decimal would otherwise have gone through. Filed against the engine separately.

Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or was handed back by the engine, so the two numbers read out of one are two this engine already holds.

What needed nothing

The column side. A decimal column is a complex column and rides the per-value path, so the kind() fallback already names it, and zu-arrow already writes Decimal128. ZuAppendValue and ZuFrameValue are untouched, since there is no decimal column type to append to.

Checked

Run on a server rather than here.

• npm run build:debug, then binding.d.cts compared against what napi build generated: identical, byte for byte
• node --test test/values.test.mjs test/exports.test.mjs: 26 tests, 26 pass, 11 of them new
• npm run check:types, npm run check:api, npm run check:package: green, with etc/zudb.api.md updated and committed
• the corpus at the new pin: 1438 cases, 1437 passed, 0 failed, 1 unsupported, which is the one this client has always left unanswered
• node --test test/conformance*.test.mjs: 87 tests, 87 pass

One test failed on that server and is not from this change: progress.test.mjs asserts that a watch interval longer than the statement never fires, and the machine was loaded enough that the statement took 299 seconds.