@fluidframework/tree 2.1.0 → 2.3.0-288113

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

@@ -0,0 +1,200 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import {
+	createEmitter,
+	type HasListeners,
+	type IEmitter,
+	type Listenable,
+	type Off,
+} from "../../events/index.js";
+import type { TreeNode, Unhydrated } from "./types.js";
+import type { AnchorEvents, AnchorNode } from "../../core/index.js";
+import {
+	flexTreeSlot,
+	isFreedSymbol,
+	LazyEntity,
+	TreeStatus,
+	treeStatusFromAnchorCache,
+} from "../../feature-libraries/index.js";
+import type { TreeNodeSchema } from "./treeNodeSchema.js";
+
+const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();
+
+export function getKernel(node: TreeNode): TreeNodeKernel {
+	const kernel = treeNodeToKernel.get(node);
+	assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
+	return kernel;
+}
+
+/**
+ * Detects if the given 'candidate' is a TreeNode.
+ *
+ * @remarks
+ * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
+ *
+ * Because the common usage is to check if a value being inserted/set is a TreeNode,
+ * this function permits calling with primitives as well as objects.
+ *
+ * Primitives will always return false (as they are copies of data, not references to nodes).
+ *
+ * @param candidate - Value which may be a TreeNode
+ * @returns true if the given 'candidate' is a hydrated TreeNode.
+ */
+export function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {
+	return treeNodeToKernel.has(candidate as TreeNode);
+}
+
+/**
+ * Returns a schema for a value if the value is a {@link TreeNode}.
+ *
+ * Returns undefined for other values.
+ * @remarks
+ * Does not give schema for a {@link TreeLeafValue}.
+ */
+export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema {
+	const kernel = treeNodeToKernel.get(value as TreeNode);
+	return kernel?.schema;
+}
+
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export class TreeNodeKernel implements Listenable<KernelEvents> {
+	private disposed = false;
+
+	/**
+	 * Generation number which is incremented any time we have an edit on the node.
+	 * Used during iteration to make sure there has been no edits that were concurrently made.
+	 */
+	public generationNumber: number = 0;
+
+	#hydrated?: {
+		anchorNode: AnchorNode;
+		offAnchorNode: Set<Off>;
+	};
+
+	/**
+	 * Events registered before hydration.
+	 * @remarks
+	 *
+	 */
+	#preHydrationEvents?: Listenable<KernelEvents> &
+		IEmitter<KernelEvents> &
+		HasListeners<KernelEvents>;
+
+	/**
+	 * Get the listener.
+	 * @remarks
+	 * If before hydration, allocates and uses `#preHydrationEvents`, otherwise the anchorNode.
+	 * This design avoids allocating `#preHydrationEvents` if unneeded.
+	 *
+	 * This design also avoids extra forwarding overhead for events from anchorNode and also
+	 * avoids registering for events that the are unneeded.
+	 * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,
+	 * since this code does not unconditionally subscribe to those events (like a design simply forwarding all events would).
+	 */
+	get #events(): Listenable<KernelEvents> {
+		if (this.#hydrated === undefined) {
+			this.#preHydrationEvents ??= createEmitter<KernelEvents>();
+			return this.#preHydrationEvents;
+		} else {
+			return this.#hydrated.anchorNode;
+		}
+	}
+
+	/**
+	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
+	 * @remarks
+	 * Exactly one kernel per TreeNode should be created.
+	 */
+	public constructor(
+		public readonly node: TreeNode,
+		public readonly schema: TreeNodeSchema,
+	) {
+		assert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
+		treeNodeToKernel.set(node, this);
+	}
+
+	/**
+	 * Transition from {@link Unhydrated} to hydrated.
+	 * @remarks
+	 * Happens at most once for any given node.
+	 */
+	public hydrate(anchorNode: AnchorNode): void {
+		assert(!this.disposed, "cannot use a disposed node");
+
+		this.#hydrated = {
+			anchorNode,
+			offAnchorNode: new Set([
+				anchorNode.on("afterDestroy", () => this.dispose()),
+				// TODO: this should be triggered on change even for unhydrated nodes.
+				anchorNode.on("childrenChanging", () => {
+					this.generationNumber += 1;
+				}),
+			]),
+		};
+
+		// If needed, register forwarding emitters for events from before hydration
+		if (this.#preHydrationEvents !== undefined) {
+			for (const eventName of kernelEvents) {
+				if (this.#preHydrationEvents.hasListeners(eventName)) {
+					this.#hydrated.offAnchorNode.add(
+						// Argument is forwarded between matching events, so the type should be correct.
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						anchorNode.on(eventName, (arg: any) =>
+							this.#preHydrationEvents?.emit(eventName, arg),
+						),
+					);
+				}
+			}
+		}
+	}
+
+	public isHydrated(): boolean {
+		assert(!this.disposed, "cannot use a disposed node");
+		return this.#hydrated !== undefined;
+	}
+
+	public getStatus(): TreeStatus {
+		if (this.disposed) {
+			return TreeStatus.Deleted;
+		}
+		if (this.#hydrated?.anchorNode === undefined) {
+			return TreeStatus.New;
+		}
+
+		// TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel
+		const flex = this.#hydrated.anchorNode.slots.get(flexTreeSlot);
+		if (flex !== undefined) {
+			assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+			if (flex[isFreedSymbol]()) {
+				return TreeStatus.Deleted;
+			}
+		}
+
+		return treeStatusFromAnchorCache(this.#hydrated.anchorNode);
+	}
+
+	public on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {
+		return this.#events.on(eventName, listener);
+	}
+
+	public dispose(): void {
+		this.disposed = true;
+		for (const off of this.#hydrated?.offAnchorNode ?? []) {
+			off();
+		}
+		// TODO: go to the context and remove myself from withAnchors
+	}
+}
+
+const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] as const;
+
+type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;

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

