@fluidframework/core-interfaces 2.41.0-338401 → 2.42.0

package/lib/jsonUtils.js.map

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

package/lib/legacy.d.ts

@@ -57,5 +57,6 @@ export {
 	IProvideFluidHandle, 
 	IProvideFluidHandleContext, 
 	IThrottlingWarning, 
-	PayloadState
+	PayloadState, 
+	TypedMessage
 } from "./index.js";

package/lib/messages.d.ts

@@ -2,6 +2,26 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * 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
  *
@@ -12,7 +32,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
      */
@@ -24,9 +44,6 @@ export interface ISignalEnvelope {
     /**
      * The contents of the envelope
      */
-    contents: {
-        type: string;
-        content: any;
-    };
+    contents: TMessage;
 }
 //# sourceMappingURL=messages.d.ts.map

package/lib/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,mCAAmC,CAAC,EAAE,MAAM,CAAC;IAE7C;;OAEG;IACH,QAAQ,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QAEb,OAAO,EAAE,GAAG,CAAC;KACb,CAAC;CACF"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,YAAY,GAAG,YAAY;IAC5E;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,mCAAmC,CAAC,EAAE,MAAM,CAAC;IAE7C;;OAEG;IACH,QAAQ,EAAE,QAAQ,CAAC;CACnB"}

package/lib/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * @internal\n *\n * @privateRemarks\n * `IRuntimeSignalEnvelope` is an interface that mirrors `ISignalEnvelope` for signals that come from an external\n * caller (not sent by a client—so no `clientBroadcastSignalSequenceNumber`) and are always addressed\n * to the Container (so no `address`).\n *\n * See at `server/routerlicious/packages/lambdas/src/utils/messageGenerator.ts`.\n */\nexport interface ISignalEnvelope {\n\t/**\n\t * The target for the envelope, undefined for the container\n\t */\n\taddress?: string;\n\n\t/**\n\t * Signal tracking identifier for self submitted broadcast signals.\n\t */\n\tclientBroadcastSignalSequenceNumber?: number;\n\n\t/**\n\t * The contents of the envelope\n\t */\n\tcontents: {\n\t\ttype: string;\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tcontent: any;\n\t};\n}\n"]}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A message that has a string `type` associated with `content`.\n *\n * @remarks\n * This type is meant to be used indirectly. Most commonly as a constraint\n * for generics of message structures.\n *\n * @legacy\n * @alpha\n */\nexport interface TypedMessage {\n\t/**\n\t * The type of the message.\n\t */\n\ttype: string;\n\n\t/**\n\t * The contents of the message.\n\t */\n\tcontent: unknown;\n}\n\n/**\n * @internal\n *\n * @privateRemarks\n * `IRuntimeSignalEnvelope` is an interface that mirrors `ISignalEnvelope` for signals that come from an external\n * caller (not sent by a client—so no `clientBroadcastSignalSequenceNumber`) and are always addressed\n * to the Container (so no `address`).\n *\n * See at `server/routerlicious/packages/lambdas/src/utils/messageGenerator.ts`.\n */\nexport interface ISignalEnvelope<TMessage extends TypedMessage = TypedMessage> {\n\t/**\n\t * The target for the envelope, undefined for the container\n\t */\n\taddress?: string;\n\n\t/**\n\t * Signal tracking identifier for self submitted broadcast signals.\n\t */\n\tclientBroadcastSignalSequenceNumber?: number;\n\n\t/**\n\t * The contents of the envelope\n\t */\n\tcontents: TMessage;\n}\n"]}

package/lib/opaqueJson.d.ts

