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

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

@@ -0,0 +1,68 @@
+/*!
+ * 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.
+ *
+ * @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"
+>;