@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/src/anchored-edits/PersistedTypes.ts

@@ -1,310 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-// All types imported into this file inherit the requirements documented below.
-// These imports are ok because they consist only of type aliases for primitive types,
-// and thus have no impact on serialization as long as the primitive type they are an alias for does not change.
-// This does mean that the various UuidString types must remain strings, and must never change the format unless the process for changing
-// persisted types (as documented below) is followed.
-import { DetachedSequenceId, NodeId, TraitLabel, UuidString } from '../Identifiers';
-import { Side } from '../Snapshot';
-import { EditBase, BuildNode, NodeData, Payload, TraitLocation, TreeNodeSequence } from '../generic';
-import {
-	Build,
-	Change,
-	ConstraintEffect,
-	Detach,
-	Insert,
-	Move,
-	SetValue,
-	StablePlace,
-	StableRange,
-	Constraint,
-	getNodeId,
-} from '../default-edits';
-
-/**
- * Types for Edits in Fluid Ops and Fluid summaries.
- *
- * Types describing locations in the tree are stable in the presence of other concurrent edits.
- *
- * All types are compatible with Fluid Serializable.
- *
- * These types can only be modified in ways that are both backwards and forwards compatible since they
- * are used in edits, and thus are persisted (using Fluid serialization).
- *
- * This means these types cannot be changed in any way that impacts their Fluid serialization
- * except through a very careful process:
- *
- * 1. The planned change must support all old data, and maintain the exact semantics of it.
- * This means that the change is pretty much limited to adding optional fields,
- * or making required fields optional.
- * 2. Support for the new format must be deployed to all users (This means all applications using SharedTree must do this),
- * and this deployment must be confirmed to be stable and will not be rolled back.
- * 3. Usage of the new format may start.
- *
- * Support for the old format can NEVER be removed: it must be maintained indefinably or old documents will break.
- * Because this process puts requirements on applications using shared tree,
- * step 3 should only ever be done in a Major version update,
- * and must be explicitly called out in the release notes
- * stating which versions of SharedTree are supported for documents modified by the new version.
- */
-
-/**
- * The information included in an anchored edit.
- * @public
- */
-export type AnchoredEditBase = EditBase<AnchoredChange>;
-
-/**
- * A change that composes an Edit.
- *
- * `Change` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
- * @example
- * Change.insert(sourceId, destination)
- * @public
- */
-export type AnchoredChange = AnchoredInsert | AnchoredDetach | Build | AnchoredSetValue | AnchoredConstraint;
-
-/**
- * Inserts a sequence of nodes at the specified destination.
- * The source can be constructed either by a Build (used to insert new nodes) or a Detach (amounts to a "move" operation).
- * @public
- */
-export interface AnchoredInsert extends Insert {
-	readonly destination: PlaceAnchor;
-}
-
-/**
- * Removes a sequence of nodes from the tree.
- * If a destination is specified, the detached sequence is associated with that ID and held for possible reuse
- * by later changes in this same Edit (such as by an Insert).
- * A Detach without a destination is a deletion of the specified sequence, as is a Detach with a destination that is not used later.
- * @public
- */
-export interface AnchoredDetach extends Detach {
-	readonly source: RangeAnchor;
-}
-
-/**
- * Modifies the payload of a node.
- * @public
- */
-export interface AnchoredSetValue extends SetValue {
-	readonly nodeToModify: NodeAnchor;
-}
-
-/**
- * A set of constraints on the validity of an Edit.
- * A Constraint is used to detect when an Edit, due to other concurrent edits, may have unintended effects or merge in
- * non-semantic ways. It is processed in order like any other Change in an Edit. It can cause an edit to fail if the
- * various constraints are not met at the time of evaluation (ex: the parentNode has changed due to concurrent editing).
- * Does not modify the document.
- * @public
- */
-export interface AnchoredConstraint extends Constraint {
-	/**
-	 * Selects a sequence of nodes which will be checked against the constraints specified by the optional fields.
-	 * If `toConstrain` is invalid, it will be treated like a constraint being unmet.
-	 * Depending on `effect` this may or may not make the Edit invalid.
-	 *
-	 * When a constraint is not met, the effects is specified by `effect`.
-	 */
-	readonly toConstrain: RangeAnchor;
-}
-
-// Note: Documentation of this constant is merged with documentation of the `AnchoredChange` interface.
-/**
- * @public
- */
-export const AnchoredChange = {
-	build: Change.build,
-	insert: Change.insert as (source: DetachedSequenceId, destination: PlaceAnchor) => AnchoredInsert,
-	detach: Change.detach as (source: RangeAnchor, destination?: DetachedSequenceId) => AnchoredDetach,
-	setPayload: Change.setPayload as (nodeToModify: NodeAnchor, payload: Payload) => AnchoredSetValue,
-	clearPayload: Change.clearPayload as (nodeToModify: NodeAnchor) => AnchoredSetValue,
-	constraint: Change.constraint as (
-		toConstrain: RangeAnchor,
-		effect: ConstraintEffect,
-		identityHash?: UuidString,
-		length?: number,
-		contentHash?: UuidString,
-		parentNode?: NodeId,
-		label?: TraitLabel
-	) => AnchoredConstraint,
-};
-
-/**
- * Helper for creating a `Delete` edit.
- * @public
- */
-export const AnchoredDelete = {
-	/**
-	 * @returns an AnchoredChange that deletes the supplied part of the tree.
-	 */
-	create: (rangeAnchor: RangeAnchor): AnchoredChange => AnchoredChange.detach(rangeAnchor),
-};
-
-/**
- * Helper for creating an `Insert` edit.
- * @public
- */
-export const AnchoredInsert = {
-	/**
-	 * @returns an AnchoredChange that inserts 'nodes' into the specified location in the tree.
-	 */
-	create: Insert.create as (nodes: TreeNodeSequence<BuildNode>, destination: PlaceAnchor) => AnchoredChange[],
-};
-
-/**
- * Helper for creating a `Move` edit.
- * @public
- */
-export const AnchoredMove = {
-	/**
-	 * @returns an AnchoredChange that moves the specified content to a new location in the tree.
-	 */
-	create: Move.create as (source: RangeAnchor, destination: PlaceAnchor) => AnchoredChange[],
-};
-
-/**
- * Indicates one of the predefined alternatives for the semantics of a place in a tree.
- */
-export enum PlaceAnchorSemanticsChoice {
-	/**
-	 * The resulting `PlaceAnchor` is valid iff the referenced sibling or parent node with the given ID exists in the snapshot on which the
-	 * change is applied.
-	 */
-	BoundToNode = 0,
-	/**
-	 * The resulting `PlaceAnchor` is interpreted as relative to the siblings in the trait (or the parent in the case of start and end).
-	 * If the sibling referenced in the `PlaceAnchor` is moved, the anchor moves with it.
-	 * If the sibling referenced in the `PlaceAnchor` is deleted, the anchor is interpreted as relative to the next remaining sibling.
-	 * If no siblings remain on the side of interest (before the referenced sibling for "After" places and after the referenced sibling
-	 *   for "Before" places) then the anchor is interpreted relative to the containing parent/trait (the start of the trait for "After"
-	 *   places and the end of the trait for "Before" places).
-	 * If no siblings and no parent remains, the anchor is invalid.
-	 */
-	RelativeToNode = 1,
-	// Future work:
-	// RelativeToRank = 2,
-}
-
-/**
- * A location in a trait with associated merge semantics.
- * See also `StablePlace`.
- * `PlaceAnchor`. objects can be conveniently constructed with the helper methods exported on a constant of the same name.
- * @example
- * PlaceAnchor.before(node)
- * PlaceAnchor.atStartOf(trait)
- * @public
- */
-export interface PlaceAnchor extends StablePlace {
-	/**
-	 * The choice of semantics for the place.
-	 * No value is equivalent to PlaceAnchorSemanticsChoice.BoundToNode.
-	 */
-	readonly semantics?: PlaceAnchorSemanticsChoice;
-}
-
-export type RelativePlaceAnchor = PlaceAnchor & { semantic: PlaceAnchorSemanticsChoice.RelativeToNode };
-
-/**
- * Specifies the range of nodes from `start` to `end` within a trait.
- * See also `StableRange`.
- * Valid iff start and end are valid and are within the same trait and the start does not occur after the end in the trait.
- *
- * `RangeAnchor`s are currently resolved by resolving their constituent places and checking the validity of the resulting range.
- * This may lead to the range becoming invalid (i.e., cannot be resolved) despite there being reasonable ways to salvage it.
- * For example the range [After(B), Before(D)] in the trait [A, B, C, D] would be made invalid by a change that moves B after D.
- * A reasonable resolution would be to resolve the range to [After(A), Before(D)]. The current implementation will instead treat
- * the range as invalid.
- * Future improvements may offer more a resilient resolution strategy for ranges.
- *
- * `RangeAnchor` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
- * @example
- * RangeAnchor.from(PlaceAnchor.before(startNode)).to(PlaceAnchor.after(endNode))
- * @public
- */
-export interface RangeAnchor extends StableRange {
-	readonly start: PlaceAnchor;
-	readonly end: PlaceAnchor;
-}
-
-export type NodeAnchor = NodeId;
-
-/**
- * The remainder of this file consists of ergonomic factory methods for persisted types, or common combinations thereof (e.g. "Move" as a
- * combination of a "Detach" change and an "Insert" change).
- *
- * None of these helpers are persisted in documents, and therefore changes to their semantics need only follow standard semantic versioning
- * practices.
- */
-
-// Note: Documentation of this constant is merged with documentation of the `PlaceAnchor` interface.
-/**
- * @public
- */
-export const PlaceAnchor = {
-	/**
-	 * @returns The location directly before `node`.
-	 */
-	before: (
-		node: NodeData | NodeId,
-		semantics: PlaceAnchorSemanticsChoice = PlaceAnchorSemanticsChoice.RelativeToNode
-	): PlaceAnchor => ({
-		side: Side.Before,
-		referenceSibling: getNodeId(node),
-		semantics,
-	}),
-	/**
-	 * @returns The location directly after `node`.
-	 */
-	after: (
-		node: NodeData | NodeId,
-		semantics: PlaceAnchorSemanticsChoice = PlaceAnchorSemanticsChoice.RelativeToNode
-	): PlaceAnchor => ({ side: Side.After, referenceSibling: getNodeId(node), semantics }),
-	/**
-	 * @returns The location at the start of `trait`.
-	 */
-	atStartOf: (
-		trait: TraitLocation,
-		semantics: PlaceAnchorSemanticsChoice = PlaceAnchorSemanticsChoice.RelativeToNode
-	): PlaceAnchor => ({ side: Side.After, referenceTrait: trait, semantics }),
-	/**
-	 * @returns The location at the end of `trait`.
-	 */
-	atEndOf: (
-		trait: TraitLocation,
-		semantics: PlaceAnchorSemanticsChoice = PlaceAnchorSemanticsChoice.RelativeToNode
-	): PlaceAnchor => ({ side: Side.Before, referenceTrait: trait, semantics }),
-};
-
-// Note: Documentation of this constant is merged with documentation of the `RangeAnchor` interface.
-/**
- * @public
- */
-export const RangeAnchor = {
-	/**
-	 * Factory for producing a `RangeAnchor` from a start `StablePlace` to an end `StablePlace`.
-	 * @example
-	 * RangeAnchor.from(StablePlace.before(startNode)).to(StablePlace.after(endNode))
-	 */
-	from: StableRange.from as (start: PlaceAnchor) => { to: (end: PlaceAnchor) => RangeAnchor },
-	/**
-	 * @returns a `RangeAnchor` which contains only the provided `node`.
-	 * Both the start and end `PlaceAnchor` objects used to anchor this `RangeAnchor` are in terms of the passed in node.
-	 */
-	only: (
-		node: NodeData | NodeAnchor,
-		semantics: PlaceAnchorSemanticsChoice = PlaceAnchorSemanticsChoice.RelativeToNode
-	): RangeAnchor => ({ start: PlaceAnchor.before(node, semantics), end: PlaceAnchor.after(node, semantics) }),
-	/**
-	 * @returns a `RangeAnchor` which contains everything in the trait.
-	 * This is anchored using the provided `trait`, and is independent of the actual contents of the trait:
-	 * it does not use sibling anchoring.
-	 */
-	all: StableRange.all as (trait: TraitLocation) => RangeAnchor,
-};

