refactor(presence): Use branded JsonDeserialized type internally

packages/framework/presence/api-report/presence.alpha.api.md

@@ -109,12 +109,12 @@ export namespace InternalTypes {
     // @system (undocumented)
     export interface ValueOptionalState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value?: JsonDeserialized<TValue>;
+        value?: InternalUtilityTypes.JsonDeserializedHandle<TValue>;
     }
     // @system (undocumented)
     export interface ValueRequiredState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value: JsonDeserialized<TValue>;
+        value: InternalUtilityTypes.JsonDeserializedHandle<TValue>;
     }
     // @system (undocumented)
     export interface ValueStateMetadata {
@@ -129,8 +129,18 @@ export namespace InternalTypes {
 export namespace InternalUtilityTypes {
     // @system
     export type IsNotificationListener<Event> = Event extends (...args: infer P) => void ? InternalUtilityTypes_2.IfSameType<P, JsonSerializable<P> & JsonDeserialized<P>, true, false> : false;
+    // @system (undocumented)
+    export class JsonDeserializedBrand<T> {
+    }
+    // @system (undocumented)
+    export type JsonDeserializedHandle<T> = T & JsonDeserializedBrand<T>;
     // @system
     export type JsonDeserializedParameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? JsonDeserialized<P> : never;
+    // @system (undocumented)
+    export class JsonSerializableBrand<T> {
+    }
+    // @system (undocumented)
+    export type JsonSerializableHandle<T> = T & JsonSerializableBrand<T>;
     // @system
     export type JsonSerializableParameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? JsonSerializable<P> : never;
     // @system

packages/framework/presence/src/exposedInternalTypes.ts

@@ -8,6 +8,8 @@ import type {
 	JsonSerializable,
 } from "@fluidframework/core-interfaces/internal/exposedUtilityTypes";
 
+import type { InternalUtilityTypes } from "./exposedUtilityTypes.js";
+
 /**
  * Collection of value types that are not intended to be used/imported
  * directly outside of this package.
@@ -29,14 +31,14 @@ export namespace InternalTypes {
 	 * @system
 	 */
 	export interface ValueOptionalState<TValue> extends ValueStateMetadata {
-		value?: JsonDeserialized<TValue>;
+		value?: InternalUtilityTypes.JsonDeserializedHandle<TValue>;
 	}
 
 	/**
 	 * @system
 	 */
 	export interface ValueRequiredState<TValue> extends ValueStateMetadata {
-		value: JsonDeserialized<TValue>;
+		value: InternalUtilityTypes.JsonDeserializedHandle<TValue>;
 	}
 
 	/**

packages/framework/presence/src/exposedUtilityTypes.ts

@@ -76,4 +76,52 @@ export namespace InternalUtilityTypes {
 	) => any
 		? JsonSerializable<P>
 		: never;
+
+	/**
+	 * @system
+	 */
+	export declare class JsonDeserializedBrand<T> {
+		private readonly JsonDeserialized: JsonDeserialized<T>;
+	}
+
+	/**
+	 * @system
+	 */
+	// export type JsonDeserializedHandle<T> = Tagged<JsonDeserialized<T>, "JsonDeserialized">;
+	export type JsonDeserializedHandle<T> = T & JsonDeserializedBrand<T>;
+
+	/**
+	 * @system
+	 */
+	export declare class JsonSerializableBrand<T> {
+		private readonly JsonSerializable: JsonSerializable<T>;
+	}
+
+	/**
+	 * @system
+	 */
+	// export type JsonDeserializedHandle<T> = Tagged<JsonDeserialized<T>, "JsonDeserialized">;
+	export type JsonSerializableHandle<T> = T & JsonSerializableBrand<T>;
+}
+
+/**
+ * Cast a JsonDeserialized value to its branded version.
+ *
+ * @system
+ */
+export function toJsonDeserializedHandle<T>(
+	value: JsonDeserialized<T>,
+): InternalUtilityTypes.JsonDeserializedHandle<T> {
+	return value as InternalUtilityTypes.JsonDeserializedHandle<T>;
+}
+
+/**
+ * Cast a branded JsonDeserialized value back to its unbranded version.
+ *
+ * @system
+ */
+export function fromJsonDeserializedHandle<T>(
+	value: InternalUtilityTypes.JsonDeserializedHandle<T>,
+): JsonDeserialized<T> {
+	return value as JsonDeserialized<T>;
 }

packages/framework/presence/src/latestMapValueManager.ts

@@ -15,6 +15,11 @@ import type {
 import type { BroadcastControls, BroadcastControlSettings } from "./broadcastControls.js";
 import { OptionalBroadcastControl } from "./broadcastControls.js";
 import type { InternalTypes } from "./exposedInternalTypes.js";
+import {
+	fromJsonDeserializedHandle,
+	toJsonDeserializedHandle,
+	// type InternalUtilityTypes,
+} from "./exposedUtilityTypes.js";
 import type { PostUpdateAction, ValueManager } from "./internalTypes.js";
 import { asDeeplyReadonly, objectEntries, objectKeys } from "./internalUtils.js";
 import type { LatestClientData, LatestData, LatestMetadata } from "./latestValueTypes.js";
@@ -266,22 +271,24 @@ class ValueMapImpl<T, K extends string | number> implements StateMap<K, T> {
 	): void {
 		for (const [key, item] of objectEntries(this.value.items)) {
 			if (item.value !== undefined) {
-				callbackfn(asDeeplyReadonly(item.value), key, this);
+				const unbrandedValue = fromJsonDeserializedHandle(item.value);
+				callbackfn(asDeeplyReadonly(unbrandedValue), key, this);
 			}
 		}
 	}
 	public get(key: K): DeepReadonly<JsonDeserialized<T>> | undefined {
-		return asDeeplyReadonly(this.value.items[key]?.value);
+		const data = this.value.items[key]?.value;
+		return data === undefined ? undefined : asDeeplyReadonly(fromJsonDeserializedHandle(data));
 	}
 	public has(key: K): boolean {
 		return this.value.items[key]?.value !== undefined;
 	}
 	public set(key: K, value: JsonSerializable<T> & JsonDeserialized<T>): this {
 		if (!(key in this.value.items)) {
 			this.countDefined += 1;
-			this.value.items[key] = { rev: 0, timestamp: 0, value };
+			this.value.items[key] = { rev: 0, timestamp: 0, value: toJsonDeserializedHandle(value) };
 		}
-		this.updateItem(key, value);
+		this.updateItem(key, toJsonDeserializedHandle(value));
 		this.emitter.emit("localItemUpdated", { key, value: asDeeplyReadonly(value) });
 		return this;
 	}
@@ -413,7 +420,7 @@ class LatestMapRawValueManagerImpl<
 			const value = item.value;
 			if (value !== undefined) {
 				items.set(key, {
-					value: asDeeplyReadonly(value),
+					value: asDeeplyReadonly(fromJsonDeserializedHandle(value)),
 					metadata: { revision: item.rev, timestamp: item.timestamp },
 				});
 			}
@@ -464,13 +471,13 @@ class LatestMapRawValueManagerImpl<
 			currentState.items[key] = item;
 			const metadata = { revision: item.rev, timestamp: item.timestamp };
 			if (item.value !== undefined) {
-				const itemValue = asDeeplyReadonly(item.value);
+				const itemValue = asDeeplyReadonly(fromJsonDeserializedHandle(item.value));
 				const updatedItem = {
 					attendee,
 					key,
 					value: itemValue,
 					metadata,
-				};
+				} satisfies LatestMapItemUpdatedClientData<T, Keys>;
 				postUpdateActions.push(() => this.events.emit("remoteItemUpdated", updatedItem));
 				allUpdates.items.set(key, { value: itemValue, metadata });
 			} else if (hadPriorValue !== undefined) {
@@ -539,7 +546,7 @@ export function latestMap<
 			value.items[key] = {
 				rev: 0,
 				timestamp,
-				value: initialValues[key],
+				value: toJsonDeserializedHandle(initialValues[key]),
 			};
 		}
 	}

packages/framework/presence/src/latestValueManager.ts

@@ -15,6 +15,11 @@ import { shallowCloneObject } from "@fluidframework/core-utils/internal";
 import type { BroadcastControls, BroadcastControlSettings } from "./broadcastControls.js";
 import { OptionalBroadcastControl } from "./broadcastControls.js";
 import type { InternalTypes } from "./exposedInternalTypes.js";
+import type { InternalUtilityTypes } from "./exposedUtilityTypes.js";
+import {
+	fromJsonDeserializedHandle,
+	toJsonDeserializedHandle,
+} from "./exposedUtilityTypes.js";
 import type { PostUpdateAction, ValueManager } from "./internalTypes.js";
 import { asDeeplyReadonly, objectEntries } from "./internalUtils.js";
 import type { LatestClientData, LatestData } from "./latestValueTypes.js";
@@ -112,13 +117,13 @@ class LatestValueManagerImpl<T, Key extends string>
 	}
 
 	public get local(): DeepReadonly<JsonDeserialized<T>> {
-		return asDeeplyReadonly(this.value.value);
+		return asDeeplyReadonly(fromJsonDeserializedHandle(this.value.value));
 	}
 
 	public set local(value: JsonSerializable<T> & JsonDeserialized<T>) {
 		this.value.rev += 1;
 		this.value.timestamp = Date.now();
-		this.value.value = value;
+		this.value.value = toJsonDeserializedHandle(value);
 		this.datastore.localUpdate(this.key, this.value, {
 			allowableUpdateLatencyMs: this.controls.allowableUpdateLatencyMs,
 		});
@@ -132,7 +137,7 @@ class LatestValueManagerImpl<T, Key extends string>
 			if (attendeeId !== allKnownStates.self) {
 				yield {
 					attendee: this.datastore.lookupClient(attendeeId),
-					value: asDeeplyReadonly(value.value),
+					value: asDeeplyReadonly(fromJsonDeserializedHandle(value.value)),
 					metadata: { revision: value.rev, timestamp: value.timestamp },
 				};
 			}
@@ -153,7 +158,7 @@ class LatestValueManagerImpl<T, Key extends string>
 			throw new Error("No entry for clientId");
 		}
 		return {
-			value: asDeeplyReadonly(clientState.value),
+			value: asDeeplyReadonly(fromJsonDeserializedHandle(clientState.value)),
 			metadata: { revision: clientState.rev, timestamp: Date.now() },
 		};
 	}
