@fluidframework/tree 2.41.0-338186 → 2.41.0

package/src/shared-tree/treeAlpha.ts

@@ -16,8 +16,6 @@ import {
 	TreeBeta,
 	tryGetSchema,
 	createFromCursor,
-	createFromInsertable,
-	cursorFromInsertable,
 	FieldKind,
 	normalizeFieldSchema,
 	type ImplicitFieldSchema,
@@ -36,9 +34,13 @@ import {
 	extractPersistedSchema,
 	type TreeBranch,
 	TreeViewConfigurationAlpha,
+	getStoredKey,
+	getPropertyKeyFromStoredKey,
+	treeNodeApi,
+	getIdentifierFromNode,
 	mapTreeFromNodeData,
 } from "../simple-tree/index.js";
-import type { JsonCompatible } from "../util/index.js";
+import { extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
 import type { ITreeCursorSynchronous } from "../core/index.js";
 import {
@@ -50,12 +52,125 @@ import {
 	TreeCompressionStrategy,
 	type FieldBatch,
 	type FieldBatchEncodingContext,
+	fluidVersionToFieldBatchCodecWriteVersion,
+	type LocalNodeIdentifier,
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
 import { currentVersion } from "../codec/index.js";
 import { createFromMapTree } from "../simple-tree/index.js";
 
+const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
+	const nodeIdentifier = getIdentifierFromNode(node, "uncompressed");
+	if (typeof nodeIdentifier === "number") {
+		throw new TypeError("identifier should be uncompressed.");
+	}
+	return nodeIdentifier;
+};
+
+identifier.shorten = (branch: TreeBranch, nodeIdentifier: string): number | undefined => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	const localNodeKey = nodeKeyManager.tryLocalizeNodeIdentifier(nodeIdentifier);
+	return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+};
+
+identifier.lengthen = (branch: TreeBranch, nodeIdentifier: number): string => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	return nodeKeyManager.stabilizeNodeIdentifier(
+		nodeIdentifier as unknown as LocalNodeIdentifier,
+	);
+};
+
+identifier.getShort = (node: TreeNode): number | undefined => {
+	const shortIdentifier = getIdentifierFromNode(node, "compressed");
+	return typeof shortIdentifier === "number" ? shortIdentifier : undefined;
+};
+
+identifier.create = (branch: TreeBranch): string => {
+	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+		.nodeKeyManager;
+	return nodeKeyManager.stabilizeNodeIdentifier(nodeKeyManager.generateLocalNodeIdentifier());
+};
+
+Object.freeze(identifier);
+
+/**
+ * A utility interface for retrieving or converting node identifiers.
+ *
+ * @remarks
+ * This provides methods to:
+ *
+ * - Retrieve long or short identifiers from nodes
+ *
+ * - Convert between long identifiers and short identifiers
+ *
+ * - Generates long identifiers
+ *
+ * @alpha @sealed
+ */
+export interface TreeIdentifierUtils {
+	/**
+	 * Returns the contents of a node's {@link SchemaFactory.identifier} field as a stable identifier.
+	 * If the identifier field does not exist, returns undefined.
+	 *
+	 * @param node - The TreeNode you want to get the identifier from,
+	 */
+	(node: TreeNode): string | undefined;
+
+	/**
+	 * Returns the shortened identifier as a number given long identifier known by the id compressor on the branch if possible.
+	 * Otherwise, it will return the original string identifier provided.
+	 * If the id does not exist, or is unknown by the id compressor, it returns undefined.
+	 *
+	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}. If you shorten an identifier
+	 * and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
+	 *
+	 * @param branch - TreeBranch from where you get the idCompressor to do the decompression.
+	 * @param nodeIdentifier - the stable identifier that needs to be shortened.
+	 */
+	shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
+
+	/**
+	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor. Otherwise, it will throw an error.
+	 *
+	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}. If you lengthen an identifier
+	 * and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
+	 *
+	 * @param branch - TreeBranch from where you want to get the id compressor to do the decompression.
+	 * @param nodeIdentifier - The local identifier that needs to be expanded.
+	 */
+	lengthen(branch: TreeBranch, nodeIdentifier: number): string;
+
+	/**
+	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
+	 * @remarks
+	 * If the node is {@link Unhydrated | hydrated} and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.
+	 * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
+	 * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.
+	 *
+	 * If the node's identifier is any other user-provided string, then this will return undefined.
+	 *
+	 * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.
+	 *
+	 * If the node has more than one identifier, then this will throw an error.
+	 *
+	 * The returned integer should not be serialized or preserved outside of the current process.
+	 * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.
+	 * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.
+	 */
+	getShort(node: TreeNode): number | undefined;
+
+	/**
+	 * Creates and returns a long identifier.
+	 * The long identifier is a compressible, stable identifier generated by the tree's ID compressor.
+	 *
+	 * @param branch - TreeBranch from where you want to get the id compressor to generate the identifier from.
+	 */
+	create(branch: TreeBranch): string;
+}
+
 /**
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
  * @remarks
@@ -176,7 +291,7 @@ export interface TreeAlpha {
 	 * Additionally using `createIdCompressor` to make an idCompressor is `@legacy` and thus not intended for use in this API surface.
 	 * It would probably make more sense if we provided a way to get an idCompressor from the context of a node,
 	 * which could be optional (and settable if missing) for un0hydrated nodes and required for hydrated ones.
-	 * Add in a stable public APi for creating idCompressors, and a way to get them from a tree (without view schema), and that should address the anticipated use-cases.
+	 * Add in a stable public API for creating idCompressors, and a way to get them from a tree (without view schema), and that should address the anticipated use-cases.
 	 */
 	exportCompressed(
 		tree: TreeNode | TreeLeafValue,
@@ -207,6 +322,20 @@ export interface TreeAlpha {
 		compressedData: JsonCompatible<IFluidHandle>,
 		options: { idCompressor?: IIdCompressor } & ICodecOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+
+	/**
+	 * APIs for creating, converting, and retrieving identifiers.
+	 */
+	readonly identifier: TreeIdentifierUtils;
+
+	/**
+	 * The key of the given node under its parent.
+	 * @remarks
+	 * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).
+	 * If `node` is the root node, this returns undefined.
+	 * Otherwise, this returns the key of the field that it is under (a `string`).
+	 */
+	key2(node: TreeNode): string | number | undefined;
 }
 
 /**
@@ -257,14 +386,10 @@ export const TreeAlpha: TreeAlpha = {
 			? TreeFieldFromImplicitField<TSchema>
 			: TreeNode | TreeLeafValue | undefined
 	> {
-		return createFromInsertable<UnsafeUnknownSchema>(
-			schema,
-			data as InsertableField<UnsafeUnknownSchema>,
-		) as Unhydrated<
-			TSchema extends ImplicitFieldSchema
-				? TreeFieldFromImplicitField<TSchema>
-				: TreeNode | TreeLeafValue | undefined
-		>;
+		// `importConcise` does not need to support all the formats that `create` does.
+		// Perhaps it should error instead of hydrating nodes for example.
+		// For now however, it is a simple wrapper around `create`.
+		return this.create(schema, data as InsertableField<TSchema>);
 	},
 
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
@@ -307,7 +432,7 @@ export const TreeAlpha: TreeAlpha = {
 		},
 	): JsonCompatible<IFluidHandle> {
 		const schema = tryGetSchema(node) ?? fail(0xacf /* invalid input */);
-		const format = versionToFormat[options.oldestCompatibleClient];
+		const format = fluidVersionToFieldBatchCodecWriteVersion(options.oldestCompatibleClient);
 		const codec = makeFieldBatchCodec({ jsonValidator: noopValidator }, format);
 		const cursor = borrowFieldCursorFromTreeNodeOrValue(node);
 		const batch: FieldBatch = [cursor];
@@ -339,6 +464,23 @@ export const TreeAlpha: TreeAlpha = {
 		const view = independentInitializedView(config, options, content);
 		return TreeBeta.clone<TSchema>(view.root);
 	},
+
+	identifier,
+
+	key2(node: TreeNode): string | number | undefined {
+		// If the parent is undefined, then this node is under the root field,
+		const parent = treeNodeApi.parent(node);
+		if (parent === undefined) {
+			return undefined;
+		}
+
+		// The flex-domain strictly operates in terms of "stored keys".
+		// To find the associated developer-facing "property key", we need to look up the field associated with
+		// the stored key from the flex-domain, and get property key its simple-domain counterpart was created with.
+		const storedKey = getStoredKey(node);
+		const parentSchema = treeNodeApi.schema(parent);
+		return getPropertyKeyFromStoredKey(parentSchema, storedKey);
+	},
 };
 
 function exportConcise(
@@ -368,32 +510,35 @@ function exportConcise(
 	);
 }
 
