[2.x] Add formatters for booleans, bytes, enums and public keys

[lorisleiva]

This PR adds formatters for the remaining leaf values of decoded nodes, and makes every formatter share the same (decoded, options) signature.

formatBoolean(decoded); // "true"
formatBytes(decoded); // "0x0102", whatever encoding the bytes were decoded with
formatEnum(decoded); // the variant's label, otherwise its identifier in title case, e.g. "Move To"
formatPublicKey(decoded, { formatAddress: address => names.get(address) ?? address }); // "USDC"

• Addresses: the new formatAddress option formats addresses however the caller needs, e.g. to name them from a trusted token list or address book, or to truncate them. It defaults to the address itself.
• Uniform signatures: every formatter now accepts FormatOptions, even those that use none of them yet, so any formatter can stand in for another.
• Invalid ticks: formatDateTime and formatDuration now throw the new CODAMA_ERROR__INVALID_TICKS_PER_SECOND when ticksPerSecond is not a positive integer, instead of returning null. formatInteger is now the only formatter returning null, for amounts whose decimals cannot be resolved.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d09bf71

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]

• [2.x] Format decoded nodes into formatted node trees #1218
• [2.x] Add formatters for booleans, bytes, enums and public keys #1217 👈 (View in Graphite)
• [2.x] Return decoded nodes from dynamic parsers #1216
• [2.x] Add formatters for decoded nodes #1215
• [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.

[lorisleiva]

@trevor-cortex

[trevor-cortex]

Summary

Adds formatBoolean, formatBytes, formatEnum and formatPublicKey to @codama/dynamic-codecs, gives every formatter the uniform (decoded, options) signature, introduces the formatAddress option, and replaces the null return of formatDateTime/formatDuration on bad ticksPerSecond with a new CODAMA_ERROR__INVALID_TICKS_PER_SECOND. getCodecFromBytesEncoding is extracted to bytes.ts so both codecs.ts and format.ts can use it.

The implementation is straightforward and the tests cover the interesting paths (title-cased identifiers vs. string vs. textNode labels, variant data excluded, base58-decoded bytes with leading zeros re-encoded exactly, empty bytes, custom address formatters). Docs and JSDoc are consistent with the new behaviour. Error code 18 follows the precedent set by 17 for dynamic-codecs errors in the general range, and the CodamaErrorCode union / context / messages are all updated.

Things to watch

• Import ordering in format.ts: getTextNodeContent is inserted after isNode, which breaks the case-insensitive sort the rest of the file follows. pnpm lint:fix should sort it out, but worth doing before merge so CI doesn't trip on it.
• Changeset: the diff doesn't include one, and this is user-facing for both @codama/dynamic-codecs (new exports, new option, null → throw) and @codama/errors (new code). If the 2.x branch still expects per-PR changesets, this needs one (two concerns, so probably two files per CONTRIBUTING). If the seeded major changeset already covers everything on this branch, ignore this.
• Behaviour change: formatDateTime/formatDuration now throw instead of returning null. Callers that were checking for null will need updating — fine for a major era, just flagging it for anyone reading the changelog later.

Notes for subsequent reviewers

• formatBytes always renders hex, even for utf8-decoded bytes. That's a deliberate and documented choice (README + JSDoc explain the lossy utf8 round-trip), not an oversight.
• formatPublicKey casts decoded.value as Address because DecodedPublicKeyTypeNode types its value as string. Narrowing that decoded type to Address could be a nice follow-up but is out of scope here.

[trevor-cortex]

Re-review

All three nits from the previous pass are addressed:

• getTextNodeContent is now in case-insensitive sort order in the @codama/nodes import.
• formatBytes.test.ts gains a utf8 round-trip case (hex('6869') → ['utf8', 'hi'] → '0x6869'), pinning the one encoding where formatting can be lossy.
• formatPublicKey.test.ts uses address(USDC) and hoists the shared decoded, which also reads better now that all three cases share the same input.

Nothing else changed in the source, error registry, or README. Still no changeset in the diff — if the 2.x stack relies on a seeded major changeset that's fine, otherwise this still needs one for @codama/dynamic-codecs and @codama/errors.

Approving.