@@ -0,0 +1,60 @@
+/*!
+ * 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, 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;
+        };
+    };
+    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, in out Option_AllowExactly extends unknown[] = [], out Option_AllowExtensionOf = never> extends BrandedType<"JsonSerializable"> {
+    protected readonly JsonSerializable: {
+        Type: T;
+        Options: {
+            AllowExactly: Option_AllowExactly;
+            AllowExtensionOf: Option_AllowExtensionOf;
+        };
+    };
+    protected readonly Option_AllowExactly_Invariance: (Option_AllowExactly: Option_AllowExactly) => void;
+    private constructor();
+}
+//# sourceMappingURL=opaqueJson.d.ts.map

package/lib/opaqueJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opaqueJson.d.ts","sourceRoot":"","sources":["../src/opaqueJson.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAsB,CAC1C,CAAC,EAMD,EAAE,CAAC,GAAG,CAAC,mBAAmB,SAAS,OAAO,EAAE,GAAG,EAAE,EACjD,GAAG,CAAC,uBAAuB,GAAG,KAAK,CAClC,SAAQ,WAAW,CAAC,kBAAkB,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACpC,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE;YACR,YAAY,EAAE,mBAAmB,CAAC;YAClC,gBAAgB,EAAE,uBAAuB,CAAC;SAC1C,CAAC;KACF,CAAC;IAEF,SAAS,CAAC,QAAQ,CAAC,8BAA8B,EAAE,CAClD,mBAAmB,EAAE,mBAAmB,KACpC,IAAI,CAAC;IACV,OAAO;CACP;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAsB,CAC1C,CAAC,EAMD,EAAE,CAAC,GAAG,CAAC,mBAAmB,SAAS,OAAO,EAAE,GAAG,EAAE,EACjD,GAAG,CAAC,uBAAuB,GAAG,KAAK,CAElC,SAAQ,WAAW,CAAC,kBAAkB,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE;QACpC,IAAI,EAAE,CAAC,CAAC;QACR,OAAO,EAAE;YACR,YAAY,EAAE,mBAAmB,CAAC;YAClC,gBAAgB,EAAE,uBAAuB,CAAC;SAC1C,CAAC;KACF,CAAC;IAEF,SAAS,CAAC,QAAQ,CAAC,8BAA8B,EAAE,CAClD,mBAAmB,EAAE,mBAAmB,KACpC,IAAI,CAAC;IACV,OAAO;CACP"}

package/lib/opaqueJson.js

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { BrandedType } from "./brandedType.js";
+//# sourceMappingURL=opaqueJson.js.map

package/lib/opaqueJson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opaqueJson.js","sourceRoot":"","sources":["../src/opaqueJson.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { BrandedType } from \"./brandedType.js\";\n\n/**\n * Placeholder for value that is known to be JSON because it has been\n * deserialized (`T` filtered through {@link JsonDeserialized} as out value).\n *\n * @remarks\n * Usage:\n *\n * - Cast to with `as unknown as OpaqueJsonDeserialized<T>` when value `T`\n * has been filtered through {@link JsonDeserialized}.\n *\n * - Cast from with `as unknown as JsonDeserialized<T>` when \"instance\" will\n * be read.\n *\n * @sealed\n * @beta\n */\nexport declare class OpaqueJsonDeserialized<\n\tT,\n\t// These options are split from typical `JsonDeserializedOptions` as this type\n\t// requires correct variance per the two options and AllowExactly has special\n\t// variance and must be treated as invariant. In actuality, each member of the\n\t// AllowExactly tuple is invariant, but tuple as a set is covariant. This is not\n\t// expressible in TypeScript.\n\tin out Option_AllowExactly extends unknown[] = [],\n\tout Option_AllowExtensionOf = never,\n> extends BrandedType<\"JsonDeserialized\"> {\n\tprotected readonly JsonDeserialized: {\n\t\tType: T;\n\t\tOptions: {\n\t\t\tAllowExactly: Option_AllowExactly;\n\t\t\tAllowExtensionOf: Option_AllowExtensionOf;\n\t\t};\n\t};\n\t// Option_AllowExactly is covariant from above. This removes covariance, leaving only invariance.\n\tprotected readonly Option_AllowExactly_Invariance: (\n\t\tOption_AllowExactly: Option_AllowExactly,\n\t) => void;\n\tprivate constructor();\n}\n\n/**\n * Placeholder for value that is known to be JSON because it will have been\n * serialized checked (`T` filtered through {@link JsonSerializable} before \"created\").\n *\n * @remarks\n * Usage:\n *\n * - Cast to with `as unknown as OpaqueJsonSerializable<T>` when value `T`\n * has been filtered through {@link JsonSerializable}.\n *\n * - Cast from with `as unknown as JsonSerializable<T>` or `as unknown as T`\n * when \"instance\" will be forwarded along.\n *\n * @sealed\n * @beta\n */\nexport declare class OpaqueJsonSerializable<\n\tT,\n\t// These options are split from typical `JsonSerializableOptions` as this type\n\t// requires correct variance per the two options and AllowExactly has special\n\t// variance and must be treated as invariant. In actuality, each member of the\n\t// AllowExactly tuple is invariant, but tuple as a set is covariant. This is not\n\t// expressible in TypeScript.\n\tin out Option_AllowExactly extends unknown[] = [],\n\tout Option_AllowExtensionOf = never,\n\t// JsonSerializableOptions.IgnoreInaccessibleMembers is ignored\n> extends BrandedType<\"JsonSerializable\"> {\n\tprotected readonly JsonSerializable: {\n\t\tType: T;\n\t\tOptions: {\n\t\t\tAllowExactly: Option_AllowExactly;\n\t\t\tAllowExtensionOf: Option_AllowExtensionOf;\n\t\t};\n\t};\n\t// Option_AllowExactly is covariant from above. This removes covariance, leaving only invariance.\n\tprotected readonly Option_AllowExactly_Invariance: (\n\t\tOption_AllowExactly: Option_AllowExactly,\n\t) => void;\n\tprivate constructor();\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-interfaces",
-  "version": "2.41.0-338401",
+  "version": "2.42.0",
   "description": "Fluid object interfaces",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -76,8 +76,8 @@
     "@fluid-tools/build-cli": "^0.55.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.55.0",
