[2.x] Add formatters for decoded nodes

[lorisleiva]

This PR adds formatters that turn decoded nodes into human-readable strings, using the presentation metadata of the nodes that decoded them: units, display nodes, scales and ticks.

// u64 with amountNumberDisplayNode({ decimals: integerValueNode('6'), unit: stringValueNode('USDC') })
formatInteger(decoded); // "1.5 USDC"
formatFixedPoint(decoded); // "123.45%"
formatDateTime(decoded); // "2024-01-01T00:00:00.5Z"
formatDuration(decoded); // "49:00:00"

• Formatters: formatInteger, formatFloat, formatFixedPoint, formatDateTime, formatDuration and formatString each take the decoded node of their kind.
• Exact: amounts and fixed points, including 128-bit and binary (Q-format) ones, use the fixed points of @solana/codecs. Date-times are exact ISO 8601 UTC strings for any year, computed with bigint calendar maths.
• Units: a display node's unit wins over the type's unit, which is the fallback when the former is absent or can't be resolved. Units follow their value after a space, except %, ‰ and °.
• Amounts with unresolved decimals: formatInteger returns null instead of a wrongly scaled amount, so callers can show the raw value.
• Options: formatUnit places units, e.g. "USD 40.5"; numberFormat formats for a locale, its options deciding the digits shown, without ever going through a JavaScript float; resolveInjectedValue resolves injected decimals and units from their path through the decoded node.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e128735

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[lorisleiva]

@trevor-cortex

[lorisleiva]

• [2.x] Format decoded nodes into formatted node trees #1218
• [2.x] Add formatters for booleans, bytes, enums and public keys #1217
• [2.x] Return decoded nodes from dynamic parsers #1216
• [2.x] Add formatters for decoded nodes #1215 👈 (View in Graphite)
• [2.x] Decode Codama nodes into decoded node trees #1214
• [2.x] Report defined types without a finite value in validators #1213
• [2.x] Support recursive defined types in dynamic codecs #1212
• [2.x] Detect cyclic defined types #1211
• [2.x] Port the dynamic client to Codama v2 #1209
• [2.x] Reject duplicate set items in dynamic codecs #1208
• [2.x] Upgrade v1 instructions, programs and roots to v2 #1207
• [2.x] Keep the cause of validation items and drop their node #1206
• [2.x] Make NodePath non-distributive over node unions #1205
• [2.x] Use the published v1 node types in @codama/upgrade #1201
• [2.x] Add v1 to v2 upgrade converters for types and values #1200
• [2.x] Adapt to spec 2.0.0-rc.1 #1196
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[trevor-cortex]

Summary

Adds formatInteger, formatFloat, formatFixedPoint, formatDateTime, formatDuration and formatString to @codama/dynamic-codecs. Each takes the decoded node of its kind and renders it using the presentation metadata of the node that decoded it: unit, display (amount / unit / string display nodes), scale/base, and ticksPerSecond. Scaled numbers go through Kit's @solana/fixed-points (rawDecimalFixedPoint / rawBinaryFixedPoint) so 128-bit and Q-format values are exact; date-times use bigint calendar maths (Hinnant's civil_from_days) so any i64 timestamp formats correctly. Options cover unit placement, Intl.NumberFormat and a resolveInjectedValue callback for display-node inputs.

The core logic is solid. I walked through getCivilDate against the reference algorithm (the floorDiv for era and truncating division for the rest is correct since dayOfEra is always non-negative), floorDiv's sign handling, the nanosecond rounding path (half signed to round away from zero, then truncating division — correct), and the unit precedence (display wins, type unit is the fallback when the display unit is absent, injected-and-unresolved, or resolves to ''), which matches the spec text on amountNumberDisplayNode / unitNumberDisplayNode. Tests are thorough on the number and date paths, including the i64 extremes and a cross-check against Date.prototype.toISOString within JS's range.

Things to address / consider

• Missing changeset. CONTRIBUTING.md asks for one for any user-facing change (npx changeset add --empty), and this adds new public exports to @codama/dynamic-codecs. No .changeset/*.md is in the diff.
• formatString slices UTF-16 code units while the spec says indices apply to the "decoded character sequence". See inline — if that's meant to be code points, non-BMP characters (emoji, some CJK) will be split.
• Unbounded decimals from the resolver — see inline on resolveIntegerInput. Low risk, but a cheap guard.
• Fractional ticksPerSecond. Both formatDateTime and formatDuration return null unless ticksPerSecond is a positive integer. If the spec allows e.g. 1/60 for minute-resolution timestamps, that's a legit value we'd refuse to format. If the validators already restrict it to positive integers, ignore this — just want to make sure the null isn't hiding a supported case.

Notes for subsequent reviewers

• @solana/codecs@^8.4.0 already re-exports @solana/fixed-points, so the new imports (rawDecimalFixedPoint, formatDecimalFixedPoint, Signedness, …) don't need a dependency bump.
• The resolveInjectedValue option is intentionally a plain callback rather than reusing the package's ProvidedScope machinery from getValueNodeVisitor — display-node inputs like decimals typically come from external providers (e.g. a mint account), not from the instruction scope. Worth keeping in mind if someone later wants a default resolver built on scope.
• Test coverage gaps that are minor but would be nice: formatInteger with an amount display on shortU16 (exercises the special-case in getIntegerLayout), a 128-bit binary fixed point, a resolved (not just unresolved) injected unit on formatFixedPoint, and formatDuration with a non-power-of-10 ticksPerSecond.

[trevor-cortex]

Re-review

Re-fetched the diff. Everything actionable from my first pass has been addressed:

• formatString now slices by Unicode code point (Array.from(...).slice(...).join('')), with tests for both a sliceEnd and a sliceStart landing after an emoji. README and JSDoc document the semantics.
• DecimalFixedPoint / BinaryFixedPoint are imported directly instead of Parameters<typeof …>[0].
• numberFormat docs (JSDoc + README) now say its options decide the digits shown, with the 3-fraction-digit default called out, and that only amounts and fixed points bypass JS floats. There's a maximumFractionDigits: 2 test on an amount pinning this.
• README documents the ticksPerSecond → null behaviour.
• Coverage gaps filled: shortU16 amount (checked dc0b → 1500), 128-bit binary fixed point (verified the (2^128 − 1) / 2^64 expansion by hand — correct), resolved injected unit on formatFixedPoint, and a locale test on fixed points.

Still open (non-blocking)

• Changeset. There's still no .changeset/*.md in the diff. If it's being added at the top of the Graphite stack along with the rest of the dynamic-codecs work, ignore this — just flagging so it doesn't fall through the cracks before the stack merges.
• decimals upper bound in resolveIntegerInput is still MAX_SAFE_INTEGER. Purely defensive; happy to leave it as-is if you'd rather trust the resolver.

Approving — the implementation is correct and well tested.

(Apologies for the delay — GitHub's API was returning 500s on my earlier attempts to post this.)