@fluidframework/tree 2.23.0 → 2.30.0

package/src/feature-libraries/default-schema/mappedEditBuilder.ts

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NormalizedFieldUpPath, NormalizedUpPath } from "../../core/index.js";
+import type {
+	IDefaultEditBuilder,
+	OptionalFieldEditBuilder,
+	SequenceFieldEditBuilder,
+	ValueFieldEditBuilder,
+} from "./defaultEditBuilder.js";
+
+/**
+ * An IDefaultEditBuilder implementation based on another IDefaultEditBuilder that uses a different content type for insertions.
+ */
+export class MappedEditBuilder<TBase, TAdapted> implements IDefaultEditBuilder<TAdapted> {
+	public constructor(
+		private readonly baseBuilder: IDefaultEditBuilder<TBase>,
+		private readonly mapDelegate: (input: TAdapted) => TBase,
+	) {}
+	public valueField(field: NormalizedFieldUpPath): ValueFieldEditBuilder<TAdapted> {
+		const baseField = this.baseBuilder.valueField(field);
+		return {
+			set: (newContent: TAdapted): void => {
+				const mappedContent = this.mapDelegate(newContent);
+				baseField.set(mappedContent);
+			},
+		};
+	}
+	public optionalField(field: NormalizedFieldUpPath): OptionalFieldEditBuilder<TAdapted> {
+		const baseField = this.baseBuilder.optionalField(field);
+		return {
+			set: (newContent: TAdapted | undefined, wasEmpty: boolean): void => {
+				const mappedContent =
+					newContent === undefined ? undefined : this.mapDelegate(newContent);
+				baseField.set(mappedContent, wasEmpty);
+			},
+		};
+	}
+	public sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditBuilder<TAdapted> {
+		const baseField = this.baseBuilder.sequenceField(field);
+		return {
+			insert: (index: number, content: TAdapted): void => {
+				const mappedContent = this.mapDelegate(content);
+				baseField.insert(index, mappedContent);
+			},
+			remove: (index: number, count: number): void => {
+				baseField.remove(index, count);
+			},
+		};
+	}
+	public move(
+		sourceField: NormalizedFieldUpPath,
+		sourceIndex: number,
+		count: number,
+		destinationField: NormalizedFieldUpPath,
+		destinationIndex: number,
+	): void {
+		this.baseBuilder.move(sourceField, sourceIndex, count, destinationField, destinationIndex);
+	}
+	public addNodeExistsConstraint(path: NormalizedUpPath): void {
+		this.baseBuilder.addNodeExistsConstraint(path);
+	}
+	public addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void {
+		this.baseBuilder.addNodeExistsConstraintOnRevert(path);
+	}
+}

package/src/feature-libraries/deltaUtils.ts

