@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/core/README.md

@@ -1,9 +1,5 @@
 # core
 
-Reexports the contents of the "core" libraries.
-This is the set of libraries on which [shared-tree-core](../shared-tree-core/README.md) depends.
+The set of libraries on which [shared-tree-core](../shared-tree-core/README.md) depends.
 
 This mainly exists to simplify imports for code like [feature-libraries](../feature-libraries/README.md) and [shared-tree](../shared-tree/README.md).
-
-The core libraries could be nested inside this directory (as is done with [feature-libraries](../feature-libraries/README.md));
-for now this was avoided to keep the nesting levels lower and avoid having to move a lot of code.

package/src/core/change-family/changeFamily.ts

@@ -4,10 +4,11 @@
  */
 
 import { SessionId } from "@fluidframework/id-compressor";
+
 import { ICodecFamily, IJsonCodec } from "../../codec/index.js";
-import { ChangeRebaser } from "../rebase/index.js";
+import { SchemaAndPolicy } from "../../core/index.js";
 import { JsonCompatibleReadOnly } from "../../util/index.js";
-import { SchemaAndPolicy } from "../../feature-libraries/index.js";
+import { ChangeRebaser } from "../rebase/index.js";
 
 export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
 	buildEditor(changeReceiver: (change: TChange) => void): TEditor;

package/src/core/forest/editableForest.ts

@@ -3,19 +3,21 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import { RevisionTagCodec } from "../rebase/index.js";
 import { FieldKey } from "../schema-stored/index.js";
 import {
-	DetachedField,
 	Anchor,
-	ITreeCursorSynchronous,
+	DeltaRoot,
 	DeltaVisitor,
+	DetachedField,
+	ITreeCursorSynchronous,
 	applyDelta,
-	makeDetachedFieldIndex,
 	deltaForRootInitialization,
-	DeltaRoot,
+	makeDetachedFieldIndex,
 } from "../tree/index.js";
