@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/src/SummaryBackCompatibility.ts

@@ -3,27 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { IFluidSerializer } from '@fluidframework/shared-object-base';
-import { ErrorString } from './Common';
-import { EditLog } from './EditLog';
-import { ChangeNode, Edit, SharedTreeSummaryBase, SharedTreeSummary } from './generic';
-
-/** The summary format version that is read by SharedTree. */
-export const readFormatVersion = '0.1.0';
-
-/**
- * Legacy summary format currently still used for writing.
- * TODO:#49901: Remove export when this format is no longer written.
- * @internal
- */
-export interface SharedTreeSummary_0_0_2<TChange> extends SharedTreeSummaryBase {
-	readonly currentTree: ChangeNode;
-
-	/**
-	 * A list of edits.
-	 */
-	readonly sequencedEdits: readonly Edit<TChange>[];
-}
+import type { ITelemetryProperties } from '@fluidframework/common-definitions';
+import type { IFluidSerializer } from '@fluidframework/shared-object-base';
+import { fail } from './Common';
+import { getNumberOfHandlesFromEditLogSummary } from './EditLog';
+import { SharedTreeSummary, SharedTreeSummaryBase, SharedTreeSummary_0_0_2, WriteFormat } from './persisted-types';
 
 /**
  * Deserializes a JSON object produced by `serialize()` and uses it to initialize the tree with the encoded state.
@@ -31,19 +15,20 @@ export interface SharedTreeSummary_0_0_2<TChange> extends SharedTreeSummaryBase
  *
  * @param jsonSummary - The string to deserialize.
  * @param serializer - The serializer required to deserialize handles in the string.
- * @returns A SharedTree summary or an ErrorString if the summary could not be interpreted.
+ * @returns A SharedTree summary.
+ * @throws If the summary could not be interpreted.
  *
  */
-export function deserialize(jsonSummary: string, serializer: IFluidSerializer): SharedTreeSummaryBase | ErrorString {
+export function deserialize(jsonSummary: string, serializer: IFluidSerializer): SharedTreeSummaryBase {
 	let summary: Partial<SharedTreeSummaryBase>;
 	try {
 		summary = serializer.parse(jsonSummary);
 	} catch {
-		return 'Json syntax error in Summary';
+		fail('Json syntax error in Summary');
 	}
 
 	if (typeof summary !== 'object') {
-		return 'Summary is not an object';
+		fail('Summary is not an object');
 	}
 
 	const { version } = summary;
@@ -52,57 +37,62 @@ export function deserialize(jsonSummary: string, serializer: IFluidSerializer):
 		return { version, ...summary };
 	}
 
-	return 'Missing fields on summary';
+	fail('Missing fields on summary');
 }
 
 /**
- * @returns SharedTreeSummary that can be used to initialize a SharedTree, or an ErrorString if the summary could not be converted.
- *
+ * General statistics about summaries.
  */
