@fluid-experimental/tree 0.58.2001 → 0.59.2000-61729

package/src/generic/GenericTransaction.ts

@@ -1,194 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { assert, fail } from '../Common';
-import { ReconciliationChange, ReconciliationPath } from '../ReconciliationPath';
-import { Snapshot } from '../Snapshot';
-import { EditStatus } from './PersistedTypes';
-
-/**
- * Result of applying a transaction.
- * @public
- */
-export type EditingResult<TChange> =
-	| {
-			readonly status: EditStatus.Invalid | EditStatus.Malformed;
-			readonly changes: readonly TChange[];
-			readonly steps?: undefined;
-			readonly before: Snapshot;
-	  }
-	| ValidEditingResult<TChange>;
-
-/**
- * Result of applying a valid transaction.
- * @public
- */
-export interface ValidEditingResult<TChange> {
-	readonly status: EditStatus.Applied;
-	readonly changes: readonly TChange[];
-	readonly steps: readonly { resolvedChange: TChange; after: Snapshot }[];
-	readonly before: Snapshot;
-	readonly after: Snapshot;
-}
-
-/**
- * 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 abstract class GenericTransaction<TChange> {
-	protected readonly before: Snapshot;
-	protected _view: Snapshot;
-	protected _status: EditStatus = EditStatus.Applied;
-	protected readonly changes: TChange[] = [];
-	protected readonly steps: ReconciliationChange<TChange>[] = [];
-	protected isOpen = true;
-
-	/**
-	 * Create and open an edit of the provided `Snapshot`. After applying 0 or more changes, this editor should be closed via `close()`.
-	 * @param view - the `Snapshot` at which this edit begins. The first change will be applied against this view.
-	 */
-	public constructor(view: Snapshot) {
-		this._view = view;
-		this.before = view;
-	}
-
-	/** The most up-to-date `Snapshot` for this edit. This is the state of the tree after all changes applied so far. */
-	public get view(): Snapshot {
-		return this._view;
-	}
-
-	/** The status code of the most recent attempted change */
-	public get status(): EditStatus {
-		return this._status;
-	}
-
-	/** @returns the final `EditStatus` and `Snapshot` after all changes are applied. */
-	public close(): EditingResult<TChange> {
-		assert(this.isOpen, 'transaction has already been closed');
-		this.isOpen = false;
-		if (this.status === EditStatus.Applied) {
-			this._status = this.validateOnClose();
-		}
-		if (this.status === EditStatus.Applied) {
-			return {
-				status: EditStatus.Applied,
-				before: this.before,
-				after: this._view,
-				changes: this.changes,
-				steps: this.steps,
-			};
-		}
-		return {
-			status: this.status,
-			changes: this.changes,
-			before: this.before,
-		};
-	}
-
-	/**
-	 * Override to provide additional transaction validation when the transaction is closed.
-	 * Only invoked when a transaction is otherwise valid.
-	 */
-	protected abstract validateOnClose(): EditStatus;
-
-	/**
-	 * A helper to apply a sequence of changes. Changes will be applied one after the other. If a change fails to apply,
-	 * the remaining changes in `changes` will be ignored.
-	 * @param changes - the sequence of changes to apply.
-	 * @param path - the reconciliation path for the first change.
-	 * @returns this
-	 */
-	public applyChanges(changes: Iterable<TChange>, path: ReconciliationPath<TChange> = []): this {
-		const iter = changes[Symbol.iterator]();
-		const firstChange = iter.next().value;
-		let iterResult = iter.next();
-		if (iterResult.done === true) {
-			for (const change of changes) {
-				if (this.applyChange(change, path).status !== EditStatus.Applied) {
-					return this;
-				}
-			}
-			return this;
-		}
-
-		if (this.applyChange(firstChange, path).status !== EditStatus.Applied) {
-			return this;
-		}
-
-		const ongoingEdit = {
-			0: this.steps[this.steps.length - 1],
-			before: this.view,
-			after: this.view,
-			length: 1,
-		};
-
-		/**
-		 * We use a Proxy instead of `{ ...path, ...objectWithOngoingEdit }` to avoid eagerly demanding all parts of the path, which may
-		 * require extensive computation.
-		 */
-		const pathWithOngoingEdit = new Proxy(path, {
-			get: (
-				target: ReconciliationPath<TChange>,
-				prop: string
-			): ReconciliationPath<TChange>[number | 'length'] => {
-				if (prop === 'length') {
-					return target.length + 1;
-				}
-
-				return prop === String(target.length) ? ongoingEdit : target[prop];
-			},
-		});
-
-		while (iterResult.done !== true) {
-			if (this.applyChange(iterResult.value, pathWithOngoingEdit).status !== EditStatus.Applied) {
-				return this;
-			}
-
-			ongoingEdit[ongoingEdit.length] = this.steps[this.steps.length - 1];
-			ongoingEdit.length += 1;
-			ongoingEdit.after = this.view;
-			iterResult = iter.next();
-		}
-		return this;
-	}
-
-	protected tryResolveChange(change: TChange, path: ReconciliationPath<TChange>): TChange | undefined {
-		return change;
-	}
-
-	/**
-	 * Attempt to apply the given change as part of this edit. This method should not be called if a previous change in this edit failed to
-	 * apply.
-	 * @param change - the change to apply
-	 * @param path - the reconciliation path for the change.
-	 * @returns this
-	 */
-	public applyChange(change: TChange, path: ReconciliationPath<TChange> = []): this {
-		assert(this.isOpen, 'Editor must be open to apply changes.');
-		if (this.status !== EditStatus.Applied) {
-			fail('Cannot apply change to an edit unless all previous changes have applied');
-		}
-		const resolvedChange = this.tryResolveChange(change, path);
-		if (resolvedChange === undefined) {
-			this._status = EditStatus.Invalid;
-			return this;
-		}
-		this.changes.push(change);
-		this._status = this.dispatchChange(resolvedChange);
-		this.steps.push({ resolvedChange, after: this.view });
-		return this;
-	}
-
-	protected abstract dispatchChange(change: TChange): EditStatus;
-}

