@fluidframework/tree 2.33.1 → 2.40.0-336023

package/src/serializableDomainSchema.ts

@@ -21,14 +21,14 @@ const sf = new SchemaFactory("com.fluidframework.serializable");
  * @remarks
  * Schema which replicate the Fluid Serializable data model with {@link TreeNode}s.
  *
- * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link TreeAlpha.importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
+ * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link (TreeAlpha:interface).importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
  * @internal
  */
 export namespace FluidSerializableAsTree {
 	/**
 	 * Data which can be serialized by Fluid.
 	 * @remarks
-	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link TreeAlpha.importConcise}.
+	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link (TreeAlpha:interface).importConcise}.
 	 * @internal
 	 */
 	export type Data = JsonCompatible<IFluidHandle>;
@@ -100,7 +100,7 @@ export namespace FluidSerializableAsTree {
 	/**
 	 * Arbitrary Fluid Serializable array as a {@link TreeNode}.
 	 * @remarks
-	 * This can be imported using {@link TreeAlpha.importConcise}.
+	 * This can be imported using {@link (TreeAlpha:interface).importConcise}.
 	 * @example
 	 * ```typescript
 	 * // Due to TypeScript restrictions on recursive types, the constructor can be somewhat limiting.

package/src/shared-tree/independentView.ts

@@ -134,7 +134,7 @@ export function independentInitializedView<const TSchema extends ImplicitFieldSc
  */
 export interface ViewContent {
 	/**
-	 * Compressed tree from {@link TreeAlpha.exportCompressed}.
+	 * Compressed tree from {@link (TreeAlpha:interface).exportCompressed}.
 	 * @remarks
 	 * This is an owning reference:
 	 * consumers of this content might modify this data in place (for example when applying edits) to avoid copying.

package/src/shared-tree/index.ts

@@ -45,13 +45,10 @@ export type {
 	SharedTreeEditBuilder,
 } from "./sharedTreeEditBuilder.js";
 
-export {
-	treeApi as Tree,
-	type TreeApi,
-	type RunTransaction,
-} from "./treeApi.js";
+export { Tree } from "./tree.js";
+export type { RunTransaction } from "./tree.js";
 
-export { TreeAlpha } from "./treeApiAlpha.js";
+export { TreeAlpha } from "./treeAlpha.js";
 
 export {
 	independentInitializedView,

package/src/shared-tree/schematizeTree.ts

@@ -23,7 +23,7 @@ import {
 import { isReadonlyArray } from "../util/index.js";
 
 import type { ITreeCheckout } from "./treeCheckout.js";
-import { toStoredSchema, type ViewSchema } from "../simple-tree/index.js";
+import type { SchemaCompatibilityTester } from "../simple-tree/index.js";
 
 /**
  * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
@@ -113,7 +113,7 @@ export enum UpdateType {
 }
 
 export function evaluateUpdate(
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	allowedSchemaModifications: AllowedUpdateType,
 	checkout: ITreeCheckout,
 ): UpdateType {
@@ -209,7 +209,7 @@ export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredConte
 }
 
 /**
- * Ensure a {@link ITreeCheckout} can be used with a given {@link ViewSchema}.
+ * Ensure a {@link ITreeCheckout} can be used with a given {@link SchemaCompatibilityTester}.
  *
  * @remarks
  * It is up to the caller to ensure that compatibility is reevaluated if the checkout's stored schema is edited in the future.
@@ -221,7 +221,7 @@ export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredConte
  * @returns true iff checkout now is compatible with `viewSchema`.
  */
 export function ensureSchema(
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	allowedSchemaModifications: AllowedUpdateType,
 	checkout: ITreeCheckout,
 	treeContent: TreeStoredContent | undefined,
@@ -241,7 +241,7 @@ export function ensureSchema(
 			return false;
 		}
 		case UpdateType.SchemaCompatible: {
-			checkout.updateSchema(toStoredSchema(viewSchema.schema));
+			checkout.updateSchema(viewSchema.viewSchemaAsStored);
 			return true;
 		}
 		case UpdateType.Initialize: {

package/src/shared-tree/schematizingTreeView.ts

@@ -30,13 +30,12 @@ import {
 	getTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
-	ViewSchema,
+	SchemaCompatibilityTester,
 	type InsertableContent,
 	type TreeViewConfiguration,
 	mapTreeFromNodeData,
 	prepareContentForHydration,
 	comparePersistedSchemaInternal,
-	toStoredSchema,
 	type TreeViewAlpha,
 	type InsertableField,
 	type ReadableField,
@@ -98,7 +97,7 @@ export class SchematizingSimpleTreeView<
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
 
-	private readonly viewSchema: ViewSchema;
+	private readonly viewSchema: SchemaCompatibilityTester;
 
 	private readonly unregisterCallbacks = new Set<() => void>();
 
@@ -133,7 +132,11 @@ export class SchematizingSimpleTreeView<
 			allowUnknownOptionalFields: createUnknownOptionalFieldPolicy(this.rootFieldSchema),
 		};
 
-		this.viewSchema = new ViewSchema(this.schemaPolicy, {}, this.rootFieldSchema);
+		this.viewSchema = new SchemaCompatibilityTester(
+			this.schemaPolicy,
+			{},
+			this.rootFieldSchema,
+		);
 		// This must be initialized before `update` can be called.
 		this.currentCompatibility = {
 			canView: false,
@@ -182,7 +185,7 @@ export class SchematizingSimpleTreeView<
 
 			prepareContentForHydration(mapTree, this.checkout.forest);
 			initialize(this.checkout, {
-				schema: toStoredSchema(this.viewSchema.schema),
+				schema: this.viewSchema.viewSchemaAsStored,
 				initialTree: mapTree === undefined ? undefined : cursorForMapTreeNode(mapTree),
 			});
 		});
@@ -209,7 +212,7 @@ export class SchematizingSimpleTreeView<
 				AllowedUpdateType.SchemaCompatible,
 				this.checkout,
 				{
-					schema: toStoredSchema(this.viewSchema.schema),
+					schema: this.viewSchema.viewSchemaAsStored,
 					initialTree: undefined,
 				},
 			);
@@ -502,12 +505,12 @@ export function getCheckout(context: TreeBranch): TreeCheckout {
 }
 
 /**
- * Creates a view that self-disposes whenenever the stored schema changes.
+ * Creates a view that self-disposes whenever the stored schema changes.
  * This may only be called when the schema is already known to be compatible (typically via ensureSchema).
  */
 export function requireSchema(
 	checkout: ITreeCheckout,
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	onDispose: () => void,
 	nodeKeyManager: NodeIdentifierManager,
 	schemaPolicy: FullSchemaPolicy,

package/src/shared-tree/{treeApi.ts → tree.ts}

@@ -22,6 +22,56 @@ import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
 import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 
+/**
+ * Provides various functions for interacting with {@link TreeNode}s.
+ * @remarks
+ * This type should only be used via the {@link (Tree:variable)} export.
+ * @system @sealed @public
+ */
+export interface Tree extends TreeNodeApi {
+	/**
+	 * Run a {@link RunTransaction | transaction}.
+	 */
+	readonly runTransaction: RunTransaction;
+	/**
+	 * Check if the subtree defined by `node` contains `other`.
+	 *
+	 * @returns true if `other` is an inclusive descendant of `node`, and false otherwise.
+	 * @remarks
+	 * This includes direct and indirect children:
+	 * as long as `node` is an ancestor of `other` (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
+	 *
+	 * `node` is considered to contain itself, so the case where `node === other` returns true.
+	 *
+	 * This is handy when checking if moving `node` into `other` would create a cycle and would thus be invalid.
+	 *
+	 * This check walks the parents of `other` looking for `node`,
+	 * and thus runs in time proportional to the depth of child in the tree.
+	 */
+	contains(node: TreeNode, other: TreeNode): boolean;
+}
+
+/**
+ * The {@link (Tree:interface)} singleton which holds various functions for interacting with {@link TreeNode}s.
+ * @public
+ */
+export const Tree: Tree = {
+	...treeNodeApi,
+
+	runTransaction: createRunTransaction(),
+
+	contains(parent: TreeNode, child: TreeNode): boolean {
+		let toCheck: TreeNode | undefined = child;
+		while (toCheck !== undefined) {
+			if (toCheck === parent) {
+				return true;
+			}
+			toCheck = Tree.parent(toCheck);
+		}
+		return false;
+	},
+};
+
 /**
  * A function which runs a transaction in a SharedTree.
  * @privateRemarks
@@ -326,56 +376,6 @@ export interface RunTransaction {
 	): void;
 }
 
-/**
- * Provides various functions for interacting with {@link TreeNode}s.
- * @remarks
- * This type should only be used via the public `Tree` export.
- * @system @sealed @public
- */
-export interface TreeApi extends TreeNodeApi {
-	/**
-	 * Run a {@link RunTransaction | transaction}.
-	 */
-	readonly runTransaction: RunTransaction;
-	/**
-	 * Check if the subtree defined by `node` contains `other`.
-	 *
-	 * @returns true if `other` is an inclusive descendant of `node`, and false otherwise.
-	 * @remarks
-	 * This includes direct and indirect children:
-	 * as long as `node` is an ancestor of `other` (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
-	 *
-	 * `node` is considered to contain itself, so the case where `node === other` returns true.
-	 *
-	 * This is handy when checking if moving `node` into `other` would create a cycle and thus is invalid.
-	 *
-	 * This check walks the parents of `other` looking for `node`,
-	 * and thus runs in time proportional to the depth of child in the tree.
-	 */
-	contains(node: TreeNode, other: TreeNode): boolean;
-}
-
-/**
- * The `Tree` object holds various functions for interacting with {@link TreeNode}s.
- * @public
- */
-export const treeApi: TreeApi = {
-	...treeNodeApi,
-
-	runTransaction: createRunTransaction(),
-
-	contains(parent: TreeNode, child: TreeNode): boolean {
-		let toCheck: TreeNode | undefined = child;
-		while (toCheck !== undefined) {
-			if (toCheck === parent) {
-				return true;
-			}
-			toCheck = treeApi.parent(toCheck);
-		}
-		return false;
-	},
-};
-
 // TODO: Add more constraint types here
 
 /** Creates a copy of `runTransaction` with the `rollback` property added so as to satisfy the `RunTransaction` interface. */
@@ -443,7 +443,7 @@ function runTransactionInCheckout<TResult>(
 		switch (constraint.type) {
 			case "nodeInDocument": {
 				const node = getOrCreateInnerNode(constraint.node);
-				const nodeStatus = treeApi.status(constraint.node);
+				const nodeStatus = Tree.status(constraint.node);
 				if (nodeStatus !== TreeStatus.InDocument) {
 					throw new UsageError(
 						`Attempted to add a "nodeInDocument" constraint, but the node is not currently in the document. Node status: ${nodeStatus}`,

package/src/shared-tree/{treeApiAlpha.ts → treeAlpha.ts}

@@ -54,10 +54,12 @@ import { independentInitializedView, type ViewContent } from "./independentView.
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
 
 /**
- * Extensions to {@link Tree} and {@link TreeBeta} which are not yet stable.
- * @sealed @alpha
+ * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
+ * @remarks
+ * Use via the {@link (TreeAlpha:variable)} singleton.
+ * @system @sealed @alpha
  */
-export const TreeAlpha: {
+export interface TreeAlpha {
 	/**
 	 * Retrieve the {@link TreeBranch | branch}, if any, for the given node.
 	 * @param node - The node to query
@@ -79,7 +81,7 @@ export const TreeAlpha: {
 	 * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
 	 *
 	 * Like with {@link TreeNodeSchemaClass}'s constructor, it's an error to provide an existing node to this API.
-	 * For that case, use {@link TreeBeta.clone}.
+	 * For that case, use {@link (TreeBeta:interface).clone}.
 	 * @privateRemarks
 	 * There should be a way to provide a source for defaulted identifiers, wither via this API or some way to add them to its output later.
 	 */
@@ -95,7 +97,7 @@ export const TreeAlpha: {
 	>;
 
 	/**
-	 * Less type safe version of {@link TreeAlpha.create}, suitable for importing data.
+	 * Less type safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.
 	 * @remarks
 	 * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.
 	 * This does not support {@link ConciseTree|ConciseTrees} with customized handle encodings or using persisted keys.
@@ -103,8 +105,8 @@ export const TreeAlpha: {
 	 *
 	 * When using this function,
 	 * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.
-	 * If the schema is ambiguous, consider using {@link TreeAlpha.create} and {@link Unhydrated} nodes where needed,
-	 * or using {@link TreeAlpha.(importVerbose:1)} and specify all types.
+	 * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,
+	 * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.
 	 *
 	 * Documented (and thus recoverable) error handling/reporting for this is not yet implemented,
 	 * but for now most invalid inputs will throw a recoverable error.
@@ -123,7 +125,7 @@ export const TreeAlpha: {
 	/**
 	 * Construct tree content compatible with a field defined by the provided `schema`.
 	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
-	 * @param data - The data used to construct the field content. See {@link TreeAlpha.(exportVerbose:1)}.
+	 * @param data - The data used to construct the field content. See {@link (TreeAlpha:interface).(exportVerbose:1)}.
 	 */
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
@@ -149,7 +151,7 @@ export const TreeAlpha: {
 	 * Uses the {@link VerboseTree} format, with an explicit type on every node.
 	 *
 	 * @remarks
-	 * There are several cases this may be preferred to {@link TreeAlpha.(exportConcise:1)}:
+	 * There are several cases this may be preferred to {@link (TreeAlpha:interface).(exportConcise:1)}:
 	 *
 	 * 1. When not using {@link ITreeConfigurationOptions.preventAmbiguity} (or when using `useStableFieldKeys`), `exportConcise` can produce ambiguous data (the type may be unclear on some nodes).
 	 * `exportVerbose` will always be unambiguous and thus lossless.
@@ -182,11 +184,11 @@ export const TreeAlpha: {
 	): JsonCompatible<IFluidHandle>;
 
 	/**
-	 * Import data encoded by {@link TreeAlpha.exportCompressed}.
+	 * Import data encoded by {@link (TreeAlpha:interface).exportCompressed}.
 	 *
 	 * @param schema - Schema with which the data must be compatible. This compatibility is not verified and must be ensured by the caller.
-	 * @param compressedData - Data compressed by {@link TreeAlpha.exportCompressed}.
-	 * @param options - If {@link TreeAlpha.exportCompressed} was given an `idCompressor`, it must be provided here.
+	 * @param compressedData - Data compressed by {@link (TreeAlpha:interface).exportCompressed}.
+	 * @param options - If {@link (TreeAlpha:interface).exportCompressed} was given an `idCompressor`, it must be provided here.
 	 *
 	 * @remarks
 	 * If the data could have been encoded with a different schema, consider encoding the schema along side it using {@link extractPersistedSchema} and loading the data using {@link independentView}.
@@ -203,7 +205,14 @@ export const TreeAlpha: {
 		compressedData: JsonCompatible<IFluidHandle>,
 		options: { idCompressor?: IIdCompressor } & ICodecOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
-} = {
+}
+
+/**
+ * Extensions to {@link (Tree:variable)} and {@link (TreeBeta:variable)} which are not yet stable.
+ * @see {@link (TreeAlpha:interface)}.
+ * @alpha
+ */
+export const TreeAlpha: TreeAlpha = {
 	branch(node: TreeNode): TreeBranch | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {

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

@@ -21,7 +21,7 @@ import { getUnhydratedContext } from "../createContext.js";
  * @remarks
  * This is "concise" meaning that explicit type information is omitted.
  * If the schema is compatible with {@link ITreeConfigurationOptions.preventAmbiguity},
- * types will be lossless and compatible with {@link TreeAlpha.create} (unless the options are used to customize it).
+ * types will be lossless and compatible with {@link (TreeAlpha:interface).create} (unless the options are used to customize it).
  *
  * Every {@link TreeNode} is an array or object.
  * Any IFluidHandle values have been replaced by `THandle`.