refactor(core-utils): Deprecate `assert` for external use by Josmithr · Pull Request #28080 · microsoft/FluidFramework

Joshua Smithrud (Josmithr) · 2026-08-26T00:22:27Z

The legacy assert API is intended only for use within the Fluid Framework client codebase and is now deprecated for external consumers.
Consumers should replace it with an assertion utility appropriate for their application.

Usage within the Fluid Framework client is still permitted.

Existing usages of assert in example apps were replaced with Errors.

github-actions · 2026-08-26T00:23:19Z

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

Based on the diff (435 lines, 41 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

Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>

Copilot

Pull request overview

This PR deprecates the external assert export from @fluidframework/core-utils while preserving a non-deprecated assertion API for Fluid-internal consumers via a dedicated @fluidframework/core-utils/internal entry point. It also updates examples to stop relying on the deprecated external assert.

Changes:

Split @fluidframework/core-utils into shared (main.ts) plus external (index.ts) vs internal (internal.ts) entry points, exporting non-deprecated assert only from /internal.
Introduce assertInternal() and route the deprecated external assert() implementation through it.
Remove @fluidframework/core-utils usage from multiple examples (replace with explicit runtime checks / throws) and update lockfile accordingly.

Reviewed changes

Copilot reviewed 42 out of 43 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pnpm-lock.yaml	Removes `@fluidframework/core-utils` from several example importers after usage cleanup
packages/common/core-utils/src/timer.ts	Switches local usage to `assertInternal` to avoid deprecated symbol internally
packages/common/core-utils/src/math.ts	Switches local usage to `assertInternal` to avoid deprecated symbol internally
packages/common/core-utils/src/main.ts	New shared barrel for exports common to external + internal entry points (omits `assert`)
packages/common/core-utils/src/internal.ts	New internal entry point barrel that re-exports shared API + internal `assert`
packages/common/core-utils/src/index.ts	External entry point barrel now re-exports shared API + deprecated external `assert`
packages/common/core-utils/src/assert.ts	Adds `assertInternal`; deprecates external `assert`; routes `assert` through `assertInternal`
packages/common/core-utils/package.json	Updates `./internal` export map to point at `internal.{js,d.ts}` outputs
packages/common/core-utils/DEV.md	Documents the new entry point structure and rationale
packages/common/core-utils/api-report/core-utils.legacy.beta.api.md	API report updates `assert` to include `@deprecated`
packages/common/core-utils/api-extractor/api-extractor-lint-bundle.json	Lint-bundle now uses `lib/internal.d.ts` as the entry point
examples/view-integration/external-views/src/container/diceRoller/diceRoller.ts	Replaces deprecated `assert` usage with explicit runtime validation + throw
examples/view-integration/external-views/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/view-integration/container-views/src/container/diceRoller/diceRoller.ts	Replaces deprecated `assert` usage with explicit runtime validation + throw
examples/view-integration/container-views/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/version-migration/live-schema-upgrade/src/modelVersion2/diceCounter.ts	Replaces deprecated `assert` checks with explicit throws
examples/version-migration/live-schema-upgrade/src/app.ts	Replaces deprecated `assert` checks with explicit throws
examples/version-migration/live-schema-upgrade/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/utils/migration-tools/src/migrator/migrator.ts	Replaces deprecated `assert` checks with explicit throws
examples/utils/migration-tools/src/migrationTool/migrationTool.ts	Replaces deprecated `assert` checks with explicit throws
examples/utils/migration-tools/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/utils/example-utils/src/migrator/sameContainerMigrator.ts	Replaces deprecated `assert` checks with explicit throws
examples/utils/example-utils/src/migrationTool/sameContainerMigrationTool.ts	Replaces deprecated `assert` checks with explicit throws
examples/utils/example-utils/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/data-objects/webflow/src/html/formatters.ts	Replaces deprecated `assert` check with explicit throw
examples/data-objects/webflow/src/document/index.ts	Replaces deprecated `assert` check with explicit throw
examples/data-objects/webflow/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/data-objects/table-document/src/interception/tableWithInterception.ts	Replaces deprecated `assert` checks with explicit throws
examples/data-objects/table-document/src/cellrange.ts	Replaces deprecated `assert` check with explicit throw
examples/data-objects/table-document/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/data-objects/smde/src/smde.ts	Replaces deprecated `assert` check with explicit throw
examples/data-objects/smde/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/data-objects/prosemirror/src/fluidCollabManager.ts	Replaces deprecated `assert` check with explicit throw
examples/data-objects/prosemirror/src/fluidBridge.ts	Replaces deprecated `assert` checks with explicit throws
examples/data-objects/prosemirror/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/apps/task-selection/src/taskManagerDiceRoller.ts	Replaces deprecated `assert` checks with explicit throws
examples/apps/task-selection/src/oldestClientDiceRoller.ts	Replaces deprecated `assert` checks with explicit throws
examples/apps/task-selection/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/apps/staging/src/container/groceryList/groceryList.ts	Replaces deprecated `assert` check with explicit throw
examples/apps/staging/package.json	Drops unused `@fluidframework/core-utils` dependency
examples/apps/presence-tracker/src/datastoreSupport.ts	Replaces deprecated `assert` checks with explicit throws (including a TypeError for type mismatch)
examples/apps/presence-tracker/package.json	Drops unused `@fluidframework/core-utils` dependency
.changeset/tricky-rules-fly.md	Adds a changeset documenting the deprecation (minor bump, deprecation section)

Files not reviewed (1)

pnpm-lock.yaml: Generated file

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

Jason Hartman (jason-ha) · 2026-08-26T21:39:24Z

I think the reason I use api.ts in telemetry-utils was to preserve the history and be able to see the actual change. But, yeah, it means touching more places in package.json.
No need to change.

Jason Hartman (jason-ha) · 2026-08-26T21:42:20Z

+						// This package contains candidate shipping tools, not only example code, so it can use Fluid's internal assertion utility.
+						"@fluidframework/core-utils/internal",


Matt Rakow (@ChumpChief), sounds like an experiment and not an example.

Is the comment even right? example-utils to me sounded like utilities to be able to write examples without duplicating a ton of code. And I noted in a comment above that if that's the case, I'd argue assert isn't necessary in this package.

I think the point is that if these shared utilities are useful for writing most of our examples, then it might be natural to productionize them. I can clarify in the comment.

Alex Villarreal (alexvy86) · 2026-08-27T16:39:49Z

+						// This package contains candidate shipping tools, not only example code, so it can use Fluid's internal assertion utility.
+						"@fluidframework/core-utils/internal",


Is the comment even right? example-utils to me sounded like utilities to be able to write examples without duplicating a ton of code. And I noted in a comment above that if that's the case, I'd argue assert isn't necessary in this package.

github-actions · 2026-08-27T17:26:57Z

🔗 Found some broken links! 💔

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

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --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 --host 127.0.0.1 --no-open

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

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

Crawling...

http://127.0.0.1:3000/docs/data-structures/tree/schema-evolution/feature-flag-schema-upgrades
- (72:12) 'isStaged..' => http://127.0.0.1:3000/docs/api/fluid-framework/treeviewalpha-interface#isstagedupgradeenabled-methodsignature (HTTP 200 but missing anchor)


Stats:
  338443 links
    2041 destination URLs
    2297 URLs ignored
       1 warnings
       0 errors

Error: Command failed with exit code 1: npm run check-links
    at makeError (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/lib/error.js:60:11)
    at handlePromise (/home/runner/work/FluidFramework/FluidFramework/website/node_modules/.pnpm/execa@5.1.1/node_modules/execa/index.js:118:26)
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5) {
  shortMessage: 'Command failed with exit code 1: npm run check-links',
  command: 'npm run check-links',
  escapedCommand: '"npm run check-links"',
  exitCode: 1,
  signal: undefined,
  signalDescription: undefined,
  stdout: undefined,
  stderr: undefined,
  failed: true,
  timedOut: false,
  isCanceled: false,
  killed: false
}
[ELIFECYCLE] Command failed with exit code 1.

