@fluidframework/tree 2.1.1 → 2.2.1

package/src/simple-tree/proxyBinding.ts

@@ -22,48 +22,75 @@ import {
 	isMapTreeNode,
 } from "../feature-libraries/index.js";
 import { fail } from "../util/index.js";
-import type { WithType } from "./schemaTypes.js";
+import type { WithType, TreeNode } from "./core/index.js";
 import type { TreeArrayNode } from "./arrayNode.js";
-import type { TreeNode } from "./types.js";
 // TODO: decide how to deal with dependencies on flex-tree implementation.
 // eslint-disable-next-line import/no-internal-modules
 import { makeTree } from "../feature-libraries/flex-tree/lazyNode.js";
 import type { TreeMapNode } from "./mapNode.js";
-import { TreeNodeKernel } from "./treeNodeKernel.js";
+import { getKernel } from "./core/index.js";
 
-// This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).
+// This file contains various maps and helpers for supporting associating simple TreeNodes with their InnerNodes, and swapping those InnerNodes as part of hydration.
 // See ./ProxyBinding.md for a high-level overview of the process.
 
 /**
- * An anchor slot which associates an anchor with its corresponding node proxy, if there is one.
+ * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.
+ * @remarks
+ * For this to work, we have to require that there is at most a single view using a given AnchorSet.
+ * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.
  */
 const proxySlot = anchorSlot<TreeNode>();
 
-// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the node proxy itself.
+// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the TreeNode.
 // The map behaves essentially the same, except that performing a lookup in the map will not perform a property read/get on the key object (as is the case with a symbol).
 // Since `SharedTreeNodes` are proxies with non-trivial `get` traps, this choice is meant to prevent the confusion of the lookup passing through multiple objects
 // via the trap, or the trap not properly handling the special symbol, etc.
 
-/** A reverse mapping of {@link proxySlot} that is updated at the same time. */
+/**
+ * A reverse mapping of {@link proxySlot} that is updated at the same time.
+ *
+ * @remarks
+ * Nodes in this map are hydrated (and thus "marinated" or "cooked").
+ * Nodes not in this map are known to be {@link Unhydrated}.
+ * Thus this map can be used to check if a node is hydrated.
+ *
+ * Any node not in this map must be in {@link proxyToMapTreeNode} since it contains all unhydrated nodes.
+ * It also contains "marinated" nodes which are in both.
+ */
 const proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();
 
-// Map unhydrated nodes to and from their underlying flex tree implementation.
-// These maps are populated after a user calls `const proxy = new Foo({})` but before `proxy` is inserted into the tree and queried.
+/**
+ * Map {@link Unhydrated} nodes and "marinated" nodes to and from their underlying MapTreeNode.
+ * These maps are populated by the TreeNode's constructor when called by a user before the node is inserted into the tree and queried.
+ */
 const proxyToMapTreeNode = new WeakMap<TreeNode, MapTreeNode>();
+
+/**
+ * {@inheritdoc proxyToMapTreeNode}
+ */
 const mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();
