@fluidframework/tree 2.41.0-338401 → 2.42.0

package/src/shared-tree-core/branchCommitEnricher.ts

@@ -4,15 +4,17 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+
 import {
 	type ChangeRebaser,
 	type GraphCommit,
 	replaceChange,
 	type RevisionTag,
 } from "../core/index.js";
+
+import type { SharedTreeBranchChange } from "./branch.js";
 import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
 import { TransactionEnricher } from "./transactionEnricher.js";
-import type { SharedTreeBranchChange } from "./branch.js";
 
 /**
  * Utility for enriching commits from a {@link Branch} before these commits are applied and submitted.

package/src/shared-tree-core/defaultResubmitMachine.ts

@@ -4,8 +4,10 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
+
 import type { GraphCommit, TaggedChange } from "../core/index.js";
 import { disposeSymbol, hasSome } from "../util/index.js";
+
 import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
 
 /**

package/src/shared-tree-core/editManager.ts

@@ -627,8 +627,10 @@ export class EditManager<
 	}
 
 	/**
-	 * @returns The length of the longest branch maintained by this EditManager.
+	 * Gets the length of the longest branch maintained by this `EditManager`.
 	 * This may be the length of a peer branch or the local branch.
+	 *
+	 * @remarks
 	 * The length is counted from the lowest common ancestor with the trunk such that a fully sequenced branch would
 	 * have length zero.
 	 */