github-actions · 2026-08-27T18:12:32Z

Bundle size comparison

Base commit: 915a86a6bec93625346165686adce4f25e92cd6b
Head commit: 39cc9be88e808b3666843cc048e66918b8828748

Notable changes

No bundles changed by ≥ 500 bytes parsed.

Per-bundle deltas

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

fluidFrameworkAllAlpha.js: parsed 802853 → 802909 (+56), gzip 220698 → 220761 (+63)
azureClient.js: parsed 633562 → 633557 (-5), gzip 169791 → 169872 (+81)
odspClient.js: parsed 604831 → 604940 (+109), gzip 162591 → 162737 (+146)
aqueduct.js: parsed 537466 → 537479 (+13), gzip 144387 → 144433 (+46)
fluidFramework.js: parsed 412878 → 412911 (+33), gzip 117150 → 117198 (+48)
sharedTree.js: parsed 402257 → 402283 (+26), gzip 114578 → 114620 (+42)
containerRuntime.js: parsed 314235 → 314213 (-22), gzip 86216 → 86213 (-3)
sharedString.js: parsed 175205 → 175212 (+7), gzip 49660 → 49666 (+6)
experimentalSharedTree.js: parsed 161812 → 161812 (0), gzip 46711 → 46711 (0)
matrix.js: parsed 159584 → 159591 (+7), gzip 45903 → 45910 (+7)
loader.js: parsed 147289 → 147305 (+16), gzip 40028 → 40038 (+10)
odspDriver.js: parsed 105655 → 105713 (+58), gzip 32926 → 32991 (+65)
directory.js: parsed 65635 → 65642 (+7), gzip 18481 → 18489 (+8)
578.js: parsed 58686 → 58686 (0), gzip 17657 → 17657 (0)
odspPrefetchSnapshot.js: parsed 45884 → 45865 (-19), gzip 15335 → 15350 (+15)
map.js: parsed 45786 → 45793 (+7), gzip 14109 → 14116 (+7)
252.js: parsed 44362 → 44362 (0), gzip 13735 → 13735 (0)
summarizerDelayLoadedModule.js: parsed 31287 → 31287 (0), gzip 7929 → 7929 (0)
socketModule.js: parsed 26992 → 26962 (-30), gzip 8019 → 8052 (+33)
createNewModule.js: parsed 12464 → 12464 (0), gzip 4792 → 4805 (+13)
summaryModule.js: parsed 3888 → 3888 (0), gzip 1874 → 1874 (0)
connectionState.js: parsed 909 → 909 (0), gzip 500 → 500 (0)
sharedTreeAttributes.js: parsed 845 → 852 (+7), gzip 493 → 503 (+10)
debugAssert.js: parsed 429 → 429 (0), gzip 299 → 299 (0)
FluidFramework-HashFallback.js: parsed 419 → 419 (0), gzip 313 → 313 (0)

