@fluid-experimental/tree 0.58.2002 → 0.59.1000

package/src/IdConversion.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { copyPropertyIfDefined, fail, Mutable, ReplaceRecursive } from './Common';
+import { convertTreeNodes } from './EditUtilities';
+import { DetachedSequenceId, isDetachedSequenceId, NodeId } from './Identifiers';
+import {
+	BuildNodeInternal,
+	ChangeInternal,
+	ChangeTypeInternal,
+	ConstraintInternal,
+	DetachInternal,
+	Edit,
+	NodeData,
+	StablePlaceInternal,
+	StableRangeInternal,
+	TreeNode,
+} from './persisted-types';
+
+export function convertEditIds<IdFrom, IdTo>(
+	edit: ReplaceRecursive<Edit<ChangeInternal>, NodeId, IdFrom>,
+	convert: (id: IdFrom) => IdTo
+): Edit<ReplaceRecursive<ChangeInternal, NodeId, IdTo>> {
+	const changes = edit.changes.map((change): ReplaceRecursive<ChangeInternal, NodeId, IdTo> => {
+		switch (change.type) {
+			case ChangeTypeInternal.Build:
+				return {
+					type: ChangeTypeInternal.Build,
+					destination: change.destination,
+					source: change.source.map((tree) => {
+						return convertTreeNodes<
+							TreeNode<ReplaceRecursive<BuildNodeInternal, NodeId, IdFrom>, IdFrom>,
+							TreeNode<ReplaceRecursive<BuildNodeInternal, NodeId, IdTo>, IdTo>,
+							DetachedSequenceId
+						>(tree, (node) => convertNodeDataIds(node, convert), isDetachedSequenceId);
+					}),
+				};
+			case ChangeTypeInternal.Insert:
+				return {
+					type: ChangeTypeInternal.Insert,
+					source: change.source,
+					destination: convertStablePlaceIds(change.destination, convert),
+				};
+			case ChangeTypeInternal.Detach: {
+				const detach: ReplaceRecursive<DetachInternal, NodeId, IdTo> = {
+					type: ChangeTypeInternal.Detach,
+					source: convertStableRangeIds(change.source, convert),
+				};
+				copyPropertyIfDefined(change, detach, 'destination');
+				return detach;
+			}
+			case ChangeTypeInternal.SetValue:
+				return {
+					type: ChangeTypeInternal.SetValue,
+					nodeToModify: convert(change.nodeToModify),
+					payload: change.payload,
+				};
+			case ChangeTypeInternal.Constraint: {
+				const constraint: Mutable<ReplaceRecursive<ConstraintInternal, NodeId, IdTo>> = {
+					type: ChangeTypeInternal.Constraint,
+					effect: change.effect,
+					toConstrain: convertStableRangeIds(change.toConstrain, convert),
+				};
+				copyPropertyIfDefined(change, constraint, 'identityHash');
+				copyPropertyIfDefined(change, constraint, 'label');
+				copyPropertyIfDefined(change, constraint, 'length');
+				copyPropertyIfDefined(change, constraint, 'contentHash');
+				if (change.parentNode !== undefined) {
+					constraint.parentNode = convert(change.parentNode);
+				}
+				return constraint;
+			}
+			default:
+				fail('Unknown change type.');
+		}
+	});
+	const newEdit = { id: edit.id, changes };
+	copyPropertyIfDefined(edit, newEdit, 'pastAttemptCount');
+	return newEdit;
+}
+
+export function convertNodeDataIds<IdFrom, IdTo>(
+	nodeData: NodeData<IdFrom>,
+	convert: (id: IdFrom) => IdTo
+): NodeData<IdTo> {
+	const identifier = convert(nodeData.identifier);
+	const output = { definition: nodeData.definition, identifier };
+	copyPropertyIfDefined(nodeData, output, 'payload');
+	return output;
+}
+
+export function convertStableRangeIds<IdFrom, IdTo>(
+	range: ReplaceRecursive<StableRangeInternal, NodeId, IdFrom>,
+	convert: (id: IdFrom) => IdTo
+): ReplaceRecursive<StableRangeInternal, NodeId, IdTo> {
+	const start = convertStablePlaceIds(range.start, convert);
+	const end = convertStablePlaceIds(range.end, convert);
+	return { start, end };
+}
+
+export function convertStablePlaceIds<IdFrom, IdTo>(
+	{ side, referenceSibling, referenceTrait }: ReplaceRecursive<StablePlaceInternal, NodeId, IdFrom>,
+	convert: (id: IdFrom) => IdTo
+): ReplaceRecursive<StablePlaceInternal, NodeId, IdTo> {
+	const stablePlaceNew: Mutable<ReplaceRecursive<StablePlaceInternal, NodeId, IdTo>> = {
+		side,
+	};
+
+	if (referenceSibling !== undefined) {
+		const nodeId = convert(referenceSibling);
+		stablePlaceNew.referenceSibling = nodeId;
+	}
+
+	if (referenceTrait !== undefined) {
+		const parent = convert(referenceTrait.parent);
+		stablePlaceNew.referenceTrait = {
+			label: referenceTrait.label,
+			parent,
+		};
+	}
+
+	return stablePlaceNew;
+}

