refactor(presence): Use branded JsonDeserialized type internally

packages/common/core-interfaces/src/internal.ts

@@ -41,12 +41,14 @@ import type {
 // Also not useful, at least in VS Code, as substitution is not made in place.
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 export type DeepReadonly<T> = ExposedDeepReadonly<T>;
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 export type JsonDeserialized<
 	T,
@@ -57,7 +59,8 @@ export type JsonDeserialized<
 > = ExposedJsonDeserialized<T, Options>;
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 export type JsonSerializable<
 	T,
@@ -78,7 +81,8 @@ export type JsonTypeWith<T> = ExposedJsonTypeWith<T>;
 export type ReadonlyNonNullJsonObjectWith<T> = ExposedReadonlyNonNullJsonObjectWith<T>;
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 export type OpaqueJsonDeserialized<
 	T,
@@ -87,7 +91,8 @@ export type OpaqueJsonDeserialized<
 > = ExposedOpaqueJsonDeserialized<T, Option_AllowExactly, Option_AllowExtensionOf>;
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 export type OpaqueJsonSerializable<
 	T,
@@ -96,7 +101,8 @@ export type OpaqueJsonSerializable<
 > = ExposedOpaqueJsonSerializable<T, Option_AllowExactly, Option_AllowExtensionOf>;
 
 /**
- * @internal
+ * @beta
+ * @system
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace InternalUtilityTypes {

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

@@ -86,7 +86,7 @@ export namespace InternalTypes {
     // @system (undocumented)
     export interface NotificationType {
         // (undocumented)
-        args: (JsonSerializable<unknown> & JsonDeserialized<unknown>)[];
+        args: unknown[];
         // (undocumented)
         name: string;
     }
@@ -109,15 +109,15 @@ export namespace InternalTypes {
     }
     // @system (undocumented)
     export type ValueDirectoryOrState<T> = ValueRequiredState<T> | ValueDirectory<T>;
-    // @system (undocumented)
+    // @system
     export interface ValueOptionalState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value?: JsonDeserialized<TValue>;
+        value?: OpaqueJsonDeserialized<TValue>;
     }
-    // @system (undocumented)
+    // @system
     export interface ValueRequiredState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value: JsonDeserialized<TValue>;
+        value: OpaqueJsonDeserialized<TValue>;
     }
     // @system (undocumented)
     export interface ValueStateMetadata {
@@ -131,23 +131,23 @@ export namespace InternalTypes {
 // @alpha @system
 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;
+    export type IfNotificationListener<Event, IfListener, Else> = Event extends (...args: infer P) => void ? InternalUtilityTypes_2.IfSameType<P, JsonSerializable<P>, IfListener, Else> : Else;
     // @system
-    export type JsonDeserializedParameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? JsonDeserialized<P> : never;
+    export type JsonDeserializedParameters<T extends (...args: any[]) => any> = T extends (...args: infer P) => any ? JsonDeserialized<P> : never;
     // @system
-    export type JsonSerializableParameters<T extends (...args: any) => any> = T extends (...args: infer P) => any ? JsonSerializable<P> : never;
+    export type JsonSerializableParameters<T extends (...args: any[]) => any> = T extends (...args: infer P) => any ? JsonSerializable<P> : never;
     // @system
     export type NotificationListeners<E> = {
-        [P in string & keyof E as IsNotificationListener<E[P]> extends true ? P : never]: E[P];
+        [P in keyof E as IfNotificationListener<E[P], P, never>]: E[P];
     };
 }
 
 // @beta
 export function latest<T extends object | null, Key extends string = string>(args: LatestArguments<T>): InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<T>, LatestRaw<T>>;
 
-// @beta
+// @beta @input
 export interface LatestArguments<T extends object | null> {
-    local: JsonSerializable<T> & JsonDeserialized<T> & (object | null);
+    local: JsonSerializable<T>;
     settings?: BroadcastControlSettings | undefined;
 }
 
@@ -165,10 +165,10 @@ export interface LatestData<T> {
 // @beta
 export function latestMap<T, Keys extends string | number = string | number, RegistrationKey extends string = string>(args?: LatestMapArguments<T, Keys>): InternalTypes.ManagerFactory<RegistrationKey, InternalTypes.MapValueState<T, Keys>, LatestMapRaw<T, Keys>>;
 
-// @beta
+// @beta @input
 export interface LatestMapArguments<T, Keys extends string | number = string | number> {
     local?: {
-        [K in Keys]: JsonSerializable<T> & JsonDeserialized<T>;
+        [K in Keys]: JsonSerializable<T>;
     };
     settings?: BroadcastControlSettings | undefined;
 }
@@ -210,7 +210,7 @@ export interface LatestMapRawEvents<T, K extends string | number> {
     }) => void;
     // @eventProperty
     localItemUpdated: (updatedItem: {
-        value: DeepReadonly<JsonSerializable<T> & JsonDeserialized<T>>;
+        value: DeepReadonly<JsonSerializable<T>>;
         key: K;
     }) => void;
     // @eventProperty
@@ -235,24 +235,24 @@ export interface LatestRaw<T> {
     getRemotes(): IterableIterator<LatestClientData<T>>;
     getStateAttendees(): Attendee[];
     get local(): DeepReadonly<JsonDeserialized<T>>;
-    set local(value: JsonSerializable<T> & JsonDeserialized<T>);
+    set local(value: JsonSerializable<T>);
     readonly presence: Presence;
 }
 
 // @beta @sealed
 export interface LatestRawEvents<T> {
     // @eventProperty
     localUpdated: (update: {
-        value: DeepReadonly<JsonSerializable<T> & JsonDeserialized<T>>;
+        value: DeepReadonly<JsonSerializable<T>>;
     }) => void;
     // @eventProperty
     remoteUpdated: (update: LatestClientData<T>) => void;
 }
 
 // @alpha @sealed
 export interface NotificationEmitter<E extends InternalUtilityTypes.NotificationListeners<E>> {
-    broadcast<K extends string & keyof InternalUtilityTypes.NotificationListeners<E>>(notificationName: K, ...args: Parameters<E[K]>): void;
-    unicast<K extends string & keyof InternalUtilityTypes.NotificationListeners<E>>(notificationName: K, targetAttendee: Attendee, ...args: Parameters<E[K]>): void;
+    broadcast<K extends keyof InternalUtilityTypes.NotificationListeners<E>>(notificationName: K, ...args: Parameters<E[K]>): void;
+    unicast<K extends keyof InternalUtilityTypes.NotificationListeners<E>>(notificationName: K, targetAttendee: Attendee, ...args: Parameters<E[K]>): void;
 }
 
 // @alpha @sealed
@@ -339,7 +339,7 @@ export interface StateMap<K extends string | number, V> {
     get(key: K): DeepReadonly<JsonDeserialized<V>> | undefined;
     has(key: K): boolean;
     keys(): IterableIterator<K>;
-    set(key: K, value: JsonSerializable<V> & JsonDeserialized<V>): this;
+    set(key: K, value: JsonSerializable<V>): this;
     readonly size: number;
 }
 

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

@@ -73,7 +73,7 @@ export namespace InternalTypes {
     // @system (undocumented)
     export interface NotificationType {
         // (undocumented)
-        args: (JsonSerializable<unknown> & JsonDeserialized<unknown>)[];
+        args: unknown[];
         // (undocumented)
         name: string;
     }
@@ -96,15 +96,15 @@ export namespace InternalTypes {
     }
     // @system (undocumented)
     export type ValueDirectoryOrState<T> = ValueRequiredState<T> | ValueDirectory<T>;
-    // @system (undocumented)
+    // @system
     export interface ValueOptionalState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value?: JsonDeserialized<TValue>;
+        value?: OpaqueJsonDeserialized<TValue>;
     }
-    // @system (undocumented)
+    // @system
     export interface ValueRequiredState<TValue> extends ValueStateMetadata {
         // (undocumented)
-        value: JsonDeserialized<TValue>;
+        value: OpaqueJsonDeserialized<TValue>;
     }
     // @system (undocumented)
     export interface ValueStateMetadata {
@@ -118,9 +118,9 @@ export namespace InternalTypes {
 // @beta
 export function latest<T extends object | null, Key extends string = string>(args: LatestArguments<T>): InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<T>, LatestRaw<T>>;
 
-// @beta
+// @beta @input
 export interface LatestArguments<T extends object | null> {
-    local: JsonSerializable<T> & JsonDeserialized<T> & (object | null);
+    local: JsonSerializable<T>;
     settings?: BroadcastControlSettings | undefined;
 }
 
@@ -138,10 +138,10 @@ export interface LatestData<T> {
 // @beta
 export function latestMap<T, Keys extends string | number = string | number, RegistrationKey extends string = string>(args?: LatestMapArguments<T, Keys>): InternalTypes.ManagerFactory<RegistrationKey, InternalTypes.MapValueState<T, Keys>, LatestMapRaw<T, Keys>>;
 
-// @beta
+// @beta @input
 export interface LatestMapArguments<T, Keys extends string | number = string | number> {
     local?: {
-        [K in Keys]: JsonSerializable<T> & JsonDeserialized<T>;
+        [K in Keys]: JsonSerializable<T>;
     };
     settings?: BroadcastControlSettings | undefined;
 }
@@ -183,7 +183,7 @@ export interface LatestMapRawEvents<T, K extends string | number> {
     }) => void;
     // @eventProperty
     localItemUpdated: (updatedItem: {
-        value: DeepReadonly<JsonSerializable<T> & JsonDeserialized<T>>;
+        value: DeepReadonly<JsonSerializable<T>>;
         key: K;
     }) => void;
     // @eventProperty
@@ -208,15 +208,15 @@ export interface LatestRaw<T> {
     getRemotes(): IterableIterator<LatestClientData<T>>;
     getStateAttendees(): Attendee[];
     get local(): DeepReadonly<JsonDeserialized<T>>;
-    set local(value: JsonSerializable<T> & JsonDeserialized<T>);
+    set local(value: JsonSerializable<T>);
     readonly presence: Presence;
 }
 
 // @beta @sealed
 export interface LatestRawEvents<T> {
     // @eventProperty
     localUpdated: (update: {
-        value: DeepReadonly<JsonSerializable<T> & JsonDeserialized<T>>;
+        value: DeepReadonly<JsonSerializable<T>>;
     }) => void;
     // @eventProperty
     remoteUpdated: (update: LatestClientData<T>) => void;
@@ -257,7 +257,7 @@ export interface StateMap<K extends string | number, V> {
     get(key: K): DeepReadonly<JsonDeserialized<V>> | undefined;
     has(key: K): boolean;
     keys(): IterableIterator<K>;
-    set(key: K, value: JsonSerializable<V> & JsonDeserialized<V>): this;
+    set(key: K, value: JsonSerializable<V>): this;
     readonly size: number;
 }
 

packages/framework/presence/src/exposedInternalTypes.ts

@@ -3,10 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type {
-	JsonDeserialized,
-	JsonSerializable,
-} from "@fluidframework/core-interfaces/internal/exposedUtilityTypes";
+import type { OpaqueJsonDeserialized } from "@fluidframework/core-interfaces/internal";
 
 /**
  * Collection of value types that are not intended to be used/imported
@@ -26,17 +23,35 @@ export namespace InternalTypes {
 	}
 
 	/**
+	 * `ValueRequiredState` is used to represent a state that may have a value.
+	 * And it includes standard metadata.
+	 *
+	 * @remarks
+	 * See {@link InternalTypes.ValueRequiredState}.
+	 *
 	 * @system
 	 */
 	export interface ValueOptionalState<TValue> extends ValueStateMetadata {
-		value?: JsonDeserialized<TValue>;
+		value?: OpaqueJsonDeserialized<TValue>;
 	}
 
 	/**
+	 * `ValueRequiredState` is used to represent a state that must have a value.
+	 * And it includes standard metadata.
+	 *
+	 * @remarks
+	 * The value is wrapped in `OpaqueJsonDeserialized` as uses are expected
+	 * to involve generic or unknown types that will be filtered. It is here
+	 * mostly as a convenience to the many such uses that would otherwise
+	 * need to specify some wrapper themselves.
+	 *
+	 * For known cases, construct a custom interface that extends
+	 * {@link InternalTypes.ValueStateMetadata}.
+	 *
 	 * @system
 	 */
 	export interface ValueRequiredState<TValue> extends ValueStateMetadata {
-		value: JsonDeserialized<TValue>;
+		value: OpaqueJsonDeserialized<TValue>;
 	}
 
 	/**
@@ -121,6 +136,6 @@ export namespace InternalTypes {
 	 */
 	export interface NotificationType {
 		name: string;
-		args: (JsonSerializable<unknown> & JsonDeserialized<unknown>)[];
+		args: unknown[];
 	}
 }