@@ -36,7 +36,7 @@ export function mapRootChanges<TIn, TOut>(
 	if (root.build !== undefined) {
 		out.build = root.build.map(({ id, trees }) => ({
 			id,
-			trees: trees.map(func),
+			trees: func(trees),
 		}));
 	}
 	if (root.global !== undefined) {

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

@@ -14,7 +14,7 @@ import {
 } from "../../core/index.js";
 import type { Listenable } from "@fluidframework/core-interfaces";
 import { type IDisposable, disposeSymbol } from "../../util/index.js";
-import type { NodeKeyManager } from "../node-key/index.js";
+import type { NodeIdentifierManager } from "../node-identifier/index.js";
 
 import type { FlexTreeField } from "./flexTreeTypes.js";
 import { type LazyEntity, prepareForEditSymbol } from "./lazyEntity.js";
@@ -56,7 +56,7 @@ export interface FlexTreeHydratedContext extends FlexTreeContext {
 	 */
 	get root(): FlexTreeField;
 
-	readonly nodeKeyManager: NodeKeyManager;
+	readonly nodeKeyManager: NodeIdentifierManager;
 
 	/**
 	 * The checkout object associated with this context.
@@ -90,7 +90,7 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 	public constructor(
 		public readonly schemaPolicy: SchemaPolicy,
 		public readonly checkout: ITreeCheckout,
-		public readonly nodeKeyManager: NodeKeyManager,
+		public readonly nodeKeyManager: NodeIdentifierManager,
 	) {
 		this.eventUnregister = [
 			this.checkout.forest.events.on("beforeChange", () => {
@@ -178,7 +178,7 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 export function getTreeContext(
 	schema: SchemaPolicy,
 	checkout: ITreeCheckout,
-	nodeKeyManager: NodeKeyManager,
+	nodeKeyManager: NodeIdentifierManager,
 ): Context {
 	return new Context(schema, checkout, nodeKeyManager);
 }

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

@@ -8,8 +8,8 @@ import {
 	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldKindIdentifier,
-	type FieldUpPath,
 	type ITreeCursorSynchronous,
+	type NormalizedFieldUpPath,
 	type TreeNodeSchemaIdentifier,
 	type TreeValue,
 	anchorSlot,
@@ -255,7 +255,7 @@ export interface FlexTreeField extends FlexTreeEntity {
 	/**
 	 * Gets the FieldUpPath of a field.
 	 */
-	getFieldPath(): FieldUpPath;
+	getFieldPath(): NormalizedFieldUpPath;
 
 	/**
 	 * Schema for this entity.

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

@@ -13,9 +13,9 @@ import {
 	type FieldAnchor,
 	type FieldKey,
 	type FieldKindIdentifier,
-	type FieldUpPath,
 	type ITreeCursorSynchronous,
 	type ITreeSubscriptionCursor,
+	type NormalizedFieldUpPath,
 	type TreeNavigationResult,
 	inCursorNode,
 	iterateCursorField,
@@ -24,6 +24,8 @@ import {
 import { disposeSymbol, fail, getOrCreate } from "../../util/index.js";
 import {
 	FieldKinds,
+	MappedEditBuilder,
+	type IDefaultEditBuilder,
 	type OptionalFieldEditBuilder,
 	type SequenceFieldEditBuilder,
 	type ValueFieldEditBuilder,
@@ -54,7 +56,7 @@ import {
 } from "./lazyEntity.js";
 import { type LazyTreeNode, makeTree } from "./lazyNode.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
-import { cursorForMapTreeField, cursorForMapTreeNode } from "../mapTreeCursor.js";
+import { cursorForMapTreeField } from "../mapTreeCursor.js";
 
 /**
  * Reuse fields.
@@ -224,15 +226,15 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		);
 	}
 
-	public getFieldPath(): FieldUpPath {
-		return this[cursorSymbol].getFieldPath();
+	public getFieldPath(): NormalizedFieldUpPath {
+		return { parent: this.parent?.anchorNode, field: this.key };
 	}
 
 	/**
 	 * Returns the path to this field to use for editing. Throws iff this path is not {@link TreeStatus#InDocument}.
 	 * This path is not valid to hold onto across edits: this must be recalled for each edit.
 	 */
-	public getFieldPathForEditing(): FieldUpPath {
+	public getFieldPathForEditing(): NormalizedFieldUpPath {
 		if (!this[isFreedSymbol]()) {
 			if (
 				// Only allow editing if we are the root document field...
@@ -247,6 +249,13 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 
 		throw new UsageError("Editing only allowed on fields with TreeStatus.InDocument status");
 	}
+
+	protected getEditor(): IDefaultEditBuilder<ITreeCursorSynchronous> {
+		return new MappedEditBuilder(
+			this.context.checkout.editor,
+			(cursor: ITreeCursorSynchronous) => this.context.checkout.forest.chunkField(cursor),
+		);
+	}
 }
 
 export class LazySequence extends LazyField implements FlexTreeSequenceField {
@@ -274,7 +283,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 
 	private sequenceEditor(): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
-		return this.context.checkout.editor.sequenceField(fieldPath);
+		return this.getEditor().sequenceField(fieldPath);
 	}
 }
 
@@ -293,13 +302,13 @@ export class ReadonlyLazyValueField extends LazyField implements FlexTreeRequire
 export class LazyValueField extends ReadonlyLazyValueField implements FlexTreeRequiredField {
 	public override editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
 		set: (newContent) => {
-			this.valueFieldEditor().set(cursorForMapTreeNode(newContent));
+			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},
 	};
 
 	private valueFieldEditor(): ValueFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
-		const fieldEditor = this.context.checkout.editor.valueField(fieldPath);
+		const fieldEditor = this.getEditor().valueField(fieldPath);
 		return fieldEditor;
 	}
 
@@ -312,7 +321,7 @@ export class LazyOptionalField extends LazyField implements FlexTreeOptionalFiel
 	public editor: OptionalFieldEditBuilder<ExclusiveMapTree> = {
 		set: (newContent, wasEmpty) => {
 			this.optionalEditor().set(
-				newContent !== undefined ? cursorForMapTreeNode(newContent) : newContent,
+				newContent !== undefined ? cursorForMapTreeField([newContent]) : newContent,
 				wasEmpty,
 			);
 		},
@@ -320,7 +329,7 @@ export class LazyOptionalField extends LazyField implements FlexTreeOptionalFiel
 
 	private optionalEditor(): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
 		const fieldPath = this.getFieldPathForEditing();
-		const fieldEditor = this.context.checkout.editor.optionalField(fieldPath);
+		const fieldEditor = this.getEditor().optionalField(fieldPath);
 		return fieldEditor;
 	}
 

package/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -25,7 +25,6 @@ import {
 	applyDelta,
 	forEachField,
 	makeDetachedFieldIndex,
-	mapCursorField,
 } from "../../core/index.js";
 import type {
 	Summarizable,
@@ -34,7 +33,7 @@ import type {
 } from "../../shared-tree-core/index.js";
 import { idAllocatorFromMaxId } from "../../util/index.js";
 // eslint-disable-next-line import/no-internal-modules
-import { chunkField, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
+import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
 import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
 
 import { type ForestCodec, makeForestSummarizerCodec } from "./codec.js";
@@ -127,19 +126,16 @@ export class ForestSummarizer implements Summarizable {
 			const fieldChanges: [FieldKey, DeltaFieldChanges][] = [];
 			const build: DeltaDetachedNodeBuild[] = [];
 			for (const [fieldKey, field] of fields) {
-				const chunked = chunkField(field, {
+				const chunked = chunkFieldSingle(field, {
 					policy: defaultChunkPolicy,
 					idCompressor: this.idCompressor,
 				});
-				const nodeCursors = chunked.flatMap((chunk) =>
-					mapCursorField(chunk.cursor(), (cursor) => cursor.fork()),
-				);
-				const buildId = { minor: allocator.allocate(nodeCursors.length) };
+				const buildId = { minor: allocator.allocate(chunked.topLevelLength) };
 				build.push({
 					id: buildId,
-					trees: nodeCursors,
+					trees: chunked,
 				});
-				fieldChanges.push([fieldKey, [{ count: nodeCursors.length, attach: buildId }]]);
+				fieldChanges.push([fieldKey, [{ count: chunked.topLevelLength, attach: buildId }]]);
 			}
 
 			assert(this.forest.isEmpty, 0x797 /* forest must be empty */);

package/src/feature-libraries/index.ts

@@ -107,15 +107,15 @@ export {
 } from "./chunked-forest/index.js";
 
 export {
-	compareLocalNodeKeys,
-	createNodeKeyManager,
-	isStableNodeKey,
-	type LocalNodeKey,
-	MockNodeKeyManager,
-	type NodeKeyManager,
+	compareLocalNodeIdentifiers,
+	createNodeIdentifierManager,
+	isStableNodeIdentifier,
+	type LocalNodeIdentifier,
+	MockNodeIdentifierManager,
+	type NodeIdentifierManager,
 	nodeKeyTreeIdentifier,
-	type StableNodeKey,
-} from "./node-key/index.js";
+	type StableNodeIdentifier,
+} from "./node-identifier/index.js";
 
 export {
 	FieldKinds,
@@ -193,3 +193,5 @@ export {
 	type TreeIndexKey,
 	type TreeIndexNodes,
 } from "./indexing/index.js";
+
+export { initializeForest } from "./initializeForest.js";

package/src/feature-libraries/indexing/anchorTreeIndex.ts

@@ -19,10 +19,10 @@ import {
 	CursorLocationType,
 	rootField,
 	type UpPath,
-	type ProtoNodes,
 	keyAsDetachedField,
 	compareUpPaths,
 	TreeNavigationResult,
+	type ITreeCursorSynchronous,
 } from "../../core/index.js";
 import type { TreeIndex, TreeIndexKey, TreeIndexNodes } from "./types.js";
 import { TreeStatus } from "../flex-tree/index.js";
@@ -123,7 +123,7 @@ export class AnchorTreeIndex<TKey extends TreeIndexKey, TValue>
 
 		return createAnnouncedVisitor({
 			// nodes (and their entire subtrees) are added to the index as soon as they are created
-			afterCreate: (content: ProtoNodes, destination: FieldKey) => {
+			afterCreate: (content: readonly ITreeCursorSynchronous[], destination: FieldKey) => {
 				const detachedCursor = this.forest.allocateCursor();
 				assert(
 					this.forest.tryMoveCursorToField(

package/src/feature-libraries/initializeForest.ts

@@ -0,0 +1,55 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SessionSpaceCompressedId, IIdCompressor } from "@fluidframework/id-compressor";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import {
+	type DeltaRoot,
+	type IEditableForest,
+	type ITreeCursorSynchronous,
+	type RevisionTagCodec,
+	combineVisitors,
+	deltaForRootInitialization,
+	makeDetachedFieldIndex,
+	visitDelta,
+} from "../core/index.js";
+
+/**
+ * Initializes the given forest with the given content.
+ * @remarks The forest must be empty when this function is called.
+ * This does not perform an edit in the typical sense.
+ * Instead, it creates a delta expressing a creation and insertion of the `content` under the {@link rootFieldKey}, and then applies the delta to the forest.
+ * If `visitAnchors` is enabled, then the delta will also be applied to the forest's {@link AnchorSet} (in which case there must be no existing anchors when this function is called).
+ *
+ * @remarks
+ * This does not perform an edit: it updates the forest content as if there was an edit that did that.
+ */
+export function initializeForest(
+	forest: IEditableForest,
+	content: ITreeCursorSynchronous,
+	revisionTagCodec: RevisionTagCodec,
+	idCompressor: IIdCompressor,
+	visitAnchors = false,
+): void {
+	assert(forest.isEmpty, 0x747 /* forest must be empty */);
+	const delta: DeltaRoot = deltaForRootInitialization(forest.chunkField(content));
+	let visitor = forest.acquireVisitor();
+	if (visitAnchors) {
+		assert(forest.anchors.isEmpty(), 0x9b7 /* anchor set must be empty */);
+		const anchorVisitor = forest.anchors.acquireVisitor();
+		visitor = combineVisitors([visitor, anchorVisitor]);
+	}
+
+	// any detached trees built here are immediately attached so the revision used here doesn't matter
+	// we use a dummy revision to make correctness checks in the detached field index easier
+	visitDelta(
+		delta,
+		visitor,
+		makeDetachedFieldIndex("init", revisionTagCodec, idCompressor),
+		0 as SessionSpaceCompressedId,
+	);
+	visitor.free();
+}

package/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -13,7 +13,6 @@ import {
 	type ChangeFamilyEditor,
 	type ChangeRebaser,
 	type ChangesetLocalId,
-	CursorLocationType,
 	type DeltaDetachedNodeBuild,
 	type DeltaDetachedNodeDestruction,
 	type DeltaDetachedNodeId,
@@ -24,14 +23,12 @@ import {
 	type FieldKey,
 	type FieldKindIdentifier,
 	type FieldUpPath,
-	type ITreeCursorSynchronous,
 	type RevisionInfo,
 	type RevisionMetadataSource,
 	type RevisionTag,
 	type TaggedChange,
 	type UpPath,
 	makeDetachedNodeId,
-	mapCursorField,
 	replaceAtomRevisions,
 	revisionMetadataSourceFromInfo,
 	areEqualChangeAtomIds,
@@ -59,13 +56,7 @@ import {
 	RangeMap,
 	balancedReduce,
 } from "../../util/index.js";
-import {
-	type TreeChunk,
-	chunkFieldSingle,
-	chunkTree,
-	defaultChunkPolicy,
-} from "../chunked-forest/index.js";
-import { cursorForMapTreeNode, mapTreeFromCursor } from "../mapTreeCursor.js";
+import type { TreeChunk } from "../chunked-forest/index.js";
 
 import {
 	type CrossFieldManager,
@@ -96,7 +87,6 @@ import {
 	type NodeChangeset,
 	type NodeId,
 } from "./modularChangeTypes.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * Implementation of ChangeFamily which delegates work in a given field to the appropriate FieldKind
@@ -2044,12 +2034,10 @@ function copyDetachedNodes(
 	const copiedDetachedNodes: DeltaDetachedNodeBuild[] = [];
 	for (const [[major, minor], chunk] of detachedNodes.entries()) {
 		if (chunk.topLevelLength > 0) {
-			const trees = mapCursorField(chunk.cursor(), (c) =>
-				cursorForMapTreeNode(mapTreeFromCursor(c)),
-			);
+			chunk.referenceAdded();
 			copiedDetachedNodes.push({
 				id: makeDetachedNodeId(major, minor),
-				trees,
+				trees: chunk,
 			});
 		}
 	}
@@ -2665,29 +2653,25 @@ export class ModularEditBuilder extends EditBuilder<ModularChangeset> {
 
 	/**
 	 * @param firstId - The ID to associate with the first node
-	 * @param content - The node(s) to build. Can be in either Field or Node mode.
+	 * @param content - The node(s) to build.
 	 * @param revision - The revision to use for the build.
 	 * @returns A description of the edit that can be passed to `submitChanges`.
+	 * The returned object may contain an owning reference to the given TreeChunk.
 	 */
 	public buildTrees(
 		firstId: ChangesetLocalId,
-		content: ITreeCursorSynchronous,
+		content: TreeChunk,
 		revision: RevisionTag,
-		idCompressor?: IIdCompressor,
 	): GlobalEditDescription {
-		if (content.mode === CursorLocationType.Fields && content.getFieldLength() === 0) {
+		if (content.topLevelLength === 0) {
 			return { type: "global", revision };
 		}
+
+		// This content will be added to a GlobalEditDescription whose lifetime exceeds the scope of this function.
+		content.referenceAdded();
+
 		const builds: ChangeAtomIdBTree<TreeChunk> = newTupleBTree();
-		const chunkCompressor = {
-			policy: defaultChunkPolicy,
-			idCompressor,
-		};
-		const chunk =
-			content.mode === CursorLocationType.Fields
-				? chunkFieldSingle(content, chunkCompressor)
-				: chunkTree(content, chunkCompressor);
-		builds.set([revision, firstId], chunk);
+		builds.set([revision, firstId], content);
 
 		return {
 			type: "global",

package/src/feature-libraries/node-identifier/README.md

@@ -0,0 +1,11 @@
+# Node Identifier
+
+Nodes identifiers provide references to nodes in a shared tree.
+
+## Local Node Identifier
+
+Local node identifiers are an efficient representation of a node identifier and are unique within the local session (machine memory).
+
+## Stable Node Identifier
+
+Stable node identifiers are UUIDs that are globally unique and can be persisted outside of the document.

package/src/feature-libraries/node-identifier/index.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { MockNodeIdentifierManager } from "./mockNodeIdentifierManager.js";
+export {
+	compareLocalNodeIdentifiers,
+	type LocalNodeIdentifier,
+	type StableNodeIdentifier,
+	nodeKeyTreeIdentifier,
+} from "./nodeIdentifier.js";
+export {
+	createNodeIdentifierManager,
+	isStableNodeIdentifier,
+	type NodeIdentifierManager,
+} from "./nodeIdentifierManager.js";

package/src/feature-libraries/node-identifier/mockNodeIdentifierManager.ts

@@ -0,0 +1,59 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import type { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
+import { assertIsStableId } from "@fluidframework/id-compressor/internal";
+import type { LocalNodeIdentifier, StableNodeIdentifier } from "./nodeIdentifier.js";
+import {
+	isStableNodeIdentifier,
+	type NodeIdentifierManager,
+} from "./nodeIdentifierManager.js";
+import { brand, extractFromOpaque, fail } from "../../util/index.js";
+
+/**
+ * Mock {@link NodeIdentifierManager} that generates deterministic {@link StableNodeIdentifier}s and {@link LocalNodeIdentifier}s.
+ * @remarks This is useful for test environments because it will always yield the same keys in the same order.
+ * It should not be used for production environments for the same reason; the {@link StableNodeIdentifier}s are not universally unique.
+ */
+export class MockNodeIdentifierManager implements NodeIdentifierManager {
+	private count = 0;
+
+	public generateStableNodeIdentifier(): StableNodeIdentifier {
+		return brand(this.getId(this.count++));
+	}
+
+	public generateLocalNodeIdentifier(): LocalNodeIdentifier {
+		return this.localizeNodeIdentifier(this.generateStableNodeIdentifier());
+	}
+
+	public localizeNodeIdentifier(key: StableNodeIdentifier): LocalNodeIdentifier {
+		return (
+			this.tryLocalizeNodeIdentifier(key) ?? fail(0xb26 /* Identifier is not compressible */)
+		);
+	}
+
+	public stabilizeNodeIdentifier(key: LocalNodeIdentifier): StableNodeIdentifier {
+		return brand(this.getId(extractFromOpaque(key)));
+	}
+
+	public tryLocalizeNodeIdentifier(key: string): LocalNodeIdentifier | undefined {
+		if (!isStableNodeIdentifier(key) || !key.startsWith("a110ca7e-add1-4000-8000-")) {
+			return undefined;
+		}
+		const localNodeIdentifier = Number.parseInt(key.substring(24), 16);
+		return localNodeIdentifier < this.count
+			? brand(localNodeIdentifier as SessionSpaceCompressedId)
+			: undefined;
+	}
+
+	public getId(offset: number): StableId {
+		assert(offset >= 0, 0x6e7 /* UUID offset may not be negative */);
+		assert(offset < 281_474_976_710_656, 0x6e8 /* UUID offset must be at most 16^12 */);
+		return assertIsStableId(
+			`a110ca7e-add1-4000-8000-${Math.round(offset).toString(16).padStart(12, "0")}`,
+		);
+	}
+}

package/src/feature-libraries/node-identifier/nodeIdentifier.ts

@@ -0,0 +1,50 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
+
+import type { TreeNodeSchemaIdentifier } from "../../core/index.js";
+import { type Brand, type Opaque, brand } from "../../util/index.js";
+
+/**
+ * An identifier which uniquely identifies a node in the tree within this session.
+ * @remarks {@link LocalNodeIdentifier}s must not be serialized and stored as data without first being converted into a {@link StableNodeIdentifier}.
+ * They are local to the current session and equivalent nodes in another session will not necessarily have the same {@link LocalNodeIdentifier}.
+ * However, they are otherwise preferential to use over {@link StableNodeIdentifier}s as they are much smaller.
+ * For example, they are more efficient than {@link StableNodeIdentifier}s when used as keys in a map.
+ * {@link LocalNodeIdentifier}s may be compared or equated via {@link compareLocalNodeIdentifiers}.
+ */
+export interface LocalNodeIdentifier
+	extends Opaque<Brand<SessionSpaceCompressedId, "Local Node Identifier">> {}
+
+/**
+ * A UUID which identifies a node in the tree.
+ * This key is universally unique and stable forever; therefore it is safe to persist as data in a SharedTree or other DDS/database.
+ * When not persisted or serialized, it is preferable to use a {@link LocalNodeIdentifier} instead for better performance.
+ */
+export type StableNodeIdentifier = Brand<StableId, "Stable Node Identifier">;
+
+/**
+ * Compares two {@link LocalNodeIdentifier}s.
+ * All {@link LocalNodeIdentifier}s retrieved from a single SharedTree client can be totally ordered using this comparator.
+ * @param a - the first identifier to compare
+ * @param b - the second identifier to compare
+ * @returns `0` if `a` and `b` are the same identifier, otherwise `-1` if `a` is ordered before `b` or `1` if `a` is ordered after `b`.
+ */
+export function compareLocalNodeIdentifiers(
+	a: LocalNodeIdentifier,
+	b: LocalNodeIdentifier,
+): -1 | 0 | 1 {
+	return a === b ? 0 : a > b ? 1 : -1;
+}
+
+/**
+ * The TreeNodeSchemaIdentifier for node identifiers.
+ * @privateRemarks TODO: Come up with a unified and collision-resistant naming schema for types defined by the system.
+ * For now, we'll use `__` to reduce the change of collision, since this is what other internal properties use in Fluid.
+ */
+export const nodeKeyTreeIdentifier: TreeNodeSchemaIdentifier = brand(
+	"com.fluidframework.nodeIdentifier.NodeIdentifier",
+);