-export function convertSummaryToReadFormat<TChange>(
-	summary: SharedTreeSummaryBase
-): SharedTreeSummary<TChange> | ErrorString {
+export interface SummaryStatistics extends ITelemetryProperties {
+	/** Format version the summary is written in. */
+	readonly formatVersion: string;
+	/** Number of edits. */
+	readonly historySize: number;
+	/** Number of edit chunks in the history. */
+	readonly totalNumberOfChunks?: number;
+	/** Number of chunks in the summary that have handles stored. */
+	readonly uploadedChunks?: number;
+}
+
+/**
+ * @returns SummaryStatistics.
+ * @throws If statistics could not be obtained from the summary.
+ */
+export function getSummaryStatistics(summary: SharedTreeSummaryBase): SummaryStatistics {
 	const { version } = summary;
 
-	if (version === readFormatVersion) {
-		const { currentTree, editHistory } = summary as SharedTreeSummary<TChange>;
+	if (version === WriteFormat.v0_1_1) {
+		const { editHistory } = summary as SharedTreeSummary;
 
 		if (editHistory !== undefined) {
 			if (typeof editHistory !== 'object') {
-				return 'Edit history is not an object';
+				fail('Edit history is not an object');
 			}
 
 			const { editChunks, editIds } = editHistory;
 
 			// TODO:#45414: Add more robust validation of the summary's fields. Even if they are present, they may be malformed.
 			if (editChunks !== undefined && editIds !== undefined) {
-				return { currentTree, editHistory, version };
+				return {
+					formatVersion: version,
+					historySize: editIds.length,
+					totalNumberOfChunks: editChunks.length,
+					uploadedChunks: getNumberOfHandlesFromEditLogSummary(editHistory),
+				};
 			}
-		}
-	} else if (version === '0.0.2') {
-		const { currentTree, sequencedEdits } = summary as SharedTreeSummary_0_0_2<TChange>;
 
-		if (sequencedEdits !== undefined) {
-			/**
-			 * The number of edits that can safely fit in a blob upload.
-			 */
-			const maxChunkSize = 1000;
-
-			// This saves all of the edits in the summary as part of the first chunk.
-			const temporaryLog = new EditLog<TChange>(undefined, undefined, maxChunkSize);
-			sequencedEdits.forEach((edit) =>
-				temporaryLog.addSequencedEdit(edit, { sequenceNumber: 1, referenceSequenceNumber: 0 })
-			);
-
-			return {
-				currentTree,
-				editHistory: temporaryLog.getEditLogSummary(),
-				version: readFormatVersion,
-			};
+			fail('Missing fields on edit log summary');
 		}
+	} else if (version === WriteFormat.v0_0_2) {
+		const { sequencedEdits } = summary as SharedTreeSummary_0_0_2;
+
+		return {
+			formatVersion: version,
+			historySize: sequencedEdits.length,
+		};
 	} else {
-		return 'Format version is not supported';
+		fail('Format version is not supported');
 	}
 
-	return 'Missing fields on summary';
+	fail('Missing fields on summary');
 }

package/src/SummaryTestUtilities.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IsoBuffer } from '@fluidframework/common-utils';
+import type { EditLog } from './EditLog';
+import type { ChangeInternal, EditChunkContents, FluidEditHandle } from './persisted-types';
+import type { SharedTree } from './SharedTree';
+
+/**
+ * Format used for exporting an uploaded edit chunk and its associated handle path. Primarily used for testing SharedTree summaries.
+ * @public
+ */
+export interface UploadedEditChunkContents {
+	/**
+	 * The handle path associated with the edit chunk.
+	 */
+	absolutePath: string;
+	/**
+	 * The edits uploaded as part of the edit chunk.
+	 */
+	chunkContents: EditChunkContents;
+}
+
+/**
+ * Returns a list of blob paths and their associated contents for all uploaded edit chunks in the given edit log, in order of edit sequence numbers.
+ * The contents will not be decoded from the format used in the blob.
+ */
+export async function getUploadedEditChunkContents(sharedTree: SharedTree): Promise<UploadedEditChunkContents[]> {
+	const editChunks: UploadedEditChunkContents[] = [];
+	const { editChunks: editsOrHandles } = (sharedTree.edits as EditLog<ChangeInternal>).getEditLogSummary();
+	for (const { chunk } of editsOrHandles) {
+		if (!Array.isArray(chunk)) {
+			const handle = chunk as FluidEditHandle;
+
+			const chunkContents: EditChunkContents = JSON.parse(IsoBuffer.from(await handle.get()).toString());
+			editChunks.push({
+				absolutePath: handle.absolutePath,
+				chunkContents,
+			});
+		}
+	}
+
+	return editChunks;
+}
+
+/**
+ * Returns a serialized description of blob paths and their associated contents for all uploaded edit chunks in the given edit log.
+ * @public
+ */
+export async function getSerializedUploadedEditChunkContents(sharedTree: SharedTree): Promise<string> {
+	return JSON.stringify(await getUploadedEditChunkContents(sharedTree));
+}

package/src/Transaction.ts

@@ -0,0 +1,120 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IErrorEvent } from '@fluidframework/common-definitions';
+import { TypedEventEmitter } from '@fluidframework/common-utils';
+import { ChangeInternal, Edit, EditStatus } from './persisted-types';
+import { newEditId } from './EditUtilities';
+import { TreeView } from './TreeView';
+import { Change } from './ChangeTypes';
+import { SharedTree } from './SharedTree';
+import { GenericTransaction, TransactionInternal } from './TransactionInternal';
+import { CachingLogViewer } from './LogViewer';
+
+/**
+ * An event emitted by a `Transaction` to indicate a state change. See {@link TransactionEvents} for event argument information.
+ * @public
+ */
+export enum TransactionEvent {
+	/**
+	 * `currentView` has changed from `before` to `after`
+	 */
+	ViewChange = 'viewChange',
+}
+
+/**
+ * Events which may be emitted by `Transaction`
+ */
+export interface TransactionEvents extends IErrorEvent {
+	(event: TransactionEvent.ViewChange, listener: (before: TreeView, after: TreeView) => void);
+}
+
+/**
+ * Buffers changes to be applied to an isolated view of a `SharedTree` over time before applying them directly to the tree itself as a
+ * single edit
+ */
+export class Transaction extends TypedEventEmitter<TransactionEvents> {
+	/** The view of the tree when this transaction was created */
+	public readonly startingView: TreeView;
+	private readonly transaction: GenericTransaction;
+
+	/**
+	 * Create a new transaction over the given tree. The tree's `currentView` at this time will become the `startingView` for this
+	 * transaction.
+	 * @param tree - the `SharedTree` that this transaction applies changes to
+	 */
+	public constructor(public readonly tree: SharedTree) {
+		super();
+		const { currentView } = tree;
+		this.transaction = new GenericTransaction(currentView, new TransactionInternal.Policy());
+		this.startingView = currentView;
+	}
+
+	/**
+	 * True if this transaction is open, false if it is closed. A transaction may be closed manually via `closeAndApplyEdit()`, or may
+	 * be automatically closed by a change in this transaction failing to apply (see `applyChange()`).
+	 */
+	public get isOpen(): boolean {
+		return this.transaction.isOpen && this.status === EditStatus.Applied;
+	}
+
+	/**
+	 * The status of the most recently applied change in this transaction
+	 */
+	public get status(): EditStatus {
+		return this.transaction.status;
+	}
+
+	/**
+	 * The state of the tree following the most change that was successfully applied. If no changes have been applied, this is the same as
+	 * `startingView`.
+	 */
+	public get currentView(): TreeView {
+		return this.transaction.view;
+	}
+
+	/**
+	 * Attempt to apply a sequence of changes in this transaction. The `currentView` will be updated to reflect the new tree state after all
+	 * applied changes. If any change fails to apply, the remaining changes will be ignored and this transaction will be automatically
+	 * closed (see `isOpen`). If this transaction is already closed, this method has no effect. This method will emit a
+	 * `TransactionEvent.ViewChange` event at most once per call.
+	 * @param changes - the changes to apply
+	 * @returns either the `EditStatus` of the given changes or the `EditStatus` of the last change before the transaction was closed
+	 */
+	public apply(...changes: Change[]): EditStatus;
+	public apply(changes: Change[]): EditStatus;
+	public apply(headOrChanges: Change | Change[], ...tail: Change[]): EditStatus {
+		if (this.isOpen) {
+			const changes = Array.isArray(headOrChanges) ? headOrChanges : [headOrChanges, ...tail];
+			if (changes.length > 0) {
+				const previousView = this.currentView;
+				this.transaction.applyChanges(changes.map((c) => this.tree.internalizeChange(c)));
+				if (
+					this.listenerCount(TransactionEvent.ViewChange) > 0 &&
+					!previousView.hasEqualForest(this.currentView)
+				) {
+					this.emit(TransactionEvent.ViewChange, previousView, this.currentView);
+				}
+			}
+		}
+		return this.status;
+	}
+
+	/**
+	 * Close this transaction and apply its changes to the `SharedTree`. If this transaction is already closed, this method has no effect.
+	 */
+	public closeAndCommit(): void {
+		if (this.isOpen) {
+			if (this.transaction.changes.length > 0) {
+				const result = this.transaction.close();
+				const edit: Edit<ChangeInternal> = { id: newEditId(), changes: result.changes };
+				if (this.tree.editsInternal instanceof CachingLogViewer) {
+					this.tree.editsInternal.setKnownEditingResult(edit, result);
+				}
+				this.tree.applyEditInternal(edit);
+			}
+		}
+	}
+}