@@ -0,0 +1,184 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { InternalTreeNode, Unhydrated } from "./types.js";
+
+/**
+ * Schema for a tree node.
+ * @typeParam Name - The full (including scope) name/identifier for the schema.
+ * @typeParam Kind - Which kind of node this schema is for.
+ * @typeParam TNode - API for nodes that use this schema.
+ * @typeParam TBuild - Data which can be used to construct an {@link Unhydrated} node of this type.
+ * @typeParam Info - Data used when defining this schema.
+ * @remarks
+ * Captures the schema both as runtime data and compile time type information.
+ * @sealed @public
+ */
+export type TreeNodeSchema<
+	Name extends string = string,
+	Kind extends NodeKind = NodeKind,
+	TNode = unknown,
+	TBuild = never,
+	ImplicitlyConstructable extends boolean = boolean,
+	Info = unknown,
+> =
+	| TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+	| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
+
+/**
+ * Schema which is not a class.
+ * @remarks
+ * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.
+ * @privateRemarks
+ * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.
+ * @sealed @public
+ */
+export interface TreeNodeSchemaNonClass<
+	out Name extends string = string,
+	out Kind extends NodeKind = NodeKind,
+	out TNode = unknown,
+	in TInsertable = never,
+	out ImplicitlyConstructable extends boolean = boolean,
+	out Info = unknown,
+> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
+	create(data: TInsertable): TNode;
+}
+
+/**
+ * Tree node schema which is implemented using a class.
+ * @remarks
+ * Instances of this class are nodes in the tree.
+ * This is also a constructor so that it can be subclassed.
+ *
+ * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.
+ * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer "any" in the d.ts file.
+ *
+ * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:
+ *
+ * - Only ever use a single class from the schema's class hierarchy within a document and its schema.
+ * For example, if using {@link SchemaFactory.object} you can do:
+ * ```typescript
+ * // Recommended "customizable" object schema pattern.
+ * class Good extends schemaFactory.object("A", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	public exampleCustomMethod(): void {
+ * 		this.exampleField++;
+ * 	}
+ * }
+ * ```
+ * But should avoid:
+ * ```typescript
+ * // This by itself is ok, and opts into "POJO mode".
+ * const base = schemaFactory.object("A", {});
+ * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.
+ * // 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", {
+ * 	exampleField: schemaFactory.number,
+ * }) {
+ * 	// This Modifies the type of the constructor input.
+ * 	// This is unsupported due to programmatic access to the constructor being used internally.
+ * 	public constructor(a: number) {
+ * 		super({ exampleField: a });
+ * 	}
+ * }
+ * ```
+ * @sealed @public
+ */
+export interface TreeNodeSchemaClass<
+	out Name extends string = string,
+	out Kind extends NodeKind = NodeKind,
+	out TNode = unknown,
+	in TInsertable = never,
+	out ImplicitlyConstructable extends boolean = boolean,
+	out Info = unknown,
+> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
+	/**
+	 * Constructs an {@link Unhydrated} node with this schema.
+	 * @remarks
+	 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
+	 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
+	 * @sealed
+	 */
+	new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;
+}
+/**
+ * Data common to all tree node schema.
+ * @remarks
+ * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.
+ * @sealed @public
+ */
+
+export interface TreeNodeSchemaCore<
+	out Name extends string,
+	out Kind extends NodeKind,
+	out ImplicitlyConstructable extends boolean,
+	out Info = unknown,
+> {
+	/**
+	 * Unique (within a document's schema) identifier used to associate nodes with their schema.
+	 * @remarks
+	 * This is used when encoding nodes, and when decoding nodes to re-associate them with the schema.
+	 * Since this decoding may happen in a different version of the application (or even a different application altogether),
+	 * this identifier should generally correspond to some specific semantics for the data (how to interpret the node with this identifier).
+	 * Any time the semantics change such that data would be misinterpreted if the old semantics were applied
+	 * (for example the units of a value are changed),
+	 * it is best practice to pick a new identifier.
+	 */
+	readonly identifier: Name;
+	readonly kind: Kind;
+
+	/**
+	 * Data used to define this schema.
+	 *
+	 * @remarks
+	 * The format depends on the kind of node it is for.
+	 * For example, the "object" node kind could store the field schema here.
+	 */
+	readonly info: Info;
+
+	/**
+	 * When constructing insertable content,
+	 * data that could be passed to the node's constructor can be used instead of an {@link Unhydrated} node
+	 * iff implicitlyConstructable is true.
+	 * @privateRemarks
+	 * Currently the logic for traversing insertable content,
+	 * both to build trees and to hydrate them does not defer to the schema classes to handle the policy,
+	 * so if their constructors differ from what is supported, some cases will not work.
+	 * Setting this to false adjusts the insertable types to disallow cases which could be impacted by these inconsistencies.
+	 */
+	readonly implicitlyConstructable: ImplicitlyConstructable;
+}
+
+/**
+ * Kind of tree node.
+ * @remarks
+ * More kinds may be added over time, so do not assume this is an exhaustive set.
+ * @public
+ */
+export enum NodeKind {
+	/**
+	 * A node which serves as a map, storing children under string keys.
+	 */
+	Map,
+	/**
+	 * A node which serves as an array, storing children in an ordered sequence.
+	 */
+	Array,
+	/**
+	 * A node which stores a heterogenous collection of children in named fields.
+	 * @remarks
+	 * Each field gets its own schema.
+	 */
+	Object,
+	/**
+	 * A node which stores a single leaf value.
+	 */
+	Leaf,
+}

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

