@fluidframework/tree 2.10.0-306579 → 2.10.0-307399

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

@@ -73,8 +73,8 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 /**
  * Converts an enum into a collection of schema which can be used in a union.
  * @remarks
- * Currently only supports `string` enums.
  * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
+ * Numeric enums values have the value implicitly converted into a string.
  * Consider making a dedicated schema factory with a nested scope to avoid the enum members colliding with other schema.
  * @example
  * ```typescript
@@ -87,7 +87,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * // Define the schema for each member of the enum using a nested scope to group them together.
  * const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
  * // Defined the types of the nodes which correspond to this the schema.
- * type ModeNodes = NodeFromSchema<(typeof ModeNodes.schema)[number]>;
+ * type ModeNodes = TreeNodeFromImplicitAllowedTypes<(typeof ModeNodes.schema)>;
  * // An example schema which has an enum as a child.
  * class Parent extends schemaFactory.object("Parent", {
  * 	// adaptEnum's return value has a ".schema" property can be use as an `AllowedTypes` array allowing any of the members of the enum.
@@ -106,8 +106,6 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * }
  * ```
  * @privateRemarks
- * TODO:
- * Extend this to support numeric enums.
  * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
  * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
  * @alpha
@@ -139,9 +137,12 @@ export function adaptEnum<
 
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Values>(value: TValue) => {
-		return new out[inverse.get(value) ?? fail("missing enum value")]() as NodeFromSchema<
-			ReturnType<typeof singletonSchema<TScope, TValue>>
-		>;
+		return new out[
+			inverse.get(value) ?? fail("missing enum value")
+			// "extends unknown" is required here to handle when TValue is an union: each member of the union should be processed independently.
+		]() as TValue extends unknown
+			? NodeFromSchema<ReturnType<typeof singletonSchema<TScope, TValue>>>
+			: never;
 	};
 	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
 	for (const [key, value] of Object.entries(members)) {
@@ -176,7 +177,7 @@ export function adaptEnum<
  * ```typescript
  * const schemaFactory = new SchemaFactory("com.myApp");
  * const Mode = enumFromStrings(schemaFactory, ["Fun", "Cool"]);
- * type Mode = NodeFromSchema<(typeof Mode.schema)[number]>;
+ * type Mode = TreeNodeFromImplicitAllowedTypes<typeof Mode.schema>;
  * const nodeFromString: Mode = Mode("Fun");
  * const nodeFromSchema: Mode = new Mode.Fun();
  *
@@ -198,21 +199,32 @@ export function enumFromStrings<
 		throw new UsageError("All members of enums must have distinct names");
 	}
 
-	type TOut = Record<
-		Members[number],
-		ReturnType<typeof singletonSchema<TScope, Members[number]>>
-	>;
-	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	const factoryOut = <TValue extends Members[number]>(value: TValue) => {
-		return new out[value]() as NodeFromSchema<
-			ReturnType<typeof singletonSchema<TScope, TValue>>
+	type MembersUnion = Members[number];
+
+	// Get all keys of the Members tuple which are numeric strings as union of numbers:
+	type Indexes = Extract<keyof Members, `${number}`> extends `${infer N extends number}`
+		? N
+		: never;
+
+	type TOut = {
+		[Index in Indexes as Members[Index]]: ReturnType<
+			typeof singletonSchema<TScope, Members[Index] & string>
 		>;
 	};
 
-	type SchemaArray = UnionToTuple<TOut[Members[number]]>;
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	const factoryOut = <TValue extends MembersUnion>(value: TValue) => {
+		// "extends unknown" is required here to handle when TValue is an union: each member of the union should be processed independently.
+		return new recordOut[value]() as TValue extends unknown
+			? NodeFromSchema<ReturnType<typeof singletonSchema<TScope, TValue>>>
+			: never;
+	};
+
+	type SchemaArray = UnionToTuple<MembersUnion extends unknown ? TOut[MembersUnion] : never>;
 	const schemaArray: TreeNodeSchema[] = [];
 
 	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
+	const recordOut = out as Record<MembersUnion, new () => unknown>;
 	for (const name of members) {
 		const schema = singletonSchema(factory, name);
 		schemaArray.push(schema);

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

@@ -804,6 +804,8 @@ export class SchemaFactory<
 			name,
 			allowedTypes as T & ImplicitAllowedTypes,
 			true,
+			// Setting this (implicitlyConstructable) to true seems to work ok currently, but not for other node kinds.
+			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
 			false,
 		);
 
@@ -811,24 +813,29 @@ export class SchemaFactory<
 			ScopedSchemaName<TScope, Name>,
 			NodeKind.Map,
 			TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
-			{
-				/**
-				 * Iterator for the iterable of content for this node.
-				 * @privateRemarks
-				 * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)
-				 * the following compile error when declaring the recursive schema:
-				 * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`
-				 * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.
-				 *
-				 * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.
-				 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
-				 */
-				[Symbol.iterator](): Iterator<
-					[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
-				>;
-			},
-			// Ideally this would be included, but doing so breaks recursive types.
-			// | RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+			| {
+					/**
+					 * Iterator for the iterable of content for this node.
+					 * @privateRemarks
+					 * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)
+					 * the following compile error when declaring the recursive schema:
+					 * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`
+					 * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.
+					 *
+					 * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.
+					 * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.
+					 */
+					[Symbol.iterator](): Iterator<
+						[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
+					>;
+			  }
+			// Ideally this would be
+			// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+			// but doing so breaks recursive types.
+			// Instead we do a less nice version:
+			| {
+					readonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
+			  },
 			false,
 			T,
 			undefined

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

