feat(tree): getOrInsert mapNode alpha API

[brrichards]

Description

Adds getOrInsert alpha API for mapNode. Updates current mapNode alpha API changeset

Reviewer Guidance

The review process is outlined on this wiki page.

[Copilot]

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (135 lines, 5 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[yann-achard-MS]

I'm concerned the cast may hide some cases where we can't actually rely on the fallbackValue being the same thing as what this.get(key) might return. @CraigMacomber - is there a safe way to avoid having to call this.get(key) here?

[brrichards]

It wasn't letting the return happen without the cast unfortunately so curious about this as well

[CraigMacomber]

This code is incorrect, and the typing is right about your value being wrong.

fallbackValue is an insertable value, which might not be a node, but might implicitly get constructed into one.

You have 4 choices for how to handle this:

1. force the insertable value into a node before inserting (Like TreeBeta.create can do), then insert that and return it
2. let set do the implicit construction, then look it up with get
3. Require input to be a node/tree value and not an insertable value
4. Remove the return value

2 is the simplest, so I'd recommend it, but 1 is also reasonable.

[CraigMacomber]

https://fluidframework.com/docs/api/fluid-framework/treenode-class has some details about implicit node construction.

[yann-achard-MS]

Thanks Craig.
@brrichards - Please have a look at option 1, but if it seems too cumbersome then I'd be ok with option 2.

[brrichards]

updated with option 1 following sort of what set does, but if this isnt ideal can change to option 2.

[Josmithr]

Nit

Suggested change

	* This API is not equivalent to the following alternative:
	* This API is **not** equivalent to the following alternative:

[Josmithr]

Left a couple of docs suggestions. But overall they look great! Thanks for being so thorough!

[dannimad]

wait for #27824 to merge

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-website@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  309092 links
    1963 destination URLs
    2219 URLs ignored
       0 warnings
       0 errors

[github-actions]

Bundle size comparison

Base commit: d34c9cee41f6b5fcb9d157acbe53afda9402e036
Head commit: b8440aae117cc3907ecaa48fc29a355188499cfe

⚠️ Comparison unavailable.

No CI build was found for the PR HEAD commit. This shouldn't happen — the workflow only runs after the PR's Build - client packages check completes. Please report.