Joshua Smithrud (Josmithr) added 4 commits August 25, 2026 23:38

deprecate: assert

cf8f4fc

fix: Better export pattern

e414429

docs: Use ASD-STE100

0c50900

refactor(examples): Replaces usages of assert with Errors

0c97992

Joshua Smithrud (Josmithr) requested review from Jason Hartman (jason-ha) and a lite review from Copilot August 26, 2026 00:22

Joshua Smithrud (Josmithr) requested review from a team as code owners August 26, 2026 00:22

Copilot started reviewing on behalf of Joshua Smithrud (Josmithr) August 26, 2026 00:23

View session

Joshua Smithrud (Josmithr) commented Aug 26, 2026

View reviewed changes

Comment thread .changeset/tricky-rules-fly.md Outdated

docs: Update changeset title

83ff9cd

Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>

Joshua Smithrud (Josmithr) requested a review from Craig Macomber (Microsoft) (CraigMacomber) August 26, 2026 00:25

Copilot AI reviewed Aug 26, 2026

View reviewed changes

Comment thread packages/common/core-utils/src/assert.ts Outdated

This was referenced Aug 26, 2026

Remove deprecated assert API from @fluidframework/core-utils in 3.10.0 #28083

Closed

Remove deprecated assert API from @fluidframework/core-utils in 3.10.0 #28084

