feat(tree): Promote alpha change event APIs to beta by Josmithr · Pull Request #27942 · microsoft/FluidFramework

Joshua Smithrud (Josmithr) · 2026-08-12T19:07:23Z

See changeset for details

github-actions · 2026-08-12T19:09:29Z

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

Based on the diff (1117 lines, 22 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

Copilot

Pull request overview

Promotes the detailed SharedTree change-event payload surface (previously only available via TreeAlpha.on for array nodes) to the beta API, and updates entrypoints, type tests, and generated API reports accordingly.

Changes:

Adds/exports array delta operation types and delta-carrying event payload types as beta APIs, including TreeChangeEventsBeta.treeChanged for array nodes.
Refactors the alpha change-event typings (TreeChangeEventsAlpha, NodeChangedDataAlpha) into compatibility aliases of the beta event variants.
Updates type-level tests, entrypoints, changeset notes, and API report outputs to reflect the promotion.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/framework/fluid-framework/api-report/fluid-framework.legacy.beta.api.md	Generated API report updates reflecting newly beta-exported change-event payload types.
packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md	Generated API report updates reflecting newly beta-exported change-event payload types.
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	Generated API report updates reflecting promotion of previously-alpha change-event payload types to beta.
packages/dds/tree/src/test/simple-tree/api/treeNodeApi.spec.ts	Updates compile-time typing tests and runtime event tests to validate beta event payload availability.
packages/dds/tree/src/simple-tree/api/treeNodeApi.ts	Promotes array delta op types to beta and updates docs to reference beta event APIs.
packages/dds/tree/src/simple-tree/api/treeBeta.ts	Adds beta event payload typings (including `treeChanged` payloads for array nodes) and exports related event data types.
packages/dds/tree/src/simple-tree/api/treeAlpha.ts	Converts alpha event types into compatibility aliases of the beta event types.
packages/dds/tree/src/simple-tree/api/index.ts	Re-exports newly beta-promoted event payload types from the beta API surface.
packages/dds/tree/src/shared-tree/treeAlpha.ts	Updates alpha API docs to reflect that the richer event API is now available via TreeBeta.
packages/dds/tree/src/entrypoints/legacy.ts	Exports the newly beta-promoted payload and delta-op types from the legacy entrypoint.
packages/dds/tree/src/entrypoints/beta.ts	Exports the newly beta-promoted payload and delta-op types from the beta entrypoint.
packages/dds/tree/src/entrypoints/alpha.ts	Adjusts alpha entrypoint exports to avoid duplicating types now exported from beta.
packages/dds/tree/api-report/tree.legacy.beta.api.md	Generated API report updates reflecting newly beta-exported change-event payload types.
packages/dds/tree/api-report/tree.beta.api.md	Generated API report updates reflecting newly beta-exported change-event payload types.
packages/dds/tree/api-report/tree.alpha.api.md	Generated API report updates reflecting promotion of previously-alpha change-event payload types to beta.
.changeset/promote-tree-change-event-payloads.md	Changeset documenting the beta promotion and providing usage examples.

Suppressed comments (3)

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts:50

These array delta op types are now promoted to Beta Kuang (@beta), but their members are still undocumented (API reports show them as "(undocumented)"). Adding brief JSDoc to the exported members will improve the generated reference docs for the newly-beta surface area.

This issue also appears in the following locations of the same file:

line 87
line 97

 * @sealed @beta
 */
export interface ArrayNodeRetainOp {
	readonly type: "retain";
	readonly count: number;

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts:91

These array delta op types are now promoted to Beta Kuang (@beta), but their members are still undocumented (API reports show them as "(undocumented)"). Adding brief JSDoc to the exported members will improve the generated reference docs for the newly-beta surface area.

 * @sealed @beta
 */
export interface ArrayNodeInsertOp {
	readonly type: "insert";
	readonly count: number;

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts:101

These array delta op types are now promoted to Beta Kuang (@beta), but their members are still undocumented (API reports show them as "(undocumented)"). Adding brief JSDoc to the exported members will improve the generated reference docs for the newly-beta surface area.

 * @sealed @beta
 */
export interface ArrayNodeRemoveOp {
	readonly type: "remove";
	readonly count: number;

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

… instead

…e dependencies

Joshua Smithrud (Josmithr) · 2026-08-12T23:46:28Z

 // Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,
 // and where most of the actual implementation is for much of it.

-/**


Note for reviewers: to avoid circular module dependencies elsewhere, beta event types were moved to a new module: treeChangeEventsBeta.ts.

Joshua Smithrud (Josmithr) · 2026-08-12T23:46:59Z

- * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
- * @sealed @alpha
- */
-export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {


Note for reviewers: these types were moved to treeChangeEventsBeta.ts

Joshua Smithrud (Josmithr) · 2026-08-12T23:47:34Z

- * Represents elements that were neither inserted into nor removed from the array.
- * @sealed @alpha
- */
-export interface ArrayNodeRetainOp {


Note for reviewers: these types were moved to treeChangeEventsBeta.ts

Joshua Smithrud (Josmithr) · 2026-08-12T23:50:59Z

+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+


Note for reviewers: all of the below types are existing and were migrated here to prevent circular module dependencies. They are unchanged aside from the promotion of array delta types from alpha to beta.

Joshua Smithrud (Josmithr) · 2026-08-17T20:08:52Z

Copilot resolve the merge conflicts in this pull request

github-actions · 2026-08-18T21:36:34Z

🔗 Found some broken links! 💔

Run a link check locally to find them. See Checking for Broken Links for more information.

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/
[ELIFECYCLE] Command failed with exit code 1.

github-actions · 2026-08-18T22:00:26Z

Bundle size comparison

Base commit: cc08e183b8d5c6c722d6983e90b8f0373067e5d0
Head commit: 128c805b0bebf42617717aef9188aeda61a851cc

Notable changes

No bundles changed by ≥ 500 bytes parsed.

Per-bundle deltas

`@fluid-example/bundle-size-tests`

fluidFrameworkAllAlpha.js: parsed 784509 → 784551 (+42), gzip 215049 → 215079 (+30)
azureClient.js: parsed 624847 → 624903 (+56), gzip 166640 → 166685 (+45)
odspClient.js: parsed 597135 → 597191 (+56), gzip 159785 → 159826 (+41)
aqueduct.js: parsed 531223 → 531258 (+35), gzip 142114 → 142143 (+29)
fluidFramework.js: parsed 403809 → 403830 (+21), gzip 114489 → 114507 (+18)
sharedTree.js: parsed 393213 → 393227 (+14), gzip 111931 → 111940 (+9)
containerRuntime.js: parsed 309144 → 309158 (+14), gzip 84569 → 84576 (+7)
sharedString.js: parsed 176510 → 176517 (+7), gzip 49798 → 49805 (+7)
experimentalSharedTree.js: parsed 160665 → 160665 (0), gzip 46265 → 46265 (0)
matrix.js: parsed 160341 → 160348 (+7), gzip 45798 → 45805 (+7)
loader.js: parsed 145704 → 145718 (+14), gzip 39286 → 39301 (+15)
odspDriver.js: parsed 103906 → 103927 (+21), gzip 32404 → 32411 (+7)
directory.js: parsed 67110 → 67117 (+7), gzip 18859 → 18866 (+7)
578.js: parsed 58686 → 58686 (0), gzip 17657 → 17657 (0)
map.js: parsed 47205 → 47212 (+7), gzip 14455 → 14462 (+7)
odspPrefetchSnapshot.js: parsed 45635 → 45649 (+14), gzip 15242 → 15249 (+7)
252.js: parsed 44362 → 44362 (0), gzip 13735 → 13735 (0)
summarizerDelayLoadedModule.js: parsed 30717 → 30717 (0), gzip 7716 → 7716 (0)
socketModule.js: parsed 26469 → 26476 (+7), gzip 7896 → 7904 (+8)
createNewModule.js: parsed 12454 → 12454 (0), gzip 4797 → 4797 (0)
summaryModule.js: parsed 3789 → 3789 (0), gzip 1857 → 1857 (0)
connectionState.js: parsed 909 → 909 (0), gzip 500 → 500 (0)
sharedTreeAttributes.js: parsed 847 → 854 (+7), gzip 499 → 508 (+9)
debugAssert.js: parsed 429 → 429 (0), gzip 299 → 299 (0)
FluidFramework-HashFallback.js: parsed 419 → 419 (0), gzip 313 → 313 (0)

feat(tree): Promote alpha change event APIs to beta

19e34f1

Joshua Smithrud (Josmithr) requested review from Craig Macomber (Microsoft) (CraigMacomber), daesunp, Jenn (jenn-le) and Noah Encke (noencke) and a lite review from Copilot August 12, 2026 19:07

Joshua Smithrud (Josmithr) requested review from a team as code owners August 12, 2026 19:07

Copilot started reviewing on behalf of Joshua Smithrud (Josmithr) August 12, 2026 19:09 View session

refactor: Leverage beta handler in alpha handler

61feaf0

Copilot AI reviewed Aug 12, 2026

View reviewed changes

Comment thread packages/dds/tree/src/simple-tree/api/treeBeta.ts Outdated

Comment thread packages/dds/tree/src/simple-tree/api/treeBeta.ts Outdated

Joshua Smithrud (Josmithr) added 2 commits August 12, 2026 19:24

test: Update tests that leveraged TreeAlpha.on to use TreeBeta.on…

ed13119

… instead

docs: Deprecate TreeAlpha.on

f0624db

Joshua Smithrud (Josmithr) marked this pull request as draft August 12, 2026 20:56

Joshua Smithrud (Josmithr) added 5 commits August 12, 2026 22:37

Merge branch 'main' into tree/promote-alpha-event-apis

45930dc

docs: Update API reports

4384729

docs: Add "subtree" to vale dictionary

6700772

refactor: Fix inheritance

5533835

refactor: Move beta event types to new module to avoid circular modul…

7fe249b

…e dependencies

Joshua Smithrud (Josmithr) commented Aug 12, 2026

View reviewed changes

test: Add simple type test

ee74a87

Joshua Smithrud (Josmithr) marked this pull request as ready for review August 13, 2026 00:12

Joshua Smithrud (Josmithr) marked this pull request as draft August 13, 2026 00:17

Joshua Smithrud (Josmithr) marked this pull request as ready for review August 14, 2026 17:15

Noah Encke (noencke) mentioned this pull request Aug 14, 2026

Add staged optional-to-required SharedTree field migration API (sf.stagedRequired) #27952

Draft

Joshua Smithrud (Josmithr) added 2 commits August 17, 2026 21:22

Merge branch 'main' into tree/promote-alpha-event-apis

2b6425d

docs: Update changeset

9d9c28d

daesunp reviewed Aug 18, 2026

View reviewed changes

Comment thread packages/dds/tree/src/test/simple-tree/core/treeNodeKernel.spec.ts

refactor: Use beta event registration API

128c805

Navigation Menu

Uh oh!

feat(tree): Promote alpha change event APIs to beta - #27942

feat(tree): Promote alpha change event APIs to beta#27942
Joshua Smithrud (Josmithr) wants to merge 13 commits into
microsoft:mainfrom
Josmithr:tree/promote-alpha-event-apis

Joshua Smithrud (Josmithr) commented Aug 12, 2026

Uh oh!

github-actions Bot commented Aug 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Uh oh!

Joshua Smithrud (Josmithr) commented Aug 17, 2026

Uh oh!

Uh oh!

github-actions Bot commented Aug 18, 2026

Uh oh!

github-actions Bot commented Aug 18, 2026

`@fluid-example/bundle-size-tests`

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Joshua Smithrud (Josmithr) commented Aug 12, 2026

Uh oh!

github-actions Bot commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) commented Aug 17, 2026

Uh oh!

Uh oh!

github-actions Bot commented Aug 18, 2026

linkcheck output

Uh oh!

github-actions Bot commented Aug 18, 2026

Bundle size comparison

Notable changes

@fluid-example/bundle-size-tests

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Aug 12, 2026 •

edited

Loading

`@fluid-example/bundle-size-tests`