An exact decimal is a ZuDecimal by tamnd · Pull Request #31 · tamnd/zu-node

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd · 2026-08-25T08:02:54Z

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]=awaitconn.query("RETURN CAST('1.20' AS DECIMAL(5, 2)) AS total")row.total.toString()// '1.20'row.total.scale// 2row.total.unscaled// 120nJSON.stringify(row)// '{"total":"1.20"}'awaitconn.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.

The engine grew a decimal type: 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. 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. The scale rides on the value rather than only on the column, 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 takes the pair for a caller who has one. 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 and an infinity are refused at the call rather than turned into anything, because an exact number is what a decimal is. The parse checks the width itself: the engine's own parse takes a scale and does not compare the result against the maximum, and 39 ones fit an i128. Nothing on the way in is re-checked. Every ZuDecimal was built by a factory that refused what a decimal cannot hold, or handed back by the engine, so the two numbers read out of one are two this engine already holds. The column side needed nothing: a decimal column is a complex column and rides the per-value path, and zu-arrow already writes Decimal128.

tamnd merged commit a362df9 into mainAug 25, 2026
25 checks passed

tamnd deleted the engine-decimal branch August 25, 2026 08:12