@fluidframework/core-interfaces 2.41.0-338401 → 2.42.0

package/src/internal.ts

@@ -10,6 +10,8 @@ export * from "./index.js";
 //  index.js is listed as the runtime file. This is done so that all imports are
 //  using the same outer runtime file. (Could be changed if needed.)
 
+export type { JsonTypeToOpaqueJson, OpaqueJsonToJsonType } from "./jsonUtils.js";
+
 // Export set of utility types re-tagged as internal for FF client convenience.
 // These types are not intended for direct use by customers and api-extractor will
 // flag misuse. If an externally visible version of these types is needed, import
@@ -28,6 +30,10 @@ import type {
 	JsonTypeWith as ExposedJsonTypeWith,
 	ReadonlyNonNullJsonObjectWith as ExposedReadonlyNonNullJsonObjectWith,
 } from "./jsonType.js";
+import type {
+	OpaqueJsonDeserialized as ExposedOpaqueJsonDeserialized,
+	OpaqueJsonSerializable as ExposedOpaqueJsonSerializable,
+} from "./opaqueJson.js";
 
 // Note: There are no docs for these re-exports. `@inheritdoc` cannot be used as:
 //   1. api-extractor does not support renames.
@@ -71,12 +77,32 @@ export type JsonTypeWith<T> = ExposedJsonTypeWith<T>;
  */
 export type ReadonlyNonNullJsonObjectWith<T> = ExposedReadonlyNonNullJsonObjectWith<T>;
 
+/**
+ * @internal
+ */
+export type OpaqueJsonDeserialized<
+	T,
+	Option_AllowExactly extends unknown[] = [],
+	Option_AllowExtensionOf = never,
+> = ExposedOpaqueJsonDeserialized<T, Option_AllowExactly, Option_AllowExtensionOf>;
+
+/**
+ * @internal
+ */
+export type OpaqueJsonSerializable<
+	T,
+	Option_AllowExactly extends unknown[] = [],
+	Option_AllowExtensionOf = never,
+> = ExposedOpaqueJsonSerializable<T, Option_AllowExactly, Option_AllowExtensionOf>;
+
 /**
  * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace InternalUtilityTypes {
 	/* eslint-disable jsdoc/require-jsdoc */
+	export type FlattenIntersection<T extends ExposedInternalUtilityTypes.AnyRecord> =
+		ExposedInternalUtilityTypes.FlattenIntersection<T>;
 	export type IfSameType<
 		X,
 		Y,

package/src/jsonSerializable.ts

