@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/util/typeCheck.ts

@@ -0,0 +1,208 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// Normally we would put tests in the test directory.
+// However in this case,
+// it's important that the tests are run with the same compiler settings this library is being used with,
+// since this library does not work for some configurations (ex: with strictNullChecks disabled).
+// Since the tests don't generate any JS: they only produce types,
+// importing them here gets us the validation of the compiler settings we want, with no JS size overhead.
+export type { EnforceTypeCheckTests } from "./typeCheckTests";
+
+/**
+ * Utilities for manipulating the typescript typechecker.
+ *
+ * @remarks
+ * While it appears the the variance parts of this library are made obsolete by TypeScript 4.7's explicit variance annotations,
+ * many cases still type check with incorrect variance even when using the explicit annotations,
+ * and are fixed by using the patterns in this library.
+ *
+ * TypeScript uses structural typing if there are no private or protected members,
+ * and variance of generic type parameters depends on their usages.
+ * Thus when trying to constrain code by adding extra type information,
+ * it often fails to actually constrain as desired, and these utilities can help with those cases.
+ *
+ * This library is designed so that the desired variance can be documented in a way that is easy to read, concise,
+ * and allows easy navigation to documentation explaining what is being done
+ * for readers who are not familiar with this library.
+ * Additionally it constrains the types so the undesired usage patterns will not compile,
+ * and will give somewhat intelligible errors.
+ *
+ * Additionally this library provides the tools needed to test that the type constraints are working as expected,
+ * or test any other similar typing constraints in an application.
+ *
+ * This library assumes you are compiling with --strictFunctionTypes:
+ * (Covariance and Contravariance is explained along with how these helpers cause it in typescript at this link)
+ * {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types}.
+ * If compiled with a TypeScript configuration that is not strict enough for these features to work,
+ * the test suite should fail to build.
+ *
+ * Classes in TypeScript by default allow all assignments:
+ * its only though adding members that any type constraints actually get applied.
+ * This library provides types that can be used on a protected member of a class to add the desired constraints.
+ *
+ * Typical usages (use one field like this at the top of a class):
+ * ```typescript
+ * protected _typeCheck?: MakeNominal;
+ * protected _typeCheck?: Contravariant<T>;
+ * protected _typeCheck?: Covariant<T>;
+ * protected _typeCheck?: Invariant<T>;
+ * protected _typeCheck?: Contravariant<T> & Invariant<K>;
+ * ```
+ *
+ * See tests for examples.
+ *
+ * Note that all of these cause nominal typing.
+ * If constraints on generic type parameter variance are desired, but nominal typing is not,
+ * these types can be used on a public field. This case also works with interfaces.
+ *
+ * Be aware that other members of your type might apply further constraints
+ * (ex: you might try and write a Contravariant<T> class, but it ends up being Invariant<T> due to a field of type T).
+ *
+ * Be aware of TypeScript Bug:
+ * {@link https://github.com/microsoft/TypeScript/issues/36906}.
+ * This bug is why the fields here are protected not private.
+ * Note that this bug is closed as a duplicate of {@link https://github.com/microsoft/TypeScript/issues/20979}
+ * which was closed because fixing it would be too large of a breaking change.
+ * Thus we expect this bug to be part of TypeScript for the forseeable future.
+ */
+
+/**
+ * Use this as the type of a protected field to cause a type to use nominal typing instead of structural.
+ *
+ * @remarks
+ * Using nominal typing in this way prevents assignment of objects which are not instances of this class to values of this class's type.
+ * Classes which are used with "instanceof", or are supposed to be instantiated in particular ways (not just made with object literals)
+ * can use this to prevent undesired assignments.
+ * @example
+ * ```typescript
+ * protected _typeCheck?: MakeNominal;
+ * ```
+ * @privateRemarks
+ * See: {@link https://dev.azure.com/intentional/intent/_wiki/wikis/NP%20Platform/7146/Nominal-vs-Structural-Types}
+ * @beta
+ */
+export interface MakeNominal {}
+
+/**
+ * Constrain generic type parameters to Contravariant.
+ *
+ * @example
+ *
+ * ```typescript
+ * protected _typeCheck?: Contravariant<T>;
+ * ```
+ *
+ * @internal
+ */
+export interface Contravariant<in T> {
+	_removeCovariance?: (_: T) => void;
+}
+
+/**
+ * Constrain generic type parameters to Covariant.
+ *
+ * @example
+ *
+ * ```typescript
+ * protected _typeCheck?: Covariant<T>;
+ * ```
+ *
+ * @internal
+ */
+export interface Covariant<out T> {
+	_removeContravariance?: T;
+}
+
+/**
+ * Constrain generic type parameters to Invariant.
+ *
+ * @example
+ *
+ * ```typescript
+ * protected _typeCheck?: Invariant<T>;
+ * ```
+ *
+ * @internal
+ */
+export interface Invariant<in out T> extends Contravariant<T>, Covariant<T> {}
+
+/**
+ * Compile time assert that X is True.
+ * To use, simply define a type:
+ * `type _check = requireTrue<your type check>;`
+ *
+ * @internal
+ */
+export type requireTrue<_X extends true> = true;
+
+/**
+ * Compile time assert that X is False.
+ * To use, simply define a type:
+ * `type _check = requireFalse<your type check>;`
+ *
+ * @internal
+ */
+export type requireFalse<_X extends false> = true;
+
+/**
+ * Returns a type parameter that is true iff Source is assignable to Destination.
+ *
+ * @privateRemarks
+ * Use of [] in the extends clause prevents unions from being distributed over this conditional and returning `boolean` in some cases.
+ * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types | distributive-conditional-types} for details.
+ * @internal
+ */
+export type isAssignableTo<Source, Destination> = [Source] extends [Destination] ? true : false;
+
+/**
+ * Returns a type parameter that is true iff Subset is a strict subset of Superset.
+ *
+ * @internal
+ */
+export type isStrictSubset<Subset, Superset> = isAssignableTo<Subset, Superset> extends false
+	? false
+	: isAssignableTo<Superset, Subset> extends true
+	? false
+	: true;
+
+/**
+ * Returns a type parameter that is true iff A and B are assignable to each other, and neither is any.
+ * This is useful for checking if the output of a type meta-function is the expected type.
+ *
+ * @internal
+ */
+export type areSafelyAssignable<A, B> = eitherIsAny<A, B> extends true
+	? false
+	: isAssignableTo<A, B> extends true
+	? isAssignableTo<B, A>
+	: false;
+
+/**
+ * Returns a type parameter that is true iff A is any or B is any.
+ *
+ * @internal
+ */
+export type eitherIsAny<A, B> = true extends isAny<A> | isAny<B> ? true : false;
+
+/**
+ * Returns a type parameter that is true iff T is any.
+ *
+ * @privateRemarks
+ * Only `never` is assignable to `never` (`any` isn't),
+ * but `any` distributes over the `extends` here while nothing else should.
+ * This can be used to detect `any`.
+ * @internal
+ */
+export type isAny<T> = boolean extends (T extends never ? true : false) ? true : false;
+
+/**
+ * Compile time assert that A is assignable to (extends) B.
+ * To use, simply define a type:
+ * `type _check = requireAssignableTo<T, Expected>;`
+ *
+ * @internal
+ */
+export type requireAssignableTo<_A extends B, B> = true;