@@ -140,7 +140,7 @@ export type ValidateRecursiveSchema<
 				? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
 				: unknown;
 		}[T["kind"]],
-		// ImplicitlyConstructable: recursive types are not implicitly constructable.
+		// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
 		false,
 		// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
 		{

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

@@ -17,7 +17,6 @@ import {
 	assertFlexTreeEntityNotFreed,
 	ContextSlot,
 	flexTreeSlot,
-	isFlexTreeNode,
 	isFreedSymbol,
 	LazyEntity,
 	TreeStatus,
@@ -71,10 +70,15 @@ export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema
 }
 
 /** The {@link HydrationState} of a {@link TreeNodeKernel} before the kernel is hydrated */
-type UnhydratedState = Off;
+interface UnhydratedState {
+	off: Off;
+	innerNode: UnhydratedFlexTreeNode;
+}
 
 /** The {@link HydrationState} of a {@link TreeNodeKernel} after the kernel is hydrated */
 interface HydratedState {
+	/** The flex node for this kernel (lazy - undefined if it has not yet been demanded) */
+	innerNode?: FlexTreeNode;
 	/** The {@link AnchorNode} that this node is associated with. */
 	anchorNode: AnchorNode;
 	/** All {@link Off | event deregistration functions} that should be run when the kernel is disposed. */
@@ -86,14 +90,13 @@ type HydrationState = UnhydratedState | HydratedState;
 
 /** True if and only if the given {@link HydrationState} is post-hydration */
 function isHydrated(state: HydrationState): state is HydratedState {
-	return typeof state === "object";
+	return (state as Partial<HydratedState>).anchorNode !== undefined;
 }
 
 /**
  * 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 {
 	private disposed = false;
@@ -110,7 +113,7 @@ export class TreeNodeKernel {
 	 */
 	public generationNumber: number = 0;
 
-	#hydrationState: HydrationState = () => {};
+	#hydrationState: HydrationState;
 
 	/**
 	 * Events registered before hydration.
@@ -133,7 +136,7 @@ export class TreeNodeKernel {
 	public constructor(
 		public readonly node: TreeNode,
 		public readonly schema: TreeNodeSchema,
-		private innerNode: InnerNode,
+		innerNode: InnerNode,
 		private readonly initialContext: Context,
 	) {
 		assert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
@@ -144,9 +147,9 @@ export class TreeNodeKernel {
 			mapTreeNodeToProxy.set(innerNode, node);
 			// Register for change events from the unhydrated flex node.
 			// These will be fired if the unhydrated node is edited, and will also be forwarded later to the hydrated node.
-			this.#hydrationState = innerNode.events.on(
-				"childrenChangedAfterBatch",
-				({ changedFields }) => {
+			this.#hydrationState = {
+				innerNode,
+				off: innerNode.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 					this.#unhydratedEvents.value.emit("childrenChangedAfterBatch", {
 						changedFields,
 					});
@@ -161,15 +164,16 @@ export class TreeNodeKernel {
 						// This cast is safe because the parent (if it exists) of an unhydrated flex node is always another unhydrated flex node.
 						n = n.parentField.parent.parent as UnhydratedFlexTreeNode | undefined;
 					}
-				},
-			);
+				}),
+			};
 		} else {
 			// Hydrated case
+			const { anchorNode } = innerNode;
 			assert(
-				!innerNode.anchorNode.slots.has(proxySlot),
+				!anchorNode.slots.has(proxySlot),
 				0x7f5 /* Cannot associate an flex node with multiple simple-tree nodes */,
 			);
-			this.hydrate(innerNode.anchorNode);
+			this.#hydrationState = this.createHydratedState(anchorNode);
 		}
 	}
 
