@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/simple-tree/treeApi.ts

@@ -3,22 +3,33 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
-import { TreeValue } from "../core/index.js";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+
+import { Multiplicity, rootFieldKey } from "../core/index.js";
 import {
-	EditableTreeEvents,
+	FieldKinds,
 	LeafNodeSchema,
-	Multiplicity,
+	StableNodeKey,
 	TreeStatus,
 	isTreeValue,
 	valueSchemaAllows,
 } from "../feature-libraries/index.js";
-import { TreeNode } from "./types.js";
-import { getFlexNode, tryGetFlexNode } from "./flexNode.js";
-import { getClassSchema, getOrCreateNodeProxy } from "./proxies.js";
+import { fail, extractFromOpaque } from "../util/index.js";
+
+import { getOrCreateNodeProxy } from "./proxies.js";
+import { getFlexNode, tryGetFlexNode } from "./proxyBinding.js";
+import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import { schemaFromValue } from "./schemaFactory.js";
-import { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from "./schemaTypes.js";
+import {
+	NodeFromSchema,
+	NodeKind,
+	type TreeLeafValue,
+	TreeNodeSchema,
+	type ImplicitFieldSchema,
+	FieldSchema,
+} from "./schemaTypes.js";
 import { getFlexSchema } from "./toFlexSchema.js";
+import { TreeNode } from "./types.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -36,6 +47,7 @@ export interface TreeNodeApi {
 	schema<T extends TreeNode | TreeLeafValue>(
 		node: T,
 	): TreeNodeSchema<string, NodeKind, unknown, T>;
+
 	/**
 	 * Narrow the type of the given value if it satisfies the given schema.
 	 * @example
@@ -49,10 +61,12 @@ export interface TreeNodeApi {
 		value: unknown,
 		schema: TSchema,
 	): value is NodeFromSchema<TSchema>;
+
 	/**
 	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
+
 	/**
 	 * The key of the given node under its parent.
 	 * @remarks
@@ -60,20 +74,31 @@ export interface TreeNodeApi {
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
 	 */
 	key(node: TreeNode): string | number;
+
 	/**
 	 * Register an event listener on the given node.
+	 * @param node - The node whose events should be subscribed to.
+	 * @param eventName - Which event to subscribe to.
+	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
 	 * @returns A callback function which will deregister the event.
 	 * This callback should be called only once.
 	 */
-	on<K extends keyof TreeNodeEvents>(
+	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
 		eventName: K,
-		listener: TreeNodeEvents[K],
+		listener: TreeChangeEvents[K],
 	): () => void;
+
 	/**
 	 * Returns the {@link TreeStatus} of the given node.
 	 */
 	readonly status: (node: TreeNode) => TreeStatus;
+
+	/**
+	 * If the given node has an identifier specified by a field of kind "identifier" then this returns the compressed form of that identifier.
+	 * Otherwise returns undefined.
+	 */
+	shortId(node: TreeNode): number | undefined;
 }
 
 /**
@@ -94,21 +119,47 @@ export const treeNodeApi: TreeNodeApi = {
 		return output;
 	},
 	key: (node: TreeNode) => {
-		const parentField = getFlexNode(node).parentField;
-		if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
-			// The parent of `node` is an array node
-			return parentField.index;
+		// If the parent is undefined, then this node is under the root field,
+		// so we know its key is the special root one.
+		const parent = treeNodeApi.parent(node);
+		if (parent === undefined) {
+			return rootFieldKey;
 		}
 
-		// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
-		return parentField.parent.key;
+		// The flex-domain strictly operates in terms of "stored keys".
+		// To find the associated developer-facing "view key", we need to look up the field associated with
+		// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.
+		const storedKey = getStoredKey(node);
+		const parentSchema = treeNodeApi.schema(parent);
+		const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
+		return viewKey;
 	},
-	on: <K extends keyof EditableTreeEvents>(
+	on: <K extends keyof TreeChangeEvents>(
 		node: TreeNode,
 		eventName: K,
-		listener: EditableTreeEvents[K],
+		listener: TreeChangeEvents[K],
 	) => {
-		return getFlexNode(node).on(eventName, listener);
+		const flex = getFlexNode(node);
+		const anchor = flex.anchorNode;
+
+		switch (eventName) {
+			case "nodeChanged": {
+				let unsubscribeFromTreeChanged: (() => void) | undefined;
+				return anchor.on("childrenChanged", () => {
+					if (unsubscribeFromTreeChanged === undefined) {
+						unsubscribeFromTreeChanged = anchor.on("subtreeChanged", () => {
+							listener();
+							unsubscribeFromTreeChanged?.();
+							unsubscribeFromTreeChanged = undefined;
+						});
+					}
+				});
+			}
+			case "treeChanged":
+				return anchor.on("subtreeChanged", () => listener());
+			default:
+				return unreachableCase(eventName);
+		}
 	},
 	status: (node: TreeNode) => {
 		return getFlexNode(node, true).treeStatus();
@@ -125,26 +176,160 @@ export const treeNodeApi: TreeNodeApi = {
 		}
 		return tryGetFlexNode(value)?.is(flexSchema) ?? false;
 	},
-	schema<T extends TreeNode | TreeValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T> {
+	schema<T extends TreeNode | TreeLeafValue>(
+		node: T,
+	): TreeNodeSchema<string, NodeKind, unknown, T> {
 		if (isTreeValue(node)) {
 			return schemaFromValue(node) as TreeNodeSchema<string, NodeKind, unknown, T>;
 		}
-		return getClassSchema(getFlexNode(node).schema) as TreeNodeSchema<
+		return tryGetSimpleNodeSchema(getFlexNode(node).schema) as TreeNodeSchema<
 			string,
 			NodeKind,
 			unknown,
 			T
 		>;
 	},
+	shortId(node: TreeNode): number | undefined {
+		const flexNode = getFlexNode(node);
+		for (const field of flexNode.boxedIterator()) {
+			if (field.schema.kind === FieldKinds.identifier) {
+				const identifier = field.boxedAt(0);
+				assert(identifier !== undefined, 0x927 /* The identifier must exist */);
+
+				return extractFromOpaque(
+					identifier.context.nodeKeys.localize(identifier.value as StableNodeKey),
+				);
+			}
+		}
+	},
 };
 