Open

docs: Reference scheduled removal

81ce444

Jason Hartman (jason-ha) reviewed Aug 26, 2026

View reviewed changes

Comment thread packages/common/core-utils/src/assert.ts Outdated

Matt Rakow (ChumpChief) reviewed Aug 26, 2026

View reviewed changes

Comment thread examples/utils/example-utils/src/migrationTool/sameContainerMigrationTool.ts Outdated

Comment thread examples/utils/migration-tools/src/migrationTool/migrationTool.ts Outdated

Joshua Smithrud (Josmithr) added 3 commits August 26, 2026 17:43

Merge branch 'main' into core-utils/deprecate-assert

910b4d3

refactor(core-utils): Invert assert deprecation pattern

caa6ce6

refactor: Restore use of assert in example utilities packages

152a2d0

Joshua Smithrud (Josmithr) added 2 commits August 26, 2026 18:58

docs: Update API report

e9614e0

style: Formatting

309874e

Jason Hartman (jason-ha) approved these changes Aug 26, 2026

View reviewed changes

Joshua Smithrud (Josmithr) added 4 commits August 26, 2026 22:24

docs: Remove unneeded code sample

d5db2e3

docs: Update DEV.md

30d5aa0

docs: Add issue number to TODOs

e1581e9

Merge branch 'main' into core-utils/deprecate-assert

00046a5

Joshua Smithrud (Josmithr) enabled auto-merge (squash) August 26, 2026 22:52

Jason Hartman (jason-ha) approved these changes Aug 26, 2026

View reviewed changes

Alex Villarreal (alexvy86) reviewed Aug 27, 2026

View reviewed changes

Joshua Smithrud (Josmithr) commented Aug 27, 2026

View reviewed changes

Comment thread examples/utils/example-utils/eslint.config.mts Outdated

Joshua Smithrud (Josmithr) added 2 commits August 27, 2026 10:17

docs: Clarify comment

0ef90ab

Merge branch 'main' into core-utils/deprecate-assert

39cc9be

Joshua Smithrud (Josmithr) requested a review from Alex Villarreal (alexvy86) August 27, 2026 17:19

Alex Villarreal (alexvy86) approved these changes Aug 27, 2026

View reviewed changes

Matt Rakow (ChumpChief) approved these changes Aug 27, 2026

View reviewed changes

Joshua Smithrud (Josmithr) merged commit 9163ef3 into microsoft:main Aug 27, 2026
39 checks passed

github-actions Bot mentioned this pull request Aug 27, 2026

Upcoming Release: FluidFramework v3.10.0 #22101

Open

Joshua Smithrud (Josmithr) deleted the core-utils/deprecate-assert branch August 27, 2026 20:33

Mark Fields (markfields) mentioned this pull request Sep 2, 2026

Dual-write external error telemetry property #28133

Closed

		// This package contains candidate shipping tools, not only example code, so it can use Fluid's internal assertion utility.
		"@fluidframework/core-utils/internal",

Conversation

Joshua Smithrud (Josmithr) commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Jason Hartman (jason-ha) Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jason Hartman (jason-ha) Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Alex Villarreal (alexvy86) Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Joshua Smithrud (Josmithr) Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Alex Villarreal (alexvy86) Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 27, 2026

linkcheck output

Uh oh!

github-actions Bot commented Aug 27, 2026

Bundle size comparison

Notable changes

@fluid-example/bundle-size-tests

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Joshua Smithrud (Josmithr) commented Aug 26, 2026 •

edited

Loading

github-actions Bot commented Aug 26, 2026 •

edited

Loading

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