[lorisleiva]

This PR adds formatDecodedNode, which formats a decoded node of any kind, e.g. a whole account, into a formatted node tree. Formatted nodes extend their decoded nodes, so they keep the same shape and child names, plus the text and display attributes needed to present them.

const formatted = formatDecodedNode(account, { formatAddress: address => names.get(address) ?? address });
formatted.text; // "Amount: 1.5 USDC, Owner: Alice, Config: (Fee: 25 bps)"

assertIsFormattedNode(formatted.data, 'structTypeNode');
formatted.data.fields[0]; // { label: 'Amount', text: '1.5 USDC', skip: 'never', flatten: false, type: … }

getDecodedNodeAtPath(formatted, pathString('config.fee'))?.text; // "25 bps"

• Text: every node has a text. Leaves use the formatter of their kind, and containers join the text of their children, e.g. Limit (Price: 100) for an enum with data. Struct fields skipped always are left out, and flattened ones are replaced by their prefixed fields.
• Display attributes: struct fields carry their label, skip, flatten and flattenPrefix, and enum variants their label and skipInnerData, with defaults. Laying the tree out, e.g. as nested rows, is left to the caller.
• Degraded values: amounts whose decimals cannot be resolved are written as their raw value and marked degraded, as is every node whose text includes them.
• Overrides: the formatters of every leaf kind can be overridden, e.g. formatBoolean: boolean => (boolean.value ? 'Yes' : 'No'). Public keys go through formatAddress.
• Paths: getDecodedNodeAtPath finds the node a path expression points to, in decoded or formatted nodes, e.g. to fill an interpolated intent.
• Public keys: DecodedPublicKeyTypeNode's value is now typed as an Address.

[changeset-bot]

⚠️ No Changeset found

Latest commit: df5a57f

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 👈 (View in Graphite)
• [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
• [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 formatDecodedNode, which walks a decoded node tree and returns the same tree with text / degraded on every node, plus inlined display attributes (label, skip, flatten, flattenPrefix on struct fields; label, skipInnerData on enum variants). Leaf formatters are overridable per kind via options; public keys go through the existing formatAddress. Also adds getDecodedNodeAtPath for resolving PathString expressions against decoded or formatted nodes, and tightens DecodedPublicKeyTypeNode['value'] to Address (which lets formatPublicKey drop its cast).

The implementation is clean and the design holds together well: formatted nodes are structural supertypes of decoded nodes so everything in decoded.ts keeps working, degraded propagation follows "is it in the text" rather than "is it in the tree" (and the tests pin that down for skip: 'always' and skipInnerData), and FormattedNodeMap + kind satisfies never keep the switch exhaustive. I checked the link-transparency question — visitDefinedTypeLink unwraps to the linked type at decode time, so flatten and embed correctly see nested linked structs as structTypeNode without special handling.

Things to address

• Missing changeset. CONTRIBUTING.md requires one for any user-facing change, and @codama/dynamic-codecs is public and versions independently (it's outside the fixed group). This is a new API surface, so a minor bump via npx changeset add seems right. Worth mentioning the DecodedPublicKeyTypeNode value type change in it too, since anyone building decoded nodes by hand with a plain string will now need address(...).

Minor / optional

• The formatEnum override only applies when formatting through an enumTypeNode; a bare enumVariantTypeNode computes its label directly (inline comment on the case). Low stakes, but worth either documenting or unifying.
• embed wraps empty composite text as (), e.g. Items: () for an empty nested array or struct, whereas formatEnumVariant already special-cases data.text !== ''. Might be intentional as a signal of emptiness — just flagging the asymmetry (inline comment).

Notes for subsequent reviewers

• Verify no other workspace package (e.g. dynamic-parsers or its tests) constructs DecodedPublicKeyTypeNode with a plain string literal — tsc across the monorepo should catch it, but worth a glance.
• getDecodedNodeAtPath deliberately returns undefined for out-of-range array/set indices but throws for out-of-range tuple indices and unknown struct fields (schema violations vs. data-dependent misses). Documented and tested; just don't mistake it for an inconsistency.
• skip: 'whenInjected' fields are included in text — the formatter has no notion of what was injected, and the README is explicit that only always is excluded. That's a reasonable boundary to leave to callers.

[trevor-cortex]

Re-review

Re-fetched everything. Both points from my previous pass are addressed:

• Enum variant label: getEnumVariantLabel now lives in utils.ts (née bytes.ts) and is shared by formatEnum and the bare enumVariantTypeNode case, so the default path is identical, and the formatEnum option doc states that it only applies through enums. The new "same default label as their enum" test pins it down. I checked for other ./bytes importers — only codecs.ts and format.ts, both updated.
• () for empty nested containers: now documented as deliberate in the README, the formatDecodedNode JSDoc and a dedicated test. Fine by me.

No new issues in the code. The remaining changes (utils.ts rename, formatPublicKey cast removal) are mechanical.

Still open

• Changeset. There's still no .changeset/*.md in this PR. Since this is stacked on 10-08-add_formatters_for_booleans_bytes_enums_and_public_keys, it may be that a single @codama/dynamic-codecs changeset lower in the stack covers the whole formatting feature — if so, ignore this. Otherwise one is needed per CONTRIBUTING.md, ideally also mentioning the DecodedPublicKeyTypeNode['value'] → Address tightening.

Nit (non-blocking)

• In formatted.test.ts, the test named "it formats enum variants on their own" actually formats the enum and reads formatted.variant, so it exercises the enumTypeNode path, not the standalone variant path (the test just above it does). Either rename it or call formatDecodedNode(decoded.variant) so the name matches.

Approving on the assumption the changeset is handled in the stack.