refactor(presence): Create branded JsonDeserialized type #24641

tylerbutler · 2025-05-15T22:18:55Z

Updates the presence internals to use a branded internal type when passing around JsonDeserialized objects. There are two functions to brand and unbrand a JsonDeserialized object.

Externally, the API remains the same; the internal types and functions are marked @system and objects are converted between the types at the API boundaries.

packages/framework/presence/src/exposedUtilityTypes.ts

jason-ha · 2025-05-15T22:32:15Z

packages/framework/presence/src/exposedUtilityTypes.ts

+	 * @system
+	 */
+	export declare class JsonDeserializedBrand<T> {
+		private readonly JsonDeserialized: JsonDeserialized<T>;


We can probably drop the JsonDeserialized<T>. Just T is probably enough. Probably want to use the dummy accessor and iterator found in that reference PR's brand classes.

jason-ha · 2025-05-15T22:33:14Z

packages/framework/presence/src/latestMapValueManager.ts

+				const unbrandedValue = fromJsonDeserializedHandle(item.value);
+				callbackfn(asDeeplyReadonly(unbrandedValue), key, this);


Can probably combine both of these pass-through helper functions.

jason-ha · 2025-05-15T22:34:32Z

packages/framework/presence/src/latestMapValueManager.ts

+		const data = this.value.items[key]?.value;
+		return data === undefined ? undefined : asDeeplyReadonly(fromJsonDeserializedHandle(data));


Kind of silly since those are both pass through anyway - should be able to adjust the helper to handle it.

tylerbutler · 2025-05-29T17:59:22Z

packages/runtime/container-runtime-definitions/src/containerExtension.ts

+	ExtensionMessage<{
+		type: TMessage["type"];
+		content: JsonSerializable<
+			TMessage["content"],
+			{ AllowExtensionOf: OpaqueJsonDeserialized<TMessage["content"]> }
+		>;
+	}>;


Temporary workaround to be reverted.

Introduce `OpaqueJsonDeserialized`, and `OpaqueJsonSerializable` as "handles" for generic values. Opaque Json types can be used when there is no direct need to work with a complex or unknown type, but still need to respect serializability. Common use is when a value that has passed through `JsonSerializable` or `JsonDeserialized` filter utilities needs to be stored, especially in a generic context. The Opaque types are recognized by `JsonSerializable` and `JsonDeserialized` allowing those stored captures to themselves be part of flow that checks for serializability or deserialization. Test cases: JsonDeserialized positive compilation tests fully supported object types are preserved ✔ OpaqueJsonDeserialized<{number:number}> partially supported object types are modified OpaqueJsonSerialized becomes OpaqueJsonDeserialized counterpart ✔ OpaqueJsonSerializable<{number:number}> becomes OpaqueJsonDeserialized<{number:number}> ✔ OpaqueJsonSerializable<{number:number}>&OpaqueJsonDeserialized<{number:number}> becomes OpaqueJsonDeserialized<{number:number}> opaque Json types requiring extra allowed types have extras removed ✔ opaque serializable object with `bigint` ✔ opaque deserialized object with `bigint` ✔ opaque serializable and deserialized object with `bigint` ✔ opaque serializable object with number array expecting `bigint` support ✔ opaque deserialized object with number array expecting `bigint` support ✔ opaque serializable and deserialized object with number array expecting `bigint` support special cases using alternately allowed types are preserved ✔ opaque serializable object with `bigint` ✔ opaque deserialized object with `bigint` ✔ opaque serializable and deserialized object with `bigint` JsonSerializable positive compilation tests supported object types opaque Json types ✔ opaque serializable object ✔ opaque deserialized object ✔ opaque serializable and deserialized object negative compilation tests unsupported types cause compiler error opaque Json types requiring extra allowed types ✔ opaque serializable object with `bigint` ✔ opaque deserialized object with `bigint` ✔ opaque serializable and deserialized object with `bigint` ✔ opaque serializable object with number array expecting `bigint` support ✔ opaque deserialized object with number array expecting `bigint` support ✔ opaque serializable and deserialized object with number array expecting `bigint` support OpaqueJsonSerializable and OpaqueJsonDeserialized positive compilation tests ✔ OpaqueJsonSerializable is covariant (more specific is assignable to general) ✔ OpaqueJsonDeserialized is covariant (more specific is assignable to general) ✔ OpaqueJsonSerializable & OpaqueJsonDeserialized is covariant (more specific is assignable to general) in a generic context ✔ OpaqueJsonDeserialized assignability varies with JsonDeserialized Options ✔ OpaqueJsonSerializable assignability varies with JsonSerializable Options ✔ OpaqueJsonSerializable may be forwarded as JsonSerializable ✔ OpaqueJsonDeserialized may be returned to JsonDeserialized ✔ OpaqueJsonSerializable & OpaqueJsonDeserialized may be returned to JsonSerializable & JsonDeserialized ✔ OpaqueJsonSerializable & OpaqueJsonDeserialized may be forwarded as JsonSerializable ✔ OpaqueJsonSerializable & OpaqueJsonDeserialized may be returned as JsonDeserialized negative compilation tests ✔ OpaqueJsonSerializable is covariant (more general is NOT assignable to specific) ✔ OpaqueJsonDeserialized is covariant (more general is NOT assignable to specific) ✔ OpaqueJsonSerializable & OpaqueJsonDeserialized is covariant (more specific is assignable to general)

Simplify internal unknown (generic) customer data that must be Json serializable using Opaque Json types At boundaries of API ins and outs, Json filtered types are cast to/from Opaque Json types. See new helpers: - `fullySerializableToOpaqueJson` - `asDeserializedJson` - `asDeeplyReadonlyDeserializedJson` Notifications utilities are updated and removal of `string &` for `NotificationListeners` allowed clean up of `@ts-ignore-error`. `NotificationsManagerImpl`'s `emit` implementation now just types `name` to `string`.'

github-actions · 2025-06-02T23:39:50Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

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"


> [email protected] serve
> docusaurus serve --no-open

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

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  222981 links
    1707 destination URLs
    1939 URLs ignored
       0 warnings
       0 errors

tylerbutler added 3 commits May 15, 2025 14:15

typebrand the JsonDeserialized type

164b448

updates

0b1bd66

compiles

b6eca1f

github-actions bot added area: framework Framework is a tag for issues involving the developer framework. Eg Aqueduct public api change Changes to a public API base: main PRs targeted against main branch labels May 15, 2025

tylerbutler changed the title ~~typebrand the JsonDeserialized type~~ refactor(presence): Create branded JsonDeserialized type May 15, 2025

jason-ha reviewed May 15, 2025

View reviewed changes

packages/framework/presence/src/exposedUtilityTypes.ts Outdated Show resolved Hide resolved

jason-ha reviewed May 15, 2025

View reviewed changes

tylerbutler added 5 commits May 15, 2025 16:05

Remove T &

2ba11eb

feedback

d6b85e7

rename types to behopefully clearer

e716480

feedback

d727ad0

cleanup

653320a

github-actions bot added area: examples Changes that focus on our examples and removed area: examples Changes that focus on our examples labels May 28, 2025

Merge branch 'main' into presence-type-branding

1c54887

tylerbutler force-pushed the presence-type-branding branch from f6391fb to 1c54887 Compare May 28, 2025 02:08

tylerbutler added 4 commits May 28, 2025 11:02

cleanup

90063a9

fix

6d571db

Merge branch 'main' into presence-type-branding

af6b5a8

rm invalid docs changes

6cd5054

github-actions bot removed the public api change Changes to a public API label May 28, 2025

tylerbutler added 2 commits May 28, 2025 11:51

formatting

019df60

tsignore some errors

212c77f

github-actions bot added the public api change Changes to a public API label May 28, 2025

tylerbutler added 2 commits May 28, 2025 12:06

wip

0e6c144

wip

4f12474

Merge branch 'main' into presence-type-branding

c9cdf28

github-actions bot added the area: runtime Runtime related issues label May 28, 2025

tylerbutler added 2 commits May 28, 2025 16:56

wip

3d1435f

formatting

40483c0

tylerbutler commented May 29, 2025

View reviewed changes

jason-ha and others added 5 commits May 29, 2025 13:52

wip

e82eb79

Merge branch 'core/opaque-json-types' into presence-type-branding

c1d1f3f

revert container-runtime-defs changes

fb60bcf

8 errors in 3 files

34011f4

github-actions bot removed the area: runtime Runtime related issues label May 30, 2025

tylerbutler added 3 commits May 29, 2025 17:18

rename functions

4cc3372

8 errors, 3 files (still)

0a52598

rename and reorg

9043b6c

tylerbutler mentioned this pull request May 30, 2025

feat(client-core-interfaces): opaque JSON placeholder types #24733

Merged

tylerbutler and others added 7 commits June 2, 2025 12:51

Merge branch 'main' into presence-type-branding

f2aa271

workarounds

abe20ee

Merge commit 'dbf0696243' into presence-type-branding

502e103

source compiles but tests don't

bc2ba69

source compiles

1cf182c

revert

c04d35a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(presence): Create branded JsonDeserialized type #24641

refactor(presence): Create branded JsonDeserialized type #24641

tylerbutler commented May 15, 2025

Uh oh!

Uh oh!

jason-ha May 15, 2025

Uh oh!

jason-ha May 15, 2025

Uh oh!

jason-ha May 15, 2025

Uh oh!

tylerbutler May 29, 2025

Uh oh!

github-actions bot commented Jun 2, 2025

Uh oh!

Uh oh!

		const unbrandedValue = fromJsonDeserializedHandle(item.value);
		callbackfn(asDeeplyReadonly(unbrandedValue), key, this);

		const data = this.value.items[key]?.value;
		return data === undefined ? undefined : asDeeplyReadonly(fromJsonDeserializedHandle(data));

refactor(presence): Create branded JsonDeserialized type #24641

Are you sure you want to change the base?

refactor(presence): Create branded JsonDeserialized type #24641

Conversation

tylerbutler commented May 15, 2025

Uh oh!

Uh oh!

jason-ha May 15, 2025

Choose a reason for hiding this comment

Uh oh!

jason-ha May 15, 2025

Choose a reason for hiding this comment

Uh oh!

jason-ha May 15, 2025

Choose a reason for hiding this comment

Uh oh!

tylerbutler May 29, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 2, 2025

linkcheck output

Uh oh!

Uh oh!