-    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.40.0",
-    "@fluidframework/eslint-config-fluid": "^5.7.3",
+    "@fluidframework/core-interfaces-previous": "npm:@fluidframework/core-interfaces@2.41.0",
+    "@fluidframework/eslint-config-fluid": "^5.7.4",
     "@microsoft/api-extractor": "7.52.8",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.0",

package/src/brandedType.ts

@@ -0,0 +1,43 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Base branded type which can be used to annotate other type.
+ *
+ * @remarks
+ * To use derive another class declaration and ideally add additional private
+ * properties to further distinguish the type.
+ *
+ * Since branded types are not real value types, they will always need to be
+ * created using `as` syntax and very often `as unknown` first.
+ *
+ * This class should never exist at runtime, so it is only declared.
+ *
+ * @sealed
+ * @internal
+ */
+export declare class BrandedType<out Brand> {
+	/**
+	 * Compile time only marker to make type checking more strict.
+	 * This method will not exist at runtime and accessing it is invalid.
+	 *
+	 * @privateRemarks
+	 * `Brand` is used as the return type of a method rather than a simple
+	 * readonly property as this allows types with two brands to be
+	 * intersected without getting `never`.
+	 * The method takes in `never` to help emphasize that it's not callable.
+	 */
+	protected readonly brand: (dummy: never) => Brand;
+
+	protected constructor();
+
+	/**
+	 * Since this class is a compile time only type brand, `instanceof` will
+	 * never work with it. * This `Symbol.hasInstance` implementation ensures
+	 * that `instanceof` will error if used, and in TypeScript 5.3 and newer
+	 * will produce a compile time error if used.
+	 */
+	public static [Symbol.hasInstance](value: never): value is never;
+}

package/src/exposedInternalUtilityTypes.ts

@@ -12,6 +12,7 @@ import type {
 	SerializationErrorPerUndefinedArrayElement,
 } from "./jsonSerializationErrors.js";
 import type { JsonTypeWith, NonNullJsonObjectWith, ReadonlyJsonTypeWith } from "./jsonType.js";
