tree: Add alpha tree configuration APIs

.changeset/clever-dancers-post.md

@@ -0,0 +1,32 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+---
+---
+"section": tree
+---
+
+Add alpha API for providing SharedTree configuration options
+
+A new alpha `configuredSharedTree` had been added.
+This allows providing configuration options, primarily for debugging, testing and evaluation of upcoming features.
+The resulting configured `SharedTree` object can then be used in-place of the regular `SharedTree` imported from `fluid-framework`.
+
+```typescript
+import {
+	ForestType,
+	TreeCompressionStrategy,
+	configuredSharedTree,
+	typeboxValidator,
+} from "@fluid-framework/alpha";
+// Maximum debuggability and validation enabled:
+const SharedTree = configuredSharedTree({
+	forest: ForestType.Expensive,
+	jsonValidator: typeboxValidator,
+	treeEncodeType: TreeCompressionStrategy.Uncompressed,
+});
+// Opts into the under development optimized tree storage planned to be the eventual default implementation:
+const SharedTree = configuredSharedTree({
+	forest: ForestType.Optimized,
+});
+```

.vscode/settings.json

@@ -34,6 +34,7 @@
 	"cSpell.words": [
 		"boop",
 		"contoso",
+		"debuggability",
 		"denormalized",
 		"endregion",
 		"fluidframework",

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

@@ -92,6 +92,18 @@ type FlexList<Item = unknown> = readonly LazyItem<Item>[];
 // @public
 type FlexListToUnion<TList extends FlexList> = ExtractItemType<TList[number]>;
 
+// @alpha
+export interface ForestOptions {
+    readonly forest?: ForestType;
+}
+
+// @alpha
+export enum ForestType {
+    Expensive = 2,
+    Optimized = 1,
+    Reference = 0
+}
+
 // @alpha
 export function getBranch(tree: ITree): TreeBranch;
 
@@ -101,6 +113,11 @@ export function getBranch(view: TreeView<ImplicitFieldSchema>): TreeBranch;
 // @alpha
 export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;
 
+// @alpha
+export interface ICodecOptions {
+    readonly jsonValidator: JsonValidator;
+}
+
 // @public
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 
@@ -272,6 +289,11 @@ export type JsonTreeSchema = JsonFieldSchema & {
     readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
 };
 
+// @alpha
+export interface JsonValidator {
+    compile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;
+}
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -325,6 +347,9 @@ export enum NodeKind {
     Object = 2
 }
 
+// @alpha
+export const noopValidator: JsonValidator;
+
 // @public
 type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> = {
     -readonly [Property in keyof T]: Property extends string ? TreeFieldFromImplicitField<T[Property]> : unknown;
@@ -443,9 +468,34 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly string: TreeNodeSchema<"com.fluidframework.leaf.string", NodeKind.Leaf, string, string>;
 }
 
+// @alpha
+export interface SchemaValidationFunction<Schema extends TSchema> {
+    // (undocumented)
+    check(data: unknown): data is Static<Schema>;
+}
+
 // @public
 type ScopedSchemaName<TScope extends string | undefined, TName extends number | string> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;
 
+// @alpha
+export interface SharedTreeFormatOptions {
+    formatVersion: SharedTreeFormatVersion[keyof SharedTreeFormatVersion];
+    treeEncodeType: TreeCompressionStrategy;
+}
+
+// @alpha
+export const SharedTreeFormatVersion: {
+    readonly v1: 1;
+    readonly v2: 2;
+    readonly v3: 3;
+};
+
+// @alpha
+export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
+
+// @alpha
+export type SharedTreeOptions = Partial<ICodecOptions> & Partial<SharedTreeFormatOptions> & ForestOptions;
+
 // @public
 export type TransactionConstraint = NodeInDocumentConstraint;
 
@@ -522,6 +572,12 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode> extends
     nodeChanged: (data: NodeChangedData<TNode> & (TNode extends WithType<string, NodeKind.Map | NodeKind.Object> ? Required<Pick<NodeChangedData<TNode>, "changedProperties">> : unknown)) => void;
 }
 