@@ -825,7 +827,7 @@ export interface SummaryData<TChangeset> {
 }
 
 /**
- * @returns the path from the base of a branch to its head
+ * Gets the path from the base of a branch to its head.
  */
 function getPathFromBase<TCommit extends { parent?: TCommit }>(
 	branchHead: TCommit,

package/src/shared-tree-core/editManagerCodecs.ts

@@ -4,6 +4,7 @@
  */
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+
 import {
 	type ICodecFamily,
 	type ICodecOptions,

package/src/shared-tree-core/editManagerSummarizer.ts

@@ -6,6 +6,7 @@
 import { bufferToString } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type {
 	ISummaryTreeWithStats,
 	ITelemetryContext,
@@ -23,7 +24,6 @@ import type {
 	SummaryElementParser,
 	SummaryElementStringifier,
 } from "./sharedTreeCore.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 const stringKey = "String";
 

package/src/shared-tree-core/messageCodecs.ts

@@ -52,7 +52,7 @@ export function makeMessageCodec<TChangeset>(
 }
 
 /**
- * @privateRemarks - Exported for testing.
+ * @privateRemarks Exported for testing.
  */
 export function makeMessageCodecs<TChangeset>(
 	changeCodecs: ICodecFamily<TChangeset, ChangeEncodingContext>,

package/src/shared-tree-core/sequenceIdUtils.ts

@@ -4,6 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+
 import { brand } from "../util/index.js";
 
 import type { SequenceId } from "./editManagerFormat.js";

package/src/shared-tree-core/sharedTreeCore.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { IFluidLoadable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
@@ -17,6 +18,7 @@ import type {
 	IChannelView,
 	IFluidSerializer,
 } from "@fluidframework/shared-object-base/internal";
+import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
 
 import type { ICodecOptions, IJsonCodec } from "../codec/index.js";
 import {
@@ -41,18 +43,16 @@ import {
 } from "../util/index.js";
 
 import type { SharedTreeBranch } from "./branch.js";
+import { BranchCommitEnricher } from "./branchCommitEnricher.js";
+import { type ChangeEnricherReadonlyCheckout, NoOpChangeEnricher } from "./changeEnricher.js";
+import { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
 import { makeEditManagerCodec } from "./editManagerCodecs.js";
 import type { SeqNumber } from "./editManagerFormat.js";
 import { EditManagerSummarizer } from "./editManagerSummarizer.js";
 import { type MessageEncodingContext, makeMessageCodec } from "./messageCodecs.js";
 import type { DecodedMessage } from "./messageTypes.js";
-import { type ChangeEnricherReadonlyCheckout, NoOpChangeEnricher } from "./changeEnricher.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
-import { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
-import { BranchCommitEnricher } from "./branchCommitEnricher.js";
-import { createChildLogger } from "@fluidframework/telemetry-utils/internal";
-import type { IFluidLoadable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 
 // TODO: Organize this to be adjacent to persisted types.
 const summarizablesTreeKey = "indexes";

package/src/shared-tree-core/transaction.ts

@@ -3,19 +3,21 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { IDisposable, Listenable } from "@fluidframework/core-interfaces";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import {
 	findAncestor,
 	type ChangeFamilyEditor,
 	type GraphCommit,
 	type TaggedChange,
 } from "../core/index.js";
-import type { SharedTreeBranch, SharedTreeBranchEvents } from "./branch.js";
 import { getOrCreate } from "../util/index.js";
 
+import type { SharedTreeBranch, SharedTreeBranchEvents } from "./branch.js";
+
 /**
  * Describes the result of a transaction.
  * Transactions may either succeed and commit, or fail and abort.

package/src/shared-tree-core/transactionEnricher.ts

@@ -4,7 +4,9 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+
 import type { ChangeRebaser, GraphCommit, RevisionTag } from "../core/index.js";
+
 import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
 
 /**

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

@@ -6,15 +6,16 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
 import type { ITreeCursor } from "../../core/index.js";
-import type { TreeLeafValue, ImplicitAllowedTypes } from "../schemaTypes.js";
 import type { TreeNodeSchema } from "../core/index.js";
+import { getUnhydratedContext } from "../createContext.js";
+import type { TreeLeafValue, ImplicitAllowedTypes } from "../schemaTypes.js";
+
 import {
 	customFromCursor,
 	replaceHandles,
 	type TreeEncodingOptions,
 	type HandleConverter,
 } from "./customTree.js";
-import { getUnhydratedContext } from "../createContext.js";
 
 /**
  * Concise encoding of a {@link TreeNode} or {@link TreeLeafValue}.

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

@@ -16,7 +16,7 @@ import {
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
+import { isObjectNodeSchema, type ObjectNodeSchema } from "../node-kinds/index.js";
 import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -107,8 +107,8 @@ export interface ITreeConfigurationOptions {
 	 *
 	 * To make this more permissive in the future we can:
 	 *
-	 * - Make toMapTree more permissive (ex: allow disambiguation based on leaf type)
-	 * - Update this check to more tightly match toMapTree
+	 * - Make unhydratedFlexTreeFromInsertable more permissive (ex: allow disambiguation based on leaf type)
+	 * - Update this check to more tightly match unhydratedFlexTreeFromInsertable
 	 * - Add options to help schema authors disambiguate their types, such as "constant fields" which are not persisted, and always have a constant value.
 	 *
 	 * The above examples exist in executable form in this files tests, and should be updated there then copied back here.
@@ -343,7 +343,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 			// Allow using the type of the field to disambiguate, at least for leaf types.
 			// Add "constant" fields which can be used to disambiguate even more cases without adding persisted data: maybe make them optional in constructor?
 			// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).
-			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/toMapTree.ts.
+			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/unhydratedFlexTreeFromInsertable.ts.
 
 			errors.push(
 				`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,

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

@@ -5,112 +5,46 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import type {
-	ExclusiveMapTree,
-	ITreeCursorSynchronous,
-	SchemaAndPolicy,
+import {
+	CursorLocationType,
+	mapCursorField,
+	mapCursorFields,
+	type ITreeCursorSynchronous,
+	type SchemaAndPolicy,
 } from "../../core/index.js";
-import type {
-	ImplicitFieldSchema,
-	TreeFieldFromImplicitField,
-	FieldSchema,
-	FieldKind,
-	UnsafeUnknownSchema,
-	InsertableField,
-	TreeLeafValue,
-} from "../schemaTypes.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
 import {
+	type Context,
 	getOrCreateNodeFromInnerNode,
-	UnhydratedFlexTreeNode,
-	type TreeNode,
+	type NodeKind,
 	type Unhydrated,
+	UnhydratedFlexTreeNode,
+	createField,
 } from "../core/index.js";
 import {
-	cursorForMapTreeNode,
 	defaultSchemaPolicy,
 	inSchemaOrThrow,
-	mapTreeFromCursor,
-	type NodeIdentifierManager,
+	isFieldInSchema,
 } from "../../feature-libraries/index.js";
-import { isFieldInSchema } from "../../feature-libraries/index.js";
-import { mapTreeFromNodeData } from "../toMapTree.js";
 import { getUnhydratedContext } from "../createContext.js";
-import { createUnknownOptionalFieldPolicy } from "../objectNode.js";
-
-/**
- * Construct tree content that is compatible with the 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.
- * @remarks
- * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
- * This function exists as a generalization that can be used in other cases as well,
- * 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, its an error to provide an existing node to this API.
- * For that case, use {@link TreeBeta.clone}.
- */
-export function createFromInsertable<
-	const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
->(
-	schema: UnsafeUnknownSchema extends TSchema
-		? ImplicitFieldSchema
-		: TSchema & ImplicitFieldSchema,
-	data: InsertableField<TSchema>,
-	context?: NodeIdentifierManager | undefined,
-): Unhydrated<
-	TSchema extends ImplicitFieldSchema
-		? TreeFieldFromImplicitField<TSchema>
-		: TreeNode | TreeLeafValue | undefined
-> {
-	const cursor = cursorFromInsertable(schema, data, context);
-	const result = cursor === undefined ? undefined : createFromCursor(schema, cursor);
-	return result as Unhydrated<
-		TSchema extends ImplicitFieldSchema
-			? TreeFieldFromImplicitField<TSchema>
-			: TreeNode | TreeLeafValue | undefined
-	>;
-}
-
-/**
- * Construct tree content that is compatible with the 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.
- * @remarks
- * When providing a {@link TreeNodeSchemaClass},
- * this is the same as invoking its constructor except that an unhydrated node can also be provided and the returned value is a cursor.
- * When `undefined` is provided (for an optional field), `undefined` is returned.
- */
-export function cursorFromInsertable<
-	TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
->(
-	schema: UnsafeUnknownSchema extends TSchema
-		? ImplicitFieldSchema
-		: TSchema & ImplicitFieldSchema,
-	data: InsertableField<TSchema>,
-	context?: NodeIdentifierManager | undefined,
-):
-	| ITreeCursorSynchronous
-	| (TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never) {
-	const mapTree = mapTreeFromNodeData(
-		data as InsertableField<UnsafeUnknownSchema>,
-		schema,
-		context,
-	);
-	if (mapTree === undefined) {
-		return undefined as TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never;
-	}
-	return cursorForMapTreeNode(mapTree);
-}
+import { createUnknownOptionalFieldPolicy } from "../node-kinds/index.js";
+import type { SimpleNodeSchema, SimpleNodeSchemaBase } from "../simpleSchema.js";
+import { getStoredSchema } from "../toStoredSchema.js";
+import { unknownTypeError } from "./customTree.js";
 
 /**
  * Creates an unhydrated simple-tree field from a cursor in nodes mode.
+ * @remarks
+ * Does not support defaults.
+ * Validates the field is in schema.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const mapTrees = cursor === undefined ? [] : [mapTreeFromCursor(cursor)];
 	const context = getUnhydratedContext(schema);
+	const mapTrees = cursor === undefined ? [] : [unhydratedFlexTreeFromCursor(context, cursor)];
+
 	const flexSchema = context.flexContext.schema;
 
 	const schemaValidationPolicy: SchemaAndPolicy = {
@@ -135,21 +69,40 @@ export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	// Length asserted above, so this is safe. This assert is done instead of checking for undefined after indexing to ensure a length greater than 1 also errors.
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const mapTree = mapTrees[0]!;
-	return createFromMapTree(schema, mapTree);
+
+	return getOrCreateNodeFromInnerNode(mapTree) as Unhydrated<
+		TreeFieldFromImplicitField<TSchema>
+	>;
 }
 
 /**
- * Creates an unhydrated simple-tree field from an ExclusiveMapTree.
+ * Construct an {@link UnhydratedFlexTreeNode} from a cursor in Nodes mode.
+ * @remarks
+ * This does not validate the node is in schema.
  */
-export function createFromMapTree<const TSchema extends ImplicitFieldSchema>(
-	schema: TSchema,
-	mapTree: ExclusiveMapTree,
-): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const mapTreeNode = UnhydratedFlexTreeNode.getOrCreate(
-		getUnhydratedContext(schema),
-		mapTree,
+export function unhydratedFlexTreeFromCursor(
+	context: Context,
+	cursor: ITreeCursorSynchronous,
+): UnhydratedFlexTreeNode {
+	assert(cursor.mode === CursorLocationType.Nodes, 0xbb4 /* Expected nodes cursor */);
+	const schema = context.schema.get(cursor.type) ?? unknownTypeError(cursor.type);
+	const storedSchema = getStoredSchema(
+		schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema,
+	);
+	const fields = new Map(
+		mapCursorFields(cursor, () => [
+			cursor.getFieldKey(),
+			createField(
+				context.flexContext,
+				storedSchema.getFieldSchema(cursor.getFieldKey()).kind,
+				cursor.getFieldKey(),
+				mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
+			),
+		]),
+	);
+	return new UnhydratedFlexTreeNode(
+		{ type: cursor.type, value: cursor.value },
+		fields,
+		context,
 	);
-
-	const result = getOrCreateNodeFromInnerNode(mapTreeNode);
-	return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }

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

@@ -4,8 +4,9 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	EmptyKey,
@@ -19,8 +20,8 @@ import {
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 } from "../../core/index.js";
+import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 import { cloneWithReplacements } from "../../util/index.js";
-import type { TreeLeafValue } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import {
 	booleanSchema,
@@ -29,8 +30,8 @@ import {
 	numberSchema,
 	stringSchema,
 } from "../leafNodeSchema.js";
-import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
 
 /**
  * Options for how to interpret or encode a tree when schema information is available.
@@ -231,3 +232,12 @@ export function replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>):
 		}
 	});
 }
+
+/**
+ * Throws a `UsageError` indicating that a type is unknown in the current context.
+ */
+export function unknownTypeError(type: string): never {
+	throw new UsageError(
+		`Failed to parse tree due to occurrence of type ${JSON.stringify(type)} which is not defined in this context.`,
+	);
+}

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

@@ -5,6 +5,7 @@
 
 import type { ImplicitFieldSchema } from "../schemaTypes.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
+
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**

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

@@ -7,7 +7,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { TreeIndexKey } from "../../feature-libraries/index.js";
 import { FieldKind, type ImplicitFieldSchema } from "../schemaTypes.js";
 import type { TreeNode } from "../core/index.js";
-import { ObjectNodeSchema } from "../objectNodeTypes.js";
+import { ObjectNodeSchema } from "../node-kinds/index.js";
 import type { TreeView } from "./tree.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";

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

@@ -50,13 +50,9 @@ export {
 	tryGetSchema,
 	getStoredKey,
 	getPropertyKeyFromStoredKey,
+	getIdentifierFromNode,
 } from "./treeNodeApi.js";
-export {
-	createFromInsertable,
-	cursorFromInsertable,
-	createFromCursor,
-	createFromMapTree,
-} from "./create.js";
+export { createFromCursor } from "./create.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,
@@ -137,11 +133,3 @@ export {
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 export type { TreeChangeEvents } from "./treeChangeEvents.js";
-
-// Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
-// These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639
-export {
-	RecursiveObject as test_RecursiveObject,
-	base as test_RecursiveObject_base,
-	RecursiveObjectPojoMode as test_RecursiveObjectPojoMode,
-} from "./testRecursiveDomain.js";

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

@@ -4,6 +4,7 @@
  */
 
 import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
+
 import {
 	AdaptedViewSchema,
 	type TreeNodeStoredSchema,
@@ -24,6 +25,7 @@ import {
 } from "../../feature-libraries/index.js";
 import type { FieldSchema } from "../schemaTypes.js";
 import { toStoredSchema } from "../toStoredSchema.js";
+
 import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**