+import type { OpaqueJsonDeserialized, OpaqueJsonSerializable } from "./opaqueJson.js";
 
 /**
  * Unique symbol for recursion meta-typing.
@@ -535,20 +536,41 @@ export namespace InternalUtilityTypes {
 	 */
 	export type IsExactlyObject<T extends object> = IsSameType<T, object>;
 
+	/**
+	 * Any Record type.
+	 *
+	 * @system
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any -- `any` for property types is required to avoid "Index signature for type 'string' is missing in type" in some outside `FlattenIntersection` uses.
+	export type AnyRecord = Record<keyof any, any>;
+
 	/**
 	 * Creates a simple object type from an intersection of multiple.
 	 * @privateRemarks
-	 * `T extends Record` within the implementation encourages tsc to process
+	 * `T extends AnyRecord` within the implementation encourages tsc to process
 	 * intersections within unions.
 	 *
 	 * @system
 	 */
-	export type FlattenIntersection<T extends Record<string | number | symbol, unknown>> =
-		T extends Record<string | number | symbol, unknown>
-			? {
-					[K in keyof T]: T[K];
-				}
-			: T;
+	export type FlattenIntersection<T extends AnyRecord> = T extends AnyRecord
+		? {
+				[K in keyof T]: T[K];
+			}
+		: T;
+
+	/**
+	 * Convenience constraint for any Opaque Json type.
+	 *
+	 * @remarks
+	 * Use in extends check: `T extends AnyOpaqueJsonType`
+	 *
+	 * @system
+	 */
+	export type AnyOpaqueJsonType =
+		/* eslint-disable @typescript-eslint/no-explicit-any -- must use `any` for invariant constraint override */
+		| OpaqueJsonSerializable<unknown, any, unknown>
+		| OpaqueJsonDeserialized<unknown, any, unknown>;
+	/* eslint-enable @typescript-eslint/no-explicit-any */
 
 	/**
 	 * Extracts Function portion from an intersection (&) type returning
@@ -768,15 +790,23 @@ export namespace InternalUtilityTypes {
 		AllowExtensionOf: Options extends { AllowExtensionOf: unknown }
 			? Options["AllowExtensionOf"]
 			: never;
-		// There Substitute type could be extracted to helper type, but are kept explicit here
-		// to make JsonTypeWith show explicitly in results for users, rather
-		// than either the helper type name or a partially unrolled version.
-		DegenerateSubstitute: JsonTypeWith<
-			| (Options extends { AllowExactly: unknown[] }
-					? TupleToUnion<Options["AllowExactly"]>
-					: never)
-			| (Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never)
-		>;
+		// The Substitute type could be extracted to helper type, but is kept explicit here
+		// to make JsonTypeWith and OpaqueJsonSerializable show explicitly in results for
+		// users, rather than either the helper type name or a partially unrolled version.
+		DegenerateSubstitute:
+			| JsonTypeWith<
+					| (Options extends { AllowExactly: unknown[] }
+							? TupleToUnion<Options["AllowExactly"]>
+							: never)
+					| (Options extends { AllowExtensionOf: unknown }
+							? Options["AllowExtensionOf"]
+							: never)
+			  >
+			| OpaqueJsonSerializable<
+					unknown,
+					Options extends { AllowExactly: unknown[] } ? Options["AllowExactly"] : [],
+					Options extends { AllowExtensionOf: unknown } ? Options["AllowExtensionOf"] : never
+			  >;
 	} extends infer Controls
 		? /* Controls should always satisfy FilterControlsWithSubstitution, but Typescript wants a check */
 			Controls extends FilterControlsWithSubstitution