@@ -191,27 +195,11 @@ export class TreeNodeKernel {
 	 * Happens at most once for any given node.
 	 * Cleans up mappings to {@link UnhydratedFlexTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.
 	 */
-	public hydrate(anchorNode: AnchorNode): void {
+	private hydrate(anchorNode: AnchorNode): void {
 		assert(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);
 		assert(!isHydrated(this.#hydrationState), 0xa2b /* hydration should only happen once */);
-
-		// If the this node is raw and thus has a MapTreeNode, forget it:
-		if (this.innerNode instanceof UnhydratedFlexTreeNode) {
-			mapTreeNodeToProxy.delete(this.innerNode);
-		}
-
-		// 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, this.node);
-		this.#hydrationState = {
-			anchorNode,
-			offAnchorNode: new Set([
-				anchorNode.events.on("afterDestroy", () => this.dispose()),
-				// TODO: this should be triggered on change even for unhydrated nodes.
-				anchorNode.events.on("childrenChanging", () => {
-					this.generationNumber += 1;
-				}),
-			]),
-		};
+		mapTreeNodeToProxy.delete(this.#hydrationState.innerNode);
+		this.#hydrationState = this.createHydratedState(anchorNode);
 
 		// If needed, register forwarding emitters for events from before hydration
 		if (this.#unhydratedEvents.evaluated) {
@@ -228,6 +216,20 @@ export class TreeNodeKernel {
 		}
 	}
 
+	private createHydratedState(anchorNode: AnchorNode): HydratedState {
+		anchorNode.slots.set(proxySlot, this.node);
+		return {
+			anchorNode,
+			offAnchorNode: new Set([
+				anchorNode.events.on("afterDestroy", () => this.dispose()),
+				// TODO: this should be triggered on change even for unhydrated nodes.
+				anchorNode.events.on("childrenChanging", () => {
+					this.generationNumber += 1;
+				}),
+			]),
+		};
+	}
+
 	public getStatus(): TreeStatus {
 		if (this.disposed) {
 			return TreeStatus.Deleted;
@@ -282,13 +284,12 @@ export class TreeNodeKernel {
 	 * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
 	 */
 	public getOrCreateInnerNode(allowFreed = false): InnerNode {
-		if (!(this.innerNode instanceof UnhydratedFlexTreeNode)) {
-			// Cooked case
-			return this.innerNode;
+		if (!isHydrated(this.#hydrationState)) {
+			return this.#hydrationState.innerNode; // Unhydrated case
 		}
 
-		if (!isHydrated(this.#hydrationState)) {
-			return this.innerNode;
+		if (this.#hydrationState.innerNode !== undefined) {
+			return this.#hydrationState.innerNode; // Cooked case
 		}
 
 		// Marinated case -> cooked
@@ -296,21 +297,23 @@ export class TreeNodeKernel {
 		// 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);
 		if (flexNode !== undefined) {
-			this.innerNode = flexNode;
-			return flexNode; // If it does have a flex node, return it...
-		} // ...otherwise, the flex node must be created
-		const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
-		const cursor = context.checkout.forest.allocateCursor("getFlexNode");
-		context.checkout.forest.moveCursorToPath(anchorNode, cursor);
-		const newFlexNode = makeTree(context, cursor);
-		cursor.free();
-		this.innerNode = newFlexNode;
-		// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
-		anchorForgetters?.get(this.node)?.();
-		if (!allowFreed) {
-			assertFlexTreeEntityNotFreed(newFlexNode);
+			// If the flex node already exists, use it...
+			this.#hydrationState.innerNode = flexNode;
+		} else {
+			// ...otherwise, the flex node must be created
+			const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+			const cursor = context.checkout.forest.allocateCursor("getFlexNode");
+			context.checkout.forest.moveCursorToPath(anchorNode, cursor);
+			this.#hydrationState.innerNode = 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(this.node)?.();
+			if (!allowFreed) {
+				assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
+			}
 		}
-		return newFlexNode;
+
+		return this.#hydrationState.innerNode;
 	}
 
 	/**
@@ -344,24 +347,19 @@ export class TreeNodeKernel {
 	/**
 	 * 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 an unhydrated node, returns its UnhydratedFlexTreeNode.
 	 * 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.
+	 * If the target is a marinated node with no FlexTreeNode for its anchor, returns undefined.
 	 */
 	public tryGetInnerNode(): InnerNode | undefined {
-		if (isFlexTreeNode(this.innerNode)) {
-			// Cooked case
-			return this.innerNode;
-		}
-
-		if (!isHydrated(this.#hydrationState)) {
-			return this.innerNode;
+		if (isHydrated(this.#hydrationState)) {
+			return (
+				this.#hydrationState.innerNode ??
+				this.#hydrationState.anchorNode.slots.get(flexTreeSlot)
+			);
 		}
 
-		// Marinated case -> cooked
-		const anchorNode = this.#hydrationState.anchorNode;
-		// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
-		return anchorNode.slots.get(flexTreeSlot);
+		return this.#hydrationState.innerNode;
 	}
 }
 

package/src/simple-tree/objectNode.ts

@@ -47,7 +47,7 @@ import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
 
 /**
- * Helper used to produce types for object nodes.
+ * Generates the properties for an ObjectNode from its field schema object.
  * @system @public
  */
 export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> = {

package/src/simple-tree/objectNodeTypes.ts

@@ -58,7 +58,9 @@ export interface ObjectNodeSchemaInternalData {
 }
 
 export const ObjectNodeSchema = {
-	// instanceof-based narrowing support for Javascript and TypeScript 5.3 or newer.
+	/**
+	 * instanceof-based narrowing support for ObjectNodeSchema in Javascript and TypeScript 5.3 or newer.
+	 */
 	[Symbol.hasInstance](value: TreeNodeSchema): value is ObjectNodeSchema {
 		return isObjectNodeSchema(value);
 	},