@fluidframework/tree 2.30.0 → 2.31.0

package/src/shared-tree/treeApiAlpha.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import { createIdCompressor } from "@fluidframework/id-compressor/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
@@ -38,7 +38,7 @@ import {
 	TreeViewConfiguration,
 	type TreeBranch,
 } from "../simple-tree/index.js";
-import { fail, type JsonCompatible } from "../util/index.js";
+import type { JsonCompatible } from "../util/index.js";
 import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
 import type { ITreeCursorSynchronous } from "../core/index.js";
 import {
@@ -137,12 +137,20 @@ export const TreeAlpha: {
 	 */
 	exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
 
+	/**
+	 * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.
+	 */
+	exportConcise(
+		node: TreeNode | TreeLeafValue | undefined,
+		options?: EncodeOptions,
+	): ConciseTree | undefined;
+
 	/**
 	 * Copy a snapshot of the current version of a TreeNode into a JSON compatible plain old JavaScript Object (except for {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles}).
 	 * Uses the {@link VerboseTree} format, with an explicit type on every node.
 	 *
 	 * @remarks
-	 * There are several cases this may be preferred to {@link TreeAlpha.exportConcise}:
+	 * There are several cases this may be preferred to {@link TreeAlpha.(exportConcise:1)}:
 	 *
 	 * 1. When not using {@link ITreeConfigurationOptions.preventAmbiguity} (or when using `useStableFieldKeys`), `exportConcise` can produce ambiguous data (the type may be unclear on some nodes).
 	 * `exportVerbose` will always be unambiguous and thus lossless.
@@ -251,16 +259,7 @@ export const TreeAlpha: {
 		return createFromCursor(schema, cursor);
 	},
 
-	exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree {
-		const config: EncodeOptions = { ...options };
-
-		const cursor = borrowCursorFromTreeNodeOrValue(node);
-		return conciseFromCursor(
-			cursor,
-			tryGetSchema(node) ?? fail(0xacd /* invalid input */),
-			config,
-		);
-	},
+	exportConcise,
 
 	exportVerbose(node: TreeNode | TreeLeafValue, options?: EncodeOptions): VerboseTree {
 		const config: EncodeOptions = { ...options };
@@ -315,6 +314,30 @@ export const TreeAlpha: {
 	},
 };
 