package/src/generic/PersistedTypes.ts

@@ -1,221 +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 { Serializable } from '@fluidframework/datastore-definitions';
-import { Definition, DetachedSequenceId, EditId, NodeId, TraitLabel } from '../Identifiers';
-
-/**
- * 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.
- */
-
-/**
- * A collection of changes to the tree that are applied atomically along with a unique identifier for the edit.
- * If any individual change fails to apply, the entire Edit will fail to apply.
- * @public
- */
-export interface Edit<TChange> extends EditBase<TChange> {
-	/**
-	 * Unique identifier for this edit. Must never be reused.
-	 * Used for referencing and de-duplicating edits.
-	 */
-	readonly id: EditId;
-}
-
-/**
- * A collection of changes to the tree that are applied atomically. If any individual change fails to apply,
- * the entire Edit will fail to apply.
- * @public
- */
-export interface EditWithoutId<TChange> extends EditBase<TChange> {
-	/**
-	 * Used to explicitly state that EditWithoutId cannot contain an id and prevents type Edit from being assigned to type EditWithoutId.
-	 */
-	readonly id?: never;
-}
-
-/**
- * The information included in an edit.
- * @public
- */
-export interface EditBase<TChange> {
-	/**
-	 * Actual changes to apply.
-	 * Applied in order as part of a single transaction.
-	 */
-	readonly changes: readonly TChange[];
-
-	// Add more metadata fields as needed in the future.
-	// Include "high level"/"Domain Specific"/"Hierarchal" edits for application/domain use in implementing domain aware merge heuristics.
-}
-
-/**
- * Json compatible map as object.
- * Keys are TraitLabels,
- * Values are the content of the trait specified by the key.
- * @public
- */
-export interface TraitMap<TChild> {
-	readonly [key: string]: TreeNodeSequence<TChild>;
-}
-
-/**
- * A sequence of Nodes that make up a trait under a Node
- * @public
- */
-export type TreeNodeSequence<TChild> = readonly TChild[];
-
-/**
- * Json compatible representation of a payload storing arbitrary Serializable data.
- *
- * Keys starting with "IFluid" are reserved for special use such as the JavaScript feature detection pattern and should not be used.
- *
- * See {@link comparePayloads} for equality semantics and related details (like what is allowed to be lost when serializing)
- *
- * TODO:#51984: Allow opting into heuristic blobbing in snapshots with a special IFluid key.
- *
- * @public
- */
-export type Payload = Serializable;
-
-/**
- * The fields required by a node in a tree
- * @public
- */
-export interface NodeData {
-	readonly payload?: Payload;
-
-	/**
-	 * The meaning of this node.
-	 * Provides contexts/semantics for this node and its content.
-	 * Typically use to associate a node with metadata (including a schema) and source code (types, behaviors, etc).
-	 */
-	readonly definition: Definition;
-
-	/**
-	 * Identifier which can be used to refer to this Node.
-	 */
-	readonly identifier: NodeId;
-}
-
-/**
- * Satisfies `NodeData` and may contain children under traits (which may or may not be `TreeNodes`)
- * @public
- */
-export interface TreeNode<TChild> extends NodeData {
-	readonly traits: TraitMap<TChild>;
-}
-
-/**
- * Specifies the location of a trait (a labeled sequence of nodes) within the tree.
- * @public
- */
-export interface TraitLocation {
-	readonly parent: NodeId;
-	readonly label: TraitLabel;
-}
-
-/**
- * JSON-compatible Node type. Objects of type `ChangeNode` will be persisted in `Changes` (under Edits) in the SharedTree history.
- * @public
- */
-export type ChangeNode = TreeNode<ChangeNode>;
-
-/**
- * Node or sequence of Nodes for use in a Build change.
- *
- * Other formats for sub-sequences of Nodes can be added here, and those formats should be supported in blobs as well.
- * Future formats will include referenced blobs containing sequences of Nodes,
- * template based metadata and identity deduplication, and possibly compressed and binary formats.
- * These optimized formats should also be used within snapshots.
- * @public
- */
-export type BuildNode = TreeNode<BuildNode> | DetachedSequenceId;
-
-/**
- * The status code of an attempt to apply the changes in an Edit.
- * @public
- */
-export enum EditStatus {
-	/**
-	 * The edit contained one or more malformed changes (e.g. was missing required fields such as `id`),
-	 * or contained a sequence of changes that could not possibly be applied sequentially without error
-	 * (e.g. an edit which tries to insert the same detached node twice).
-	 */
-	Malformed,
-	/**
-	 * The edit contained a well-formed sequence of changes that couldn't be applied to the current view,
-	 * generally because concurrent changes caused one or more merge conflicts.
-	 */
-	Invalid,
-	/**
-	 * The edit was applied to the current view successfully.
-	 */
-	Applied,
-}
-
-/**
- * Types of ops handled by SharedTree.
- */
-export enum SharedTreeOpType {
-	/** An op that includes edit information. */
-	Edit,
-	/** Includes a Fluid handle that corresponds to an edit chunk. */
-	Handle,
-	/** An op that does not affect the tree's state. */
-	NoOp,
-}
-
-/**
- * Requirements for SharedTree ops.
- */
-export interface SharedTreeOp {
-	type: SharedTreeOpType;
-}
-
-/**
- * A SharedTree op that includes edit information.
- */
-export interface SharedTreeEditOp<TChange> extends SharedTreeOp {
-	edit: Edit<TChange>;
-}
-
-/**
- * A SharedTree op that includes edit handle information.
- * The handle corresponds to an edit chunk in the edit log.
- */
-export interface SharedTreeHandleOp extends SharedTreeOp {
-	/** The serialized handle to an uploaded edit chunk. */
-	editHandle: string;
-	/** The index of the first edit in the chunk that corresponds to the handle. */
-	startRevision: number;
-}