package/src/anchored-edits/SharedTreeWithAnchors.ts

@@ -1,200 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
-import { EditId } from '../Identifiers';
-import { Snapshot } from '../Snapshot';
-import { Edit, BuildNode, fullHistorySummarizer, GenericSharedTree, NodeData, SharedTreeSummaryBase } from '../generic';
-import { OrderedEditSet } from '../EditLog';
-import { noHistorySummarizer, revert } from '../default-edits';
-import {
-	AnchoredChange,
-	AnchoredDelete,
-	AnchoredInsert,
-	AnchoredMove,
-	RangeAnchor,
-	PlaceAnchor,
-	NodeAnchor,
-} from './PersistedTypes';
-import { SharedTreeWithAnchorsFactory, SharedTreeWithAnchorsFactoryNoHistory } from './Factory';
-import { TransactionWithAnchors } from './TransactionWithAnchors';
-
-/**
- * Wrapper around a `SharedTreeWithAnchorsEditor` 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(...AnchoredInsert.create([newNode], PlaceAnchor.before(existingNode)));
- * tree.editor.insert(newNode, PlaceAnchor.before(existingNode))
- * @public
- */
-export class SharedTreeWithAnchorsEditor {
-	private readonly tree: SharedTreeWithAnchors;
-
-	public constructor(tree: SharedTreeWithAnchors) {
-		this.tree = tree;
-	}
-
-	/**
-	 * Inserts a node at a location.
-	 * @param node - Node to insert.
-	 * @param destination - PlaceAnchor at which the insert should take place.
-	 */
-	public insert(node: BuildNode, destination: PlaceAnchor): EditId;
-	/**
-	 * Inserts nodes at a location.
-	 * @param nodes - Nodes to insert.
-	 * @param destination - PlaceAnchor at which the insert should take place.
-	 */
-	public insert(nodes: BuildNode[], destination: PlaceAnchor): EditId;
-	public insert(nodeOrNodes: BuildNode | BuildNode[], destination: PlaceAnchor): EditId {
-		return this.tree.applyEdit(
-			...AnchoredInsert.create(Array.isArray(nodeOrNodes) ? nodeOrNodes : [nodeOrNodes], destination)
-		);
-	}
-
-	/**
-	 * Moves a node to a specified location.
-	 * @param source - Node to move.
-	 * @param destination - PlaceAnchor to which the node should be moved.
-	 */
-	public move(source: NodeData, destination: PlaceAnchor): EditId;
-	/**
-	 * Moves a node to a specified location.
-	 * @param source - Node to move.
-	 * @param destination - PlaceAnchor to which the node should be moved.
-	 */
-	public move(source: NodeAnchor, destination: PlaceAnchor): EditId;
-	/**
-	 * Moves a part of a trait to a specified location.
-	 * @param source - Portion of a trait to move.
-	 * @param destination - PlaceAnchor to which the portion of the trait should be moved.
-	 */
-	public move(source: RangeAnchor, destination: PlaceAnchor): EditId;
-	public move(source: NodeData | NodeAnchor | RangeAnchor, destination: PlaceAnchor): EditId {
-		if (!this.isRange(source)) {
-			return this.tree.applyEdit(...AnchoredMove.create(RangeAnchor.only(source), destination));
-		}
-
-		return this.tree.applyEdit(...AnchoredMove.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: NodeAnchor): EditId;
-	/**
-	 * Deletes a portion of a trait.
-	 * @param target - Range of nodes to delete, specified as a `RangeAnchor`
-	 */
-	public delete(target: RangeAnchor): EditId;
-	public delete(target: NodeData | NodeAnchor | RangeAnchor): EditId {
-		if (!this.isRange(target)) {
-			return this.tree.applyEdit(AnchoredDelete.create(RangeAnchor.only(target)));
-		}
-
-		return this.tree.applyEdit(AnchoredDelete.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<AnchoredChange>, view: Snapshot): EditId {
-		return this.tree.applyEdit(...revert(edit.changes, view));
-	}
-
-	public applyChanges(changes: readonly AnchoredChange[]): EditId {
-		return this.tree.applyEdit(...changes);
-	}
-
-	private isRange(source: NodeData | NodeAnchor | RangeAnchor): source is RangeAnchor {
-		return (source as RangeAnchor).start !== undefined && (source as RangeAnchor).end !== undefined;
-	}
-}
-
-/**
- * A distributed tree.
- *
- * Does not currently guarantee convergence among nodes. This is due to the fact that the current summary information is insufficient to
- * ensure that all nodes have access to all the relevant data for the application of a given edit. For example, if edit was sequenced after
- * a given summary but references an edit before that summary then nodes that do not have that earlier edit's information in memory will not
- * have the full context for the application of the change. This currently leads to a "best effort" application which takes into account
- * whatever data is available. Remedying this is tracked by #57176.
- *
- * @public
- * @sealed
- */
-export class SharedTreeWithAnchors extends GenericSharedTree<AnchoredChange> {
-	/**
-	 * Create a new SharedTreeWithAnchors. It will contain the default value (see initialTree).
-	 */
-	public static create(runtime: IFluidDataStoreRuntime, id?: string): SharedTreeWithAnchors {
-		return runtime.createChannel(id, SharedTreeWithAnchorsFactory.Type) as SharedTreeWithAnchors;
-	}
-
-	/**
-	 * Get a factory for SharedTreeWithAnchors to register with the data store.
-	 * @param historySummarizing - determines how history is summarized by the returned `SharedTreeWithAnchors`.
-	 * @returns A factory that creates `SharedTreeWithAnchors`s and loads them from storage.
-	 */
-	public static getFactory(summarizeHistory = true): SharedTreeWithAnchorsFactory {
-		return summarizeHistory ? new SharedTreeWithAnchorsFactory() : new SharedTreeWithAnchorsFactoryNoHistory();
-	}
-
-	/**
-	 * Create a new SharedTreeFactory.
-	 * @param runtime - The runtime the SharedTreeWithAnchors will be associated with
-	 * @param id - Unique ID for the SharedTreeWithAnchors
-	 * @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,
-			TransactionWithAnchors.factory,
-			SharedTreeWithAnchorsFactory.Attributes,
-			expensiveValidation,
-			summarizeHistory
-		);
-	}
-
-	private _editor: SharedTreeWithAnchorsEditor | undefined;
-
-	/**
-	 * Returns a `SharedTreeEditor` for editing this tree in an imperative fashion. All edits are performed on the current tree view.
-	 */
-	public get editor(): SharedTreeWithAnchorsEditor {
-		if (!this._editor) {
-			this._editor = new SharedTreeWithAnchorsEditor(this);
-		}
-
-		return this._editor;
-	}
-
-	/**
-	 * {@inheritDoc GenericSharedTree.generateSummary}
-	 */
-	protected generateSummary(editLog: OrderedEditSet<AnchoredChange>): SharedTreeSummaryBase {
-		if (!this.summarizeHistory) {
-			return noHistorySummarizer(editLog, this.currentView);
-		}
-		return fullHistorySummarizer(editLog, this.currentView);
-	}
-}

package/src/anchored-edits/TransactionWithAnchors.ts

@@ -1,39 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { NodeId, DetachedSequenceId } from '../Identifiers';
-import { Snapshot } from '../Snapshot';
-import { ReconciliationPath } from '../ReconciliationPath';
-import { Transaction } from '../default-edits';
-import { AnchoredChange } from './PersistedTypes';
-import { resolveChangeAnchors } from './AnchorResolution';
-
-/**
- * A mutable transaction for applying sequences of changes to a Snapshot.
- * Allows viewing the intermediate states.
- *
- * Contains necessary state to apply changes within an edit to a Snapshot.
- *
- * May have any number of changes applied to make up the edit.
- * Use `close` to complete the transaction, returning the array of changes and an EditingResult showing the
- * results of applying the changes as an Edit to the initial Snapshot (passed to the constructor).
- *
- * No data outside the Transaction is modified by Transaction:
- * the results from `close` must be used to actually submit an `Edit`.
- */
-export class TransactionWithAnchors extends Transaction {
-	protected readonly detached: Map<DetachedSequenceId, readonly NodeId[]> = new Map();
-
-	public static factory(snapshot: Snapshot): TransactionWithAnchors {
-		return new TransactionWithAnchors(snapshot);
-	}
-
-	protected tryResolveChange(
-		change: AnchoredChange,
-		path: ReconciliationPath<AnchoredChange>
-	): AnchoredChange | undefined {
-		return resolveChangeAnchors(change, this.view, path);
-	}
-}

package/src/anchored-edits/index.ts

@@ -1,21 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-// API Exports
-
-export { SharedTreeWithAnchors, SharedTreeWithAnchorsEditor } from './SharedTreeWithAnchors';
-export * from './PersistedTypes';
-export * from './Factory';
-export { TransactionWithAnchors } from './TransactionWithAnchors';
-export {
-	resolveChangeAnchors,
-	findLastOffendingChange,
-	resolveNodeAnchor,
-	resolvePlaceAnchor,
-	resolveRangeAnchor,
-	updateRelativePlaceAnchorForChange,
-	updateRelativePlaceAnchorForPath,
-	EvaluatedChange,
-} from './AnchorResolution';