+function exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
+
+function exportConcise(
+	node: TreeNode | TreeLeafValue | undefined,
+	options?: EncodeOptions,
+): ConciseTree | undefined;
+
+function exportConcise(
+	node: TreeNode | TreeLeafValue | undefined,
+	options?: EncodeOptions,
+): ConciseTree | undefined {
+	if (node === undefined) {
+		return undefined;
+	}
+	const config: EncodeOptions = { ...options };
+
+	const cursor = borrowCursorFromTreeNodeOrValue(node);
+	return conciseFromCursor(
+		cursor,
+		tryGetSchema(node) ?? fail(0xacd /* invalid input */),
+		config,
+	);
+}
+
 function borrowCursorFromTreeNodeOrValue(
 	node: TreeNode | TreeLeafValue,
 ): ITreeCursorSynchronous {

package/src/shared-tree/treeCheckout.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
@@ -60,13 +60,7 @@ import {
 	type SharedTreeBranchChange,
 	type Transactor,
 } from "../shared-tree-core/index.js";
-import {
-	Breakable,
-	disposeSymbol,
-	fail,
-	getOrCreate,
-	type WithBreakable,
-} from "../util/index.js";
+import { Breakable, disposeSymbol, getOrCreate, type WithBreakable } from "../util/index.js";
 
 import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";

package/src/shared-tree-core/branch.ts

@@ -282,10 +282,11 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	 * Apply all the divergent changes on the given branch to this branch.
 	 *
 	 * @param branch - the branch to merge into this branch
-	 * @returns the net change to this branch and the commits that were added to this branch by the merge,
-	 * or undefined if nothing changed
+	 * @returns the commits that were added to this branch by the merge, or undefined if nothing changed
 	 */
-	public merge(branch: SharedTreeBranch<TEditor, TChange>): void {
+	public merge(
+		branch: SharedTreeBranch<TEditor, TChange>,
+	): { sourceCommits: GraphCommit<TChange>[] } | undefined {
 		this.assertNotDisposed();
 		branch.assertNotDisposed();
 
@@ -316,6 +317,7 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 		this.#events.emit("beforeChange", changeEvent);
 		this.head = rebaseResult.newSourceHead;
 		this.#events.emit("afterChange", changeEvent);
+		return { sourceCommits };
 	}
 
 	/** Rebase `branchHead` onto `onto`, but return undefined if nothing changed */

package/src/shared-tree-core/editManager.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { SessionId } from "@fluidframework/id-compressor";
 import { BTree } from "@tylerbu/sorted-btree-es6";
@@ -16,11 +16,10 @@ import {
 	findAncestor,
 	findCommonAncestor,
 	mintCommit,
-	rebaseChange,
 	type RebaseStatsWithDuration,
 	tagChange,
 } from "../core/index.js";
-import { type Mutable, brand, fail, getOrCreate, mapIterable } from "../util/index.js";
+import { type Mutable, brand, getOrCreate, mapIterable } from "../util/index.js";
 
 import { SharedTreeBranch, type BranchTrimmingEvents, onForkTransitive } from "./branch.js";
 import type {
@@ -39,7 +38,6 @@ import {
 } from "./sequenceIdUtils.js";
 import {
 	TelemetryEventBatcher,
-	measure,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
 
@@ -706,51 +704,45 @@ export class EditManager<
 		}
 
 		// Remote changes, i.e., changes from remote clients are applied in three steps.
-		for (const newCommit of newCommits) {
-			// Step 1 - Recreate the peer remote client's local environment.
-			// Get the revision that the remote change is based on
-			const [, baseRevisionInTrunk] = this.getClosestTrunkCommit(referenceSequenceNumber);
-			// Rebase that peer local branch over the part of the trunk up to the base revision
-			// This will be a no-op if the sending client has not advanced since the last time we received an edit from it
-			const peerLocalBranch = getOrCreate(
-				this.peerLocalBranches,
-				sessionId,
-				() =>
-					new SharedTreeBranch(baseRevisionInTrunk, this.changeFamily, this.mintRevisionTag),
-			);
-			peerLocalBranch.rebaseOnto(this.trunk, baseRevisionInTrunk);
+		// Step 1 - Recreate the peer remote client's local environment.
+		// Get the revision that the remote change is based on and rebase that peer local branch over the part of the
+		// trunk up to the base revision. This will be a no-op if the sending client has not advanced since the last
+		// time we received an edit from it
+		const [, baseRevisionInTrunk] = this.getClosestTrunkCommit(referenceSequenceNumber);
+		const peerLocalBranch = getOrCreate(
+			this.peerLocalBranches,
+			sessionId,
+			() => new SharedTreeBranch(baseRevisionInTrunk, this.changeFamily, this.mintRevisionTag),
+		);
+		peerLocalBranch.rebaseOnto(this.trunk, baseRevisionInTrunk);
 
-			// Step 2 - Append the change to the peer branch. Rebase the change to the tip of the trunk.
-			if (peerLocalBranch.getHead() === this.trunk.getHead()) {
-				// If the branch is fully caught up and empty after being rebased, then push to the trunk directly
+		// Step 2 - Append the changes to the peer branch and rebase the changes to the tip of the trunk.
+		if (peerLocalBranch.getHead() === this.trunk.getHead()) {
+			// If the peer local branch is fully caught up and empty (no changes relative to the trunk) after being
+			// rebased, then push changes to the trunk directly and update the peer branch to the trunk's head.
+			for (const newCommit of newCommits) {
 				this.pushCommitToTrunk(nextSequenceId, { ...newCommit, sessionId });
-				peerLocalBranch.setHead(this.trunk.getHead());
-			} else {
-				// Otherwise, rebase the change over the trunk and append it, and append the original change to the peer branch.
-				const { duration, output: newChangeFullyRebased } = measure(() =>
-					rebaseChange(
-						this.changeFamily.rebaser,
-						newCommit,
-						peerLocalBranch.getHead(),
-						this.trunk.getHead(),
-						this.mintRevisionTag,
-					),
-				);
-
-				this.telemetryEventBatcher?.accumulateAndLog({
-					duration,
-					...newChangeFullyRebased.telemetryProperties,
-				});
-
+				nextSequenceId = getNextSequenceId(nextSequenceId);
+			}
+			peerLocalBranch.setHead(this.trunk.getHead());
+		} else {
+			// Otherwise, push the changes to the peer local branch and merge the branch into the trunk.
+			for (const newCommit of newCommits) {
 				peerLocalBranch.apply(tagChange(newCommit.change, newCommit.revision));
-				this.pushCommitToTrunk(nextSequenceId, {
-					...newCommit,
-					sessionId,
-					change: newChangeFullyRebased.change,
-				});
 			}
-
-			nextSequenceId = getNextSequenceId(nextSequenceId);
+			const result = this.trunk.merge(peerLocalBranch);
+			if (result !== undefined) {
+				// If the merge resulted in any changes to the trunk, update the sequence map and trunk metadata
+				// with the rebased commits.
+				for (const sourceCommit of result.sourceCommits) {
+					this.sequenceMap.set(nextSequenceId, sourceCommit);
+					this.trunkMetadata.set(sourceCommit.revision, {
+						sequenceId: nextSequenceId,
+						sessionId,
+					});
+					nextSequenceId = getNextSequenceId(nextSequenceId);
+				}
+			}
 		}
 
 		// Step 3 - Rebase the local branch over the updated trunk.

package/src/sharedTreeAttributes.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IChannelAttributes } from "@fluidframework/datastore-definitions/internal";
+import { pkgVersion } from "./packageVersion.js";
+
+/**
+ * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
+ * @alpha
+ * @legacy
+ */
+export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
+
+/**
+ * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
+ * @alpha
+ * @legacy
+ */
+export const SharedTreeAttributes: IChannelAttributes = {
+	type: SharedTreeFactoryType,
+	snapshotFormatVersion: "0.0.0",
+	packageVersion: pkgVersion,
+};

package/src/simple-tree/api/customTree.ts

@@ -5,7 +5,7 @@
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	EmptyKey,
@@ -19,7 +19,7 @@ import {
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 } from "../../core/index.js";
-import { fail, cloneWithReplacements } from "../../util/index.js";
+import { cloneWithReplacements } from "../../util/index.js";
 import type { TreeLeafValue } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import {

package/src/simple-tree/api/getJsonSchema.ts

@@ -60,6 +60,16 @@ const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
  * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
  * For now, while still an experimental API, it is surfaced as a free function.
  *
+ * TODO:
+ * This API should allow generating JSON schema for the whole matrix of combinations:
+ *
+ * 1. VerboseTree and ConciseTree
+ * 2. With and without requiring values with defaults (for insertion vs reading)
+ * 3. Using stored keys and property keys
+ *
+ * This current API seems to give ConciseTree with property keys and ignoring default values.
+ *
+ *
  * @alpha
  */
 export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema {

package/src/simple-tree/api/getSimpleSchema.ts

@@ -6,7 +6,7 @@
 import { getOrCreate } from "../../util/index.js";
 import type { TreeNodeSchema } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../schemaTypes.js";
-import type { SimpleTreeSchema } from "./simpleSchema.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**
@@ -15,57 +15,27 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 const simpleSchemaCache = new WeakMap<TreeNodeSchema, SimpleTreeSchema>();
 
 /**
- * Creates a simplified representation of the provided {@link TreeNodeSchema}.
+ * Creates a {@link SimpleTreeSchema} from the provided {@link ImplicitFieldSchema}.
  *
- * @remarks Caches the result on the input schema for future calls.
+ * @remarks
+ * This provides easy access by identifier to any schema transitively referenced by the input schema via {@link SimpleTreeSchema.definitions}.
  *
- * @example
+ * Caches the result on the input schema for future calls.
  *
- * A Shared Tree schema like the following:
- *
- * ```typescript
- * class MyObject extends schemaFactory.object("MyObject", {
- * 	foo: schemaFactory.number,
- * 	bar: schemaFactory.optional(schemaFactory.string),
- * });
- * ```
+ * @privateRemarks
+ * In the future, we may wish to move this to a more discoverable API location.
+ * For now, while still an experimental API, it is surfaced as a free function.
  *
- * Will yield JSON Schema like the following:
+ * If the main use for this is the "definitions" map, we should provide a better way to access it (that doesn't type erase the TreeNodeSchema down to SimpleNodeSchema).
+ * TODO: Having TreeViewConfiguration implement SimpleTreeSchema directly but with more specific types would be a good way to do this.
  *
- * ```typescript
- * {
- * 	definitions: [
- * 		["com.fluidframework.leaf.number", {
- * 			kind: "leaf",
- * 			type: "number",
- * 		}],
- * 		["com.fluidframework.leaf.string", {
- * 			kind: "leaf",
- * 			type: "string",
- * 		}],
- * 		["com.myapp.MyObject", {
- * 			kind: "object",
- * 			fields: {
- * 				foo: {
- * 					kind: "required",
- * 					allowedTypes: ["com.fluidframework.leaf.number"]
- * 				},
- * 				bar: {
- * 					kind: "optional",
- * 					allowedTypes: ["com.fluidframework.leaf.string"]
- * 				},
- * 			},
- * 		}],
- * 	],
- * 	allowedTypes: ["com.myapp.MyObject"],
- * }
- * ```
+ * Note that all TreeNodeSchema get a {@link Context} cached on them as part of one time initialization which contains a map from identifier to all transitively referenced schema.
+ * Perhaps exposing access to that would cover this use-case as well.
  *
- * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
- * For now, while still an experimental API, it is surfaced as a free function.
+ * TODO: does having this caching layer add value? Maybe this wrapper around toSimpleTreeSchema should be removed.
  *
  * @internal
  */
 export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
-	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema));
+	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema, false));
 }

package/src/simple-tree/api/index.ts

@@ -22,7 +22,7 @@ export {
 	SchemaFactory,
 	type ScopedSchemaName,
 	type SchemaFactoryObjectOptions,
-	type schemaStatics,
+	type SchemaStatics,
 } from "./schemaFactory.js";
 export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {
@@ -36,16 +36,6 @@ export {
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
-export type {
-	SimpleTreeSchema,
-	SimpleNodeSchema,
-	SimpleFieldSchema,
-	SimpleLeafNodeSchema,
-	SimpleMapNodeSchema,
-	SimpleArrayNodeSchema,
-	SimpleObjectNodeSchema,
-	SimpleNodeSchemaBase,
-} from "./simpleSchema.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,
@@ -84,8 +74,13 @@ export type {
 	TreeNodeSchemaClassUnsafe,
 	TreeNodeSchemaUnsafe,
 	AllowedTypesUnsafe,
+	ImplicitAllowedTypesUnsafe,
+	ImplicitFieldSchemaUnsafe,
 	TreeNodeSchemaNonClassUnsafe,
 	InsertableTreeNodeFromAllowedTypesUnsafe,
+	FieldSchemaAlphaUnsafe,
+	ArrayNodeCustomizableSchemaUnsafe,
+	MapNodeCustomizableSchemaUnsafe,
 } from "./typesUnsafe.js";
 
 export {
@@ -141,6 +136,7 @@ export {
 } from "./transactionTypes.js";
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
+export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639

package/src/simple-tree/api/schemaCreationUtilities.ts

@@ -4,8 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-
-import { fail } from "../../util/index.js";
+import { fail } from "@fluidframework/core-utils/internal";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
 import type { NodeFromSchema } from "../schemaTypes.js";