@fluidframework/tree 2.33.2 → 2.40.0

package/src/simple-tree/api/typesUnsafe.ts

@@ -3,7 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import type { RestrictiveStringRecord, UnionToIntersection } from "../../util/index.js";
+import type {
+	IsUnion,
+	RestrictiveStringRecord,
+	UnionToIntersection,
+} from "../../util/index.js";
 
 import type {
 	ApplyKind,
@@ -239,16 +243,16 @@ export namespace System_Unsafe {
 	 * of the JsonAsTree schema.
 	 * @system @public
 	 */
-	export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> = [
-		TList,
-	] extends [
-		readonly [
-			LazyItem<infer TSchema extends TreeNodeSchemaUnsafe>,
-			...infer Rest extends AllowedTypesUnsafe,
-		],
-	]
-		? InsertableTypedNodeUnsafe<TSchema> | InsertableTreeNodeFromAllowedTypesUnsafe<Rest>
-		: never;
+	export type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> =
+		IsUnion<TList> extends true
+			? never
+			: {
+					readonly [Property in keyof TList]: TList[Property] extends LazyItem<
+						infer TSchema extends TreeNodeSchemaUnsafe
+					>
+						? InsertableTypedNodeUnsafe<TSchema>
+						: never;
+				}[number];
 
 	/**
 	 * {@link Unenforced} version of {@link InsertableTypedNode}.

package/src/simple-tree/arrayNode.ts

@@ -16,11 +16,14 @@ import {
 import { prepareContentForHydration } from "./proxies.js";
 import {
 	normalizeAllowedTypes,
+	unannotateImplicitAllowedTypes,
 	type ImplicitAllowedTypes,
+	type ImplicitAnnotatedAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 	type NodeSchemaMetadata,
 	type TreeLeafValue,
 	type TreeNodeFromImplicitAllowedTypes,
+	type UnannotateImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
 	type WithType,
@@ -170,8 +173,11 @@ export interface TreeArrayNode<
 	 * For example, if the array contains items `[A, B, C]` before the move, the `destinationGap` must be one of the following:
 	 *
 	 * - `0` (between the start of the array and `A`'s original position)
+	 *
 	 * - `1` (between `A`'s original position and `B`'s original position)
+	 *
 	 * - `2` (between `B`'s original position and `C`'s original position)
+	 *
 	 * - `3` (between `C`'s original position and the end of the array)
 	 *
 	 * So moving `A` between `B` and `C` would require `destinationGap` to be `2`.
@@ -180,13 +186,17 @@ export interface TreeArrayNode<
 	 * or relative to the start or end of the array:
 	 *
 	 * - Move to the start of the array: `array.moveToIndex(0, ...)` (see also `moveToStart`)
+	 *
 	 * - Move to before some item X: `array.moveToIndex(indexOfX, ...)`
+	 *
 	 * - Move to after some item X: `array.moveToIndex(indexOfX + 1`, ...)
+	 *
 	 * - Move to the end of the array: `array.moveToIndex(array.length, ...)` (see also `moveToEnd`)
 	 *
 	 * This interpretation of `destinationGap` does however make it less obvious how to move an item relative to its current position:
 	 *
 	 * - Move item B before its predecessor: `array.moveToIndex(indexOfB - 1, ...)`
+	 *
 	 * - Move item B after its successor: `array.moveToIndex(indexOfB + 2, ...)`
 	 *
 	 * Notice the asymmetry between `-1` and `+2` in the above examples.
@@ -212,8 +222,11 @@ export interface TreeArrayNode<
 	 * For example, if the array contains items `[A, B, C]` before the move, the `destinationGap` must be one of the following:
 	 *
 	 * - `0` (between the start of the array and `A`'s original position)
+	 *
 	 * - `1` (between `A`'s original position and `B`'s original position)
+	 *
 	 * - `2` (between `B`'s original position and `C`'s original position)
+	 *
 	 * - `3` (between `C`'s original position and the end of the array)
 	 *
 	 * So moving `A` between `B` and `C` would require `destinationGap` to be `2`.
@@ -222,13 +235,17 @@ export interface TreeArrayNode<
 	 * or relative to the start or end of the array:
 	 *
 	 * - Move to the start of the array: `array.moveToIndex(0, ...)` (see also `moveToStart`)
+	 *
 	 * - Move to before some item X: `array.moveToIndex(indexOfX, ...)`
+	 *
 	 * - Move to after some item X: `array.moveToIndex(indexOfX + 1`, ...)
+	 *
 	 * - Move to the end of the array: `array.moveToIndex(array.length, ...)` (see also `moveToEnd`)
 	 *
 	 * This interpretation of `destinationGap` does however make it less obvious how to move an item relative to its current position:
 	 *
 	 * - Move item B before its predecessor: `array.moveToIndex(indexOfB - 1, ...)`
+	 *
 	 * - Move item B after its successor: `array.moveToIndex(indexOfB + 2, ...)`
 	 *
 	 * Notice the asymmetry between `-1` and `+2` in the above examples.
@@ -296,8 +313,11 @@ export interface TreeArrayNode<
 	 * For example, if the array contains items `[A, B, C]` before the move, the `destinationGap` must be one of the following:
 	 *
 	 * - `0` (between the start of the array and `A`'s original position)
+	 *
 	 * - `1` (between `A`'s original position and `B`'s original position)
+	 *
 	 * - `2` (between `B`'s original position and `C`'s original position)
+	 *
 	 * - `3` (between `C`'s original position and the end of the array)
 	 *
 	 * So moving `A` between `B` and `C` would require `destinationGap` to be `2`.
@@ -306,13 +326,17 @@ export interface TreeArrayNode<
 	 * or relative to the start or end of the array:
 	 *
 	 * - Move to the start of the array: `array.moveToIndex(0, ...)` (see also `moveToStart`)
+	 *
 	 * - Move to before some item X: `array.moveToIndex(indexOfX, ...)`
+	 *
 	 * - Move to after some item X: `array.moveToIndex(indexOfX + 1`, ...)
+	 *
 	 * - Move to the end of the array: `array.moveToIndex(array.length, ...)` (see also `moveToEnd`)
 	 *
 	 * This interpretation of `destinationGap` does however make it less obvious how to move an item relative to its current position:
 	 *
 	 * - Move item B before its predecessor: `array.moveToIndex(indexOfB - 1, ...)`
+	 *
 	 * - Move item B after its successor: `array.moveToIndex(indexOfB + 2, ...)`
 	 *
 	 * Notice the asymmetry between `-1` and `+2` in the above examples.
@@ -340,8 +364,11 @@ export interface TreeArrayNode<
 	 * For example, if the array contains items `[A, B, C]` before the move, the `destinationGap` must be one of the following:
 	 *
 	 * - `0` (between the start of the array and `A`'s original position)
+	 *
 	 * - `1` (between `A`'s original position and `B`'s original position)
+	 *
 	 * - `2` (between `B`'s original position and `C`'s original position)
+	 *
 	 * - `3` (between `C`'s original position and the end of the array)
 	 *
 	 * So moving `A` between `B` and `C` would require `destinationGap` to be `2`.
@@ -350,13 +377,17 @@ export interface TreeArrayNode<
 	 * or relative to the start or end of the array:
 	 *
 	 * - Move to the start of the array: `array.moveToIndex(0, ...)` (see also `moveToStart`)
+	 *
 	 * - Move to before some item X: `array.moveToIndex(indexOfX, ...)`
+	 *
 	 * - Move to after some item X: `array.moveToIndex(indexOfX + 1`, ...)
+	 *
 	 * - Move to the end of the array: `array.moveToIndex(array.length, ...)` (see also `moveToEnd`)
 	 *
 	 * This interpretation of `destinationGap` does however make it less obvious how to move an item relative to its current position:
 	 *
 	 * - Move item B before its predecessor: `array.moveToIndex(indexOfB - 1, ...)`
+	 *
 	 * - Move item B after its successor: `array.moveToIndex(indexOfB + 2, ...)`
 	 *
 	 * Notice the asymmetry between `-1` and `+2` in the above examples.
@@ -1064,7 +1095,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function arraySchema<
 	TName extends string,
-	const T extends ImplicitAllowedTypes,
+	const T extends ImplicitAnnotatedAllowedTypes,
 	const ImplicitlyConstructable extends boolean,
 	const TCustomMetadata = unknown,
 >(
@@ -1082,7 +1113,9 @@ export function arraySchema<
 	> &
 		ArrayNodePojoEmulationSchema<TName, T, ImplicitlyConstructable, TCustomMetadata>;
 
-	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
+	const unannotatedTypes = unannotateImplicitAllowedTypes(info);
+
+	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(unannotatedTypes));
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set([...lazyChildTypes.value].map((type) => type.identifier)),
 	);
@@ -1091,7 +1124,7 @@ export function arraySchema<
 
 	// This class returns a proxy from its constructor to handle numeric indexing.
 	// Alternatively it could extend a normal class which gets tons of numeric properties added.
-	class Schema extends CustomArrayNodeBase<T> {
+	class Schema extends CustomArrayNodeBase<UnannotateImplicitAllowedTypes<T>> {
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
 			instance: TreeNodeValid<T2>,
@@ -1178,8 +1211,8 @@ export function arraySchema<
 			return Schema.constructorCached?.constructor as unknown as Output;
 		}
 
-		protected get simpleSchema(): T {
-			return info;
+		protected get simpleSchema(): UnannotateImplicitAllowedTypes<T> {
+			return unannotatedTypes;
 		}
 		protected get allowedTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;

package/src/simple-tree/arrayNodeTypes.ts

@@ -5,8 +5,9 @@
 
 import type { TreeArrayNode } from "./arrayNode.js";
 import type {
-	ImplicitAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
 	InsertableTreeNodeFromImplicitAllowedTypes,
+	UnannotateImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
 	NodeKind,
@@ -24,14 +25,14 @@ import type { SimpleArrayNodeSchema } from "./simpleSchema.js";
  */
 export interface ArrayNodeCustomizableSchema<
 	out TName extends string = string,
-	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	in out T extends ImplicitAnnotatedAllowedTypes = ImplicitAnnotatedAllowedTypes,
 	out ImplicitlyConstructable extends boolean = true,
 	out TCustomMetadata = unknown,
 > extends TreeNodeSchemaClass<
 			TName,
 			NodeKind.Array,
-			TreeArrayNode<T> & WithType<TName, NodeKind.Array, T>,
-			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			TreeArrayNode<UnannotateImplicitAllowedTypes<T>> & WithType<TName, NodeKind.Array, T>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>>,
 			ImplicitlyConstructable,
 			T,
 			undefined,
@@ -45,14 +46,14 @@ export interface ArrayNodeCustomizableSchema<
  */
 export interface ArrayNodePojoEmulationSchema<
 	out TName extends string = string,
-	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	in out T extends ImplicitAnnotatedAllowedTypes = ImplicitAnnotatedAllowedTypes,
 	out ImplicitlyConstructable extends boolean = true,
 	out TCustomMetadata = unknown,
 > extends TreeNodeSchemaNonClass<
 			TName,
 			NodeKind.Array,
-			TreeArrayNode<T> & WithType<TName, NodeKind.Array, T>,
-			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			TreeArrayNode<UnannotateImplicitAllowedTypes<T>> & WithType<TName, NodeKind.Array, T>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>>,
 			ImplicitlyConstructable,
 			T,
 			undefined,

package/src/simple-tree/core/getOrCreateNode.ts

@@ -10,7 +10,7 @@ import {
 	proxySlot,
 	createTreeNodeFromInner,
 } from "./treeNodeKernel.js";
-import type { TreeNode } from "./types.js";
+import type { TreeNode } from "./treeNode.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 
 /**

package/src/simple-tree/core/index.ts

@@ -17,13 +17,14 @@ export {
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {
-	type TreeChangeEvents,
-	TreeNode,
 	type Unhydrated,
-	inPrototypeChain,
 	type InternalTreeNode,
-	privateToken,
 } from "./types.js";
+export {
+	TreeNode,
+	privateToken,
+	inPrototypeChain,
+} from "./treeNode.js";
 export {
 	type TreeNodeSchema,
 	NodeKind,

package/src/simple-tree/core/treeNode.ts

@@ -0,0 +1,163 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
+// eslint-disable-next-line import/no-deprecated
+import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
+import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
+
+/**
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
+ *
+ * @remarks
+ * Base type which all nodes extend.
+ *
+ * This type can be used as a type to indicate/document values which should be tree nodes.
+ * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.
+ *
+ * There are three ways to get instances of TreeNode:
+ *
+ * 1. From a {@link TreeView} loading nodes from an existing document, or creating local copies of nodes inserted by a remote collaborator.
+ * This case provides an {@link InternalTreeNode} to the constructor: subclasses must not modify how the constructor handles this case.
+ *
+ * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
+ * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
+ *
+ * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
+ * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
+ * Note that when constructing nodes, sometimes implicit construction is not allowed
+ * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
+ * in such cases, explicit construction must be used.
+ *
+ * @privateRemarks
+ * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
+ * and some runtime enforcement of schema class policy (see the the validation in the constructor).
+ * This class is however only `type` exported not value exported, preventing the class object from being used,
+ * similar to how interfaces work.
+ *
+ * Not all node implementations include this in their prototype chain (some hide it with a proxy),
+ * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
+ * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
+ * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
+ * @sealed @public
+ */
+export abstract class TreeNode implements WithType {
+	/**
+	 * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.
+	 * @remarks
+	 * This field forces TypeScript to use nominal instead of structural typing,
+	 * preventing compiler error messages and tools like "add missing properties"
+	 * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.
+	 * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.
+	 *
+	 * @privateRemarks
+	 * This is a JavaScript private field, so is not accessible from outside this class.
+	 * This prevents it from having name collisions with object fields.
+	 * Since this is private, the type of this field is stripped in the d.ts file.
+	 * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.
+	 * To avoid this having any runtime impact, the field is uninitialized.
+	 *
+	 * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.
+	 * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.
+	 * To avoid all this mess, this field is required, not optional.
+	 *
+	 * Another option would be to use a symbol (possibly as a private field).
+	 * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
+	 *
+	 * The [type] symbol provides a lot of the value this private brand does, but is not all of it:
+	 * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
+	 * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
+	 */
+	readonly #brand!: unknown;
+
+	/**
+	 * Adds a type symbol for stronger typing.
+	 * @privateRemarks
+	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+	 * @deprecated Use {@link typeSchemaSymbol} instead.
+	 */
+	// eslint-disable-next-line import/no-deprecated
+	public abstract get [typeNameSymbol](): string;
+
+	/**
+	 * Adds a type symbol for stronger typing.
+	 * @privateRemarks
+	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+	 */
+	public abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;
+
+	/**
+	 * Provides `instanceof` support for testing if a value is a `TreeNode`.
+	 * @remarks
+	 * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
+	 * @privateRemarks
+	 * Due to type-only export, this functionality is not available outside the package.
+	 */
+	public static [Symbol.hasInstance](value: unknown): value is TreeNode;
+
+	/**
+	 * Provides `instanceof` support for all schema classes with public constructors.
+	 * @remarks
+	 * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
+	 * @privateRemarks
+	 * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.
+	 */
+	public static [Symbol.hasInstance]<
+		TSchema extends abstract new (
+			...args: any[]
+		) => TreeNode,
+	>(this: TSchema, value: unknown): value is InstanceType<TSchema>;
+
+	public static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {
+		const schema = tryGetTreeNodeSchema(value);
+
+		if (schema === undefined || schema.kind === NodeKind.Leaf) {
+			return false;
+		}
+
+		assert("prototype" in schema, 0x98a /* expected class based schema */);
+		return inPrototypeChain(schema.prototype, this.prototype);
+	}
+
+	/**
+	 * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
+	 * @privateRemarks
+	 * `token` must be the {@link privateToken} value, which is not package exported.
+	 * This is used to detect invalid subclasses.
+	 *
+	 * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
+	 */
+	protected constructor(token: unknown) {
+		if (token !== privateToken) {
+			throw new UsageError("TreeNodes must extend schema classes created by SchemaFactory");
+		}
+	}
+}
+
+/**
+ * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
+ */
+export const privateToken = {};
+
+/**
+ * Check if the prototype derived's prototype chain contains `base`.
+ * @param derived - prototype to check
+ * @param base - prototype to search for
+ * @returns true iff `base` is in the prototype chain starting at `derived`.
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+export function inPrototypeChain(derived: object | null, base: object): boolean {
+	let checking = derived;
+	while (checking !== null) {
+		if (base === checking) {
+			return true;
+		}
+		checking = Reflect.getPrototypeOf(checking);
+	}
+	return false;
+}

package/src/simple-tree/core/treeNodeKernel.ts

@@ -7,7 +7,7 @@ import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/inte
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable, Off } from "@fluidframework/core-interfaces";
-import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
+import type { InternalTreeNode, Unhydrated } from "./types.js";
 import {
 	anchorSlot,
 	type AnchorEvents,
@@ -31,6 +31,7 @@ import type { TreeNodeSchema } from "./treeNodeSchema.js";
 import { makeTree } from "../../feature-libraries/flex-tree/lazyNode.js";
 import { SimpleContextSlot, type Context, type HydratedContext } from "./context.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
+import type { TreeNode } from "./treeNode.js";
 
 const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();
 

package/src/simple-tree/core/treeNodeSchema.ts

@@ -5,7 +5,8 @@
 
 import type { TreeLeafValue } from "../schemaTypes.js";
 import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
-import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
+import type { TreeNode } from "./treeNode.js";
+import type { InternalTreeNode, Unhydrated } from "./types.js";
 
 /**
  * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
@@ -136,6 +137,7 @@ export type TreeNodeSchemaNonClass<
  * // If both get used, its an error!
  * class Invalid extends base {}
  * ```
+ *
  * - Do not modify the constructor input parameter types or values:
  * ```typescript
  * class Invalid extends schemaFactory.object("A", {