+
 import { IForestSubscription, ITreeSubscriptionCursor } from "./forest.js";
 
 /**

package/src/core/forest/forest.ts

@@ -3,19 +3,21 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import { ISubscribable } from "../../events/index.js";
-import { TreeStoredSchemaSubscription, FieldKey } from "../schema-stored/index.js";
+import { FieldKey, TreeStoredSchemaSubscription } from "../schema-stored/index.js";
 import {
 	Anchor,
 	AnchorSet,
 	DetachedField,
-	detachedFieldAsKey,
 	ITreeCursor,
 	ITreeCursorSynchronous,
-	rootField,
 	UpPath,
+	detachedFieldAsKey,
+	rootField,
 } from "../tree/index.js";
+
 import type { IEditableForest } from "./editableForest.js";
 
 /**
@@ -34,6 +36,11 @@ import type { IEditableForest } from "./editableForest.js";
  * @internal
  */
 export interface ForestEvents {
+	/**
+	 * A new root field was just created in this forest.
+	 */
+	afterRootFieldCreated(key: FieldKey): void;
+
 	/**
 	 * The forest is about to be changed.
 	 * Emitted before the first change in a batch of changes.

package/src/core/index.ts

@@ -123,7 +123,7 @@ export {
 	TreeStoredSchemaSubscription as TreeStoredSchemaSubscription,
 	MutableTreeStoredSchema,
 	FieldKindIdentifier,
-	FieldKindSpecifier,
+	FieldKindData,
 	TreeTypeSet,
 	TreeStoredSchema,
 	TreeStoredSchemaRepository,
@@ -136,11 +136,14 @@ export {
 	LeafNodeStoredSchema,
 	ObjectNodeStoredSchema,
 	MapNodeStoredSchema,
-	BrandedTreeNodeSchemaDataFormat,
+	toTreeNodeSchemaDataFormat,
 	decodeFieldSchema,
 	encodeFieldSchema,
 	storedSchemaDecodeDispatcher,
 	ErasedTreeNodeSchemaDataFormat,
+	SchemaAndPolicy,
+	Multiplicity,
+	SchemaPolicy,
 } from "./schema-stored/index.js";
 
 export {
@@ -159,6 +162,8 @@ export {
 	findAncestor,
 	findCommonAncestor,
 	GraphCommit,
+	CommitKind,
+	CommitMetadata,
 	RevisionTag,
 	RevisionTagSchema,
 	RevisionTagCodec,
@@ -184,6 +189,8 @@ export {
 	RevisionInfo,
 	EncodedRevisionTag,
 	EncodedChangeAtomId,
+	taggedAtomId,
+	taggedOptAtomId,
 } from "./rebase/index.js";
 
 export {
@@ -194,9 +201,4 @@ export {
 	AllowedUpdateType,
 } from "./schema-view/index.js";
 
-export {
-	Revertible,
-	RevertibleKind,
-	RevertibleStatus,
-	RevertibleResult,
-} from "./revertible/index.js";
+export { Revertible, RevertibleStatus } from "./revertible/index.js";

package/src/core/rebase/changeRebaser.ts

@@ -4,6 +4,7 @@
  */
 
 import { Invariant } from "../../util/index.js";
+
 import type { RevisionTag } from "./types.js";
 
 /**

package/src/core/rebase/index.ts

@@ -9,6 +9,8 @@ export {
 	asChangeAtomId,
 	mintCommit,
 	GraphCommit,
+	CommitKind,
+	CommitMetadata,
 	RevisionTag,
 	RevisionTagSchema,
 	EncodedRevisionTag,
@@ -17,6 +19,8 @@ export {
 	ChangeAtomId,
 	ChangeAtomIdMap,
 	SessionIdSchema,
+	taggedAtomId,
+	taggedOptAtomId,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";
 export {

package/src/core/rebase/revisionTagCodec.ts

@@ -3,10 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
 import { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
+
 import { IJsonCodec } from "../../codec/index.js";
 import { ChangeEncodingContext } from "../change-family/index.js";
+
 import { EncodedRevisionTag, RevisionTag } from "./types.js";
 
 export class RevisionTagCodec

package/src/core/rebase/types.ts

@@ -3,12 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import { Type } from "@sinclair/typebox";
 import {
 	OpSpaceCompressedId,
 	SessionId,
 	SessionSpaceCompressedId,
 } from "@fluidframework/id-compressor";
+import { Type } from "@sinclair/typebox";
+
 import {
 	Brand,
 	NestedMap,
@@ -94,6 +95,20 @@ export function asChangeAtomId(id: ChangesetLocalId | ChangeAtomId): ChangeAtomI
 	return typeof id === "object" ? id : { localId: id };
 }
 
+export function taggedAtomId(id: ChangeAtomId, revision: RevisionTag | undefined): ChangeAtomId {
+	return makeChangeAtomId(id.localId, id.revision ?? revision);
+}
+
+export function taggedOptAtomId(
+	id: ChangeAtomId | undefined,
+	revision: RevisionTag | undefined,
+): ChangeAtomId | undefined {
+	if (id === undefined) {
+		return undefined;
+	}
+	return taggedAtomId(id, revision);
+}
+
 /**
  * A node in a graph of commits. A commit's parent is the commit on which it was based.
  */
@@ -108,6 +123,36 @@ export interface GraphCommit<TChange> {
 	inverse?: TChange;
 }
 
+/**
+ * The type of a commit. This is used to describe the context in which the commit was created.
+ *
+ * @public
+ */
+export enum CommitKind {
+	/** A commit corresponding to a change that is not the result of an undo/redo. */
+	Default,
+	/** A commit that is the result of an undo. */
+	Undo,
+	/** A commit that is the result of a redo. */
+	Redo,
+}
+
+/**
+ * Information about a commit that has been applied.
+ *
+ * @public
+ */
+export interface CommitMetadata {
+	/**
+	 * A {@link CommitKind} enum value describing whether the commit represents an Edit, an Undo, or a Redo.
+	 */
+	readonly kind: CommitKind;
+	/**
+	 * Indicates whether the commit is a local edit
+	 */
+	readonly isLocal: boolean;
+}
+
 /**
  * Creates a new graph commit object. This is useful for creating copies of commits with different parentage.
  * @param parent - the parent of the new commit

package/src/core/rebase/utils.ts

@@ -3,8 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import { Mutable } from "../../util/index.js";
+
 import {
 	ChangeRebaser,
 	RevisionInfo,
@@ -14,7 +16,7 @@ import {
 	tagChange,
 	tagRollbackInverse,
 } from "./changeRebaser.js";
-import { GraphCommit, mintCommit, RevisionTag } from "./types.js";
+import { GraphCommit, RevisionTag, mintCommit } from "./types.js";
 
 /**
  * Contains information about how the commit graph changed as the result of rebasing a source branch onto another target branch.
@@ -240,10 +242,9 @@ export function rebaseBranch<TChange>(
 	const revisionMetadata = revisionMetadataSourceFromInfo(revInfos);
 	let currentComposedEdit = makeAnonChange(changeRebaser.compose(targetRebasePath));
 	for (const c of sourcePath) {
-		const editsToCompose: TaggedChange<TChange>[] = [
-			tagRollbackInverse(changeRebaser.invert(c, true), mintRevisionTag(), c.revision),
-			currentComposedEdit,
-		];
+		const inverseTag = mintRevisionTag();
+		const inverse = tagRollbackInverse(changeRebaser.invert(c, true), inverseTag, c.revision);
+		const editsToCompose: TaggedChange<TChange>[] = [inverse, currentComposedEdit];
 		if (sourceSet.has(c.revision)) {
 			const change = changeRebaser.rebase(c.change, currentComposedEdit, revisionMetadata);
 			newHead = {
@@ -255,6 +256,8 @@ export function rebaseBranch<TChange>(
 			editsToCompose.push(tagChange(change, c.revision));
 		}
 		currentComposedEdit = makeAnonChange(changeRebaser.compose(editsToCompose));
+		revInfos.unshift({ revision: inverseTag, rollbackOf: inverse.rollbackOf });
+		revInfos.push({ revision: c.revision });
 	}
 
 	return {

package/src/core/revertible/index.ts

@@ -3,4 +3,4 @@
  * Licensed under the MIT License.
  */
 
-export { Revertible, RevertibleKind, RevertibleStatus, RevertibleResult } from "./revertible.js";
+export { Revertible, RevertibleStatus } from "./revertible.js";

package/src/core/revertible/revertible.ts

@@ -3,66 +3,45 @@
  * Licensed under the MIT License.
  */
 
+import { disposeSymbol } from "../../util/index.js";
+
 /**
  * Allows reversion of a change made to SharedTree.
  *
+ * @remarks
  * Applications wanting to implement undo/redo support might typically maintain two stacks of Revertibles, with optional eviction policy to free up memory.
- * @internal
+ *
+ * @public
  */
 export interface Revertible {
-	/** Indicates the type of edit that produced this revertible. */
-	readonly kind: RevertibleKind;
-	/**
-	 * Information about which client created the edit.
-	 */
-	readonly origin: {
-		/**
-		 * Indicates if the {@link Revertible} is from the local client (true) or a remote client (false).
-		 */
-		readonly isLocal: boolean;
-	};
 	/**
 	 * The current status of the revertible.
 	 */
 	readonly status: RevertibleStatus;
+
 	/**
-	 * Reverts the associated change and decrements the reference count of the revertible.
-	 */
-	revert(): RevertibleResult;
-	/**
-	 * Increments the reference count of the revertible.
-	 * Should be called to prevent/delay the garbage collection of the resources associated with this revertible.
+	 * Reverts the associated change and disposes it.
 	 */
-	retain(): RevertibleResult;
+	revert(): void;
 	/**
-	 * Decrements the reference count of the revertible.
+	 * Reverts the associated change and optionally disposes it.
+	 *
+	 * @param dispose - If true, the revertible will be disposed after being reverted.
+	 * If false, the revertible will remain valid. This can be useful for scenarios where the revert may be dropped
+	 * due to merge conflicts, and one wants to attempt reverting again.
 	 */
-	discard(): RevertibleResult;
-}
+	revert(dispose: boolean): void;
 
-/**
- * The type of revertible commit.
- *
- * @internal
- */
-export enum RevertibleKind {
-	/** A typical local commit */
-	Default,
-	/** A revertible that is the result of an undo. */
-	Undo,
-	/** A revertible that is the result of a redo. */
-	Redo,
 	/**
-	 * A revertible that is the result of a rebase and should replace a previously generated revertible.
-	 * todo: improve error reporting in this case
+	 * Disposes this revertible, allowing associated resources to be released.
 	 */
-	Rebase,
+	[disposeSymbol](): void;
 }
 
 /**
  * The status of a {@link Revertible}.
  *
- * @internal
+ * @public
  */
 export enum RevertibleStatus {
 	/** The revertible can be reverted. */
@@ -70,15 +49,3 @@ export enum RevertibleStatus {
 	/** The revertible has been disposed. Reverting it will have no effect. */
 	Disposed,
 }
-
-/**
- * The result of a revert operation.
- *
- * @internal
- */
-export enum RevertibleResult {
-	/** The operation was successful. */
-	Success,
-	/** The operation failed. This occurs when attempting an operation on a disposed revertible */
-	Failure,
-}

package/src/core/schema-stored/format.ts

@@ -4,6 +4,7 @@
  */
 
 import { ObjectOptions, Static, Type } from "@sinclair/typebox";
+
 import { unionOptions } from "../../codec/index.js";
 import { Brand, brandedStringType } from "../../util/index.js";
 

package/src/core/schema-stored/index.ts

@@ -8,7 +8,7 @@ export {
 	ValueSchema,
 	TreeNodeStoredSchema,
 	TreeTypeSet,
-	FieldKindSpecifier,
+	FieldKindData,
 	TreeStoredSchema,
 	forbiddenFieldKindIdentifier,
 	storedEmptyFieldSchema,
@@ -16,11 +16,13 @@ export {
 	LeafNodeStoredSchema,
 	ObjectNodeStoredSchema,
 	MapNodeStoredSchema,
-	BrandedTreeNodeSchemaDataFormat,
 	decodeFieldSchema,
 	encodeFieldSchema,
 	storedSchemaDecodeDispatcher,
 	ErasedTreeNodeSchemaDataFormat,
+	toTreeNodeSchemaDataFormat,
+	SchemaAndPolicy,
+	SchemaPolicy,
 } from "./schema.js";
 export {
 	TreeStoredSchemaSubscription,
@@ -29,6 +31,7 @@ export {
 	schemaDataIsEmpty,
 	SchemaEvents,
 } from "./storedSchemaRepository.js";
+export { Multiplicity } from "./multiplicity.js";
 
 export { TreeNodeSchemaIdentifier, FieldKey, FieldKindIdentifier } from "./format.js";
 

package/src/{feature-libraries → core/schema-stored}/multiplicity.ts

@@ -2,6 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+
 /**
  * Describes how a particular field functions.
  *

package/src/core/schema-stored/schema.ts

@@ -3,16 +3,9 @@
  * Licensed under the MIT License.
  */
 
+import type { ErasedType } from "@fluidframework/core-interfaces";
 import { DiscriminatedUnionDispatcher } from "../../codec/index.js";
-import {
-	Brand,
-	Erased,
-	MakeNominal,
-	brand,
-	brandErased,
-	fail,
-	invertMap,
-} from "../../util/index.js";
+import { MakeNominal, brand, fail, invertMap } from "../../util/index.js";
 import {
 	FieldKey,
 	FieldKindIdentifier,
@@ -21,6 +14,7 @@ import {
 	TreeNodeSchemaDataFormat,
 	TreeNodeSchemaIdentifier,
 } from "./format.js";
+import { Multiplicity } from "./multiplicity.js";
 
 /**
  * Schema for what {@link TreeValue} is allowed on a Leaf node.
@@ -67,15 +61,39 @@ export enum ValueSchema {
 export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier> | undefined;
 
 /**
- * Specifies which field kind to use.
+ * Declarative portion of a Field Kind.
  *
  * @remarks
- * This is used instead of just the FieldKindIdentifier so that it can be subtyped into a more expressive type with additional information.
+ * Enough info about a field kind to know if a given tree is is schema.
  *
  * @internal
  */
-export interface FieldKindSpecifier<T = FieldKindIdentifier> {
-	identifier: T;
+export interface FieldKindData {
+	readonly identifier: FieldKindIdentifier;
+	readonly multiplicity: Multiplicity;
+}
+
+/**
+ * Everything needed to define what it means for a tree to be in schema.
+ */
+export interface SchemaAndPolicy {
+	readonly schema: StoredSchemaCollection;
+	readonly policy: SchemaPolicy;
+}
+
+/**
+ * Extra data needed to interpret schema.
+ * @internal
+ */
+export interface SchemaPolicy {
+	/**
+	 * Policy information about FieldKinds:
+	 * This is typically stored as code, not in documents, and defines how to handle fields based on their kind.
+	 * It is assumed that all users of a document will have exactly the same FieldKind policies,
+	 * though older applications might be missing some,
+	 * and will be unable to process any changes that use those FieldKinds.
+	 */
+	readonly fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindData>;
 }
 
 /**
@@ -84,7 +102,7 @@ export interface FieldKindSpecifier<T = FieldKindIdentifier> {
  * @internal
  */
 export interface TreeFieldStoredSchema {
-	readonly kind: FieldKindSpecifier;
+	readonly kind: FieldKindIdentifier;
 	/**
 	 * The set of allowed child types.
 	 * If not specified, types are unconstrained.
@@ -110,7 +128,7 @@ export const forbiddenFieldKindIdentifier = "Forbidden";
  */
 export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
 	// This kind requires the field to be empty.
-	kind: { identifier: brand(forbiddenFieldKindIdentifier) },
+	kind: brand(forbiddenFieldKindIdentifier),
 	// This type set also forces the field to be empty not not allowing any types as all.
 	types: new Set(),
 };
@@ -119,9 +137,19 @@ export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
  * Opaque type erased handle to the encoded representation of the contents of a stored schema.
  * @internal
  */
-export interface ErasedTreeNodeSchemaDataFormat extends Erased<"TreeNodeSchemaDataFormat"> {}
-export interface BrandedTreeNodeSchemaDataFormat
-	extends Brand<TreeNodeSchemaDataFormat, ErasedTreeNodeSchemaDataFormat> {}
+export interface ErasedTreeNodeSchemaDataFormat extends ErasedType<"TreeNodeSchemaDataFormat"> {}
+
+function toErasedTreeNodeSchemaDataFormat(
+	data: TreeNodeSchemaDataFormat,
+): ErasedTreeNodeSchemaDataFormat {
+	return data as unknown as ErasedTreeNodeSchemaDataFormat;
+}
+
+export function toTreeNodeSchemaDataFormat(
+	data: ErasedTreeNodeSchemaDataFormat,
+): TreeNodeSchemaDataFormat {
+	return data as unknown as TreeNodeSchemaDataFormat;
+}
 
 /**
  * @internal
@@ -168,7 +196,7 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 				value: encodeFieldSchema(this.objectNodeFields.get(key) ?? fail("missing field")),
 			});
 		}
-		return brandErased<BrandedTreeNodeSchemaDataFormat>({
+		return toErasedTreeNodeSchemaDataFormat({
 			object: fieldsObject,
 		});
 	}
@@ -191,7 +219,7 @@ export class MapNodeStoredSchema extends TreeNodeStoredSchema {
 	}
 
 	public override encode(): ErasedTreeNodeSchemaDataFormat {
-		return brandErased<BrandedTreeNodeSchemaDataFormat>({
+		return toErasedTreeNodeSchemaDataFormat({
 			map: encodeFieldSchema(this.mapFields),
 		});
 	}
@@ -218,7 +246,7 @@ export class LeafNodeStoredSchema extends TreeNodeStoredSchema {
 	}
 
 	public override encode(): ErasedTreeNodeSchemaDataFormat {
-		return brandErased<BrandedTreeNodeSchemaDataFormat>({
+		return toErasedTreeNodeSchemaDataFormat({
 			leaf: encodeValueSchema(this.leafValue),
 		});
 	}
@@ -260,7 +288,7 @@ function decodeValueSchema(inMemory: PersistedValueSchema): ValueSchema {
 
 export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFormat {
 	const out: FieldSchemaFormat = {
-		kind: schema.kind.identifier,
+		kind: schema.kind,
 	};
 	if (schema.types !== undefined) {
 		out.types = [...schema.types];
@@ -271,7 +299,7 @@ export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFor
 export function decodeFieldSchema(schema: FieldSchemaFormat): TreeFieldStoredSchema {
 	const out: TreeFieldStoredSchema = {
 		// TODO: maybe provide actual FieldKind objects here, error on unrecognized kinds.
-		kind: { identifier: schema.kind },
+		kind: schema.kind,
 		types: schema.types === undefined ? undefined : new Set(schema.types),
 	};
 	return out;

package/src/core/schema-stored/storedSchemaRepository.ts

@@ -4,8 +4,11 @@
  */
 
 import { BTree } from "@tylerbu/sorted-btree-es6";
-import { createEmitter, ISubscribable } from "../../events/index.js";
+
+import { ISubscribable, createEmitter } from "../../events/index.js";
 import { compareStrings } from "../../util/index.js";
+
+import { TreeNodeSchemaIdentifier } from "./format.js";
 import {
 	StoredSchemaCollection,
 	TreeFieldStoredSchema,
@@ -13,7 +16,6 @@ import {
 	TreeStoredSchema,
 	storedEmptyFieldSchema,
 } from "./schema.js";
-import { TreeNodeSchemaIdentifier } from "./format.js";
 
 /**
  * Events for {@link TreeStoredSchemaSubscription}.