packages/framework/presence/src/exposedUtilityTypes.ts

@@ -7,7 +7,7 @@ import type {
 	InternalUtilityTypes as CoreInternalUtilityTypes,
 	JsonDeserialized,
 	JsonSerializable,
-} from "@fluidframework/core-interfaces/internal/exposedUtilityTypes";
+} from "@fluidframework/core-interfaces/internal";
 
 /**
  * Collection of utility types that are not intended to be used/imported
@@ -19,18 +19,16 @@ import type {
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace InternalUtilityTypes {
 	/**
-	 * `true` iff the given type is an acceptable shape for a notification.
+	 * `IfListener` iff the given type is an acceptable shape for a notification.
+	 * `Else` otherwise.
 	 *
 	 * @system
 	 */
-	export type IsNotificationListener<Event> = Event extends (...args: infer P) => void
-		? CoreInternalUtilityTypes.IfSameType<
-				P,
-				JsonSerializable<P> & JsonDeserialized<P>,
-				true,
-				false
-			>
-		: false;
+	export type IfNotificationListener<Event, IfListener, Else> = Event extends (
+		...args: infer P
+	) => void
+		? CoreInternalUtilityTypes.IfSameType<P, JsonSerializable<P>, IfListener, Else>
+		: Else;
 
 	/**
 	 * Used to specify the kinds of notifications emitted by a {@link NotificationListenable}.
@@ -52,15 +50,15 @@ export namespace InternalUtilityTypes {
 	 * @system
 	 */
 	export type NotificationListeners<E> = {
-		[P in string & keyof E as IsNotificationListener<E[P]> extends true ? P : never]: E[P];
+		[P in keyof E as IfNotificationListener<E[P], P, never>]: E[P];
 	};
 
 	/**
 	 * {@link @fluidframework/core-interfaces#JsonDeserialized} version of the parameters of a function.
 	 *
 	 * @system
 	 */
-	export type JsonDeserializedParameters<T extends (...args: any) => any> = T extends (
+	export type JsonDeserializedParameters<T extends (...args: any[]) => any> = T extends (
 		...args: infer P
 	) => any
 		? JsonDeserialized<P>
@@ -71,7 +69,7 @@ export namespace InternalUtilityTypes {
 	 *
 	 * @system
 	 */
-	export type JsonSerializableParameters<T extends (...args: any) => any> = T extends (
+	export type JsonSerializableParameters<T extends (...args: any[]) => any> = T extends (
 		...args: infer P
 	) => any
 		? JsonSerializable<P>