+/**
+ * Borrow a cursor from a node.
+ * @remarks
+ * The cursor must be put back to its original location before the node is used again.
+ */
 function borrowCursorFromTreeNodeOrValue(
 	node: TreeNode | TreeLeafValue,
 ): ITreeCursorSynchronous {
 	if (isTreeValue(node)) {
-		return cursorFromInsertable<UnsafeUnknownSchema>(
-			tryGetSchema(node) ?? fail(0xad0 /* missing schema */),
-			node,
-		);
+		return cursorFromVerbose(node, {});
 	}
 	const kernel = getKernel(node);
 	const cursor = kernel.getOrCreateInnerNode().borrowCursor();
 	return cursor;
 }
 
+/**
+ * Borrow a cursor from a field.
+ * @remarks
+ * The cursor must be put back to its original location before the node is used again.
+ */
 function borrowFieldCursorFromTreeNodeOrValue(
-	node: TreeNode | TreeLeafValue,
+	node: TreeNode | TreeLeafValue | undefined,
 ): ITreeCursorSynchronous {
+	if (node === undefined) {
+		return cursorForMapTreeField([]);
+	}
 	const cursor = borrowCursorFromTreeNodeOrValue(node);
-	// TODO: avoid copy
+	// TODO: avoid copy: borrow cursor from field instead.
 	const mapTree = mapTreeFromCursor(cursor);
 	return cursorForMapTreeField([mapTree]);
 }
