@fluidframework/core-interfaces 2.32.0 → 2.33.0

package/src/jsonType.ts

@@ -35,3 +35,39 @@ export type JsonTypeWith<T> =
 export type NonNullJsonObjectWith<T> =
 	| { [key: string | number]: JsonTypeWith<T> }
 	| JsonTypeWith<T>[];
+
+/**
+ * Deeply immutable type that is encodable as JSON and deserializable from JSON.
+ *
+ * @typeParam TReadonlyAlternates - Additional [immutable] types that are supported.
+ *
+ * @remarks
+ * If `TReadonlyAlternates` is allowed as-is. So if it is not immutable, then result type
+ * is not wholly immutable.
+ *
+ * A `const` variable is still required to avoid top-level mutability. I.e.
+ * ```typescript
+ * let x: ReadonlyJsonTypeWith<never> = { a: 1 };
+ * ```
+ * does not prevent later `x = 5`. (Does prevent `x.a = 2`.)
+ *
+ * @beta
+ */
+export type ReadonlyJsonTypeWith<TReadonlyAlternates> =
+	// eslint-disable-next-line @rushstack/no-new-null
+	| null
+	| boolean
+	| number
+	| string
+	| TReadonlyAlternates
+	| { readonly [key: string | number]: ReadonlyJsonTypeWith<TReadonlyAlternates> }
+	| readonly ReadonlyJsonTypeWith<TReadonlyAlternates>[];
+
+/**
+ * Portion of {@link ReadonlyJsonTypeWith} that is an object (including array) and not null.
+ *
+ * @internal
+ */
+export type ReadonlyNonNullJsonObjectWith<TReadonlyAlternates> =
+	| { readonly [key: string | number]: ReadonlyJsonTypeWith<TReadonlyAlternates> }
+	| readonly ReadonlyJsonTypeWith<TReadonlyAlternates>[];

package/src/shallowReadonly.ts

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	InternalUtilityTypes,
+	ReadonlySupportedGenerics,
+} from "./exposedInternalUtilityTypes.js";
+import type { IFluidHandle } from "./handles.js";
+
+/**
+ * Default set of generic that {@link ShallowReadonly} will apply shallow immutability
+ * to generic types.
+ *
+ * @privateRemarks
+ * WeakRef should be added when lib is updated to ES2021 or later.
+ *
+ * @system
+ */
+export type ShallowReadonlySupportedGenericsDefault = Promise<unknown> | IFluidHandle;
+
+/**
+ * Options for {@link ShallowReadonly}.
+ *
+ * @beta
+ */
+export interface ShallowReadonlyOptions {
+	/**
+	 * Union of Built-in and IFluidHandle whose generics will also be made shallowly immutable.
+	 *
+	 * The default value is `IFluidHandle` | `Promise`.
+	 */
+	DeepenedGenerics?: ReadonlySupportedGenerics;
+}
+
+/**
+ * Transforms type to a shallowly immutable type.
+ *
+ * @remarks
+ * This utility type is similar to `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 ShallowReadonlySupportedGenericsDefault} for generics that have
+ * immutability applied to generic type by default.
+ *
+ * @beta
+ */
+export type ShallowReadonly<
+	T,
+	Options extends ShallowReadonlyOptions = {
+		DeepenedGenerics: ShallowReadonlySupportedGenericsDefault;
+	},
+> = InternalUtilityTypes.ShallowReadonlyImpl<
+	T,
+	Options extends { DeepenedGenerics: unknown }
+		? Options["DeepenedGenerics"]
+		: ShallowReadonlySupportedGenericsDefault
+>;