package/src/Identifiers.ts

@@ -15,6 +15,18 @@
  */
 export type UuidString = string & { readonly UuidString: '9d40d0ae-90d9-44b1-9482-9f55d59d5465' };
 
+/**
+ * A version 4, variant 2 uuid (https://datatracker.ietf.org/doc/html/rfc4122).
+ * @internal
+ */
+export type StableId = UuidString & { readonly StableId: '53172b0d-a3d5-41ea-bd75-b43839c97f5a' };
+
+/**
+ * A StableId which is suitable for use as a session identifier
+ * @internal
+ */
+export type SessionId = StableId & { readonly SessionId: '4498f850-e14e-4be9-8db0-89ec00997e58' };
+
 /**
  * Edit identifier
  * @public
@@ -31,12 +43,91 @@ export type EditId = UuidString & { readonly EditId: '56897beb-53e4-4e66-85da-4b
  */
 export type DetachedSequenceId = number & { readonly DetachedSequenceId: 'f7d7903a-194e-45e7-8e82-c9ef4333577d' };
 
+/**
+ * An identifier (UUID) that has been shortened by a distributed compression algorithm.
+ * @public
+ */
+export type CompressedId = FinalCompressedId | LocalCompressedId;
+
+/**
+ * The ID of the string that has been interned, which can be used by a {@link StringInterner} to retrieve the original string.
+ * @public
+ */
+export type InternedStringId = number & { readonly InternedStringId: 'e221abc9-9d17-4493-8db0-70c871a1c27c' };
+
+/**
+ * A brand for identity types that are unique within a particular session (SharedTree instance).
+ */
+export interface SessionUnique {
+	readonly SessionUnique: 'cea55054-6b82-4cbf-ad19-1fa645ea3b3e';
+}
+
+/**
+ * A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
+ * Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the
+ * compressor that produced them.
+ * @public
+ */
+export type SessionSpaceCompressedId = CompressedId & SessionUnique;
+
+/**
+ * A compressed ID that has been normalized into "op space" (see `IdCompressor` for more).
+ * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require no normalizing when
+ * received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
+ * @internal
+ */
+export type OpSpaceCompressedId = CompressedId & {
+	readonly OpNormalized: '9209432d-a959-4df7-b2ad-767ead4dbcae';
+};
+
+/**
+ * A compressed ID that is local to a document. Stable across all revisions of a document starting from the one in which it was created.
+ * It should not be persisted outside of the history as it can only be decompressed in the context of the originating document.
+ * If external persistence is needed (e.g. by a client), a StableId should be used instead.
+ * @public
+ */
+export type FinalCompressedId = number & {
+	readonly FinalCompressedId: '5d83d1e2-98b7-4e4e-a889-54c855cfa73d';
+
+	// Same brand as OpNormalizedCompressedId, as final IDs are always finally normalized
+	readonly OpNormalized: '9209432d-a959-4df7-b2ad-767ead4dbcae';
+};
+
+/**
+ * A compressed ID that is local to a session (can only be decompressed when paired with a SessionId).
+ * It should not be persisted outside of the history as it can only be decompressed in the context of the originating session.
+ * If external persistence is needed (e.g. by a client), a StableId should be used instead.
+ * @public
+ */
+export type LocalCompressedId = number & {
+	readonly LocalCompressedId: '6fccb42f-e2a4-4243-bd29-f13d12b9c6d1';
+} & SessionUnique; // Same brand as CompressedId, as local IDs are always locally normalized
+
+export interface NodeIdBrand {
+	readonly NodeId: 'e53e7d6b-c8b9-431a-8805-4843fc639342';
+}
+
 /**
  * Node identifier.
  * Identifies a node within a document.
  * @public
  */
