Add createIndependentTree (microsoft#25785)

## Description

IndependentView had some limitations, like being very difficult to use
for schema evolution and out of schema handling tests.

This new IndependentTree API provides a more general alternative.

Author: CraigMacomber

.changeset/some-geese-mate.md

@@ -0,0 +1,48 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+"__section": tree
+---
+Add IndependentTree API
+
+New `IndependentTreeAlpha` and `IndependentTreeBeta` APIs provide similar utility to the existing alpha [`IndependentView`](https://fluidframework.com/docs/api/tree#independentview-function) API, except providing access to the [`ViewableTree`](https://fluidframework.com/docs/api/fluid-framework/viewabletree-interface).
+
+This allows for multiple views (in sequence, not concurrently) to be created to test things like schema upgrades and incompatible view schema much more easily (see example below).
+For `IndependentTreeAlpha`, this also provides access to `exportVerbose` and `exportSimpleSchema` from [`ITreeAlpha`](https://fluidframework.com/docs/api/tree/itreealpha-interface).
+
+An example of how to use `createIndependentTreeBeta` to create multiple views to test a schema upgrade:
+```typescript
+const tree = createIndependentTreeBeta();
+
+const stagedConfig = new TreeViewConfiguration({
+	schema: SchemaFactoryAlpha.types([
+		SchemaFactory.number,
+		SchemaFactoryAlpha.staged(SchemaFactory.string),
+	]),
+});
+const afterConfig = new TreeViewConfigurationAlpha({
+	schema: [SchemaFactory.number, SchemaFactory.string],
+});
+
+// Initialize tree
+{
+	const view = tree.viewWith(stagedConfig);
+	view.initialize(1);
+	view.dispose();
+}
+
+// Do schema upgrade
+{
+	const view = tree.viewWith(afterConfig);
+	view.upgradeSchema();
+	view.root = "A";
+	view.dispose();
+}
+
+// Can still view tree with staged schema
+{
+	const view = tree.viewWith(stagedConfig);
+	assert.equal(view.root, "A");
+	view.dispose();
+}
+```

packages/dds/tree/api-report/tree.alpha.api.md

@@ -172,6 +172,20 @@ export const contentSchemaSymbol: unique symbol;
 // @alpha
 export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): IdentifierIndex;
 
+// @alpha
+export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions & (({
+    idCompressor?: IIdCompressor | undefined;
+} & {
+    content?: undefined;
+}) | (ICodecOptions & {
+    content: ViewContent;
+} & {
+    idCompressor?: undefined;
+}))): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">;
+
+// @beta
+export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions): ViewableTree;
+
 // @alpha
 export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;
 

packages/dds/tree/api-report/tree.beta.api.md

@@ -94,6 +94,9 @@ export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidH
 // @beta
 export function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): SharedObjectKind<ITree>;
 
+// @beta
+export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions): ViewableTree;
+
 // @public @sealed @system
 interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider"> {
 }

packages/dds/tree/api-report/tree.legacy.beta.api.md

@@ -97,6 +97,9 @@ export function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): Shared
 // @beta @legacy
 export function configuredSharedTreeBetaLegacy(options: SharedTreeOptionsBeta): ISharedObjectKind<ITree> & SharedObjectKind<ITree>;
 
+// @beta
+export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions): ViewableTree;
+
 // @public @sealed @system
 interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider"> {
 }

packages/dds/tree/src/index.ts

@@ -73,6 +73,8 @@ export {
 	type ObservationResults,
 	type TreeIdentifierUtils,
 	independentView,
+	createIndependentTreeBeta,
+	createIndependentTreeAlpha,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
 	ForestTypeReference,

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

@@ -12,11 +12,9 @@ import {
 
 import type { ICodecOptions } from "../codec/index.js";
 import {
-	type ITreeCursorSynchronous,
 	type RevisionTag,
 	RevisionTagCodec,
 	SchemaVersion,
-	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
 } from "../core/index.js";
 import {
@@ -34,11 +32,23 @@ import type {
 	TreeViewConfiguration,
 	ImplicitFieldSchema,
 	TreeViewAlpha,
+	ITreeAlpha,
+	ViewableTree,
+	TreeView,
+	ReadSchema,
+	VerboseTree,
+	SimpleTreeSchema,
 } from "../simple-tree/index.js";
-import { type JsonCompatibleReadOnly, type JsonCompatible, Breakable } from "../util/index.js";
+import {
+	type JsonCompatibleReadOnly,
+	type JsonCompatible,
+	Breakable,
+	oneFromIterable,
+} from "../util/index.js";
 import {
 	buildConfiguredForest,
 	defaultSharedTreeOptions,
+	exportSimpleSchema,
 	type ForestOptions,
 } from "./sharedTree.js";
 import { createTreeCheckout } from "./treeCheckout.js";
@@ -59,30 +69,9 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
 	options: ForestOptions & { idCompressor?: IIdCompressor | undefined },
 ): TreeViewAlpha<TSchema> {
-	const breaker = new Breakable("independentView");
-	const idCompressor: IIdCompressor = options.idCompressor ?? createIdCompressor();
-	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
-	const revisionTagCodec = new RevisionTagCodec(idCompressor);
-	const schema = new TreeStoredSchemaRepository();
-	const forest = buildConfiguredForest(
-		breaker,
-		options.forest ?? defaultSharedTreeOptions.forest,
-		schema,
-		idCompressor,
-		defaultIncrementalEncodingPolicy,
-	);
-	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
-		forest,
-		schema,
-		breaker,
-	});
-	const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
-		checkout,
-		config,
-		createNodeIdentifierManager(idCompressor),
-	);
-	return out;
+	return createIndependentTreeAlpha(options).viewWith(config) as TreeViewAlpha<TSchema>;
 }
