Refactor ITree extension interfaces (microsoft#23792)

## Description

Refactor ITree extension interfaces to better separate APIs for
different consumers of shared tree.

This makes it possible to expose APIs like `id` (needed by the dev
tools) or `contentSnapshot` (used for unit testing) without exposing the
runtime facing APIs like load and summarize.

Future refactoring work is planned which will separate the code where
these are implemented as part of decoupling most of the tree code from
the SharedObject class hierarchy similar to how SharedMap does so with
its MapKernel. The change here helps with that planed work.

Author: CraigMacomber

packages/dds/tree/src/index.ts

@@ -85,6 +85,7 @@ export {
 	ForestTypeReference,
 	SharedTreeAttributes,
 	SharedTreeFactoryType,
+	type IChannelView,
 } from "./shared-tree/index.js";
 
 export {
@@ -216,6 +217,7 @@ export {
 	asTreeViewAlpha,
 	type NodeSchemaOptions,
 	type NodeSchemaMetadata,
+	type ITreeAlpha,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

packages/dds/tree/src/shared-tree/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	type ISharedTree,
+	type ITreePrivate,
 	type SharedTreeOptionsInternal,
 	type SharedTreeOptions,
 	SharedTree,
@@ -20,6 +21,7 @@ export {
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
 	ForestTypeReference,
+	type IChannelView,
 } from "./sharedTree.js";
 
 export {

packages/dds/tree/src/shared-tree/sharedTree.ts

@@ -9,6 +9,7 @@ import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
 	IChannelStorageService,
+	IChannel,
 } from "@fluidframework/datastore-definitions/internal";
 import type { ISharedObject } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -72,6 +73,7 @@ import {
 	FieldKind,
 	type CustomTreeNode,
 	type CustomTreeValue,
+	type ITreeAlpha,
 } from "../simple-tree/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
@@ -84,7 +86,7 @@ import { breakingClass, fail, throwIfBroken } from "../util/index.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
- * Copy of data from an {@link ISharedTree} at some point in time.
+ * Copy of data from an {@link ITreePrivate} at some point in time.
  * @remarks
  * This is unrelated to Fluids concept of "snapshots".
  */
@@ -108,30 +110,26 @@ export interface SharedTreeContentSnapshot {
 }
 
 /**
- * {@link ITree} extended with some non-public APIs.
+ * Information about a Fluid channel.
+ * @privateRemarks
+ * This is distinct from {@link IChannel} as it omits the APIs used by the runtime to manage the channel and instead only has things which are useful (and safe) to expose to users of the channel.
  * @internal
  */
-export interface ITreeInternal extends ISharedObject, ITree {
-	/**
-	 * Exports root in the same format as {@link TreeAlpha.(exportVerbose:1)} using stored keys.
-	 * @privateRemarks
-	 * TODO:
-	 * This should probably get promoted to a public API on ITree eventually.
-	 */
-	exportVerbose(): VerboseTree | undefined;
+export type IChannelView = Pick<IChannel, "id" | "attributes" | "isAttached">;
 
-	/**
-	 * Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.
-	 * @remarks
-	 * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.
-	 */
-	exportSimpleSchema(): SimpleTreeSchema;
-}
+/**
+ * {@link ITree} extended with some non-public APIs.
+ * @internal
+ */
+export interface ITreeInternal extends IChannelView, ITreeAlpha {}
 
 /**
  * {@link ITreeInternal} extended with some non-exported APIs.
+ * @remarks
+ * This allows access to the tree content using the internal data model used at the storage and "flex" layers,
+ * and should only be needed for testing and debugging this package's internals.
  */
-export interface ISharedTree extends ISharedObject, ITreeInternal {
+export interface ITreePrivate extends ITreeInternal {
 	/**
 	 * Provides a copy of the current content of the tree.
 	 * This can be useful for inspecting the tree when no suitable view schema is available.
@@ -142,6 +140,13 @@ export interface ISharedTree extends ISharedObject, ITreeInternal {
 	contentSnapshot(): SharedTreeContentSnapshot;
 }
 
+/**
+ * {@link ITreePrivate} extended with ISharedObject.
+ * @remarks
+ * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.
+ */
+export interface ISharedTree extends ISharedObject, ITreePrivate {}
+
 /**
  * Has an entry for each codec which writes an explicit version into its data.
  *

packages/dds/tree/src/simple-tree/api/index.ts

@@ -15,6 +15,7 @@ export {
 	type TreeViewAlpha,
 	type TreeBranch,
 	type TreeBranchEvents,
+	type ITreeAlpha,
 	asTreeViewAlpha,
 } from "./tree.js";
 export {

packages/dds/tree/src/simple-tree/api/tree.ts

@@ -42,6 +42,8 @@ import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
+import type { VerboseTree } from "./verboseTree.js";
+import type { SimpleTreeSchema } from "./simpleSchema.js";
 /**
  * A tree from which a {@link TreeView} can be created.
  *
@@ -52,7 +54,6 @@ import { walkFieldSchema } from "../walkFieldSchema.js";
  * Maybe rename "exportJsonSchema" to align on "concise" terminology.
  * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
  * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
- * Some of these APIs are on ISharedTree and can get moved here.
  * @system @sealed @public
  */
 export interface ViewableTree {
@@ -101,6 +102,28 @@ export interface ViewableTree {
  */
 export interface ITree extends ViewableTree, IFluidLoadable {}
 
+/**
+ * {@link ITree} extended with some alpha APIs.
+ * @privateRemarks
+ * TODO: Promote this to alpha.
+ * @internal
+ */
+export interface ITreeAlpha extends ITree {
+	/**
+	 * Exports root in the same format as {@link TreeAlpha.(exportVerbose:1)} using stored keys.
+	 * @remarks
+	 * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).
+	 */
+	exportVerbose(): VerboseTree | undefined;
+
+	/**
+	 * Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.
+	 * @remarks
+	 * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.
+	 */
+	exportSimpleSchema(): SimpleTreeSchema;
+}
+
 /**
  * Options when constructing a tree view.
  * @public

packages/dds/tree/src/simple-tree/index.ts

@@ -124,6 +124,7 @@ export {
 	type CustomTreeNode,
 	type CustomTreeValue,
 	tryStoredSchemaAsArray,
+	type ITreeAlpha,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,

packages/dds/tree/src/test/feature-libraries/node-key/nodeKey.spec.ts

@@ -16,14 +16,14 @@ import {
 	createNodeKeyManager,
 	MockNodeKeyManager,
 } from "../../../feature-libraries/index.js";
-import type { ISharedTree } from "../../../shared-tree/index.js";
+import type { ITreePrivate } from "../../../shared-tree/index.js";
 import { TestTreeProvider } from "../../utils.js";
 
 /**
  * Acquire an {@link IIdCompressor} via unsavory means.
  * @remarks TODO: Figure out a better way to get an IIDCompressor
  */
-async function getIIDCompressor(tree?: ISharedTree): Promise<IIdCompressor> {
+async function getIIDCompressor(tree?: ITreePrivate): Promise<IIdCompressor> {
 	const runtime = (
 		(tree ?? (await TestTreeProvider.create(1)).trees[0]) as unknown as {
 			runtime: IFluidDataStoreRuntime;

packages/dds/tree/src/test/shared-tree/fuzz/fuzzEditGenerators.ts

@@ -24,7 +24,7 @@ import type {
 	TreeNodeSchemaIdentifier,
 } from "../../../core/index.js";
 import { type DownPath, toDownPath } from "../../../feature-libraries/index.js";
-import { Tree, type ISharedTree, type SharedTree } from "../../../shared-tree/index.js";
+import { Tree, type ITreePrivate, type SharedTree } from "../../../shared-tree/index.js";
 import { fail, getOrCreate, makeArray } from "../../../util/index.js";
 
 import {
@@ -109,7 +109,7 @@ export interface FuzzTestState extends DDSFuzzTestState<TreeFactory> {
 	 * Maintaining a separate view here is necessary since async transactions are not supported on the root checkout,
 	 * and the fuzz testing model only simulates async transactions.
 	 */
-	transactionViews?: Map<ISharedTree, FuzzTransactionView>;
+	transactionViews?: Map<ITreePrivate, FuzzTransactionView>;
 }
 
 export function viewFromState(

packages/dds/tree/src/test/shared-tree/fuzz/fuzzUtils.ts

@@ -36,6 +36,7 @@ import {
 	TreeViewConfiguration,
 	type TreeNodeSchema,
 	type ValidateRecursiveSchema,
+	type ViewableTree,
 } from "../../../simple-tree/index.js";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
@@ -166,16 +167,16 @@ export class SharedTreeFuzzTestFactory extends SharedTreeTestFactory {
 	}
 }
 
-export const FuzzTestOnCreate = (tree: SharedTree) => {
+export const FuzzTestOnCreate = (tree: ViewableTree) => {
 	const view = tree.viewWith(new TreeViewConfiguration({ schema: initialFuzzSchema }));
 	view.initialize(populatedInitialState);
 	view.dispose();
 };
 
 export function createOnCreate(
 	initialState: NodeBuilderData<typeof FuzzNode> | undefined,
-): (tree: SharedTree) => void {
-	return (tree: SharedTree) => {
+): (tree: ViewableTree) => void {
+	return (tree: ViewableTree) => {
 		const view = tree.viewWith(new TreeViewConfiguration({ schema: initialFuzzSchema }));
 		view.initialize(initialState);
 		view.dispose();

packages/dds/tree/src/test/shared-tree/opSize.bench.ts

@@ -21,7 +21,7 @@ import {
 import type { Value } from "../../core/index.js";
 import { typeboxValidator } from "../../external-utilities/index.js";
 import { TreeCompressionStrategy } from "../../feature-libraries/index.js";
-import { Tree, type ISharedTree, type SharedTree } from "../../shared-tree/index.js";
+import { Tree, type ITreePrivate } from "../../shared-tree/index.js";
 import { type JsonCompatibleReadOnly, getOrAddEmptyToMap } from "../../util/index.js";
 import { treeTestFactory } from "../utils.js";
 import {
@@ -52,7 +52,7 @@ class Parent extends schemaFactory.array("Test:Opsize-Bench-Root", Child) {}
 /**
  * Create a default attached tree for op submission
  */
-function createConnectedTree(): SharedTree {
+function createConnectedTree(): ITreePrivate {
 	const containerRuntimeFactory = new MockContainerRuntimeFactory();
 	const dataStoreRuntime = new MockFluidDataStoreRuntime({
 		idCompressor: createIdCompressor(),
@@ -299,7 +299,7 @@ describe("Op Size", () => {
 	const currentTestOps: ISequencedDocumentMessage[] = [];
 
 	function registerOpListener(
-		tree: ISharedTree,
+		tree: ITreePrivate,
 		resultArray: ISequencedDocumentMessage[],
 	): void {
 		// TODO: better way to hook this up. Needs to detect local ops exactly once.
@@ -332,7 +332,7 @@ describe("Op Size", () => {
 		};
 	};
 
-	const initializeOpDataCollection = (tree: ISharedTree) => {
+	const initializeOpDataCollection = (tree: ITreePrivate) => {
 		currentTestOps.length = 0;
 		registerOpListener(tree, currentTestOps);
 	};

packages/dds/tree/src/test/shared-tree/sharedTree.spec.ts

@@ -51,7 +51,7 @@ import {
 	ForestTypeOptimized,
 	ForestTypeReference,
 	getBranch,
-	type ISharedTree,
+	type ITreePrivate,
 	type SharedTree,
 	Tree,
 	type TreeCheckout,
@@ -1861,7 +1861,7 @@ describe("SharedTree", () => {
 				pendingOps,
 			);
 			const dataStore = (await loadedContainer.getEntryPoint()) as ITestFluidObject;
-			const tree = await dataStore.getSharedObject<ISharedTree>("TestSharedTree");
+			const tree = await dataStore.getSharedObject<ITreePrivate>("TestSharedTree");
 			await waitForContainerConnection(loadedContainer, true);
 			await provider.ensureSynchronized();
 

packages/dds/tree/src/test/snapshots/opFormat.spec.ts

@@ -14,7 +14,7 @@ import {
 } from "@fluidframework/test-runtime-utils/internal";
 import { takeJsonSnapshot, useSnapshotDirectory } from "./snapshotTools.js";
 import { SchemaFactory, TreeViewConfiguration } from "../../simple-tree/index.js";
-import { type SharedTree, SharedTreeFormatVersion } from "../../shared-tree/index.js";
+import { type ISharedTree, SharedTreeFormatVersion } from "../../shared-tree/index.js";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
 import { TreeFactory } from "../../treeFactory.js";
 
@@ -40,7 +40,7 @@ describe("SharedTree op format snapshots", () => {
 	}) {}
 
 	let containerRuntime: MockContainerRuntime;
-	let tree: SharedTree;
+	let tree: ISharedTree;
 
 	for (const versionKey of Object.keys(SharedTreeFormatVersion)) {
 		describe(`using SharedTreeFormatVersion.${versionKey}`, () => {

packages/dds/tree/src/test/utils.ts

@@ -114,7 +114,7 @@ import { makeSchemaCodec } from "../feature-libraries/schema-index/codec.js";
 import {
 	type CheckoutEvents,
 	CheckoutFlexTreeView,
-	type ISharedTree,
+	type ITreePrivate,
 	type ITreeCheckout,
 	SharedTree,
 	type SharedTreeContentSnapshot,
@@ -282,7 +282,7 @@ export class TestTreeProvider {
 	}
 
 	/**
-	 * Create and initialize a new {@link ISharedTree} that is connected to all other trees from this provider.
+	 * Create and initialize a new {@link ITreePrivate} that is connected to all other trees from this provider.
 	 * @returns the tree that was created. For convenience, the tree can also be accessed via `this[i]` where
 	 * _i_ is the index of the tree in order of creation.
 	 */
@@ -323,7 +323,7 @@ export class TestTreeProvider {
 		return summarizeNow(this.summarizer, "TestTreeProvider");
 	}
 
-	public [Symbol.iterator](): IterableIterator<ISharedTree> {
+	public [Symbol.iterator](): IterableIterator<ITreePrivate> {
 		return this.trees[Symbol.iterator]();
 	}
 
@@ -564,7 +564,7 @@ export function checkRemovedRootsAreSynchronized(trees: readonly ITreeCheckout[]
  * This does NOT check that the trees have the same edits, same edit manager state or anything like that.
  * This ONLY checks if the content of the forest of the main branch of the trees match.
  */
-export function validateTreeConsistency(treeA: ISharedTree, treeB: ISharedTree): void {
+export function validateTreeConsistency(treeA: ITreePrivate, treeB: ITreePrivate): void {
 	// TODO: validate other aspects of these trees are consistent, for example their collaboration window information.
 	validateSnapshotConsistency(
 		treeA.contentSnapshot(),

packages/tools/devtools/devtools-core/src/data-visualization/DefaultVisualizers.ts

@@ -15,13 +15,12 @@ import {
 	type ISharedMap,
 	SharedMap,
 	type ISharedDirectory,
-	// eslint-disable-next-line import/no-deprecated
 	SharedDirectory,
 } from "@fluidframework/map/internal";
 import { SharedMatrix } from "@fluidframework/matrix/internal";
 import { SharedString } from "@fluidframework/sequence/internal";
 import type { ISharedObject } from "@fluidframework/shared-object-base/internal";
-import type { ITreeInternal } from "@fluidframework/tree/internal";
+import type { ITreeInternal, IChannelView } from "@fluidframework/tree/internal";
 import { SharedTree } from "@fluidframework/tree/internal";
 
 import { EditType } from "../CommonInterfaces.js";
@@ -250,13 +249,13 @@ export const visualizeSharedString: VisualizeSharedObject = async (
 };
 
 /**
- * {@link VisualizeSharedObject} for {@link ISharedTree}.
+ * {@link VisualizeSharedObject} for {@link ITree}.
  */
 export const visualizeSharedTree: VisualizeSharedObject = async (
 	sharedObject: ISharedObject,
 	visualizeChildData: VisualizeChildData,
 ): Promise<FluidObjectNode> => {
-	const sharedTree = sharedObject as ITreeInternal;
+	const sharedTree = sharedObject as IChannelView as ITreeInternal;
 
 	// Root node of the SharedTree's content.
 	const treeView = sharedTree.exportVerbose();