Decimals

1import { type Reader } from "./core.js";
2import { readInt32, readInt64, readInt128, readInt256 } from "./integers.js";
3
4/**
5 * A decimal kept lossless as its raw parts: `value = unscaled / 10 ** scale`.
6 * The `readDecimal*` readers return this so no precision or scale information is
7 * thrown away at decode time.
8 */
9export type DecimalValue = readonly [unscaled: bigint, scale: number];
10
11/**
12 * Format a {@link DecimalValue} as a fixed-point decimal string with `scale`
13 * fractional digits (e.g. `[15000n, 4]` -> `"1.5000"`). Plug in only when you
14 * need a string.
15 *
16 * Trailing zeros are preserved to reflect the declared scale, deliberately unlike
17 * ClickHouse's text output, which trims them (`"1.5"`) and drops the point for
18 * integers (`"10"`).
19 */
20export function formatDecimal([unscaled, scale]: DecimalValue): string {
21  if (scale === 0) return unscaled.toString();
22  if (unscaled < 0n) {
23    const digits = (-unscaled).toString().padStart(scale + 1, "0");
24    const point = digits.length - scale;
25    return `-${digits.slice(0, point)}.${digits.slice(point)}`;
26  }
27  const digits = unscaled.toString().padStart(scale + 1, "0");
28  const point = digits.length - scale;
29  return `${digits.slice(0, point)}.${digits.slice(point)}`;
30}
31
32/**
33 * Read a `Decimal32(P, S)`: a 4-byte little-endian signed integer (same wire
34 * shape as `Int32`) scaled by 10^S. Pass the column's scale `S`; returns a
35 * `Reader` of the raw `[unscaled, scale]` pair (see {@link formatDecimal}).
36 *
37 * `Decimal(P, S)` is an alias: pick the width reader by precision P — P<=9 ->
38 * Decimal32, <=18 -> Decimal64, <=38 -> Decimal128, <=76 -> Decimal256.
39 */
40export function readDecimal32(scale: number): Reader<DecimalValue> {
41  return (state) => [BigInt(readInt32(state)), scale];
42}
43
44/** Read a `Decimal64(P, S)`: 8-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
45export function readDecimal64(scale: number): Reader<DecimalValue> {
46  return (state) => [readInt64(state), scale];
47}
48
49/** Read a `Decimal128(P, S)`: 16-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
50export function readDecimal128(scale: number): Reader<DecimalValue> {
51  return (state) => [readInt128(state), scale];
52}
53
54/** Read a `Decimal256(P, S)`: 32-byte LE signed integer scaled by 10^S. Returns `[unscaled, scale]`; see {@link formatDecimal}. */
55export function readDecimal256(scale: number): Reader<DecimalValue> {
56  return (state) => [readInt256(state), scale];
57}