@@ -174,7 +179,7 @@ class LatestValueManagerImpl<T, Key extends string>
 			() =>
 				this.events.emit("remoteUpdated", {
 					attendee,
-					value: asDeeplyReadonly(value.value),
+					value: asDeeplyReadonly(fromJsonDeserializedHandle(value.value)),
 					metadata: { revision: value.rev, timestamp: value.timestamp },
 				}),
 		];
@@ -211,10 +216,17 @@ export function latest<T extends object | null, Key extends string = string>(
 
 	// Latest takes ownership of the initial local value but makes a shallow
 	// copy for basic protection.
+	const internalValue =
+		local === null
+			? (local as InternalUtilityTypes.JsonDeserializedHandle<T>)
+			: // FIXME: Why isn't this directly castable?
+				(shallowCloneObject(
+					local,
+				) as unknown as InternalUtilityTypes.JsonDeserializedHandle<T>);
 	const value: InternalTypes.ValueRequiredState<T> = {
 		rev: 0,
 		timestamp: Date.now(),
-		value: local === null ? local : shallowCloneObject(local),
+		value: internalValue,
 	};
 	const factory = (
 		key: Key,

packages/framework/presence/src/notificationsManager.ts

@@ -177,7 +177,11 @@ class NotificationsManagerImpl<
 				{
 					rev: 0,
 					timestamp: 0,
-					value: { name, args: [...(args as JsonTypeWith<never>[])] },
+					value: {
+						name,
+						args: [...(args as JsonTypeWith<never>[])],
+						// FIXME: Why doesn't as cast work?
+					} as unknown as InternalUtilityTypes.JsonDeserializedHandle<InternalTypes.NotificationType>,
 					ignoreUnmonitored: true,
 				},
 				// This is a notification, so we want to send it immediately.
@@ -190,7 +194,11 @@ class NotificationsManagerImpl<
 				{
 					rev: 0,
 					timestamp: 0,
-					value: { name, args: [...(args as JsonTypeWith<never>[])] },
+					value: {
+						name,
+						args: [...(args as JsonTypeWith<never>[])],
+						// FIXME: Why doesn't as cast work?
+					} as unknown as InternalUtilityTypes.JsonDeserializedHandle<InternalTypes.NotificationType>,
 					ignoreUnmonitored: true,
 				},
 				// This is a notification, so we want to send it immediately.

packages/framework/presence/src/systemWorkspace.ts

@@ -9,6 +9,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import type { ClientConnectionId } from "./baseTypes.js";
 import type { InternalTypes } from "./exposedInternalTypes.js";
+import { toJsonDeserializedHandle } from "./exposedUtilityTypes.js";
 import type { PostUpdateAction } from "./internalTypes.js";
 import type { Attendee, AttendeesEvents, AttendeeId, Presence } from "./presence.js";
 import { AttendeeStatus } from "./presence.js";
@@ -169,7 +170,7 @@ class SystemWorkspaceImpl implements PresenceStatesInternal, SystemWorkspace {
 		this.datastore.clientToSessionId[clientConnectionId] = {
 			rev: this.selfAttendee.order++,
 			timestamp: Date.now(),
-			value: this.selfAttendee.attendeeId,
+			value: toJsonDeserializedHandle(this.selfAttendee.attendeeId),
 		};
 
 		// Mark 'Connected' remote attendees connections as stale