@fluidframework/core-interfaces 2.41.0 → 2.42.0

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",
+  "version": "2.42.0",
   "description": "Fluid object interfaces",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -76,7 +76,7 @@
     "@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/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",

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.
@@ -557,6 +558,20 @@ export namespace InternalUtilityTypes {
 			}
 		: 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
 	 * the extracted portion in the `function` property or `unknown` if
@@ -775,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
@@ -796,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",
@@ -825,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.
@@ -933,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;
 
@@ -1015,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<
@@ -1109,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}.
 	 *
@@ -1157,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/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,6 +77,24 @@ 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
  */

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;