+/**
+ * Gets the stored key with which the provided node is associated in the parent.
+ */
+function getStoredKey(node: TreeNode): string | number {
+	// Note: the flex domain strictly works with "stored keys", and knows nothing about the developer-facing
+	// "view keys".
+	const parentField = getFlexNode(node).parentField;
+	if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
+		// The parent of `node` is an array node
+		return parentField.index;
+	}
+
+	// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
+	return parentField.parent.key;
+}
+
+/**
+ * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.
+ */
+function getViewKeyFromStoredKey(
+	schema: TreeNodeSchema,
+	storedKey: string | number,
+): string | number {
+	// Only object nodes have the concept of a "stored key", differentiated from the developer-facing "view key".
+	// For any other kind of node, the stored key and the view key are the same.
+	if (schema.kind !== NodeKind.Object) {
+		return storedKey;
+	}
+
+	const fields = schema.info as Record<string, ImplicitFieldSchema>;
+
+	// Invariants:
+	// - The set of all view keys under an object must be unique.
+	// - The set of all stored keys (including those implicitly created from view keys) must be unique.
+	// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).
+	// If we don't find any, then search for a matching view key.
+	for (const [viewKey, fieldSchema] of Object.entries(fields)) {
+		if (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {
+			return viewKey;
+		}
+	}
+
+	if (fields[storedKey] === undefined) {
+		fail("Existing stored key should always map to a view key");
+	}
+
+	return storedKey;
+}
+
 /**
  * A collection of events that can be raised by a {@link TreeNode}.
+ *
+ * @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.
+ *
  * @public
  */
-export interface TreeNodeEvents {
+export interface TreeChangeEvents {
 	/**
-	 * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.
+	 * Emitted by a node when a batch of changes is applied to it, where a change is:
+	 *
+	 * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
+	 * to something else, including `undefined`).
+	 *
+	 * - For an array node, when an element is added, removed, or moved.
+	 *
+	 * - For a map node, when an entry is added, updated, or removed.
+	 *
+	 * @remarks
+	 * This event is not raised when:
+	 *
+	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+	 * elements/entries) will raise 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 raised 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.
+	 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+	 * how many times this event will be raised during any intermediate states.
+	 * When it is raised, 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).
+	 */
+	nodeChanged(): void;
+
+	/**
+	 * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.
+	 *
+	 * @remarks
+	 * This event is guaranteed to be emitted whenever the subtree _has_ changed.
+	 * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.
+	 *
+	 * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario
+	 * where the event fires with no visible changes as well.
+	 *
+	 * This event is not raised when the node itself is moved to a different location in the tree or removed from the tree.
+	 * In that case it is raised 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.
+	 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+	 * how many times this event will be raised during any intermediate states.
+	 * When it is raised, the tree is guaranteed to be in-schema.
 	 */
-	afterChange(): void;
+	treeChanged(): void;
 }

package/src/simple-tree/types.ts

@@ -3,13 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
-	FlexFieldNodeSchema,
-	FlexMapNodeSchema,
-	FlexObjectNodeSchema,
-} from "../feature-libraries/index.js";
-import { type, WithType } from "./schemaTypes.js";
-import { IterableTreeArrayContent } from "./treeArrayNode.js";
+import { WithType, type } from "./schemaTypes.js";
 
 /**
  * Type alias to document which values are un-hydrated.
@@ -74,169 +68,3 @@ export abstract class TreeNode implements WithType {
 	 */
 	public abstract get [type](): string;
 }