-
-const versionToFormat = {
-	v2_0: 1,
-	v2_1: 1,
-	v2_2: 1,
-	v2_3: 1,
-};

package/src/shared-tree/treeCheckout.ts

@@ -276,8 +276,9 @@ export function createTreeCheckout(
 		disposeForksAfterTransaction?: boolean;
 	},
 ): TreeCheckout {
-	const forest = args?.forest ?? buildForest();
+	const breaker = args?.breaker ?? new Breakable("TreeCheckout");
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
+	const forest = args?.forest ?? buildForest(breaker, schema);
 	const defaultCodecOptions = { jsonValidator: noopValidator };
 	const defaultFieldBatchVersion = 1;
 	const changeFamily =
@@ -312,7 +313,7 @@ export function createTreeCheckout(
 		idCompressor,
 		args?.removedRoots,
 		args?.logger,
-		args?.breaker,
+		breaker,
 		args?.disposeForksAfterTransaction,
 	);
 }

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

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import { type TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
@@ -21,9 +23,6 @@ import {
 	tagRollbackInverse,
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
-import type { Listenable } from "@fluidframework/core-interfaces";
-import { createEmitter } from "@fluid-internal/client-utils";
-
 import { hasSome, defineLazyCachedProperty } from "../util/index.js";
 
 /**
@@ -171,7 +170,7 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	}
 
 	/**
-	 * @returns the commit at the head of this branch.
+	 * Gets the commit at the head of this branch.
 	 */
 	public getHead(): GraphCommit<TChange> {
 		return this.head;

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/sharedTreeAttributes.ts

@@ -4,6 +4,7 @@
  */
 
 import type { IChannelAttributes } from "@fluidframework/datastore-definitions/internal";
+
 import { pkgVersion } from "./packageVersion.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";

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

@@ -10,96 +10,20 @@ import type {
 	ITreeCursorSynchronous,
 	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 {
 	getOrCreateNodeFromInnerNode,
 	UnhydratedFlexTreeNode,
-	type TreeNode,
 	type Unhydrated,
 } 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 { inSchemaOrThrow, 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";
 
 /**
  * Creates an unhydrated simple-tree field from a cursor in nodes mode.

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

@@ -4,8 +4,8 @@
  */
 
 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 {
 	EmptyKey,
@@ -19,8 +19,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 +29,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.