@fluidframework/tree 2.4.0-297385 → 2.4.0-299707

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.4.0-297385",
+  "version": "2.4.0-299707",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -71,11 +71,13 @@
     "cache-dir": "nyc/.cache",
     "exclude": [
       "src/test/**/*.*ts",
+      "dist/test/**/*.*js",
       "lib/test/**/*.*js"
     ],
     "exclude-after-remap": false,
     "include": [
       "src/**/*.*ts",
+      "dist/**/*.*js",
       "lib/**/*.*js"
     ],
     "report-dir": "nyc/report",
@@ -87,38 +89,38 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.4.0-297385",
-    "@fluidframework/container-runtime": "2.4.0-297385",
-    "@fluidframework/core-interfaces": "2.4.0-297385",
-    "@fluidframework/core-utils": "2.4.0-297385",
-    "@fluidframework/datastore-definitions": "2.4.0-297385",
-    "@fluidframework/driver-definitions": "2.4.0-297385",
-    "@fluidframework/id-compressor": "2.4.0-297385",
-    "@fluidframework/runtime-definitions": "2.4.0-297385",
-    "@fluidframework/runtime-utils": "2.4.0-297385",
-    "@fluidframework/shared-object-base": "2.4.0-297385",
-    "@fluidframework/telemetry-utils": "2.4.0-297385",
+    "@fluid-internal/client-utils": "2.4.0-299707",
+    "@fluidframework/container-runtime": "2.4.0-299707",
+    "@fluidframework/core-interfaces": "2.4.0-299707",
+    "@fluidframework/core-utils": "2.4.0-299707",
+    "@fluidframework/datastore-definitions": "2.4.0-299707",
+    "@fluidframework/driver-definitions": "2.4.0-299707",
+    "@fluidframework/id-compressor": "2.4.0-299707",
+    "@fluidframework/runtime-definitions": "2.4.0-299707",
+    "@fluidframework/runtime-utils": "2.4.0-299707",
+    "@fluidframework/shared-object-base": "2.4.0-299707",
+    "@fluidframework/telemetry-utils": "2.4.0-299707",
     "@sinclair/typebox": "^0.32.29",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@ungap/structured-clone": "^1.2.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.15.2",
+    "@arethetypeswrong/cli": "^0.16.4",
     "@biomejs/biome": "~1.8.3",
-    "@fluid-internal/mocha-test-setup": "2.4.0-297385",
-    "@fluid-private/stochastic-test-utils": "2.4.0-297385",
-    "@fluid-private/test-dds-utils": "2.4.0-297385",
-    "@fluid-private/test-drivers": "2.4.0-297385",
+    "@fluid-internal/mocha-test-setup": "2.4.0-299707",
+    "@fluid-private/stochastic-test-utils": "2.4.0-299707",
+    "@fluid-private/test-dds-utils": "2.4.0-299707",
+    "@fluid-private/test-drivers": "2.4.0-299707",
     "@fluid-tools/benchmark": "^0.50.0",
-    "@fluid-tools/build-cli": "^0.46.0",
+    "@fluid-tools/build-cli": "^0.48.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.46.0",
-    "@fluidframework/container-definitions": "2.4.0-297385",
-    "@fluidframework/container-loader": "2.4.0-297385",
+    "@fluidframework/build-tools": "^0.48.0",
+    "@fluidframework/container-definitions": "2.4.0-299707",
+    "@fluidframework/container-loader": "2.4.0-299707",
     "@fluidframework/eslint-config-fluid": "^5.4.0",
-    "@fluidframework/test-runtime-utils": "2.4.0-297385",
-    "@fluidframework/test-utils": "2.4.0-297385",
+    "@fluidframework/test-runtime-utils": "2.4.0-299707",
+    "@fluidframework/test-utils": "2.4.0-299707",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@~2.3.0",
     "@microsoft/api-extractor": "7.47.8",
     "@types/diff": "^3.5.1",
@@ -139,7 +141,6 @@
     "eslint": "~8.55.0",
     "eslint-config-prettier": "~9.0.0",
     "mocha": "^10.2.0",
-    "mocha-json-output-reporter": "^2.0.1",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
     "prettier": "~3.0.3",
@@ -242,7 +243,7 @@
     "test:mocha:esm": "mocha",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
     "test:snapshots:regen": "pnpm test:mocha:esm --snapshot",