+// @alpha
+export enum TreeCompressionStrategy {
+    Compressed = 0,
+    Uncompressed = 1
+}
+
 // @public
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> = TSchema extends FieldSchema<infer Kind, infer Types> ? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind, false> : TSchema extends ImplicitAllowedTypes ? TreeNodeFromImplicitAllowedTypes<TSchema> : unknown;
 
@@ -641,6 +697,9 @@ export interface TreeViewEvents {
     schemaChanged(): void;
 }
 
+// @alpha
+export const typeboxValidator: JsonValidator;
+
 // @public @deprecated
 const typeNameSymbol: unique symbol;
 

packages/dds/tree/src/codec/codec.ts

@@ -35,7 +35,7 @@ export interface IDecoder<TDecoded, TEncoded, TContext> {
 /**
  * Validates data complies with some particular schema.
  * Implementations are typically created by a {@link JsonValidator}.
- * @internal
+ * @alpha
  */
 export interface SchemaValidationFunction<Schema extends TSchema> {
 	/**
@@ -46,7 +46,7 @@ export interface SchemaValidationFunction<Schema extends TSchema> {
 
 /**
  * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
- * @internal
+ * @alpha
  */
 export interface JsonValidator {
 	/**
@@ -63,7 +63,7 @@ export interface JsonValidator {
 
 /**
  * Options relating to handling of persisted data.
- * @internal
+ * @alpha
  */
 export interface ICodecOptions {
 	/**

packages/dds/tree/src/codec/noopValidator.ts

@@ -11,7 +11,7 @@ import type { JsonValidator } from "./codec.js";
  * A {@link JsonValidator} implementation which performs no validation and accepts all data as valid.
  * @privateRemarks Having this as an option unifies opting out of validation with selection of
  * validators, simplifying code performing validation.
- * @internal
+ * @alpha
  */
 export const noopValidator: JsonValidator = {
 	compile: <Schema extends TSchema>() => ({ check: (data): data is Static<Schema> => true }),

packages/dds/tree/src/external-utilities/typeboxValidator.ts

@@ -19,7 +19,7 @@ import type { JsonValidator } from "../codec/index.js";
  *
  * Defining this validator in its own file also helps to ensure it is tree-shakeable.
  *
- * @internal
+ * @alpha
  */
 export const typeboxValidator: JsonValidator = {
 	compile: <Schema extends TSchema>(schema: Schema) => {

packages/dds/tree/src/feature-libraries/treeCompressionUtils.ts

@@ -7,7 +7,7 @@
  * Selects which heuristics to use when encoding tree content.
  * All encoding options here are compatible with the same decoder:
  * the selection here does not impact compatibility.
- * @internal
+ * @alpha
  */
 export enum TreeCompressionStrategy {
 	/**

packages/dds/tree/src/index.ts

@@ -58,6 +58,7 @@ export {
 	type NodeInDocumentConstraint,
 	type RunTransaction,
 	rollback,
+	type ForestOptions,
 	getBranch,
 	type TreeBranch,
 	type TreeBranchFork,
@@ -150,9 +151,16 @@ export {
 	type JsonLeafSchemaType,
 	getJsonSchema,
 } from "./simple-tree/index.js";
-export { SharedTree, configuredSharedTree } from "./treeFactory.js";
+export {
+	SharedTree,
+	configuredSharedTree,
+} from "./treeFactory.js";
 
-export type { ICodecOptions, JsonValidator, SchemaValidationFunction } from "./codec/index.js";
+export type {
+	ICodecOptions,
+	JsonValidator,
+	SchemaValidationFunction,
+} from "./codec/index.js";
 export { noopValidator } from "./codec/index.js";
 export { typeboxValidator } from "./external-utilities/index.js";
 

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

@@ -13,6 +13,9 @@ export {
 	type SharedTreeContentSnapshot,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
+	buildConfiguredForest,
+	defaultSharedTreeOptions,
+	type ForestOptions,
 } from "./sharedTree.js";
 
 export {
@@ -29,6 +32,8 @@ export {
 
 export { type TreeStoredContent } from "./schematizeTree.js";
 
+export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
+
 export { CheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
 
 export type { ISharedTreeEditor, ISchemaEditor } from "./sharedTreeEditBuilder.js";

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IChannelFactory,
@@ -16,10 +16,12 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type ICodecOptions, noopValidator } from "../codec/index.js";
 import {
+	type IEditableForest,
 	type JsonableTree,
 	RevisionTagCodec,
 	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
+	type TreeStoredSchemaSubscription,
 	makeDetachedFieldIndex,
 	moveToDetachedField,
 } from "../core/index.js";
@@ -66,6 +68,7 @@ import {
 	createTreeCheckout,
 } from "./treeCheckout.js";
 import { breakingClass, throwIfBroken } from "../util/index.js";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * Copy of data from an {@link ISharedTree} at some point in time.
@@ -149,6 +152,27 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
+export function buildConfiguredForest(
+	type: ForestType,
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+): IEditableForest {
+	switch (type) {
+		case ForestType.Optimized:
+			return buildChunkedForest(
+				makeTreeChunker(schema, defaultSchemaPolicy),
+				undefined,
+				idCompressor,
+			);
+		case ForestType.Reference:
+			return buildForest();
+		case ForestType.Expensive:
+			return buildForest(undefined, true);
+		default:
+			unreachableCase(type);
+	}
+}
+
 /**
  * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
@@ -181,16 +205,7 @@ export class SharedTree
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest =
-			options.forest === ForestType.Optimized
-				? buildChunkedForest(
-						makeTreeChunker(schema, defaultSchemaPolicy),
-						undefined,
-						runtime.idCompressor,
-					)
-				: options.forest === ForestType.Reference
-					? buildForest()
-					: buildForest(undefined, true);
+		const forest = buildConfiguredForest(options.forest, schema, runtime.idCompressor);
 		const revisionTagCodec = new RevisionTagCodec(runtime.idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
@@ -348,7 +363,7 @@ export function getBranch(treeOrView: ITree | TreeView<ImplicitFieldSchema>): Tr
  * Format versions supported by SharedTree.
  *
  * Each version documents a required minimum version of the \@fluidframework/tree package.
- * @internal
+ * @alpha
  */
 export const SharedTreeFormatVersion = {
 	/**
@@ -374,26 +389,34 @@ export const SharedTreeFormatVersion = {
  * Format versions supported by SharedTree.
  *
  * Each version documents a required minimum version of the \@fluidframework/tree package.
- * @internal
+ * @alpha
  * @privateRemarks
  * See packages/dds/tree/docs/main/compatibility.md for information on how to add support for a new format.
  */
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
 /**
- * @internal
+ * Configuration options for SharedTree.
+ * @alpha
  */
 export type SharedTreeOptions = Partial<ICodecOptions> &
-	Partial<SharedTreeFormatOptions> & {
-		/**
-		 * The {@link ForestType} indicating which forest type should be created for the SharedTree.
-		 */
-		forest?: ForestType;
-	};
+	Partial<SharedTreeFormatOptions> &
+	ForestOptions;
+
+/**
+ * Configuration options for SharedTree's internal tree storage.
+ * @alpha
+ */
+export interface ForestOptions {
+	/**
+	 * The {@link ForestType} indicating which forest type should be created for the SharedTree.
+	 */
+	readonly forest?: ForestType;
+}
 
 /**
  * Options for configuring the persisted format SharedTree uses.
- * @internal
+ * @alpha
  */
 export interface SharedTreeFormatOptions {
 	/**
@@ -417,7 +440,7 @@ export interface SharedTreeFormatOptions {
 
 /**
  * Used to distinguish between different forest types.
- * @internal
+ * @alpha
  */
 export enum ForestType {
 	/**

packages/dds/tree/src/treeFactory.ts

@@ -81,6 +81,7 @@ export const SharedTree = configuredSharedTree({});
  * });
  * ```
  * @privateRemarks
+ * This should be legacy, but has to be internal due to limitations of API tagging preventing it from being both alpha and alpha+legacy.
  * TODO:
  * Expose Ajv validator for better error message quality somehow.
  * Maybe as part of a test utils or dev-tool package?