Skip to content

feat: BigNumber fixed-point decimal safety wrapper for multi-tariff scaling. - #83

Merged
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/decimal-fixed-point
Jun 25, 2026
Merged

feat: BigNumber fixed-point decimal safety wrapper for multi-tariff scaling. #83
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/decimal-fixed-point

Conversation

@real-venus

Copy link
Copy Markdown
Contributor

BigNumber Fixed-Point Arithmetic Safety Wrapper for Multi-Tariff Decimal Scaling (#53)

Closes #53

What's included

File Responsibility
src/utils/decimal.ts Branded Decimal<P> over a cloned BigNumber (28 sig digits, ROUND_HALF_UP — no global-config mutation). Factory decimal(value, precision) + add/sub/mul/div/min/max/sum/average/neg/abs and eq/gt/gte/lt/lte. Overflow past MAX_SAFE (10²¹) throws SafetyRangeError; unsupported precision / bad input throws PrecisionError. toRedux()/fromRedux() give lossless string serialization; toDecimalNumber() warns on precision loss.
src/types/meter.ts MeterReading / ResourceConsumption / TariffRate keyed to Decimal, with canonical precision per resource (water 0, cost 2, electricity 3, gas 4, submeter 6, nano 9).
src/utils/aggregation.ts sumReadings, averageReadings, min/maxReading, cumulativeTotals, aggregateByWindow, and applyTariff — Decimal end-to-end, never cast back to number mid-pipeline.
src/store/slices/resourceSlice.ts Store keeps readings as string-encoded SerializedDecimal (JSON/DevTools-safe) and rehydrates Decimals only inside selectors.
src/components/dashboard/ResourceChart.tsx SVG time-series that converts each value via toDecimalNumber once at render, while the headline total stays exact (toFixed).
src/hooks/useResourceData.ts Converts the API's string-encoded decimals into Decimal at the resource's precision on ingestion (never parsed as number).
tests/unit/{decimal,aggregation,resourceSlice}.test.ts Mixed-precision add upcast, mul overflow, serialization round-trip, 1000-iteration zero-drift, tariff rounding, and store round-trip.

…caling (Utility-Protocol#53)

Replaces Number-based arithmetic (which drifts up to 0.05% over aggregation
windows) with an exact fixed-point Decimal layer over BigNumber.js.

- utils/decimal.ts: branded Decimal<P> over a cloned BigNumber (28 sig digits,
  ROUND_HALF_UP); factory + add/sub/mul/div/min/max/sum/average/neg/abs and
  comparisons. Intermediates stay exact; overflow past MAX_SAFE (10^21) throws
  SafetyRangeError; unsupported precision throws PrecisionError. toRedux()/
  fromRedux() give lossless string serialization; toDecimalNumber() warns on
  precision loss at the charting boundary
- types/meter.ts: MeterReading/ResourceConsumption/TariffRate keyed to the
  Decimal type, with canonical precision per resource (water 0, cost 2,
  electricity 3, gas 4, submeter 6, nano 9)
- utils/aggregation.ts: sum/average/min/max/cumulative/windowed totals and
  applyTariff, all Decimal end-to-end (never cast back to number)
- store/slices/resourceSlice.ts: store keeps readings string-encoded
  (SerializedDecimal) and rehydrates Decimals only in selectors
- components/dashboard/ResourceChart.tsx: SVG series that converts via
  toDecimalNumber at render while keeping the headline total exact
- hooks/useResourceData.ts: converts API string decimals to Decimal at the
  resource precision on ingestion
- tests: mixed-precision add upcast, multiplication overflow, serialization
  round-trip, and 1000-iteration zero-drift accumulation
@elizabetheonoja-art
elizabetheonoja-art merged commit 482f59b into Utility-Protocol:main Jun 25, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BigNumber Fixed-Point Arithmetic Safety Wrapper for Multi-Tariff Decimal Scaling

2 participants