-/** Used by `anchorProxy` as an optimization to ensure that only one anchor is remembered at a time for a given anchor node */
+
+/**
+ * Used by {@link anchorProxy} as an optimization to ensure that only one anchor is remembered at a time for a given anchor node
+ */
 const anchorForgetters = new WeakMap<TreeNode, () => void>();
 
 /**
  * Creates an anchor node and associates it with the given proxy.
- * @privateRemarks Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.
+ * @privateRemarks
+ * Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.
  * In practice, this happens when either the anchor node is destroyed, or another anchor to the same node is created by a new flex node.
+ *
+ * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,
+ * so this would be unnecessary except for the case of "marinated" nodes, which have an anchor,
+ * but might not have a FlexTreeNode.
+ * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.
  */
 export function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode {
 	assert(!anchorForgetters.has(proxy), 0x91c /* Proxy anchor should not be set twice */);
 	const anchor = anchors.track(path);
 	const anchorNode = anchors.locate(anchor) ?? fail("Expected anchor node to be present");
-	bindProxyToAnchorNode(proxy, anchorNode);
+	bindHydratedNodeToAnchor(proxy, anchorNode);
 	const forget = (): void => {
 		if (anchors.locate(anchor)) {
 			anchors.forget(anchor);
@@ -77,21 +104,26 @@ export function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode):
 }
 
 /**
- * Retrieves the flex node associated with the given target via {@link setFlexNode}.
- * @remarks Fails if the flex node has not been set.
+ * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+ * @remarks
+ * For {@link Unhydrated} nodes, this returns the MapTreeNode.
+ *
+ * For hydrated nodes it returns a FlexTreeNode backed by the forest.
+ * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
  */
-export function getFlexNode(
-	proxy: TypedNode<FlexObjectNodeSchema>,
+export function getOrCreateInnerNode(
+	treeNode: TypedNode<FlexObjectNodeSchema>,
 	allowFreed?: true,
-): FlexTreeObjectNode;
-export function getFlexNode(proxy: TreeArrayNode, allowFreed?: true): FlexTreeNode;
-export function getFlexNode(
-	proxy: TreeMapNode,
+): InnerNode & FlexTreeObjectNode;
+export function getOrCreateInnerNode(treeNode: TreeArrayNode, allowFreed?: true): InnerNode;
+export function getOrCreateInnerNode(
+	treeNode: TreeMapNode,
 	allowFreed?: true,
-): FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;
-export function getFlexNode(proxy: TreeNode, allowFreed?: true): FlexTreeNode;
-export function getFlexNode(proxy: TreeNode, allowFreed = false): FlexTreeNode {
-	const anchorNode = proxyToAnchorNode.get(proxy);
+): InnerNode &
+	FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;
+export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed?: true): InnerNode;
+export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): InnerNode {
+	const anchorNode = proxyToAnchorNode.get(treeNode);
 	if (anchorNode !== undefined) {
 		// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
 		const flexNode = anchorNode.slots.get(flexTreeSlot);
@@ -104,89 +136,125 @@ export function getFlexNode(proxy: TreeNode, allowFreed = false): FlexTreeNode {
 		const newFlexNode = makeTree(context, cursor);
 		cursor.free();
 		// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
-		anchorForgetters?.get(proxy)?.();
+		anchorForgetters?.get(treeNode)?.();
 		if (!allowFreed) {
 			assertFlexTreeEntityNotFreed(newFlexNode);
 		}
 		return newFlexNode;
 	}
 
-	return proxyToMapTreeNode.get(proxy) ?? fail("Expected raw tree node for proxy");
+	// Unhydrated case
+	return proxyToMapTreeNode.get(treeNode) ?? fail("Expected raw tree node for proxy");
 }
 
 /**
- * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.
+ * For "cooked" nodes this is a FlexTreeNode thats a projection of forest content.
+ * For {@link Unhydrated} nodes this is a MapTreeNode.
+ * For "marinated" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.
+ *
+ * @remarks
+ * Currently MapTreeNode extends FlexTreeNode, and most code which can work with either just uses FlexTreeNode.
+ * TODO: Code should be migrating toward using this type to distinguish to two use-cases.
+ *
+ * TODO: The inconsistent handling of "marinated" cases should be cleaned up.
+ * Maybe getOrCreateInnerNode should cook marinated nodes so they have a proper InnerNode?
+ */
+export type InnerNode = FlexTreeNode | MapTreeNode;
+
+/**
+ * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.
+ * @remarks
+ * If `target` is a unhydrated node, returns its MapTreeNode.
+ * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.
+ * If the target is not a node, or a marinated node with no FlexTreeNode for its anchor, returns undefined.
  */
-export function tryGetFlexNode(target: unknown): FlexTreeNode | undefined {
+export function tryGetInnerNode(target: unknown): InnerNode | undefined {
 	// Calling 'WeakMap.get()' with primitives (numbers, strings, etc.) will return undefined.
 	// This is in contrast to 'WeakMap.set()', which will throw a TypeError if given a non-object key.
-	return (
-		proxyToAnchorNode.get(target as TreeNode)?.slots.get(flexTreeSlot) ??
-		proxyToMapTreeNode.get(target as TreeNode)
-	);
+	const anchorNode = proxyToAnchorNode.get(target as TreeNode);
+	// Hydrated node case
+	if (anchorNode !== undefined) {
+		const flex = anchorNode.slots.get(flexTreeSlot);
+		if (flex !== undefined) {
+			// Cooked, or possible Marinated but something else cased the flex tree node to exist.
+			return flex;
+		}
+		// Marinated case
+		assert(
+			proxyToMapTreeNode.get(target as TreeNode) === undefined,
+			0xa05 /* marinated nodes should not have MapTreeNodes */,
+		);
+		return undefined;
+	}
+	// Unhydrated node or not a node case:
+	return proxyToMapTreeNode.get(target as TreeNode);
 }
 
 /**
- * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.
+ * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.
  */
-export function tryGetProxy(flexNode: FlexTreeNode): TreeNode | undefined {
+export function tryGetCachedTreeNode(flexNode: InnerNode): TreeNode | undefined {
 	if (isMapTreeNode(flexNode)) {
+		// Unhydrated case
 		return mapTreeNodeToProxy.get(flexNode);
 	}
+	// Hydrated case
 	return flexNode.anchorNode.slots.get(proxySlot);
 }
 
 /**
- * Associate the given proxy and the given flex node.
- * @returns The proxy
+ * Associate the given TreeNode and the given flex node.
+ * @returns The node.
  * @remarks
- * This creates a 1:1 mapping between the proxy and tree node.
- * Either can be retrieved from the other via {@link getFlexNode}/{@link tryGetFlexNode} or {@link tryGetProxy}.
+ * This creates a 1:1 mapping between the tree node and InnerNode.
+ * Either can be retrieved from the other via {@link getOrCreateInnerNode}/{@link tryGetInnerNode} or {@link tryGetCachedTreeNode}.
  * If the given proxy is already mapped to an flex node, the existing mapping will be overwritten.
  * If the given flex node is already mapped to a different proxy, this function will fail.
  */
-export function setFlexNode<TProxy extends TreeNode>(
-	proxy: TProxy,
-	flexNode: FlexTreeNode,
-): TProxy {
-	const existingFlexNode = proxyToAnchorNode.get(proxy)?.slots.get(flexTreeSlot);
+export function setInnerNode<TNode extends TreeNode>(
+	node: TNode,
+	innerNode: InnerNode,
+): TNode {
+	const existingFlexNode = proxyToAnchorNode.get(node)?.slots.get(flexTreeSlot);
 	assert(
 		existingFlexNode === undefined,
 		0x91d /* Cannot associate a flex node with multiple targets */,
 	);
-	if (isMapTreeNode(flexNode)) {
-		proxyToMapTreeNode.set(proxy, flexNode);
-		mapTreeNodeToProxy.set(flexNode, proxy);
+	if (isMapTreeNode(innerNode)) {
+		// Unhydrated case
+		proxyToMapTreeNode.set(node, innerNode);
+		mapTreeNodeToProxy.set(innerNode, node);
 	} else {
+		// Hydrated case
 		assert(
-			tryGetProxy(flexNode) === undefined,
+			tryGetCachedTreeNode(innerNode) === undefined,
 			0x7f5 /* Cannot associate an flex node with multiple targets */,
 		);
-		bindProxyToAnchorNode(proxy, flexNode.anchorNode);
+		bindHydratedNodeToAnchor(node, innerNode.anchorNode);
 	}
-	return proxy;
+	return node;
 }
 
 /**
- * Bi-directionally associates the given proxy to the given anchor node.
- * @remarks Cleans up mappings to raw flex nodes - it is assumed that they are no longer needed once the proxy has an anchor node.
+ * Bi-directionally associates the given hydrated TreeNode to the given anchor node.
+ * @remarks Cleans up mappings to {@link MapTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.
  */
-function bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {
+function bindHydratedNodeToAnchor(node: TreeNode, anchorNode: AnchorNode): void {
 	// If the proxy currently has a raw node, forget it
-	const mapTreeNode = proxyToMapTreeNode.get(proxy);
+	const mapTreeNode = proxyToMapTreeNode.get(node);
 	if (mapTreeNode !== undefined) {
-		proxyToMapTreeNode.delete(proxy);
+		proxyToMapTreeNode.delete(node);
 		mapTreeNodeToProxy.delete(mapTreeNode);
 	}
 	// Once a proxy has been associated with an anchor node, it should never change to another anchor node
 	assert(
-		!proxyToAnchorNode.has(proxy),
+		!proxyToAnchorNode.has(node),
 		0x91e /* Proxy has already been bound to a different anchor node */,
 	);
-	proxyToAnchorNode.set(proxy, anchorNode);
+	proxyToAnchorNode.set(node, anchorNode);
 	// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.
-	anchorNode.slots.set(proxySlot, proxy);
-	getKernel(proxy).hydrate(anchorNode);
+	anchorNode.slots.set(proxySlot, node);
+	getKernel(node).hydrate(anchorNode);
 }
 
 /**
@@ -194,23 +262,10 @@ function bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {
  */
 type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;
 
-export function createKernel(node: TreeNode): void {
-	treeNodeToKernel.set(node, new TreeNodeKernel(node));
-}
-
-export function getKernel(node: TreeNode): TreeNodeKernel {
-	const kernel = treeNodeToKernel.get(node);
-	assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
-	return kernel;
-}
-
 export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
 	const treeNode = anchorNode.slots.get(proxySlot);
 	if (treeNode !== undefined) {
-		const kernel = treeNodeToKernel.get(treeNode);
-		assert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);
+		const kernel = getKernel(treeNode);
 		kernel.dispose();
 	}
 }
-
-const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();

package/src/simple-tree/schemaTypes.ts

@@ -14,149 +14,29 @@ import {
 	type FlexListToUnion,
 } from "../feature-libraries/index.js";
 import { type MakeNominal, brand, isReadonlyArray } from "../util/index.js";
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type {
+	Unhydrated,
+	NodeKind,
+	TreeNodeSchema,
+	TreeNodeSchemaClass,
+} from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./proxies.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
+ * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
  */
-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,
-> {
-	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;
+export function isTreeNodeSchemaClass<
+	Name extends string,
+	Kind extends NodeKind,
+	TNode,
+	TBuild,
+	ImplicitlyConstructable extends boolean,
+	Info,
+>(
+	schema: TreeNodeSchema<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>,
+): schema is TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info> {
+	return schema.constructor !== undefined;
 }
 
 /**
@@ -195,33 +75,6 @@ export enum FieldKind {
 	Identifier,
 }
 
-/**
- * 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,
-}
-
 /**
  * Maps from a view key to its corresponding {@link FieldProps.key | stored key} for the provided
  * {@link ImplicitFieldSchema | field schema}.
@@ -387,7 +240,7 @@ export class FieldSchema<
 	 * This class is used with instanceof, and therefore should have nominal typing.
 	 * This field enforces that.
 	 */
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck!: MakeNominal;
 
 	private readonly lazyTypes: Lazy<ReadonlySet<TreeNodeSchema>>;
 
@@ -399,6 +252,11 @@ export class FieldSchema<
 		return this.lazyTypes.value;
 	}
 
+	/**
+	 * True if and only if, when constructing a node with this field, a value must be provided for it.
+	 */
+	public readonly requiresValue: boolean;
+
 	private constructor(
 		/**
 		 * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
@@ -415,6 +273,9 @@ export class FieldSchema<
 		public readonly props?: FieldProps,
 	) {
 		this.lazyTypes = new Lazy(() => normalizeAllowedTypes(this.allowedTypes));
+		// TODO: optional fields should (by default) get a default provider that returns undefined, removing the need to special case them here:
+		this.requiresValue =
+			this.props?.defaultProvider === undefined && this.kind !== FieldKind.Optional;
 	}
 }
 
@@ -572,35 +433,9 @@ export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema
 
 /**
  * Value that may be stored as a leaf node.
+ * @remarks
+ * Some limitations apply, see the documentation for {@link SchemaFactory.number} and {@link SchemaFactory.string} for those restrictions.
  * @public
  */
 // eslint-disable-next-line @rushstack/no-new-null
 export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
-
-/**
- * The type of a {@link TreeNode}.
- * For more information about the type, use `Tree.schema(theNode)` instead.
- * @remarks
- * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
- * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
- *
- * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
- * Instead construct a real node of the desired type using its constructor.
- * @privateRemarks
- * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
- * @public
- */
-export const typeNameSymbol: unique symbol = Symbol("TreeNode Type");
-
-/**
- * Adds a type symbol to a type for stronger typing.
- * @remarks
- * An implementation detail of {@link TreeNode}'s strong typing setup: not intended for direct use outside of this package.
- * @sealed @public
- */
-export interface WithType<TName extends string = string> {
-	/**
-	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
-	 */
-	get [typeNameSymbol](): TName;
-}