package/src/util/typeCheckTests.ts

@@ -0,0 +1,237 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// These tests include making sure some banned types (like `{}`) work correctly,
+// and are authored with awareness of the issues with these types.
+
+/* eslint-disable @typescript-eslint/ban-types */
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+
+import {
+	MakeNominal,
+	Covariant,
+	Contravariant,
+	Invariant,
+	requireTrue,
+	requireFalse,
+	isAssignableTo,
+	areSafelyAssignable,
+	isAny,
+	eitherIsAny,
+	isStrictSubset,
+} from "./typeCheck";
+
+/**
+ * Checks that typeCheck's constraints work as intended.
+ * Since typescript does type erasure, these tests have to be compile time checks.
+ */
+
+declare class Empty1 {}
+declare class Empty2 {}
+
+declare class Nominal1 {
+	protected _typeCheck?: MakeNominal;
+}
+
+declare class Nominal2 {
+	protected _typeCheck?: MakeNominal;
+}
+
+declare class Derived1 extends Nominal1 {
+	protected _typeCheck?: MakeNominal;
+}
+
+declare class Derived2 extends Nominal1 {
+	protected _typeCheck?: MakeNominal;
+}
+
+declare class Generic<_T> {}
+
+declare class GenericCovariant<out T> {
+	protected _typeCheck?: Covariant<T>;
+}
+
+declare class GenericContravariant<in T> {
+	protected _typeCheck?: Contravariant<T>;
+}
+
+declare class GenericInvariant<in out T> {
+	protected _typeCheck?: Invariant<T>;
+}
+
+declare class GenericMulti<in out T, out K> {
+	protected _typeCheck?: Invariant<T> & Covariant<K>;
+}
+
+interface GenericCovariantInterface<out T> {
+	_typeCheck?: Covariant<T>;
+}
+
+interface GenericContravariantInterface<in T> {
+	_typeCheck?: Contravariant<T>;
+}
+
+interface GenericInvariantInterface<in out T> {
+	_typeCheck?: Invariant<T>;
+}
+
+// Check that interface can be implemented without needing extra members
+declare class GenericInvariantImplementation<T> implements GenericInvariantInterface<T> {}
+
+/**
+ * Import this into a context where you want to be sure the TypeCheck library is functioning properly.
+ *
+ * It's functionality depends on compiler settings (requires several of the strict options),
+ * and could break with compiler version changes.
+ * Thus for maximal confidence everything is working correctly, you need to import this.
+ */
+export type EnforceTypeCheckTests =
+	// Add dummy use of type checking types above
+	| requireTrue<
+			isAssignableTo<
+				GenericInvariantImplementation<number>,
+				GenericInvariantInterface<number>
+			>
+	  >
+
+	// Positive tests
+	| requireTrue<true>
+	| requireFalse<false>
+
+	// test isAssignableTo for normal types
+	| requireTrue<isAssignableTo<Empty1, Empty1>>
+	| requireTrue<isAssignableTo<Empty1, Empty2>>
+	| requireTrue<isAssignableTo<Nominal1, Nominal1>>
+	| requireFalse<isAssignableTo<Nominal1, Nominal2>>
+	| requireTrue<isAssignableTo<Derived1, Nominal1>>
+	| requireFalse<isAssignableTo<Derived1, Derived2>>
+	| requireTrue<isAssignableTo<Generic<Nominal1>, Generic<Nominal2>>>
+
+	// test isAssignableTo for any
+	| requireTrue<isAssignableTo<any, Nominal1>>
+	| requireTrue<isAssignableTo<Nominal1, any>>
+
+	// test isAssignableTo for unknown: all types are assignable to unknown
+	| requireFalse<isAssignableTo<unknown, Nominal1>>
+	| requireTrue<isAssignableTo<Nominal1, unknown>>
+
+	// test isAssignableTo for never: all types are assignable from never
+	| requireTrue<isAssignableTo<never, Nominal1>>
+	| requireFalse<isAssignableTo<Nominal1, never>>
+
+	// test Covariant
+	| requireFalse<isAssignableTo<GenericCovariant<Nominal1>, GenericCovariant<Nominal2>>>
+	| requireTrue<isAssignableTo<GenericCovariant<Derived1>, GenericCovariant<Nominal1>>>
+	| requireFalse<isAssignableTo<GenericCovariant<Nominal1>, GenericCovariant<Derived1>>>
+
+	// test Contravariant
+	| requireFalse<isAssignableTo<GenericContravariant<Nominal1>, GenericContravariant<Nominal2>>>
+	| requireFalse<isAssignableTo<GenericContravariant<Derived1>, GenericContravariant<Nominal1>>>
+	| requireTrue<isAssignableTo<GenericContravariant<Nominal1>, GenericContravariant<Derived1>>>
+
+	// test Invariant
+	| requireFalse<isAssignableTo<GenericInvariant<Nominal1>, GenericInvariant<Nominal2>>>
+	| requireFalse<isAssignableTo<GenericInvariant<Derived1>, GenericInvariant<Nominal1>>>
+	| requireFalse<isAssignableTo<GenericInvariant<Nominal1>, GenericInvariant<Derived1>>>
+
+	// test Multiple parameters
+	| requireFalse<isAssignableTo<GenericMulti<Nominal1, number>, GenericMulti<Derived1, number>>>
+	| requireFalse<isAssignableTo<GenericMulti<number, Nominal1>, GenericMulti<number, Derived1>>>
+	| requireTrue<isAssignableTo<GenericMulti<number, Derived1>, GenericMulti<number, Nominal1>>>
+
+	// test Covariant Interface
+	| requireFalse<
+			isAssignableTo<GenericCovariantInterface<Nominal1>, GenericCovariantInterface<Nominal2>>
+	  >
+	| requireTrue<
+			isAssignableTo<GenericCovariantInterface<Derived1>, GenericCovariantInterface<Nominal1>>
+	  >
+	| requireFalse<
+			isAssignableTo<GenericCovariantInterface<Nominal1>, GenericCovariantInterface<Derived1>>
+	  >
+
+	// test Contravariant Interface
+	| requireFalse<
+			isAssignableTo<
+				GenericContravariantInterface<Nominal1>,
+				GenericContravariantInterface<Nominal2>
+			>
+	  >
+	| requireFalse<
+			isAssignableTo<
+				GenericContravariantInterface<Derived1>,
+				GenericContravariantInterface<Nominal1>
+			>
+	  >
+	| requireTrue<
+			isAssignableTo<
+				GenericContravariantInterface<Nominal1>,
+				GenericContravariantInterface<Derived1>
+			>
+	  >
+
+	// test Invariant Interface
+	| requireFalse<
+			isAssignableTo<GenericInvariantInterface<Nominal1>, GenericInvariantInterface<Nominal2>>
+	  >
+	| requireFalse<
+			isAssignableTo<GenericInvariantInterface<Derived1>, GenericInvariantInterface<Nominal1>>
+	  >
+	| requireFalse<
+			isAssignableTo<GenericInvariantInterface<Nominal1>, GenericInvariantInterface<Derived1>>
+	  >
+
+	// test eitherIsAny
+	| requireTrue<eitherIsAny<any, Nominal1>>
+	| requireTrue<eitherIsAny<Nominal1, any>>
+	| requireTrue<eitherIsAny<any, any>>
+	| requireFalse<eitherIsAny<Nominal1, Nominal1>>
+
+	// areSafelyAssignable tests
+	| requireTrue<areSafelyAssignable<Nominal1, Nominal1>>
+	| requireFalse<areSafelyAssignable<unknown, Nominal1>>
+	| requireFalse<areSafelyAssignable<any, any>>
+	| requireTrue<areSafelyAssignable<unknown, unknown>>
+	| requireFalse<areSafelyAssignable<any, Nominal1>>
+	| requireFalse<areSafelyAssignable<Nominal1, any>>
+	| requireFalse<areSafelyAssignable<unknown, any>>
+
+	// test isAny
+	| requireTrue<isAny<any>>
+	| requireFalse<isAny<unknown>>
+	| requireFalse<isAny<Nominal1>>
+	| requireFalse<isAny<never>>
+	| requireFalse<isAny<{}>>
+	| requireFalse<isAny<boolean>>
+	| requireFalse<isAny<number | undefined>>
+	| requireFalse<isAny<1 & "x">>
+	| requireFalse<isAny<(1 & 2) | {}>>
+
+	// test isStrictSubset
+	| requireTrue<isStrictSubset<1, 1 | 2>>
+	| requireTrue<isStrictSubset<[1, true], [1 | 2, true]>>
+	| requireTrue<isStrictSubset<[1, true], [1 | 2, true | false]>>
+	| requireTrue<isStrictSubset<[1, true], [1, true | false]>>
+	| requireTrue<isStrictSubset<[1, true], [1, true] | [1 | false]>>
+	| requireFalse<isStrictSubset<1, 1>>
+	| requireFalse<isStrictSubset<1, 2>>
+	| requireFalse<isStrictSubset<[1, true], [1, true]>>
+	| requireFalse<isStrictSubset<1 | 2, 1>>;
+
+// negative tests (should not build)
+// @ts-expect-error negative test
+type _falseIsTrue = requireTrue<false>;
+// @ts-expect-error negative test
+type _trueIsFalse = requireFalse<true>;
+// @ts-expect-error negative test
+type _booleanIsTrue = requireTrue<boolean>;
+// @ts-expect-error negative test
+type _booleanIsFalse = requireFalse<boolean>;
+// @ts-expect-error negative test
+type _emptyNotAssignable = requireFalse<isAssignableTo<Empty1, Empty2>>;
+// @ts-expect-error negative test
+type _numberAssignableToString = requireTrue<isAssignableTo<number, string>>;
+// @ts-expect-error negative test
+type _anyNotAny = requireFalse<isAny<any>>;