@@ -0,0 +1,281 @@
+/*!
+ * 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 type { ErasedType } from "@fluidframework/core-interfaces";
+
+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";
+import { isFlexTreeNode, type FlexTreeNode } from "../../feature-libraries/index.js";
+
+/**
+ * Type alias to document which values are un-hydrated.
+ *
+ * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.
+ *
+ * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.
+ * This no-op wrapper is used instead.
+ * @public
+ */
+export type Unhydrated<T> = T;
+
+/**
+ * Data included for {@link TreeChangeEvents.nodeChanged}.
+ * @public
+ */
+export interface NodeChangedData {
+	/**
+	 * When the node changed is an object or Map node, this lists all the properties which changed.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 */
+	readonly changedProperties?: ReadonlySet<string>;
+}
+
+/**
+ * A collection of events that can be emitted by a {@link TreeNode}.
+ *
+ * @remarks
+ * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.
+ * This is considered a known issue, and should be fixed in future versions.
+ * Do not rely on the fact that editing unhydrated nodes does not trigger their events.
+ *
+ * @privateRemarks
+ * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
+ * Probably have object node and map node specific APIs for this.
+ *
+ * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
+ *
+ * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
+ * Some ideas:
+ *
+ * - treeChanged, but with some subtrees/fields/paths excluded
+ * - helper to batch several nodeChanged calls to a treeChanged scope
+ * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
+ * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
+ * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
+ * to allow efficiently searching for new content (and initial content) of a given type.
+ *
+ * @sealed @public
+ */
+export interface TreeChangeEvents<TNode = TreeNode> {
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
+	 *
+	 * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).
+	 *
+	 * - Array node define a change as when an element is added, removed, moved or replaced.
+	 *
+	 * - Map nodes define a change as when an entry is added, updated, or removed.
+	 *
+	 * @remarks
+	 * This event is not emitted when:
+	 *
+	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
+	 * array/map node as one of its properties.
+	 *
+	 * - The node is moved to a different location in the tree or removed from the tree.
+	 * In this case the event is emitted on the _parent_ node, not the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When the event is emitted, the tree is guaranteed to be in-schema.
+	 *
+	 * @privateRemarks
+	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+	 * node, or when the node has to be updated due to resolution of a merge conflict
+	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+	 *
+	 * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).
+	 */
+	nodeChanged(
+		data: NodeChangedData &
+			// For object and Map nodes, make properties specific to them required instead of optional:
+			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>
+				? Required<Pick<NodeChangedData, "changedProperties">>
+				: unknown),
+	): void;
+
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
+	 * subtree rooted at it.
+	 *
+	 * @remarks
+	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
+	 * In that case it is emitted on the _parent_ node, not the node itself.
+	 *
+	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
+	 * of the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 */
+	treeChanged(): void;
+}
+
+export type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;
+
+/**
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
+ *
+ * @remarks
+ * Base type which all nodes implement.
+ *
+ * This 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.
+ *
+ * Instances of tree nodes must be created by opening an existing document, inserting values into the document,
+ * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.
+ * @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;
+}
+
+/**
+ * A node type internal to `@fluidframework/tree`.
+ * @remarks
+ * This type is used in the construction of {@link TreeNode} as an implementation detail, but leaks into the public API due to how schema are implemented.
+ * @privateRemarks
+ * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.
+ * @sealed @public
+ */
+export interface InternalTreeNode
+	extends ErasedType<"@fluidframework/tree.InternalTreeNode"> {}
+
+export function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {
+	assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
+	return node;
+}