-    "test:stress": "cross-env FUZZ_TEST_COUNT=20 FUZZ_STRESS_RUN=true mocha --ignore \"lib/test/memory/**/*\" --recursive \"lib/test/**/*.spec.js\"",
+    "test:stress": "cross-env FUZZ_TEST_COUNT=20 FUZZ_STRESS_RUN=normal mocha --ignore \"lib/test/memory/**/*\" --recursive \"lib/test/**/*.spec.js\"",
     "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
     "typetests:gen": "flub generate typetests --dir . -v",
     "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"

package/src/codec/codec.ts

@@ -35,18 +35,18 @@ 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> {
 	/**
-	 * @returns Whether the data matches a schema.
+	 * Returns whether the data matches a schema.
 	 */
 	check(data: unknown): data is Static<Schema>;
 }
 
 /**
  * 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 {
 	/**

package/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 }),

package/src/core/tree/anchorSet.ts

@@ -233,6 +233,13 @@ export interface AnchorNode extends UpPath<AnchorNode>, Listenable<AnchorEvents>
 	 */
 	child(key: FieldKey, index: number): UpPath<AnchorNode>;
 
+	/**
+	 * Gets the child AnchorNode if already exists.
+	 *
+	 * Does NOT add a ref, so the returned AnchorNode must be used with care.
+	 */
+	childIfAnchored(key: FieldKey, index: number): AnchorNode | undefined;
+
 	/**
 	 * Gets a child AnchorNode (creating it if needed), and an Anchor owning a ref to it.
 	 * Caller is responsible for freeing the returned Anchor, and must not use the AnchorNode after that.
@@ -413,8 +420,10 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 
 	/**
 	 * Finds a path node if it already exists.
+	 *
+	 * Does not add a ref!
 	 */
