@fluid-experimental/tree 0.58.2000 → 0.58.3000-61081

package/src/default-edits/EditUtilities.ts

@@ -1,220 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { DetachedSequenceId, NodeId } from '../Identifiers';
-import { Snapshot, SnapshotPlace, SnapshotRange } from '../Snapshot';
-import { assert, assertNotUndefined, fail } from '../Common';
-import { EditValidationResult } from '../Checkout';
-import { BuildNode, TraitLocation, TreeNodeSequence } from '../generic';
-import { Change, StablePlace, StableRange } from './PersistedTypes';
-
-/**
- * Functions for constructing edits.
- */
-
-/**
- * Create a sequence of changes that resets the contents of `trait`.
- * @public
- */
-export function setTrait(trait: TraitLocation, nodes: TreeNodeSequence<BuildNode>): readonly Change[] {
-	const id = 0 as DetachedSequenceId;
-	const traitContents = StableRange.all(trait);
-
-	return [Change.detach(traitContents), Change.build(nodes, id), Change.insert(id, traitContents.start)];
-}
-
-/**
- * Check the validity of the given `StablePlace`
- * @param snapshot - the `Snapshot` within which to validate the given place
- * @param place - the `StablePlace` to check
- */
-export function validateStablePlace(snapshot: Snapshot, place: StablePlace): EditValidationResult {
-	/* A StablePlace is valid if the following conditions are met:
-	 *     1. A sibling or trait is defined.
-	 *     2. If a sibling is defined, both it and its parent exist in the `Snapshot`.
-	 *     3. If a trait is defined, its parent node exists in the `Snapshot`.
-	 *     4. If a sibling and a trait location are both specified, the sibling needs to actually be in that trait.
-	 */
-	const { referenceSibling, referenceTrait } = place;
-
-	// A well-formed `StablePlace` specifies exactly one of `referenceSibling` and `referenceTrait`.
-	if (
-		(referenceSibling === undefined && referenceTrait === undefined) ||
-		(referenceSibling !== undefined && referenceTrait !== undefined)
-	) {
-		return EditValidationResult.Malformed;
-	}
-
-	if (referenceSibling !== undefined) {
-		if (!snapshot.hasNode(referenceSibling)) {
-			return EditValidationResult.Invalid;
-		}
-
-		// Detached nodes and the root are invalid anchors.
-		if (snapshot.getTraitLabel(referenceSibling) === undefined) {
-			return EditValidationResult.Invalid;
-		}
-
-		return EditValidationResult.Valid;
-	}
-
-	if (!snapshot.hasNode(assertNotUndefined(referenceTrait).parent)) {
-		return EditValidationResult.Invalid;
-	}
-
-	return EditValidationResult.Valid;
-}
-
-/**
- * Check the validity of the given `StableRange`
- * @param snapshot - the `Snapshot` within which to validate the given range
- * @param range - the `StableRange` to check
- */
-export function validateStableRange(snapshot: Snapshot, range: StableRange): EditValidationResult {
-	/* A StableRange is valid if the following conditions are met:
-	 *     1. Its start and end places are valid.
-	 *     2. Its start and end places are within the same trait.
-	 *     3. Its start place is before its end place.
-	 */
-	const { start, end } = range;
-
-	const startValidationResult = validateStablePlace(snapshot, start);
-	if (startValidationResult !== EditValidationResult.Valid) {
-		return startValidationResult;
-	}
-
-	const endValidationResult = validateStablePlace(snapshot, end);
-	if (endValidationResult !== EditValidationResult.Valid) {
-		return endValidationResult;
-	}
-
-	const startTraitLocation =
-		start.referenceTrait || snapshot.getTraitLocation(assertNotUndefined(start.referenceSibling));
-	const endTraitLocation = end.referenceTrait || snapshot.getTraitLocation(assertNotUndefined(end.referenceSibling));
-	if (!compareTraits(startTraitLocation, endTraitLocation)) {
-		return EditValidationResult.Invalid;
-	}
-
-	const { start: startPlace, end: endPlace } = rangeFromStableRange(snapshot, range);
-	const startIndex = snapshot.findIndexWithinTrait(startPlace);
-	const endIndex = snapshot.findIndexWithinTrait(endPlace);
-
-	if (startIndex > endIndex) {
-		return EditValidationResult.Invalid;
-	}
-
-	return EditValidationResult.Valid;
-}
-
-/**
- * @param snapshot - the `Snapshot` within which to retrieve the trait location
- * @param range - must be well formed and valid
- */
-function getTraitLocationOfRange(snapshot: Snapshot, range: StableRange): TraitLocation {
-	const referenceTrait = range.start.referenceTrait ?? range.end.referenceTrait;
-	if (referenceTrait) {
-		return referenceTrait;
-	}
-	const sibling =
-		range.start.referenceSibling ?? range.end.referenceSibling ?? fail('malformed range does not indicate trait');
-	return snapshot.getTraitLocation(sibling);
-}
-
-/**
- * Describes the side of a range.
- */
-enum SideOfRange {
-	/**
-	 * The start of the range
-	 */
-	Start = 0,
-	/**
-	 * The end of the range
-	 */
-	End = 1,
-}
-
-function sideOfRange(range: StableRange, sideOfRange: SideOfRange, trait: TraitLocation): SnapshotPlace {
-	const siblingRelative = sideOfRange === SideOfRange.Start ? range.start : range.end;
-	return {
-		trait,
-		side: siblingRelative.side,
-		sibling: siblingRelative.referenceSibling,
-	};
-}
-
-/**
- * Express the given `StableRange` as a `Range`
- */
-export function rangeFromStableRange(snapshot: Snapshot, range: StableRange): SnapshotRange {
-	const location = getTraitLocationOfRange(snapshot, range);
-	// This can be optimized for better constant factors.
-	return {
-		start: sideOfRange(range, SideOfRange.Start, location),
-		end: sideOfRange(range, SideOfRange.End, location),
-	};
-}
-
-/**
- * Express the given `StablePlace` as a `Place`
- */
-export function placeFromStablePlace(snapshot: Snapshot, stablePlace: StablePlace): SnapshotPlace {
-	const { side } = stablePlace;
-	if (stablePlace.referenceSibling === undefined) {
-		assert(stablePlace.referenceTrait !== undefined);
-		return {
-			trait: stablePlace.referenceTrait,
-			side,
-		};
-	}
-	return {
-		trait: snapshot.getTraitLocation(stablePlace.referenceSibling),
-		side: stablePlace.side,
-		sibling: stablePlace.referenceSibling,
-	};
-}
-
-/**
- * Check if two TraitLocations are equal.
- */
-function compareTraits(traitA: TraitLocation, traitB: TraitLocation): boolean {
-	if (traitA.label !== traitB.label || traitA.parent !== traitB.parent) {
-		return false;
-	}
-
-	return true;
-}
-
-/**
- * Parents a set of nodes in a specified location within a trait.
- * @param nodesToInsert - the nodes to parent in the specified place. The nodes must already be present in the Snapshot.
- * @param placeToInsert - the location to insert the nodes.
- */
-export function insertIntoTrait(
-	snapshot: Snapshot,
-	nodesToInsert: readonly NodeId[],
-	placeToInsert: StablePlace
-): Snapshot {
-	return snapshot.attachRange(nodesToInsert, placeFromStablePlace(snapshot, placeToInsert));
-}
-
-/**
- * Detaches a range of nodes from their parent. The detached nodes remain in the Snapshot.
- * @param rangeToDetach - the range of nodes to detach
- */
-export function detachRange(
-	snapshot: Snapshot,
-	rangeToDetach: StableRange
-): { snapshot: Snapshot; detached: readonly NodeId[] } {
-	return snapshot.detachRange(rangeFromStableRange(snapshot, rangeToDetach));
-}
-
-/**
- * Determine if an BuildNode is a DetachedSequenceId.
- * @internal
- */
-export function isDetachedSequenceId(node: BuildNode): node is DetachedSequenceId {
-	return typeof node !== 'object';
-}

