@fluidframework/tree 2.4.0 → 2.5.0-302463

package/src/util/index.ts

@@ -99,8 +99,14 @@ export type {
 	RestrictiveStringRecord,
 	_InlineTrick,
 	FlattenKeys,
+	IsUnion,
+	UnionToIntersection,
+	UnionToTuple,
+	PopUnion,
 } from "./typeUtils.js";
 
+export { unsafeArrayToTuple } from "./typeUtils.js";
+
 export {
 	type BrandedKey,
 	type BrandedKeyContent,

package/src/util/typeUtils.ts

@@ -137,3 +137,90 @@ export type RestrictiveStringRecord<T> = {
 } & {
 	readonly [P in symbol]?: never;
 };
+
+/**
+ * Returns `true` if T is a union and false if it is not.
+ * @typeparam T - Type to test if it is a union.
+ * @typeparam T2 - Do not specify: default value used as implementation detail.
+ * @system @alpha
+ */
+export type IsUnion<T, T2 = T> = T extends unknown
+	? [T2] extends [T]
+		? false
+		: true
+	: "error";
+
+/**
+ * Convert a union of types to an intersection of those types. Useful for `TransformEvents`.
+ * @privateRemarks
+ * First an always true extends clause is used (T extends T) to distribute T into to a union of types contravariant over each member of the T union.
+ * Then the constraint on the type parameter in this new context is inferred, giving the intersection.
+ * @system @public
+ */
+export type UnionToIntersection<T> = (T extends T ? (k: T) => unknown : never) extends (
+	k: infer U,
+) => unknown
+	? U
+	: never;
+
+/**
+ * Gets the first item of a union type.
+ *
+ * @typeparam Union - The union to convert.
+ * @typeparam AsOverloadedFunction - Implementation detail: do not specify.
+ * @system @alpha
+ */
+export type PopUnion<
+	Union,
+	AsOverloadedFunction = UnionToIntersection<
+		Union extends unknown ? (f: Union) => void : never
+	>,
+> = AsOverloadedFunction extends (a: infer First) => void ? First : never;
+
+/**
+ * Converts a union type to a tuple type.
+ *
+ * @typeparam T - The union to convert.
+ * @typeparam A - Implementation detail: do not specify.
+ * @typeparam First - Implementation detail: do not specify.
+ *
+ * @privateRemarks
+ * `A` is a tuple to prepend members of the union to.
+ *
+ * https://www.hacklewayne.com/typescript-convert-union-to-tuple-array-yes-but-how and https://catchts.com/union-array both explain the general approach this uses pretty well.
+ * This implementation is inspired to those, but slightly different in implementation.
+ * @alpha
+ */
+export type UnionToTuple<
+	Union,
+	A extends unknown[] = [],
+	First = PopUnion<Union>,
+> = IsUnion<Union> extends true
+	? UnionToTuple<Exclude<Union, First>, [First, ...A]>
+	: [Union, ...A];
+
+/**
+ * This is unsafe, meaning that the returned value might not match its type.
+ *
+ * For the result to match its type, T must be a union of the types of each item in `items` in the order that they occur.
+ * For this to be possible, there must be no duplicate or overlapping types.
+ * This is fragile and must be used with care.
+ *
+ * @remarks
+ * The main use-case for this is recovering lost information from {@link AllowedTypes} which is necessary to preserve when using them with {@link Input} APIs.
+ * Since {@link AllowedTypes} is actually order independent, it is somewhat safer when used to produce `AllowedTypes`.
+ *
+ * @example
+ * ```typescript
+ * // Gives imprecise type (typeof A | typeof B)[]
+ * const schemaBad = [A, B];
+ * // Fixes the type to be [typeof A, typeof B]
+ * const schema = unsafeArrayToTuple(schemaBad);
+ *
+ * const config = new TreeViewConfiguration({ schema });
+ * ```
+ * @alpha
+ */
+export function unsafeArrayToTuple<T>(items: T[]): UnionToTuple<T> {
+	return items as UnionToTuple<T>;
+}