[lorisleiva]

This PR lets dynamic codecs handle defined types that link back to themselves, such as linked lists and trees. Creating their codecs used to overflow the call stack.

// list = struct { value: u8, next: option<link(list)> }
const codec = getNodeValueCodec([root, program, list]);
codec.encode({ next: { __option: 'Some', value: { next: null, value: 2 } }, value: 1 }); // 0x01010200

• Lazy links back: a link back to a type whose codec is still being created gets a lazy codec, which defers to the finished codec when first used. Every other node gets the same codec as before.
• Types with no finite value: creating the codec of a type whose every value would nest another one, e.g. loop = struct { next: link(loop) }, throws the new CODAMA_ERROR__DEFINED_TYPE_HAS_NO_FINITE_VALUE (17) with { name, path }.
• Fixed-size items: a link back to its own type is variable-size, so it cannot be the item of a fixed option or a zeroable option.
• Other packages: dynamic-parsers, dynamic-address-resolution and dynamic-instructions create their codecs through this visitor, so they handle recursive types too. A parser test covers a recursive account.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 557ab3d

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
• [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 👈 (View in Graphite)
• [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 recursive defined type support to the dynamic codec visitor. visitDefinedType registers the type in a definedTypesInProgress map (keyed by node identity) for the duration of its creation; visitDefinedTypeLink now resolves the linked path itself and, when the target is in progress, returns a getLazyCodec that defers to the finished codec on first use. Before handing out a lazy codec, hasDefinedTypeFiniteValue (from @codama/visitors-core) rejects types with no finite value with the new CODAMA_ERROR__DEFINED_TYPE_HAS_NO_FINITE_VALUE (17). Link transforms still apply on top of the lazy codec via the existing intercept layer, so size prefixes etc. work at every depth.

I walked through the key paths and they hold up:

• Identity-keyed lookup via the resolved path's last node correctly distinguishes same-named types across programs (covered by test).
• Mutual recursion through intermediate types (person ↔ friends) works because only the type whose codec is actually in progress gets the lazy treatment; intermediates are created normally.
• The finite check is anchored on the back-linked type, so usesLoop → loop correctly reports loop, and a type like a = struct { x: link(b) }, b = struct { z: link(a) } is correctly rejected as a.
• inProgress is a per-call object captured by the lazy closure, so it stays valid after the map entry is deleted in finally, and a throw mid-creation cleans up properly for reused visitors (e.g. in dynamic-parsers).
• Verified the expected hex in all four happy-path tests by hand.

Things to watch

• Changeset: @codama/dynamic-codecs and @codama/errors are both public and this is a user-facing feature + new error code, but there's no .changeset/*.md in the diff. If a lower PR in the stack already covers this concern, ignore; otherwise one is needed before merge per CONTRIBUTING.
• Finite check semantics: hasDefinedTypeFiniteValue also returns false for types containing a variant-less enum, so e.g. a = struct { next: option<link(a)>, e: enum {} } throws DEFINED_TYPE_HAS_NO_FINITE_VALUE with a message that blames nesting. The type genuinely has no values so the error code is defensible, just noting the message is slightly off in that corner — and that the non-recursive struct { e: enum {} } doesn't throw at all. Not blocking.
• Minor nits inline: optional caching of the finite check, a small readability tweak in visitDefinedType, and the untested invariant-violation branch.

For subsequent reviewers

hasDefinedTypeFiniteValue / getHasFiniteValueVisitor are not in this diff — they land in a lower PR of the stack. Their rules (options/enums/non-fixed collections stop recursion; transforms don't) are what make the "lazy codecs never recurse at creation time" guarantee hold, so review those together with this one.

[trevor-cortex]

Re-review

Re-fetched the diff. All three points from my previous pass are addressed:

• Finite check caching: finiteDefinedTypes set on the visitor, keyed by node identity, populated only on success — so a failing type still throws on every attempt, which is the right behaviour. The check and the lazy codec creation are now neatly bundled in getRecursiveCodec.
• visitDefinedType readability: inProgress is now explicitly typed and the codec is returned from a local rather than through narrowing across the try/finally.
• Invariant-violation test: the new sentinelTransformNode(constantValueNode(definedTypeLinkNode('list'), …)) case covers the branch and locks in the message. The option wrapper keeps the type finite so the check passes, and the sentinel's getConstantBytes then hits the lazy codec before inProgress.codec is set — exactly the path the comment describes.

Logic in visitDefinedTypeLink / getRecursiveCodec is otherwise unchanged from what I verified last time. Still LGTM.

Still outstanding

• Changeset: still no .changeset/*.md in this PR. @codama/dynamic-codecs is public and gains a user-facing feature; @codama/errors gains a new code (and is in the fixed group, so it'll bump with the core packages regardless). If the lower detect_cyclic_defined_types PR already adds one that mentions dynamic-codecs, fine — otherwise it needs one before merge.