@fluidframework/tree 2.10.0-305357 → 2.10.0-306579

package/src/shared-tree-core/sharedTreeCore.ts

@@ -183,16 +183,16 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			rebaseLogger,
 		);
-		this.editManager.localBranch.on("transactionStarted", () => {
+		this.editManager.localBranch.events.on("transactionStarted", () => {
 			this.commitEnricher.startNewTransaction();
 		});
-		this.editManager.localBranch.on("transactionAborted", () => {
+		this.editManager.localBranch.events.on("transactionAborted", () => {
 			this.commitEnricher.abortCurrentTransaction();
 		});
-		this.editManager.localBranch.on("transactionCommitted", () => {
+		this.editManager.localBranch.events.on("transactionCommitted", () => {
 			this.commitEnricher.commitCurrentTransaction();
 		});
-		this.editManager.localBranch.on("beforeChange", (change) => {
+		this.editManager.localBranch.events.on("beforeChange", (change) => {
 			// Ensure that any previously prepared commits that have not been sent are purged.
 			this.commitEnricher.purgePreparedCommits();
 			if (this.detachedRevision !== undefined) {
@@ -219,7 +219,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
 			}
 		});
-		this.editManager.localBranch.on("afterChange", (change) => {
+		this.editManager.localBranch.events.on("afterChange", (change) => {
 			if (this.getLocalBranch().isTransacting()) {
 				// We do not submit ops for changes that are part of a transaction.
 				return;

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

@@ -216,19 +216,45 @@ export class SchemaFactory<
 	private readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();
 
 	/**
-	 * Construct a SchemaFactory with a given scope.
+	 * Construct a SchemaFactory with a given {@link SchemaFactory.scope|scope}.
 	 * @remarks
-	 * There are no restrictions on mixing schema from different schema factories:
-	 * this is encouraged when a single schema references schema from different libraries.
-	 * If each library exporting schema picks its own globally unique scope for its SchemaFactory,
-	 * then all schema an application might depend on, directly or transitively,
-	 * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.
-	 *
-	 * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
-	 * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
-	 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+	 * There are no restrictions on mixing schema from different schema factories.
+	 * Typically each library will create one or more SchemaFactories and use them to define its schema.
 	 */
-	public constructor(public readonly scope: TScope) {}
+	public constructor(
+		/**
+		 * Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
+		 *
+		 * @remarks
+		 * Generally each independently developed library
+		 * (possibly a package, but could also be part of a package or multiple packages developed together)
+		 * should get its own unique `scope`.
+		 * Then each schema in the library get a name which is unique within the library.
+		 * The scope and name are joined (with a period) to form the {@link TreeNodeSchemaCore.identifier|schema identifier}.
+		 * Following this pattern allows a single application to depend on multiple libraries which define their own schema, and use them together in a single tree without risk of collisions.
+		 * If a library logically contains sub-libraries with their own schema, they can be given a scope nested inside the parent scope, such as "ParentScope.ChildScope".
+		 *
+		 * To avoid collisions between the scopes of libraries
+		 * it is recommended that the libraries use {@link https://en.wikipedia.org/wiki/Reverse_domain_name_notation | Reverse domain name notation} or a UUIDv4 for their scope.
+		 * If this pattern is followed, application can safely use third party libraries without risk of the schema in them colliding.
+		 *
+		 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+		 *
+		 * @example
+		 * Fluid Framework follows this pattern, placing the schema for the built in leaf types in the `com.fluidframework.leaf` scope.
+		 * If Fluid Framework publishes more schema in the future, they would be under some other `com.fluidframework` scope.
+		 * This ensures that any schema defined by any other library will not conflict with Fluid Framework's schema
+		 * as long as the library uses the recommended patterns for how to scope its schema..
+		 *
+		 * @example
+		 * A library could generate a random UUIDv4, like `242c4397-49ed-47e6-8dd0-d5c3bc31778b` and use that as the scope.
+		 * Note: do not use this UUID: a new one must be randomly generated when needed to ensure collision resistance.
+		 * ```typescript
+		 * const factory = new SchemaFactory("242c4397-49ed-47e6-8dd0-d5c3bc31778b");
+		 * ```
+		 */
+		public readonly scope: TScope,
+	) {}
 
 	private scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
 		return (

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

@@ -168,7 +168,7 @@ export const treeNodeApi: TreeNodeApi = {
 			case "nodeChanged": {
 				const nodeSchema = kernel.schema;
 				if (isObjectNodeSchema(nodeSchema)) {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						const changedProperties = new Set(
 							Array.from(
 								changedFields,
@@ -180,17 +180,17 @@ export const treeNodeApi: TreeNodeApi = {
 						listener({ changedProperties });
 					});
 				} else if (nodeSchema.kind === NodeKind.Array) {
-					return kernel.on("childrenChangedAfterBatch", () => {
+					return kernel.events.on("childrenChangedAfterBatch", () => {
 						listener({ changedProperties: undefined });
 					});
 				} else {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						listener({ changedProperties: changedFields });
 					});
 				}
 			}
 			case "treeChanged": {
-				return kernel.on("subtreeChangedAfterBatch", () => listener({}));
+				return kernel.events.on("subtreeChangedAfterBatch", () => listener({}));
 			}
 			default:
 				throw new UsageError(`No event named ${JSON.stringify(eventName)}.`);

package/src/simple-tree/arrayNode.ts

@@ -1096,7 +1096,7 @@ export function arraySchema<
 				// Since proxy reports this as a "non-configurable" property, it must exist on the underlying object used as the proxy target, not as an inherited property.
 				// This should not get used as the proxy should intercept all use.
 				Object.defineProperty(instance, "length", {
-					value: NaN,
+					value: Number.NaN,
 					writable: true,
 					enumerable: false,
 					configurable: false,

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

@@ -95,7 +95,7 @@ function isHydrated(state: HydrationState): state is HydratedState {
  * 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> {
+export class TreeNodeKernel {
 	private disposed = false;
 
 	/**
@@ -205,9 +205,9 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 		this.#hydrationState = {
 			anchorNode,
 			offAnchorNode: new Set([
-				anchorNode.on("afterDestroy", () => this.dispose()),
+				anchorNode.events.on("afterDestroy", () => this.dispose()),
 				// TODO: this should be triggered on change even for unhydrated nodes.
-				anchorNode.on("childrenChanging", () => {
+				anchorNode.events.on("childrenChanging", () => {
 					this.generationNumber += 1;
 				}),
 			]),
@@ -221,7 +221,7 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 					this.#hydrationState.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) => events.emit(eventName, arg)),
+						anchorNode.events.on(eventName, (arg: any) => events.emit(eventName, arg)),
 					);
 				}
 			}
@@ -248,13 +248,11 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 		return treeStatusFromAnchorCache(this.#hydrationState.anchorNode);
 	}
 
-	public on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {
+	public get events(): Listenable<KernelEvents> {
 		// Retrieve the correct events object based on whether this node is pre or post hydration.
-		const events: Listenable<KernelEvents> = isHydrated(this.#hydrationState)
-			? this.#hydrationState.anchorNode
+		return isHydrated(this.#hydrationState)
+			? this.#hydrationState.anchorNode.events
 			: this.#unhydratedEvents.value;
-
-		return events.on(eventName, listener);
 	}
 
 	public dispose(): void {
@@ -339,7 +337,7 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 			off();
 		};
 		anchorForgetters.set(this.node, forget);
-		const off = anchorNode.on("afterDestroy", forget);
+		const off = anchorNode.events.on("afterDestroy", forget);
 		return anchorNode;
 	}
 

package/src/simple-tree/proxies.ts

@@ -172,7 +172,7 @@ function bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription):
 	if (proxies.length > 0) {
 		// Creating a new array emits one event per element in the array, so listen to the event once for each element
 		let i = 0;
-		const off = forest.on("afterRootFieldCreated", (fieldKey) => {
+		const off = forest.events.on("afterRootFieldCreated", (fieldKey) => {
 			// Non null asserting here because of the length check above
 			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 			(proxies[i]!.rootPath as Mutable<UpPath>).parentField = fieldKey;

package/src/simple-tree/schemaTypes.ts

@@ -476,9 +476,34 @@ function evaluateLazySchema(value: LazyItem<TreeNodeSchema>): TreeNodeSchema {
 }
 
 /**
- * Types allowed in a field.
+ * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree.
  * @remarks
+ * Used by {@link TreeViewConfiguration} for the root and various kinds of {@link TreeNodeSchema} to specify their allowed child types.
+ *
+ * Use {@link SchemaFactory} to access leaf schema or declare new composite schema.
+ *
  * Implicitly treats a single type as an array of one type.
+ *
+ * Arrays of schema can be used to specify multiple types are allowed, which result in unions of those types in the Tree APIs.
+ *
+ * When saved into variables, avoid type-erasing the details, as doing so loses the compile time schema awareness of APIs derived from the types.
+ *
+ * When referring to types that are declared after the definition of the `ImplicitAllowedTypes`, the schema can be wrapped in a lambda to allow the forward reference.
+ * See {@link ValidateRecursiveSchema} for details on how to structure the `ImplicitAllowedTypes` instances when constructing recursive schema.
+ *
+ * @example Explicit use with strong typing
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * const childTypes = [sf.number, sf.string] as const satisfies ImplicitAllowedTypes;
+ * const config = new TreeViewConfiguration({ schema: childTypes });
+ * ```
+ *
+ * @example Forward reference
+ * ```typescript
+ * const sf = new SchemaFactory("myScope");
+ * class A extends sf.array("example", [() => B]) {}
+ * class B extends sf.array("Inner", sf.number) {}
+ * ```
  * @public
  */
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;

package/src/simple-tree/treeNodeValid.ts

@@ -103,7 +103,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
 
 			// This is not just an alias of `this`, but a reference to the item in the prototype chain being walked, which happens to start at `this`.
-			// eslint-disable-next-line @typescript-eslint/no-this-alias
+			// eslint-disable-next-line @typescript-eslint/no-this-alias, unicorn/no-this-assignment
 			let schemaBase: typeof TreeNodeValid = this;
 			while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
 				schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
@@ -300,7 +300,7 @@ function formattedReference(
 	object: unknown,
 	config?: DevtoolsFormatter.ObjectConfig,
 ): DevtoolsFormatter.Item {
-	if (typeof object === "undefined") {
+	if (object === undefined) {
 		return ["span", "undefined"];
 	} else if (object === "null") {
 		return ["span", "null"];

package/src/util/nestedMap.ts

@@ -4,6 +4,7 @@
  */
 
 import { oob } from "@fluidframework/core-utils/internal";
+
 import type { MapGetSet } from "./utils.js";
 
 /**