feat(client-core-interfaces): DeepReadonly and ShallowReadonly utility types (#24265)

Alternates to `Readonly` that handle `Map`, `Set`, `Promise`, `WeakMap`,
and `WeakSet` by providing readonly equivalents. The generic types of
those and `IFluidHandle` may also optionally be changed to readonly
types.
`DeepReadonly` will also apply readonly throughout the entire type not
just at the outer level.

Additionally, the utility types respect FF's `ErasedType` and class
branded primitives.

Also add `ReadonlyJsonTypeWith` and (internal)
`ReadonlyNonNullJsonObjectWith` as immutable versions of `JsonTypeWith`
and `NonNullJsonObjectWith` respectively. These are used to create
readonly versions of the `JsonTypeWith` and `NonNullJsonObjectWith`
types.

Author: jason-ha

Diff for: packages/common/core-interfaces/src/deepReadonly.ts

@@ -0,0 +1,76 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	DeepReadonlyRecursionLimit,
+	InternalUtilityTypes,
+	ReadonlySupportedGenerics,
+} from "./exposedInternalUtilityTypes.js";
+
+/**
+ * Default set of generic that {@link DeepReadonly} will apply deep immutability
+ * to generic types.
+ *
+ * @privateRemarks
+ * WeakRef should be added when lib is updated to ES2021 or later.
+ *
+ * @system
+ */
+export type DeepReadonlySupportedGenericsDefault =
+	| Map<unknown, unknown>
+	| Promise<unknown>
+	| Set<unknown>
+	| WeakMap<object, unknown>
+	| WeakSet<object>;
+
+/**
+ * Options for {@link DeepReadonly}.
+ *
+ * @beta
+ */
+export interface DeepReadonlyOptions {
+	/**
+	 * Union of Built-in and IFluidHandle whose generics will also be made deeply immutable.
+	 *
+	 * The default value is `Map` | `Promise` | `Set` | `WeakMap` | `WeakSet`.
+	 */
+	DeepenedGenerics?: ReadonlySupportedGenerics;
+
+	/**
+	 * Limit on processing recursive types.
+	 *
+	 * The default value is `"NoLimit"`.
+	 */
+	RecurseLimit?: DeepReadonlyRecursionLimit;
+}
+
+/**
+ * Transforms type to a fully and deeply immutable type, with limitations.
+ *
+ * @remarks
+ * This utility type is similar to a recursive `Readonly<T>`, but also
+ * applies immutability to common generic types like `Map` and `Set`.
+ *
+ * Optionally, immutability can be applied to supported generics types. See
+ * {@link DeepReadonlySupportedGenericsDefault} for generics that have
+ * immutability applied to generic type by default.
+ *
+ * @beta
+ */
+export type DeepReadonly<
+	T,
+	Options extends DeepReadonlyOptions = {
+		DeepenedGenerics: DeepReadonlySupportedGenericsDefault;
+		RecurseLimit: "NoLimit";
+	},
+> = InternalUtilityTypes.DeepReadonlyImpl<
+	T,
+	Options extends { DeepenedGenerics: unknown }
+		? Options["DeepenedGenerics"]
+		: DeepReadonlySupportedGenericsDefault,
+	Options extends { RecurseLimit: DeepReadonlyRecursionLimit }
+		? Options["RecurseLimit"]
+		: "NoLimit"
+>;