@@ -789,8 +819,14 @@ export namespace InternalUtilityTypes {
 								T,
 								{
 									AllowExactly: Controls["AllowExactly"];
-									// Add in primitives that may be branded to ignore intersection classes
-									AllowExtensionOf: Controls["AllowExtensionOf"] | boolean | number | string;
+									AllowExtensionOf:
+										| Controls["AllowExtensionOf"]
+										// Add in primitives that may be branded to ignore intersection classes
+										| boolean
+										| number
+										| string
+										// Add in Opaque Json types
+										| AnyOpaqueJsonType;
 									DegenerateSubstitute: Controls["DegenerateSubstitute"];
 								},
 								"found non-publics",
@@ -818,6 +854,47 @@ export namespace InternalUtilityTypes {
 			: never /* FilterControlsWithSubstitution assert else; should never be reached */
 		: never /* unreachable else for infer */;
 
+	/**
+	 * Handle Opaque Json types for {@link JsonSerializable}.
+	 *
+	 * @remarks
+	 * {@link OpaqueJsonSerializable} and {@link OpaqueJsonDeserialized} instances
+	 * are limited to `Controls` given context supports.
+	 * `T` from the original Opaque type is preserved. In the case that this now
+	 * produces an improper type such as a `bigint` being let through that is no
+	 * longer supported, then the variance of `Controls` is expected to raise
+	 * the incompatibility error.
+	 *
+	 * @privateRemarks
+	 * Additional intersections beyond {@link OpaqueJsonSerializable},
+	 * {@link OpaqueJsonDeserialized}, or intersected matching opaque pair are
+	 * not correctly filtered as need is not expected.
+	 *
+	 * @system
+	 */
+	export type JsonSerializableOpaqueAllowances<
+		T extends AnyOpaqueJsonType,
+		Controls extends FilterControlsWithSubstitution,
+	> = /* eslint-disable @typescript-eslint/no-explicit-any -- must use `any` for invariant constraint override */
+	/* infer underlying data type */ T extends
+		| OpaqueJsonSerializable<infer TData, any, unknown>
+		| OpaqueJsonDeserialized<infer TData, any, unknown>
+		? T extends OpaqueJsonSerializable<TData, any, unknown> &
+				OpaqueJsonDeserialized<TData, any, unknown>
+			? OpaqueJsonSerializable<TData, Controls["AllowExactly"], Controls["AllowExtensionOf"]> &
+					OpaqueJsonDeserialized<TData, Controls["AllowExactly"], Controls["AllowExtensionOf"]>
+			: T extends OpaqueJsonSerializable<TData, any, unknown>
+				? OpaqueJsonSerializable<TData, Controls["AllowExactly"], Controls["AllowExtensionOf"]>
+				: T extends OpaqueJsonDeserialized<TData, any, unknown>
+					? OpaqueJsonDeserialized<
+							TData,
+							Controls["AllowExactly"],
+							Controls["AllowExtensionOf"]
+						>
+					: "internal error: failed to determine Opaque Json type"
+		: never;
+	/* eslint-enable @typescript-eslint/no-explicit-any */
+
 	/**
 	 * Essentially a check for a template literal that has $\{string\} or
 	 * $\{number\} in the pattern. Just `string` and/or `number` also match.
@@ -926,45 +1003,50 @@ export namespace InternalUtilityTypes {
 											>
 										: /* test for enum like types */ IfEnumLike<T> extends never
 											? /* enum or similar simple type (return as-is) => */ T
-											: /* property bag => */ FlattenIntersection<
-													{
-														/* required properties are recursed and may not have undefined values. */
-														[K in keyof T as RequiredNonSymbolKeysOf<
-															T,
-															K
-														>]-?: IfPossiblyUndefinedProperty<
-															K,
-															T[K],
-															{
-																IfPossiblyUndefined: {
-																	["error required property may not allow `undefined` value"]: never;
-																};
-																IfUnknownNonIndexed: {
-																	["error required property may not allow `unknown` value"]: never;
-																};
-																Otherwise: JsonSerializableFilter<
-																	T[K],
-																	Controls,
-																	[TNextAncestor, ...TAncestorTypes]
-																>;
-															}
-														>;
-													} & {
-														/* optional properties are recursed and, when exactOptionalPropertyTypes is
+											: /* test for Opaque Json types */ T extends AnyOpaqueJsonType
+												? /* Opaque Json type => */ JsonSerializableOpaqueAllowances<
+														T,
+														Controls
+													>
+												: /* property bag => */ FlattenIntersection<
+														{
+															/* required properties are recursed and may not have undefined values. */
+															[K in keyof T as RequiredNonSymbolKeysOf<
+																T,
+																K
+															>]-?: IfPossiblyUndefinedProperty<
+																K,
+																T[K],
+																{
+																	IfPossiblyUndefined: {
+																		["error required property may not allow `undefined` value"]: never;
+																	};
+																	IfUnknownNonIndexed: {
+																		["error required property may not allow `unknown` value"]: never;
+																	};
+																	Otherwise: JsonSerializableFilter<
+																		T[K],
+																		Controls,
+																		[TNextAncestor, ...TAncestorTypes]
+																	>;
+																}
+															>;
+														} & {
+															/* optional properties are recursed and, when exactOptionalPropertyTypes is
 														   false, are allowed to preserve undefined value type. */
-														[K in keyof T as OptionalNonSymbolKeysOf<
-															T,
-															K
-														>]?: JsonSerializableFilter<
-															T[K],
-															Controls,
-															[TNextAncestor, ...TAncestorTypes]
-														>;
-													} & {
-														/* symbol properties are rejected */
-														[K in keyof T & symbol]: never;
-													}
-												>
+															[K in keyof T as OptionalNonSymbolKeysOf<
+																T,
+																K
+															>]?: JsonSerializableFilter<
+																T[K],
+																Controls,
+																[TNextAncestor, ...TAncestorTypes]
+															>;
+														} & {
+															/* symbol properties are rejected */
+															[K in keyof T & symbol]: never;
+														}
+													>
 								: /* not an object => */ never
 							: /* function => */ never;
 
@@ -1008,7 +1090,7 @@ export namespace InternalUtilityTypes {
 		AllowExtensionOf: Options extends { AllowExtensionOf: unknown }
 			? Options["AllowExtensionOf"]
 			: never;
-		// There Substitute types could be extracted to helper type, but are kept explicit here
+		// The Substitute types could be extracted to helper type, but are kept explicit here
 		// to make JsonTypeWith/NonNullJsonObjectWith show explicitly in results for users, rather
 		// than either the helper type name or a partially unrolled version.
 		DegenerateSubstitute: JsonTypeWith<
@@ -1102,6 +1184,35 @@ export namespace InternalUtilityTypes {
 			: Controls["DegenerateSubstitute"]
 		: JsonDeserializedFilter<T, Controls, RecurseLimit, TAncestorTypes | T>;
 
+	/**
+	 * Handle Opaque Json types for {@link JsonDeserialized}.
+	 *
+	 * @remarks
+	 * {@link OpaqueJsonSerializable} instances are converted to {@link OpaqueJsonDeserialized}.
+	 * The `AllowExactly` and `AllowExtensionOf` properties are set to match the given `Controls`.
+	 * The data type is kept exactly as-is to avoid processing in generic contexts that can't
+	 * produce a meaningful result. The data type should always be filtered through
+	 * {@link JsonDeserialized} when {@link OpaqueJsonDeserialized} is cracked open. So, really
+	 * the filtering is just deferred.
+	 *
+	 * @privateRemarks
+	 * Additional intersections beyond {@link OpaqueJsonSerializable},
+	 * {@link OpaqueJsonDeserialized}, or intersected matching opaque pair are
+	 * not correctly filtered as need is not expected.
+	 *
+	 * @system
+	 */
+	export type JsonDeserializedOpaqueConversion<
+		T extends AnyOpaqueJsonType,
+		Controls extends FilterControls,
+	> = /* eslint-disable @typescript-eslint/no-explicit-any -- must use `any` for invariant constraint override */
+	T extends
+		| OpaqueJsonSerializable<infer TData, any, unknown>
+		| OpaqueJsonDeserialized<infer TData, any, unknown>
+		? OpaqueJsonDeserialized<TData, Controls["AllowExactly"], Controls["AllowExtensionOf"]>
+		: "internal error: failed to determine Opaque Json type";
+	/* eslint-enable @typescript-eslint/no-explicit-any */
+
 	/**
 	 * Core implementation of {@link JsonDeserialized}.
 	 *
@@ -1150,36 +1261,38 @@ export namespace InternalUtilityTypes {
 									? /* `object` => */ Controls["DegenerateNonNullObjectSubstitute"]
 									: /* test for enum like types */ IfEnumLike<T> extends never
 										? /* enum or similar simple type (return as-is) => */ T
-										: /* property bag => */ FlattenIntersection<
-												/* properties with symbol keys or wholly unsupported values are removed */
-												{
-													/* properties with defined values are recursed */
-													[K in keyof T as NonSymbolWithDeserializablePropertyOf<
-														T,
-														Controls["AllowExactly"],
-														Controls["AllowExtensionOf"],
-														K
-													>]: JsonDeserializedRecursion<
-														T[K],
-														Controls,
-														RecurseLimit,
-														TAncestorTypes
-													>;
-												} & {
-													/* properties that may have undefined values are optional */
-													[K in keyof T as NonSymbolWithPossiblyDeserializablePropertyOf<
-														T,
-														Controls["AllowExactly"],
-														Controls["AllowExtensionOf"],
-														K
-													>]?: JsonDeserializedRecursion<
-														T[K],
-														Controls,
-														RecurseLimit,
-														TAncestorTypes
-													>;
-												}
-											>
+										: /* test for matching Opaque Json types */ T extends AnyOpaqueJsonType
+											? /* Opaque Json type => */ JsonDeserializedOpaqueConversion<T, Controls>
+											: /* property bag => */ FlattenIntersection<
+													/* properties with symbol keys or wholly unsupported values are removed */
+													{
+														/* properties with defined values are recursed */
+														[K in keyof T as NonSymbolWithDeserializablePropertyOf<
+															T,
+															Controls["AllowExactly"],
+															Controls["AllowExtensionOf"],
+															K
+														>]: JsonDeserializedRecursion<
+															T[K],
+															Controls,
+															RecurseLimit,
+															TAncestorTypes
+														>;
+													} & {
+														/* properties that may have undefined values are optional */
+														[K in keyof T as NonSymbolWithPossiblyDeserializablePropertyOf<
+															T,
+															Controls["AllowExactly"],
+															Controls["AllowExtensionOf"],
+															K
+														>]?: JsonDeserializedRecursion<
+															T[K],
+															Controls,
+															RecurseLimit,
+															TAncestorTypes
+														>;
+													}
+												>
 						: /* not an object => */ never;
 
 	// #endregion

package/src/exposedUtilityTypes.ts

@@ -21,6 +21,7 @@ export type {
 	NonNullJsonObjectWith,
 	ReadonlyJsonTypeWith,
 } from "./jsonType.js";
+export type { OpaqueJsonDeserialized, OpaqueJsonSerializable } from "./opaqueJson.js";
 export type { ShallowReadonly } from "./shallowReadonly.js";
 
 export type {

package/src/index.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+export type { BrandedType } from "./brandedType.js";
+
 export type { IDisposable } from "./disposable.js";
 
 export type { IErrorBase, IGenericError, IUsageError, IThrottlingWarning } from "./error.js";
@@ -52,7 +54,7 @@ export type {
 export { LogLevel } from "./logger.js";
 export type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from "./provider.js";
 export type { ConfigTypes, IConfigProviderBase } from "./config.js";
-export type { ISignalEnvelope } from "./messages.js";
+export type { ISignalEnvelope, TypedMessage } from "./messages.js";
 export type { ErasedType } from "./erasedType.js";
 
 export type {