+
 /**
  * Create an initialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *
@@ -99,52 +88,101 @@ export function independentInitializedView<const TSchema extends ImplicitFieldSc
 	options: ForestOptions & ICodecOptions,
 	content: ViewContent,
 ): TreeViewAlpha<TSchema> {
-	const idCompressor: IIdCompressor = content.idCompressor;
-	const fieldBatchCodec = makeFieldBatchCodec(options, 1);
-	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
-
-	const schema = schemaCodec.decode(content.schema as Format);
-	const context: FieldBatchEncodingContext = {
-		encodeType: TreeCompressionStrategy.Compressed,
-		idCompressor,
-		originatorId: idCompressor.localSessionId, // Is this right? If so, why is is needed?
-		schema: { schema, policy: defaultSchemaPolicy },
-	};
-
-	const fieldCursors = fieldBatchCodec.decode(content.tree as JsonCompatibleReadOnly, context);
-	assert(fieldCursors.length === 1, 0xa5b /* must have exactly 1 field in batch */);
-
-	return independentInitializedViewInternal(
+	return createIndependentTreeAlpha({ ...options, content }).viewWith(
 		config,
-		options,
-		schema,
-		// Checked above.
-		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-		fieldCursors[0]!,
-		idCompressor,
-	);
+	) as TreeViewAlpha<TSchema>;
 }
 
 /**
- * {@link independentInitializedView} but using internal types instead of persisted data formats.
+ * Create a {@link ViewableTree} that is not tied to any Fluid runtimes or services.
+ *
+ * @remarks
+ * Such a tree can never experience collaboration or be persisted to to a Fluid Container.
+ *
+ * This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.
+ *
+ * @example
+ * ```typescript
+ * const tree = createIndependentTreeBeta();
+ *
+ * const stagedConfig = new TreeViewConfiguration({
+ * 	schema: SchemaFactoryAlpha.types([
+ * 		SchemaFactory.number,
+ * 		SchemaFactoryAlpha.staged(SchemaFactory.string),
+ * 	]),
+ * });
+ * const afterConfig = new TreeViewConfigurationAlpha({
+ * 	schema: [SchemaFactory.number, SchemaFactory.string],
+ * });
+ *
+ * // Initialize tree
+ * {
+ * 	const view = tree.viewWith(stagedConfig);
+ * 	view.initialize(1);
+ * 	view.dispose();
+ * }
+ *
+ * // Do schema upgrade
+ * {
+ * 	const view = tree.viewWith(afterConfig);
+ * 	view.upgradeSchema();
+ * 	view.root = "A";
+ * 	view.dispose();
+ * }
+ *
+ * // Can still view tree with staged schema
+ * {
+ * 	const view = tree.viewWith(stagedConfig);
+ * 	assert.equal(view.root, "A");
+ * 	view.dispose();
+ * }
+ * ```
+ * @privateRemarks
+ * Before stabilizing this as public, consider if we can instead just expose a better way to create regular Fluid service based SharedTrees for tests.
+ * Something like https://github.com/microsoft/FluidFramework/pull/25422 might be a better long term stable/public solution.
+ * @beta
  */