-	private find(path: UpPath): PathNode | undefined {
+	public find(path: UpPath): PathNode | undefined {
 		if (path instanceof PathNode) {
 			if (path.anchorSet === this) {
 				return path;
@@ -422,7 +431,7 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 		}
 		const parent = path.parent ?? this.root;
 		const parentPath = this.find(parent);
-		return parentPath?.tryGetChild(path.parentField, path.parentIndex);
+		return parentPath?.childIfAnchored(path.parentField, path.parentIndex);
 	}
 
 	/**
@@ -452,7 +461,7 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 		while ((wrapWith = stack.pop()) !== undefined) {
 			if (path === undefined || path instanceof PathNode) {
 				// If path already has an anchor, get an anchor for it's child if there is one:
-				const child = (path ?? this.root).tryGetChild(
+				const child = (path ?? this.root).childIfAnchored(
 					wrapWith.parentField,
 					wrapWith.parentIndex,
 				);
@@ -1210,7 +1219,11 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 	public child(key: FieldKey, index: number): UpPath<AnchorNode> {
 		// Fast path: if child exists, return it.
 		return (
-			this.tryGetChild(key, index) ?? { parent: this, parentField: key, parentIndex: index }
+			this.childIfAnchored(key, index) ?? {
+				parent: this,
+				parentField: key,
+				parentIndex: index,
+			}
 		);
 	}
 
@@ -1271,8 +1284,7 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 			field = [];
 			this.children.set(key, field);
 		}
-		// TODO: should do more optimized search (ex: binary search).
-		let child = field.find((c) => c.parentIndex === index);
+		let child = binaryFind(field, index);
 		if (child === undefined) {
 			child = new PathNode(this.anchorSet, key, index, this);
 			field.push(child);
@@ -1284,16 +1296,11 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 		return child;
 	}
 
-	/**
-	 * Gets a child if it exists.
-	 * Does NOT add a ref.
-	 */
-	public tryGetChild(key: FieldKey, index: number): PathNode | undefined {
+	public childIfAnchored(key: FieldKey, index: number): PathNode | undefined {
 		assert(this.status === Status.Alive, 0x40d /* PathNode must be alive */);
 		const field = this.children.get(key);
 
-		// TODO: should do more optimized search (ex: binary search or better) using index.
-		return field?.find((c) => c.parentIndex === index);
+		return field === undefined ? undefined : binaryFind(field, index);
 	}
 
 	/**
@@ -1343,3 +1350,46 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 		}
 	}
 }
+
+/**
+ * Find a child PathNode by index using a binary search.
+ * @param sorted - array of PathNode's sorted by parentIndex.
+ * @param index - index being looked for.
+ * @returns child with the requested parentIndex, or undefined.
+ * @privateRemarks
+ * This function is very commonly used with small arrays (length 0 or one for all non sequence fields),
+ * and is currently a hot path due to how flex tree leaves to excessive cursor to anchor and anchor to cursor translations,
+ * both of which walk paths down the AnchorSet.
+ * Additionally current usages tends to fully populate the anchor tree leading the correct array index to be the requested parent index.
+ * This makes the performance of this performance both important in small cases and easy to overly tune to the current usage patterns.
+ * This lead to not implementing a general purpose reusable binary search.
+ * Once this function is not so heavily overused due to inefficient patterns in flex-tree,
+ * replacing it with a standard binary search is likely fine.
+ * Until then, care and benchmarking should be used when messing with this function.
+ */
+function binaryFind(sorted: readonly PathNode[], index: number): PathNode | undefined {
+	// Try guessing the list is not sparse as a starter:
+	const guess = sorted[index];
+	if (guess !== undefined && guess.parentIndex === index) {
+		return guess;
+	}
+
+	// inclusive
+	let min = 0;
+	// exclusive
+	let max = sorted.length;
+
+	while (min !== max) {
+		const mid = Math.floor((min + max) / 2);
+		const item = sorted[mid]!;
+		const found = item.parentIndex;
+		if (found === index) {
+			return item; // Found the target, return it.
+		} else if (found > index) {
+			max = mid; // Continue search on lower half.
+		} else {
+			min = mid + 1; // Continue search on left half.
+		}
+	}
+	return undefined; // If we reach here, target is not in array (or array was not sorted)
+}

package/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) => {

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -4,8 +4,10 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
+	type AnchorNode,
 	CursorLocationType,
 	type ExclusiveMapTree,
 	type FieldAnchor,
@@ -51,9 +53,7 @@ import {
 	tryMoveCursorToAnchorSymbol,
 } from "./lazyEntity.js";
 import { type LazyTreeNode, makeTree } from "./lazyNode.js";
-import { unboxedFlexNode } from "./unboxed.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { cursorForMapTreeField, cursorForMapTreeNode } from "../mapTreeCursor.js";
 
 /**
@@ -196,7 +196,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 
 	public atIndex(index: number): FlexTreeUnknownUnboxed {
 		return inCursorNode(this[cursorSymbol], index, (cursor) =>
-			unboxedFlexNode(this.context, cursor),
+			unboxedFlexNode(this.context, cursor, this[anchorSymbol]),
 		);
 	}
 
@@ -222,7 +222,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 
 	public [Symbol.iterator](): IterableIterator<FlexTreeUnknownUnboxed> {
 		return iterateCursorField(this[cursorSymbol], (cursor) =>
-			unboxedFlexNode(this.context, cursor),
+			unboxedFlexNode(this.context, cursor, this[anchorSymbol]),
 		);
 	}
 
@@ -259,9 +259,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 			return undefined;
 		}
 
-		return inCursorNode(this[cursorSymbol], finalIndex, (cursor) =>
-			unboxedFlexNode(this.context, cursor),
-		);
+		return this.atIndex(finalIndex);
 	}
 	public get asArray(): readonly FlexTreeUnknownUnboxed[] {
 		return this.map((x) => x);
@@ -352,3 +350,42 @@ const builderList: [FieldKindIdentifier, Builder][] = [
 ];
 
 const kindToClass: ReadonlyMap<FieldKindIdentifier, Builder> = new Map(builderList);
+
+/**
+ * Returns the flex tree node, or the value if it has one.
+ */
+export function unboxedFlexNode(
+	context: Context,
+	cursor: ITreeSubscriptionCursor,
+	fieldAnchor: FieldAnchor,
+): FlexTreeUnknownUnboxed {
+	const value = cursor.value;
+	if (value !== undefined) {
+		return value;
+	}
+
+	// Try accessing cached child node via anchors.
+	// This avoids O(depth) related costs from makeTree in the cached case.
+	const anchor = fieldAnchor.parent;
+	let child: AnchorNode | undefined;
+	if (anchor !== undefined) {
+		const anchorNode = context.checkout.forest.anchors.locate(anchor);
+		assert(anchorNode !== undefined, "missing anchor");
+		child = anchorNode.childIfAnchored(fieldAnchor.fieldKey, cursor.fieldIndex);
+	} else {
+		child = context.checkout.forest.anchors.find({
+			parent: undefined,
+			parentField: fieldAnchor.fieldKey,
+			parentIndex: cursor.fieldIndex,
+		});
+	}
+
+	if (child !== undefined) {
+		const cached = child.slots.get(flexTreeSlot);
+		if (cached !== undefined) {
+			return cached;
+		}
+	}
+
+	return makeTree(context, cursor);
+}

package/src/feature-libraries/index.ts

@@ -79,16 +79,6 @@ export {
 	isNeverTree,
 } from "./modular-schema/index.js";
 
-export {
-	type Unenforced,
-	markEager,
-	type LazyItem,
-	type FlexListToUnion,
-	type ExtractItemType,
-	isLazy,
-	type FlexList,
-} from "./typed-schema/index.js";
-
 export { mapRootChanges } from "./deltaUtils.js";
 
 export {

package/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 {
 	/**

package/src/index.ts

@@ -40,9 +40,7 @@ export {
 } from "./events/index.js";
 
 export {
-	type LazyItem,
 	TreeStatus,
-	type Unenforced,
 	TreeCompressionStrategy,
 } from "./feature-libraries/index.js";
 
@@ -58,6 +56,7 @@ export {
 	type NodeInDocumentConstraint,
 	type RunTransaction,
 	rollback,
+	type ForestOptions,
 	getBranch,
 	type TreeBranch,
 	type TreeBranchFork,
@@ -121,12 +120,11 @@ export {
 	// Recursive Schema APIs
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
-	// experimental @internal APIs:
+	// experimental @alpha APIs:
 	adaptEnum,
 	enumFromStrings,
 	singletonSchema,
 	typedObjectValues,
-	type EmptyObject,
 	// test recursive schema for checking that d.ts files handles schema correctly
 	test_RecursiveObject,
 	test_RecursiveObject_base,
@@ -134,6 +132,8 @@ export {
 	// Beta APIs
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	extractPersistedSchema,
+	comparePersistedSchema,
 	// Back to normal types
 	type JsonTreeSchema,
 	type JsonSchemaId,
@@ -149,10 +149,19 @@ export {
 	type JsonSchemaType,
 	type JsonLeafSchemaType,
 	getJsonSchema,
+	type LazyItem,
+	type Unenforced,
 } 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";
 
@@ -177,3 +186,5 @@ export {
 // These would be put in `internalTypes` except doing so tents to cause errors like:
 // The inferred type of 'NodeMap' cannot be named without a reference to '../../node_modules/@fluidframework/tree/lib/internalTypes.js'. This is likely not portable. A type annotation is necessary.
 export type { MapNodeInsertableData } from "./simple-tree/index.js";
+
+export type { JsonCompatible, JsonCompatibleObject } from "./util/index.js";

package/src/internalTypes.ts

@@ -34,6 +34,6 @@ export type {
 	NodeFromSchemaUnsafe,
 	ReadonlyMapInlined,
 } from "./simple-tree/index.js";
-export type { FlexList, FlexListToUnion, ExtractItemType } from "./feature-libraries/index.js";
+export type { FlexList, FlexListToUnion, ExtractItemType } from "./simple-tree/index.js";
 
 export type { TreeApi } from "./shared-tree/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.4.0-297385";
+export const pkgVersion = "2.4.0-299707";

package/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";

package/src/shared-tree/schematizingTreeView.ts

@@ -41,6 +41,7 @@ import {
 	type TreeViewConfiguration,
 	mapTreeFromNodeData,
 	prepareContentForHydration,
+	comparePersistedSchemaInternal,
 	toStoredSchema,
 } from "../simple-tree/index.js";
 import { Breakable, breakingClass, disposeSymbol, type WithBreakable } from "../util/index.js";
@@ -225,22 +226,12 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 	private update(): void {
 		this.disposeView();
 
-		const result = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
-
-		// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
-		// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
-		// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
-		// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
-		const canView =
-			result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
-		const canUpgrade = result.read === Compatibility.Compatible;
-		const isEquivalent = canView && canUpgrade;
-		const compatibility: SchemaCompatibilityStatus = {
-			canView,
-			canUpgrade,
-			isEquivalent,
-			canInitialize: canInitialize(this.checkout),
-		};
+		const compatibility = comparePersistedSchemaInternal(
+			this.checkout.storedSchema,
+			this.viewSchema,
+			canInitialize(this.checkout),
+		);
+
 		let lastRoot =
 			this.compatibility.canView && this.view !== undefined ? this.root : undefined;
 		this.currentCompatibility = compatibility;