package/src/util/typeUtils.ts

@@ -0,0 +1,168 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Utilities for manipulating types.
+ */
+
+/**
+ * Return a type thats equivalent to the input, but with different IntelliSense.
+ * This tends to convert unions and intersections into objects.
+ * @internal
+ */
+export type FlattenKeys<T> = [{ [Property in keyof T]: T[Property] }][_InlineTrick];
+
+/**
+ * Remove all fields which permit undefined from `T`.
+ * @internal
+ */
+export type RequiredFields<T> = [
+	{
+		[P in keyof T as undefined extends T[P] ? never : P]: T[P];
+	},
+][_InlineTrick];
+
+/**
+ * Extract fields which permit undefined but can also hold other types.
+ * @internal
+ */
+export type OptionalFields<T> = [
+	{
+		[P in keyof T as undefined extends T[P]
+			? T[P] extends undefined
+				? never
+				: P
+			: never]?: T[P];
+	},
+][_InlineTrick];
+
+/**
+ * Converts properties of an object which permit undefined into optional properties.
+ * Removes fields which only allow undefined.
+ *
+ * @remarks
+ * This version does not flatten the resulting type.
+ * This version exists because some cases recursive types need to avoid this
+ * flattening since it causes complication issues.
+ *
+ * See also `AllowOptional`.
+ * @internal
+ */
+// export type AllowOptionalNotFlattened<T> = [RequiredFields<T> & OptionalFields<T>][_InlineTrick];
+export type AllowOptionalNotFlattened<T> = [RequiredFields<T> & OptionalFields<T>][_InlineTrick];
+
+/**
+ * Converts properties of an object which permit undefined into optional properties.
+ * Removes fields which only allow undefined.
+ * @internal
+ */
+export type AllowOptional<T> = [FlattenKeys<RequiredFields<T> & OptionalFields<T>>][_InlineTrick];
+
+/**
+ * Use for trick to "inline" generic types.
+ *
+ * @remarks
+ * The TypeScript compiler can be convinced to inline a generic type
+ * (so the result of evaluating the generic type show up in IntelliSense and error messages instead of just the invocation of the generic type)
+ * by creating an object with a field, and returning the type of that field.
+ *
+ * For example:
+ * ```typescript
+ * type MyGeneric<T1, T2> = {x: T1 extends [] ? T1 : T2 };
+ * type MyGenericExpanded<T1, T2> = [{x: T1 extends [] ? T1 : T2 }][_InlineTrick]
+ *
+ * // Type is MyGeneric<5, string>
+ * const foo: MyGeneric<5, string> = {x: "x"}
+ * // Type is {x: "x"}
+ * const foo2: MyGenericExpanded<5, string> = {x: "x"}
+ * ```
+ *
+ * This constant is defined to provide a way to find this documentation from types which use this pattern,
+ * and to locate types which use this pattern in case they need updating for compiler changes.
+ * @internal
+ */
+export type _InlineTrick = 0;
+
+/**
+ * Use for trick to prevent self reference error `ts(2456)`.
+ *
+ * Prefix a type expression with `K extends _RecursiveTrick ? _RecursiveTrick : ` for some K to break the cycle.
+ *
+ * @remarks
+ * The TypeScript compiler handles some cases of recursive types, but not others.
+ * Sometimes adding an otherwise needless conditional can make a type compile.
+ * Use this type in such cases.
+ *
+ *For example:
+ * ```typescript
+ * // The TypeScript compiler can't handle this case
+ * type Broken<T> = FlattenKeys<
+ *	{
+ * 		[K in keyof T]: 0;
+ * 	} & {
+ * 		[K in keyof T]: Broken<T[K]>;
+ * 	}
+ * >;
+ *
+ * // Adding `K extends _RecursiveTrick ? _RecursiveTrick :` makes it compile, and has no effect on the type produced.
+ * type Works<T> = FlattenKeys<
+ * 	{
+ * 		[K in keyof T]: 0;
+ * 	} & {
+ * 		// Trick added here. Since `k` never extends `never`, the second conditional option is always taken,
+ * 		// making this equivalent to the broken version, except this one compiles.
+ * 		[K in keyof T]: K extends _RecursiveTrick ? _RecursiveTrick : Works<T[K]>;
+ * 	}
+ * >;
+ * ```
+ *
+ * This trick appears to start working in TypeScript 4.1 and is confirmed to still work in 5.0.4.
+ *
+ * This constant is defined to provide a way to find this documentation from types which use this pattern,
+ * and to locate types which use this pattern in case they need updating for compiler changes.
+ * @internal
+ */
+export type _RecursiveTrick = never;
+
+// This block is kept here to ensure the above example behaves as documented, and can be copied into the example to update it as needed.
+{
+	/* eslint-disable @typescript-eslint/no-unused-vars */
+
+	// @ts-expect-error The TypeScript compiler can't handle this case
+	type Broken<T> = FlattenKeys<
+		{
+			[K in keyof T]: 0;
+		} & {
+			// @ts-expect-error Same error as above.
+			[K in keyof T]: Broken<T[K]>;
+		}
+	>;
+
+	// Adding `K extends _RecursiveTrick ? _RecursiveTrick:` OR `T extends _RecursiveTrick ? _RecursiveTrick :` makes it compile and has no effect on the type produced.
+	type Works<T> = FlattenKeys<
+		{
+			[K in keyof T]: 0;
+		} & {
+			// Trick added here. Since `K` never extends `never`, the second conditional option is always taken,
+			// making this equivalent to the broken version, except this one compiles.
+			[K in keyof T]: T extends _RecursiveTrick ? _RecursiveTrick : Works<T[K]>;
+		}
+	>;
+
+	/* eslint-enable @typescript-eslint/no-unused-vars */
+}
+
+/**
+ * Alternative to the built in Record type which does not permit unexpected members,
+ * and is readonly.
+ *
+ * @privateRemarks
+ * `number` is not allowed as a key here since doing so causes the compiler to reject recursive schema.
+ * The cause for this is unclear, but empirically it was the case when this comment was written.
+ * @beta
+ */
+export type RestrictiveReadonlyRecord<K extends symbol | string, T> = {
+	readonly [P in symbol | string]: P extends K ? T : never;
+};