-export function independentInitializedViewInternal<const TSchema extends ImplicitFieldSchema>(
-	config: TreeViewConfiguration<TSchema>,
-	options: ForestOptions & ICodecOptions,
-	schema: TreeStoredSchema,
-	rootFieldCursor: ITreeCursorSynchronous,
-	idCompressor: IIdCompressor,
-): SchematizingSimpleTreeView<TSchema> {
-	const breaker = new Breakable("independentInitializedView");
-	const revisionTagCodec = new RevisionTagCodec(idCompressor);
+export function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(
+	options?: ForestOptions,
+): ViewableTree {
+	return createIndependentTreeAlpha<TSchema>(options);
+}
+
+/**
+ * Alpha extensions to {@link createIndependentTreeBeta}.
+ *
+ * @param options - Configuration options for the independent tree.
+ * This can be used to create an uninitialized tree, or `content` can be provided to create an initialized tree.
+ * If content is provided, the idCompressor is a required part of it: otherwise it is optional and provided at the top level.
+ *
+ * @privateRemarks
+ * TODO: Support more of {@link ITreeAlpha}, including branching APIs to allow for merges.
+ * TODO: Better unify this logic with SharedTreeKernel and SharedTreeCore.
+ *
+ * Before further stabilizing: consider better ways to handle initialized vs uninitialized trees.
+ * Perhaps it would be better to not allow initialize here at all, but expose the ability to load compressed tree content and stored schema via ITree or TreeView?
+ * If keeping the option here, maybe a separate function of overload would be better? Or maybe flatten ViewContent inline to deduplicate the idCompressor options?
+ * @alpha
+ */
+export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(
+	options?: ForestOptions &
+		(
+			| ({ idCompressor?: IIdCompressor | undefined } & { content?: undefined })
+			| (ICodecOptions & { content: ViewContent } & { idCompressor?: undefined })
+		),
+): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema"> {
+	const breaker = new Breakable("independentView");
+	const idCompressor: IIdCompressor =
+		options?.idCompressor ?? options?.content?.idCompressor ?? createIdCompressor();
 	const mintRevisionTag = (): RevisionTag => idCompressor.generateCompressedId();
+	const revisionTagCodec = new RevisionTagCodec(idCompressor);
 
 	// To ensure the forest is in schema when constructed, start it with an empty schema and set the schema repository content later.
 	const schemaRepository = new TreeStoredSchemaRepository();
 
 	const forest = buildConfiguredForest(
 		breaker,
-		options.forest ?? defaultSharedTreeOptions.forest,
+		options?.forest ?? defaultSharedTreeOptions.forest,
 		schemaRepository,
 		idCompressor,
 		defaultIncrementalEncodingPolicy,
@@ -156,18 +194,55 @@ export function independentInitializedViewInternal<const TSchema extends Implici
 		breaker,
 	});
 
-	initialize(
-		checkout,
-		schema,
-		initializerFromChunk(checkout, () =>
-			combineChunks(checkout.forest.chunkField(rootFieldCursor)),
-		),
-	);
-	return new SchematizingSimpleTreeView<TSchema>(
-		checkout,
-		config,
-		createNodeIdentifierManager(idCompressor),
-	);
+	if (options?.content !== undefined) {
+		const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
+		const fieldBatchCodec = makeFieldBatchCodec(options, 1);
+		const newSchema = schemaCodec.decode(options.content.schema as Format);
+
+		const context: FieldBatchEncodingContext = {
+			encodeType: TreeCompressionStrategy.Compressed,
+			idCompressor,
+			originatorId: idCompressor.localSessionId, // Is this right? If so, why is is needed?
+			schema: { schema: newSchema, policy: defaultSchemaPolicy },
+		};
+		const fieldCursors = fieldBatchCodec.decode(
+			options.content.tree as JsonCompatibleReadOnly,
+			context,
+		);
+		assert(fieldCursors.length === 1, 0xa5b /* must have exactly 1 field in batch */);
+
+		const fieldCursor = oneFromIterable(fieldCursors);
+		assert(fieldCursor !== undefined, "expected exactly one field in batch");
+
+		initialize(
+			checkout,
+			newSchema,
+			initializerFromChunk(checkout, () =>
+				combineChunks(checkout.forest.chunkField(fieldCursor)),
+			),
+		);
+	}
+
+	return {
+		viewWith<TRoot extends ImplicitFieldSchema>(
+			config: TreeViewConfiguration<TRoot>,
+		): TreeView<TRoot> {
+			const out: TreeViewAlpha<TSchema> = new SchematizingSimpleTreeView<TSchema>(
+				checkout,
+				config as TreeViewConfiguration as TreeViewConfiguration<ReadSchema<TSchema>>,
+				createNodeIdentifierManager(idCompressor),
+			);
+			return out as unknown as TreeView<TRoot>;
+		},
+
+		exportVerbose(): VerboseTree | undefined {
+			return checkout.exportVerbose();
+		},
+
+		exportSimpleSchema(): SimpleTreeSchema {
+			return exportSimpleSchema(checkout.storedSchema);
+		},
+	};
 }
 
 /**

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

@@ -39,6 +39,8 @@ export {
 
 export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 
+export { initialize, initializerFromChunk } from "./schematizeTree.js";
+
 export type {
 	ISharedTreeEditor,
 	ISchemaEditor,
@@ -58,6 +60,8 @@ export {
 	independentInitializedView,
 	type ViewContent,
 	independentView,
+	createIndependentTreeBeta,
+	createIndependentTreeAlpha,
 } from "./independentView.js";
 
 export type { SharedTreeChange } from "./sharedTreeChangeTypes.js";