-export type NodeId = UuidString & { readonly NodeId: 'e53e7d6b-c8b9-431a-8805-4843fc639342' };
+export type NodeId = number & SessionSpaceCompressedId & NodeIdBrand;
+
+export type FinalNodeId = FinalCompressedId & NodeIdBrand;
+
+/**
+ * A Node identifier which is persisted by SharedTree internals. Not usable as a {@link NodeId}.
+ * @internal
+ */
+export type OpSpaceNodeId = number & OpSpaceCompressedId & NodeIdBrand;
+
+/**
+ * Globally unique node identifier.
+ * Uniquely identifies a node within and across documents. Can be used across SharedTree instances.
+ * @public
+ */
+export type StableNodeId = string & { readonly StableNodeId: 'a0843b38-699d-4bb2-aa7a-16c502a71151' };
 
 /**
  * Definition.
@@ -51,3 +142,12 @@ export type Definition = UuidString & { readonly Definition: 'c0ef9488-2a78-482d
  * @public
  */
 export type TraitLabel = UuidString & { readonly TraitLabel: '613826ed-49cc-4df3-b2b8-bfc6866af8e3' };
+
+/**
+ * Determine if a node is a DetachedSequenceId.
+ * @internal
+ */
+// Nodes can be an `object` type which is a banned type.
+export function isDetachedSequenceId(node: DetachedSequenceId | object): node is DetachedSequenceId {
+	return typeof node !== 'object';
+}

package/src/InitialTree.ts

@@ -3,15 +3,16 @@
  * Licensed under the MIT License.
  */
 
-import { Definition, NodeId } from './Identifiers';
-import { ChangeNode } from './generic';
+import type { Definition, StableNodeId } from './Identifiers';
+import { legacySharedTreeInitialTreeId } from './id-compressor';
+import { ChangeNode_0_0_2 } from './persisted-types';
 
 /**
  * The initial tree.
  * @public
  */
-export const initialTree: ChangeNode = {
+export const initialTree: ChangeNode_0_0_2 = {
 	traits: {},
 	definition: '51c58718-47b9-4fe4-ad46-56312f3b9e86' as Definition,
-	identifier: '24e26f0b-3c1a-47f8-a7a1-e8461ddb69ce6' as NodeId,
+	identifier: legacySharedTreeInitialTreeId as StableNodeId,
 };

package/src/LazyCheckout.ts

@@ -0,0 +1,51 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Checkout } from './Checkout';
+import { EditId } from './Identifiers';
+import { RevisionView } from './RevisionView';
+import { EditCommittedEventArguments, SharedTree } from './SharedTree';
+import { ValidEditingResult } from './TransactionInternal';
+
+/**
+ * Checkout that only updates its view of the tree when explicitly requested.
+ * This means that the {@link Checkout.currentView} field will never change unless {@link LazyCheckout.waitForPendingUpdates} is called.
+ *
+ * @public
+ * @sealed
+ */
+export class LazyCheckout extends Checkout {
+	private latestView: RevisionView;
+
+	/**
+	 * @param tree - the tree
+	 */
+	public constructor(tree: SharedTree) {
+		super(tree, tree.currentView, (args: EditCommittedEventArguments) => {});
+		this.latestView = tree.currentView;
+	}
+
+	protected handleNewEdit(id: EditId, result: ValidEditingResult): void {
+		super.handleNewEdit(id, result);
+		this.latestView = result.after;
+	}
+
+	protected get latestCommittedView(): RevisionView {
+		return this.latestView;
+	}
+
+	public async waitForPendingUpdates(): Promise<void> {
+		if (this.tree.currentView !== this.latestView) {
+			this.latestView = this.tree.currentView;
+			this.emitChange();
+		}
+		return Promise.resolve();
+	}
+
+	public async waitForEditsToSubmit(): Promise<void> {
+		// This checkout is only lazy on updates, not edit application, so it does not need to wait for here.
+		return Promise.resolve();
+	}
+}