-
-/**
- * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
- *
- * @privateRemarks
- * Inlining this into TreeArrayNode causes recursive array use to stop compiling.
- *
- * @public
- */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>
-	extends ReadonlyArray<T>,
-		TreeNode {
-	/**
-	 * Inserts new item(s) at a specified location.
-	 * @param index - The index at which to insert `value`.
-	 * @param value - The content to insert.
-	 * @throws Throws if `index` is not in the range [0, `array.length`).
-	 */
-	insertAt(index: number, ...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-
-	/**
-	 * Inserts new item(s) at the start of the array.
-	 * @param value - The content to insert.
-	 */
-	insertAtStart(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-
-	/**
-	 * Inserts new item(s) at the end of the array.
-	 * @param value - The content to insert.
-	 */
-	insertAtEnd(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-
-	/**
-	 * Removes the item at the specified location.
-	 * @param index - The index at which to remove the item.
-	 * @throws Throws if `index` is not in the range [0, `array.length`).
-	 */
-	removeAt(index: number): void;
-
-	/**
-	 * Removes all items between the specified indices.
-	 * @param start - The starting index of the range to remove (inclusive). Defaults to the start of the array.
-	 * @param end - The ending index of the range to remove (exclusive).
-	 * @throws Throws if `start` is not in the range [0, `array.length`).
-	 * @throws Throws if `end` is less than `start`.
-	 * If `end` is not supplied or is greater than the length of the array, all items after `start` are removed.
-	 */
-	removeRange(start?: number, end?: number): void;
-
-	/**
-	 * Moves the specified item to the start of the array.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-	 */
-	moveToStart(sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the start of the array.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source array to move the item out of.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-	 */
-	moveToStart(sourceIndex: number, source: TMoveFrom): void;
-
-	/**
-	 * Moves the specified item to the end of the array.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-	 */
-	moveToEnd(sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the end of the array.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source array to move the item out of.
-	 * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-	 */
-	moveToEnd(sourceIndex: number, source: TMoveFrom): void;
-
-	/**
-	 * Moves the specified item to the desired location in the array.
-	 * @param index - The index to move the item to.
-	 * This is based on the state of the array before moving the source item.
-	 * @param sourceIndex - The index of the item to move.
-	 * @throws Throws if any of the input indices are not in the range [0, `array.length`).
-	 */
-	moveToIndex(index: number, sourceIndex: number): void;
-
-	/**
-	 * Moves the specified item to the desired location in the array.
-	 * @param index - The index to move the item to.
-	 * @param sourceIndex - The index of the item to move.
-	 * @param source - The source array to move the item out of.
-	 * @throws Throws if any of the input indices are not in the range [0, `array.length`).
-	 */
-	moveToIndex(index: number, sourceIndex: number, source: TMoveFrom): void;
-
-	/**
-	 * Moves the specified items to the start of the array.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToStart(sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the start of the array.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source array to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-	 * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToStart(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
-
-	/**
-	 * Moves the specified items to the end of the array.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToEnd(sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the end of the array.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source array to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-	 * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToEnd(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
-
-	/**
-	 * Moves the specified items to the desired location within the array.
-	 * @param index - The index to move the items to.
-	 * This is based on the state of the array before moving the source items.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @throws Throws if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToIndex(index: number, sourceStart: number, sourceEnd: number): void;
-
-	/**
-	 * Moves the specified items to the desired location within the array.
-	 * @param index - The index to move the items to.
-	 * @param sourceStart - The starting index of the range to move (inclusive).
-	 * @param sourceEnd - The ending index of the range to move (exclusive)
-	 * @param source - The source array to move items out of.
-	 * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-	 * if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-	 */
-	moveRangeToIndex(
-		index: number,
-		sourceStart: number,
-		sourceEnd: number,
-		source: TMoveFrom,
-	): void;
-}
-
-/**
- * Given a node's schema, return the corresponding object in the proxy-based API.
- */
-export type TypedNode<
-	TSchema extends FlexObjectNodeSchema | FlexFieldNodeSchema | FlexMapNodeSchema,
-> = TreeNode & WithType<TSchema["name"]>;

package/src/simple-tree/typesUnsafe.ts

@@ -5,19 +5,22 @@
 
 import { FlexListToUnion, Unenforced } from "../feature-libraries/index.js";
 import { RestrictiveReadonlyRecord } from "../util/index.js";
+
 import {
 	AllowedTypes,
 	ApplyKind,
 	FieldKind,
+	type FieldSchema,
 	ImplicitAllowedTypes,
 	ImplicitFieldSchema,
 	NodeFromSchema,
 	NodeKind,
 	TreeNodeFromImplicitAllowedTypes,
 	TreeNodeSchema,
+	WithType,
 } from "./schemaTypes.js";
-import { TreeArrayNode } from "./treeArrayNode.js";
-import { TreeArrayNodeBase, TreeNode, Unhydrated } from "./types.js";
+import { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
+import { TreeNode, Unhydrated } from "./types.js";
 
 /*
  * TODO:
@@ -32,7 +35,7 @@ import { TreeArrayNodeBase, TreeNode, Unhydrated } from "./types.js";
 
 /**
  * {@link Unenforced} version of {@link ObjectFromSchemaRecord}.
- * @beta
+ * @public
  */
 export type ObjectFromSchemaRecordUnsafe<
 	T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,
@@ -40,9 +43,18 @@ export type ObjectFromSchemaRecordUnsafe<
 	-readonly [Property in keyof T]: TreeFieldFromImplicitFieldUnsafe<T[Property]>;
 };
 
+/**
+ * {@link Unenforced} version of {@link TreeObjectNode}.
+ * @public
+ */
+export type TreeObjectNodeUnsafe<
+	T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,
+	TypeName extends string = string,
+> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName>;
+
 /**
  * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.
- * @beta
+ * @public
  */
 export type TreeFieldFromImplicitFieldUnsafe<TSchema extends Unenforced<ImplicitFieldSchema>> =
 	TSchema extends FieldSchemaUnsafe<infer Kind, infer Types>
@@ -53,7 +65,7 @@ export type TreeFieldFromImplicitFieldUnsafe<TSchema extends Unenforced<Implicit
 
 /**
  * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.
- * @beta
+ * @public
  */
 export type TreeNodeFromImplicitAllowedTypesUnsafe<
 	TSchema extends Unenforced<ImplicitAllowedTypes>,
@@ -67,7 +79,7 @@ export type TreeNodeFromImplicitAllowedTypesUnsafe<
 
 /**
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
- * @beta
+ * @public
  */
 export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
 	TSchema extends Unenforced<ImplicitAllowedTypes>,
@@ -77,7 +89,7 @@ export type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<
 
 /**
  * {@link Unenforced} version of {@link InsertableTypedNode}.
- * @beta
+ * @public
  */
 export type InsertableTypedNodeUnsafe<T extends Unenforced<TreeNodeSchema>> =
 	| Unhydrated<NodeFromSchemaUnsafe<T>>
@@ -85,7 +97,7 @@ export type InsertableTypedNodeUnsafe<T extends Unenforced<TreeNodeSchema>> =
 
 /**
  * {@link Unenforced} version of {@link NodeFromSchema}.
- * @beta
+ * @public
  */
 export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> = T extends TreeNodeSchema<
 	string,
@@ -97,7 +109,7 @@ export type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> = T exten
 
 /**
  * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.
- * @beta
+ * @public
  */
 export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> = T extends TreeNodeSchema<
 	string,
@@ -110,19 +122,18 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> = T exte
 
 /**
  * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.
- * @beta
+ * @public
  */
 export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAllowedTypes>>
-	extends TreeNode,
-		TreeArrayNodeBase<
-			TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
-			InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
-			TreeArrayNode
-		> {}
+	extends TreeArrayNodeBase<
+		TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
+		InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
+		TreeArrayNode
+	> {}
 
 /**
  * {@link Unenforced} version of {@link TreeMapNode}.
- * @beta
+ * @public
  */
 export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
 	extends ReadonlyMap<string, TreeNodeFromImplicitAllowedTypesUnsafe<T>>,
@@ -140,7 +151,7 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
 
 /**
  * {@link Unenforced} version of {@link InsertableObjectFromSchemaRecord}.
- * @beta
+ * @public
  */
 export type InsertableObjectFromSchemaRecordUnsafe<
 	T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,
@@ -150,7 +161,7 @@ export type InsertableObjectFromSchemaRecordUnsafe<
 
 /**
  * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.
- * @beta
+ * @public
  */
 export type InsertableTreeFieldFromImplicitFieldUnsafe<
 	TSchema extends Unenforced<ImplicitFieldSchema>,
@@ -160,12 +171,22 @@ export type InsertableTreeFieldFromImplicitFieldUnsafe<
 
 /**
  * {@link Unenforced} version of {@link FieldSchema}.
- * @beta
+ * @public
  */
 export interface FieldSchemaUnsafe<
 	out Kind extends FieldKind,
 	out Types extends Unenforced<ImplicitAllowedTypes>,
-> {
+> extends FieldSchema<Kind, any> {
+	/**
+	 * {@inheritDoc FieldSchema.kind}
+	 */
 	readonly kind: Kind;
+	/**
+	 * {@inheritDoc FieldSchema.allowedTypes}
+	 */
 	readonly allowedTypes: Types;
+	/**
+	 * {@inheritDoc FieldSchema.allowedTypeSet}
+	 */
+	readonly allowedTypeSet: ReadonlySet<TreeNodeSchema>;
 }