package/src/default-edits/Factory.ts

@@ -1,94 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import {
-	IChannelAttributes,
-	IFluidDataStoreRuntime,
-	IChannelServices,
-	IChannelFactory,
-} from '@fluidframework/datastore-definitions';
-import { ISharedObject } from '@fluidframework/shared-object-base';
-import { SharedTree } from './SharedTree';
-
-/**
- * Factory for SharedTree.
- * Includes history in the summary.
- * @public
- */
-export class SharedTreeFactory implements IChannelFactory {
-	/**
-	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
-	 */
-	public static Type = 'SharedTree';
-
-	/**
-	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
-	 */
-	public static Attributes: IChannelAttributes = {
-		type: SharedTreeFactory.Type,
-		snapshotFormatVersion: '0.1',
-		packageVersion: '0.1',
-	};
-
-	/**
-	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
-	 */
-	public get type(): string {
-		return SharedTreeFactory.Type;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
-	 */
-	public get attributes(): IChannelAttributes {
-		return SharedTreeFactory.Attributes;
-	}
-
-	/**
-	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.load}
-	 */
-	public async load(
-		runtime: IFluidDataStoreRuntime,
-		id: string,
-		services: IChannelServices,
-		_channelAttributes: Readonly<IChannelAttributes>
-	): Promise<ISharedObject> {
-		const sharedTree = new SharedTree(runtime, id);
-		await sharedTree.load(services);
-		return sharedTree;
-	}
-
-	/**
-	 * Create a new SharedTree.
-	 * @param runtime - data store runtime that owns the new SharedTree
-	 * @param id - optional name for the SharedTree
-	 */
-	public create(runtime: IFluidDataStoreRuntime, id: string, expensiveValidation?: boolean): SharedTree {
-		const sharedTree = new SharedTree(runtime, id, expensiveValidation, this.includeHistoryInSummary());
-		sharedTree.initializeLocal();
-		return sharedTree;
-	}
-
-	/**
-	 * Determines how the SharedTree will summarize the history.
-	 * This is a workaround for lacking the ability to construct DDSs with custom parameters.
-	 */
-	protected includeHistoryInSummary(): boolean {
-		return true;
-	}
-}
-
-/**
- * Factory for SharedTree.
- * Does not include the history in the summary.
- * This is a workaround for lacking the ability to construct DDSs with custom parameters.
- * TODO:#54918: Clean up when DDS parameterization is supported.
- * @public
- */
-export class SharedTreeFactoryNoHistory extends SharedTreeFactory {
-	protected includeHistoryInSummary(): boolean {
-		return false;
-	}
-}

package/src/default-edits/SharedTree.ts

@@ -1,174 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
-import { EditId, NodeId } from '../Identifiers';
-import { Snapshot } from '../Snapshot';
-import { Edit, BuildNode, fullHistorySummarizer, GenericSharedTree, NodeData, SharedTreeSummaryBase } from '../generic';
-import { OrderedEditSet } from '../EditLog';
-import { Change, Delete, Insert, Move, StableRange, StablePlace } from './PersistedTypes';
-import { SharedTreeFactory, SharedTreeFactoryNoHistory } from './Factory';
-import * as HistoryEditFactory from './HistoryEditFactory';
-import { Transaction } from './Transaction';
-import { noHistorySummarizer } from './Summary';
-
-/**
- * Wrapper around a `SharedTree` which provides ergonomic imperative editing functionality. All methods apply changes in their own edit.
- *
- * @example
- * // The following two lines of code are equivalent:
- * tree.applyEdit(...Insert.create([newNode], StablePlace.before(existingNode)));
- * tree.editor.insert(newNode, StablePlace.before(existingNode))
- * @public
- */
-export class SharedTreeEditor {
-	private readonly tree: SharedTree;
-
-	public constructor(tree: SharedTree) {
-		this.tree = tree;
-	}
-
-	/**
-	 * Inserts a node at a location.
-	 * @param node - Node to insert.
-	 * @param destination - StablePlace at which the insert should take place.
-	 */
-	public insert(node: BuildNode, destination: StablePlace): EditId;
-	/**
-	 * Inserts nodes at a location.
-	 * @param nodes - Nodes to insert.
-	 * @param destination - StablePlace at which the insert should take place.
-	 */
-	public insert(nodes: BuildNode[], destination: StablePlace): EditId;
-	public insert(nodeOrNodes: BuildNode | BuildNode[], destination: StablePlace): EditId {
-		return this.tree.applyEdit(
-			...Insert.create(Array.isArray(nodeOrNodes) ? nodeOrNodes : [nodeOrNodes], destination)
-		);
-	}
-
-	/**
-	 * Moves a node to a specified location.
-	 * @param source - Node to move.
-	 * @param destination - StablePlace to which the node should be moved.
-	 */
-	public move(source: NodeData, destination: StablePlace): EditId;
-	/**
-	 * Moves a node to a specified location.
-	 * @param source - Node to move.
-	 * @param destination - StablePlace to which the node should be moved.
-	 */
-	public move(source: NodeId, destination: StablePlace): EditId;
-	/**
-	 * Moves a part of a trait to a specified location.
-	 * @param source - Portion of a trait to move.
-	 * @param destination - StablePlace to which the portion of the trait should be moved.
-	 */
-	public move(source: StableRange, destination: StablePlace): EditId;
-	public move(source: NodeData | NodeId | StableRange, destination: StablePlace): EditId {
-		if (!this.isStableRange(source)) {
-			return this.tree.applyEdit(...Move.create(StableRange.only(source), destination));
-		}
-
-		return this.tree.applyEdit(...Move.create(source, destination));
-	}
-
-	/**
-	 * Deletes a node.
-	 * @param target - Node to delete
-	 */
-	public delete(target: NodeData): EditId;
-	/**
-	 * Deletes a node.
-	 * @param target - Node to delete
-	 */
-	public delete(target: NodeId): EditId;
-	/**
-	 * Deletes a portion of a trait.
-	 * @param target - Range of nodes to delete, specified as a `StableRange`
-	 */
-	public delete(target: StableRange): EditId;
-	public delete(target: NodeData | NodeId | StableRange): EditId {
-		if (!this.isStableRange(target)) {
-			return this.tree.applyEdit(Delete.create(StableRange.only(target)));
-		}
-
-		return this.tree.applyEdit(Delete.create(target));
-	}
-
-	/**
-	 * Reverts a previous edit.
-	 * @param edit - the edit to revert
-	 * @param view - the revision to which the edit is applied (not the output of applying edit: it's the one just before that)
-	 */
-	public revert(edit: Edit<Change>, view: Snapshot): EditId {
-		return this.tree.applyEdit(...HistoryEditFactory.revert(edit.changes, view));
-	}
-
-	private isStableRange(source: NodeData | NodeId | StableRange): source is StableRange {
-		return (source as StableRange).start !== undefined && (source as StableRange).end !== undefined;
-	}
-}
-
-/**
- * A distributed tree.
- * @public
- * @sealed
- */
-export class SharedTree extends GenericSharedTree<Change> {
-	/**
-	 * Create a new SharedTree. It will contain the default value (see initialTree).
-	 */
-	public static create(runtime: IFluidDataStoreRuntime, id?: string): SharedTree {
-		return runtime.createChannel(id, SharedTreeFactory.Type) as SharedTree;
-	}
-
-	/**
-	 * Get a factory for SharedTree to register with the data store.
-	 * @param historySummarizing - determines how history is summarized by the returned `SharedTree`.
-	 * @returns A factory that creates `SharedTree`s and loads them from storage.
-	 */
-	public static getFactory(summarizeHistory = true): SharedTreeFactory {
-		return summarizeHistory ? new SharedTreeFactory() : new SharedTreeFactoryNoHistory();
-	}
-
-	/**
-	 * Create a new SharedTreeFactory.
-	 * @param runtime - The runtime the SharedTree will be associated with
-	 * @param id - Unique ID for the SharedTree
-	 * @param expensiveValidation - enable expensive asserts
-	 * @param summarizeHistory - Determines if the history is included in summaries.
-	 */
-	public constructor(
-		runtime: IFluidDataStoreRuntime,
-		id: string,
-		expensiveValidation = false,
-		summarizeHistory = true
-	) {
-		super(runtime, id, Transaction.factory, SharedTreeFactory.Attributes, expensiveValidation, summarizeHistory);
-	}
-
-	private _editor: SharedTreeEditor | undefined;
-
-	/**
-	 * Returns a `SharedTreeEditor` for editing this tree in an imperative fashion. All edits are performed on the current tree view.
-	 */
-	public get editor(): SharedTreeEditor {
-		if (!this._editor) {
-			this._editor = new SharedTreeEditor(this);
-		}
-
-		return this._editor;
-	}
-
-	/**
-	 * {@inheritDoc GenericSharedTree.generateSummary}
-	 */
-	protected generateSummary(editLog: OrderedEditSet<Change>): SharedTreeSummaryBase {
-		if (!this.summarizeHistory) {
-			return noHistorySummarizer(editLog, this.currentView);
-		}
-		return fullHistorySummarizer(editLog, this.currentView);
-	}
-}

package/src/default-edits/Summary.ts

@@ -1,44 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { TraitLabel } from '../Identifiers';
-import { assert } from '../Common';
-import { OrderedEditSet } from '../EditLog';
-import { Snapshot } from '../Snapshot';
-import { initialTree } from '../InitialTree';
-import { SharedTreeSummary_0_0_2 } from '../SummaryBackCompatibility';
-import { formatVersion, newEdit } from '../generic';
-import { Change } from './PersistedTypes';
-import { setTrait } from './EditUtilities';
-
-/**
- * Does not preserve (persist) history at all.
- * Instead, the history returned in the summary will contain a single change that creates a revision identical to the supplied view.
- * @public
- */
-export function noHistorySummarizer(
-	_editLog: OrderedEditSet<Change>,
-	currentView: Snapshot
-): SharedTreeSummary_0_0_2<Change> {
-	const currentTree = currentView.getChangeNodeTree();
-	const rootId = currentTree.identifier;
-	const changes: Change[] = [];
-	// Generate a set of changes to set the root node's children to that of the root in the currentTree
-	Object.entries(currentTree.traits).forEach(([label, children]) => {
-		changes.push(...setTrait({ parent: rootId, label: label as TraitLabel }, children));
-	});
-	assert(currentTree.payload === undefined, 'setValue not yet supported.');
-	assert(
-		currentTree.identifier === initialTree.identifier && currentTree.definition === initialTree.definition,
-		'root definition and identifier should be immutable.'
-	);
-	const edit = newEdit(changes);
-
-	return {
-		currentTree,
-		sequencedEdits: [{ id: edit.id, changes: edit.changes }],
-		version: formatVersion,
-	};
-}