package/src/generic/Summary.ts

@@ -1,113 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { IFluidHandle } from '@fluidframework/core-interfaces';
-import { IFluidSerializer, serializeHandles } from '@fluidframework/shared-object-base';
-import { assert, assertNotUndefined } from '../Common';
-import { EditLogSummary, OrderedEditSet } from '../EditLog';
-import { Snapshot } from '../Snapshot';
-import { readFormatVersion, SharedTreeSummary_0_0_2 } from '../SummaryBackCompatibility';
-import { ChangeNode, Edit } from './PersistedTypes';
-
-/**
- * Format version for summaries that are written.
- * When next changing the format, we should add a new format version variable for the edit-specific summaries and assign it an independent
- * version number.
- */
-export const formatVersion = '0.0.2';
-
-/**
- * Handler for summarizing the tree state.
- * The handler is invoked when saving a summary. It accepts a view of the current state of the tree, the sequenced edits known
- * to the SharedTree, and optional helpers for serializing the edit information.
- * @returns a summary of the supplied state.
- * @internal
- */
-export type SharedTreeSummarizer<TChange> = (
-	editLog: OrderedEditSet<TChange>,
-	currentView: Snapshot
-) => SharedTreeSummaryBase;
-
-/**
- * The minimal information on a SharedTree summary. Contains the summary format version.
- */
-export interface SharedTreeSummaryBase {
-	/**
-	 * Field on summary under which version is stored.
-	 */
-	readonly version: string;
-}
-
-/**
- * The contents of a SharedTree summary: the current tree, and the edits needed to get from `initialTree` to the current tree.
- * @public
- */
-export interface SharedTreeSummary<TChange> extends SharedTreeSummaryBase {
-	readonly currentTree: ChangeNode;
-
-	/**
-	 * Information that can populate an edit log.
-	 */
-	readonly editHistory?: EditLogSummary<TChange>;
-}
-
-/**
- * Serializes a SharedTree summary into a JSON string. This may later be used to initialize a SharedTree's state via `deserialize()`
- * Also replaces handle objects with their serialized form.
- *
- * @param summary - The SharedTree summary to serialize.
- * @param serializer - The serializer required to serialize handles in the summary.
- * @param bind - The object handle required to serialize handles in the summary
- */
-export function serialize(summary: SharedTreeSummaryBase, serializer: IFluidSerializer, bind: IFluidHandle): string {
-	return assertNotUndefined(serializeHandles(summary, serializer, bind));
-}
-
-/**
- * Preserves the full history in the generated summary.
- * @public
- */
-export function fullHistorySummarizer<TChange>(
-	editLog: OrderedEditSet<TChange>,
-	currentView: Snapshot
-): SharedTreeSummary_0_0_2<TChange> {
-	const { editChunks, editIds } = editLog.getEditLogSummary();
-
-	const sequencedEdits: Edit<TChange>[] = [];
-	let idIndex = 0;
-	editChunks.forEach(({ chunk }) => {
-		assert(
-			Array.isArray(chunk),
-			'Handles should not be included in the summary until format version 0.1.0 is being written.'
-		);
-
-		chunk.forEach(({ changes }) => {
-			sequencedEdits.push({
-				changes,
-				id: assertNotUndefined(editIds[idIndex++], 'Number of edits should match number of edit IDs.'),
-			});
-		});
-	});
-
-	return {
-		currentTree: currentView.getChangeNodeTree(),
-		sequencedEdits,
-		version: formatVersion,
-	};
-}
-
-/**
- * Generates a summary with format version 0.1.0. This will prefer handles over edits in edit chunks where possible.
- */
-export function fullHistorySummarizer_0_1_0<TChange>(
-	editLog: OrderedEditSet<TChange>,
-	currentView: Snapshot
-): SharedTreeSummary<TChange> {
-	return {
-		currentTree: currentView.getChangeNodeTree(),
-		editHistory: editLog.getEditLogSummary(true),
-		version: readFormatVersion,
-	};
-}

package/src/generic/index.ts

@@ -1,41 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-// API Exports
-
-export {
-	EditCommittedHandler,
-	EditCommittedEventArguments,
-	ISharedTreeEvents,
-	GenericSharedTree,
-	SharedTreeEvent,
-	SharedTreeDiagnosticEvent,
-} from './GenericSharedTree';
-export {
-	Edit,
-	EditWithoutId,
-	EditBase,
-	TraitMap,
-	TreeNodeSequence,
-	Payload,
-	NodeData,
-	TreeNode,
-	ChangeNode,
-	BuildNode,
-	EditStatus,
-	TraitLocation,
-	SharedTreeOpType,
-} from './PersistedTypes';
-export { newEdit, newEditId } from './GenericEditUtilities';
-export { GenericTransaction, EditingResult, ValidEditingResult } from './GenericTransaction';
-export {
-	SharedTreeSummary,
-	SharedTreeSummaryBase,
-	SharedTreeSummarizer,
-	fullHistorySummarizer,
-	fullHistorySummarizer_0_1_0,
-	formatVersion,
-	serialize,
-} from './Summary';