@@ -89,8 +89,8 @@ export interface JsonSerializableOptions {
  * Also, `JsonSerializable<T>` does not prevent the construction of circular references.
  *
  * Specifying `JsonSerializable<unknown>` or `JsonSerializable<any>` yields a type
- * alias for {@link JsonTypeWith}`<never>` and should not be used if precise type
- * safety is desired.
+ * alias for {@link JsonTypeWith}`<never>` | {@link OpaqueJsonSerializable}`<unknown>`
+ * and should not be used if precise type safety is desired.
  *
  * Class instances are indistinguishable from general objects by type checking
  * unless they have non-public members.

package/src/jsonUtils.ts

@@ -0,0 +1,90 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { JsonDeserialized } from "./jsonDeserialized.js";
+import type { JsonSerializable, JsonSerializableOptions } from "./jsonSerializable.js";
+import type { OpaqueJsonDeserialized, OpaqueJsonSerializable } from "./opaqueJson.js";
+
+/**
+ * Helper to return an Opaque Json type version of Json type
+ *
+ * @remarks
+ * To use this helper, create a helper function that filters type `T` through at
+ * least {@link JsonSerializable} and optionally {@link JsonDeserialized}. Then
+ * cast value through `unknown as JsonTypeToOpaqueJson<T, Options>`, where
+ * `Options` reflects the serialization capabilities of that area.
+ *
+ * @example
+ * ```ts
+ * function castToOpaqueJson<T>(value: JsonSerializable<T>): JsonTypeToOpaqueJson<T> {
+ *     return value as unknown as JsonTypeToOpaqueJson<T>;
+ * }
+ * ```
+ *
+ * @internal
+ */
+export type JsonTypeToOpaqueJson<
+	T,
+	Options extends JsonSerializableOptions = {
+		AllowExactly: [];
+		AllowExtensionOf: never;
+	},
+> = T extends JsonSerializable<T, Options> & JsonDeserialized<T, Options>
+	? OpaqueJsonSerializable<
+			T,
+			Options extends { AllowExactly: unknown[] } ? Options["AllowExactly"] : [],
+			Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never
+		> &
+			OpaqueJsonDeserialized<
+				T,
+				Options extends { AllowExactly: unknown[] } ? Options["AllowExactly"] : [],
+				Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never
+			>
+	: T extends JsonDeserialized<T, Options>
+		? OpaqueJsonDeserialized<
+				T,
+				Options extends { AllowExactly: unknown[] } ? Options["AllowExactly"] : [],
+				Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never
+			>
+		: T extends JsonSerializable<T, Options>
+			? OpaqueJsonSerializable<
+					T,
+					Options extends { AllowExactly: unknown[] } ? Options["AllowExactly"] : [],
+					Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never
+				>
+			: never;
+
+/**
+ * Helper to extract Json type from an Opaque Json type
+ *
+ * @remarks
+ * This type only works with basic serialization capabilities (options).
+ * Attempts to make `Options` generic resulted in infinite recursion
+ * in TypeScript compiler that was not understood, so this type only
+ * supports TJson (value type) variance.
+ *
+ * To use this helper, create a helper function that accepts
+ * `OpaqueJsonSerializable<unknown> | OpaqueJsonDeserialized<unknown>`.
+ *
+ * @example
+ * ```ts
+ * function exposeFromOpaqueJson<TOpaque extends OpaqueJsonSerializable<unknown> | OpaqueJsonDeserialized<unknown>>(
+ *	 opaque: TOpaque,
+ * ): OpaqueJsonToJsonType<TOpaque> {
+ *     return opaque as unknown as OpaqueJsonToJsonType<TOpaque>;
+ * }
+ * ```
+ *
+ * @internal
+ */
+export type OpaqueJsonToJsonType<
+	TOpaque extends OpaqueJsonSerializable<unknown> | OpaqueJsonDeserialized<unknown>,
+> = TOpaque extends OpaqueJsonSerializable<infer TJson> & OpaqueJsonDeserialized<infer TJson>
+	? JsonSerializable<TJson> & JsonDeserialized<TJson>
+	: TOpaque extends OpaqueJsonDeserialized<infer TJson>
+		? JsonDeserialized<TJson>
+		: TOpaque extends OpaqueJsonSerializable<infer TJson>
+			? JsonSerializable<TJson>
+			: never;

package/src/messages.ts

@@ -3,6 +3,28 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * A message that has a string `type` associated with `content`.
+ *
+ * @remarks
+ * This type is meant to be used indirectly. Most commonly as a constraint
+ * for generics of message structures.
+ *
+ * @legacy
+ * @alpha
+ */
+export interface TypedMessage {
+	/**
+	 * The type of the message.
+	 */
+	type: string;
+
+	/**
+	 * The contents of the message.
+	 */
+	content: unknown;
+}
+
 /**
  * @internal
  *
@@ -13,7 +35,7 @@
  *
  * See at `server/routerlicious/packages/lambdas/src/utils/messageGenerator.ts`.
  */
-export interface ISignalEnvelope {
+export interface ISignalEnvelope<TMessage extends TypedMessage = TypedMessage> {
 	/**
 	 * The target for the envelope, undefined for the container
 	 */
@@ -27,9 +49,5 @@ export interface ISignalEnvelope {
 	/**
 	 * The contents of the envelope
 	 */
-	contents: {
-		type: string;
-		// eslint-disable-next-line @typescript-eslint/no-explicit-any
-		content: any;
-	};
+	contents: TMessage;
 }

package/src/opaqueJson.ts

@@ -0,0 +1,87 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BrandedType } from "./brandedType.js";
+
+/**
+ * Placeholder for value that is known to be JSON because it has been
+ * deserialized (`T` filtered through {@link JsonDeserialized} as out value).
+ *
+ * @remarks
+ * Usage:
+ *
+ * - Cast to with `as unknown as OpaqueJsonDeserialized<T>` when value `T`
+ * has been filtered through {@link JsonDeserialized}.
+ *
+ * - Cast from with `as unknown as JsonDeserialized<T>` when "instance" will
+ * be read.
+ *
+ * @sealed
+ * @beta
+ */
+export declare class OpaqueJsonDeserialized<
+	T,
+	// These options are split from typical `JsonDeserializedOptions` as this type
+	// requires correct variance per the two options and AllowExactly has special
+	// variance and must be treated as invariant. In actuality, each member of the
+	// AllowExactly tuple is invariant, but tuple as a set is covariant. This is not
+	// expressible in TypeScript.
+	in out Option_AllowExactly extends unknown[] = [],
+	out Option_AllowExtensionOf = never,
+> extends BrandedType<"JsonDeserialized"> {
+	protected readonly JsonDeserialized: {
+		Type: T;
+		Options: {
+			AllowExactly: Option_AllowExactly;
+			AllowExtensionOf: Option_AllowExtensionOf;
+		};
+	};
+	// Option_AllowExactly is covariant from above. This removes covariance, leaving only invariance.
+	protected readonly Option_AllowExactly_Invariance: (
+		Option_AllowExactly: Option_AllowExactly,
+	) => void;
+	private constructor();
+}
+
+/**
+ * Placeholder for value that is known to be JSON because it will have been
+ * serialized checked (`T` filtered through {@link JsonSerializable} before "created").
+ *
+ * @remarks
+ * Usage:
+ *
+ * - Cast to with `as unknown as OpaqueJsonSerializable<T>` when value `T`
+ * has been filtered through {@link JsonSerializable}.
+ *
+ * - Cast from with `as unknown as JsonSerializable<T>` or `as unknown as T`
+ * when "instance" will be forwarded along.
+ *
+ * @sealed
+ * @beta
+ */
+export declare class OpaqueJsonSerializable<
+	T,
+	// These options are split from typical `JsonSerializableOptions` as this type
+	// requires correct variance per the two options and AllowExactly has special
+	// variance and must be treated as invariant. In actuality, each member of the
+	// AllowExactly tuple is invariant, but tuple as a set is covariant. This is not
+	// expressible in TypeScript.
+	in out Option_AllowExactly extends unknown[] = [],
+	out Option_AllowExtensionOf = never,
+	// JsonSerializableOptions.IgnoreInaccessibleMembers is ignored
+> extends BrandedType<"JsonSerializable"> {
+	protected readonly JsonSerializable: {
+		Type: T;
+		Options: {
+			AllowExactly: Option_AllowExactly;
+			AllowExtensionOf: Option_AllowExtensionOf;
+		};
+	};
+	// Option_AllowExactly is covariant from above. This removes covariance, leaving only invariance.
+	protected readonly Option_AllowExactly_Invariance: (
+		Option_AllowExactly: Option_AllowExactly,
+	) => void;
+	private constructor();
+}