@fluidframework/tree 2.74.0-370705 → 2.80.0

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

@@ -85,14 +85,18 @@ function generateFieldSchema(
 
 	// Using createFieldSchema could work, but would require setting up the default providers.
 	switch (simple.kind) {
-		case FieldKind.Identifier:
+		case FieldKind.Identifier: {
 			return SchemaFactoryAlpha.identifier(props);
-		case FieldKind.Optional:
+		}
+		case FieldKind.Optional: {
 			return SchemaFactoryAlpha.optional(allowed, props);
-		case FieldKind.Required:
+		}
+		case FieldKind.Required: {
 			return SchemaFactoryAlpha.required(allowed, props);
-		default:
+		}
+		default: {
 			return unreachableCase(simple.kind);
+		}
 	}
 }
 
@@ -127,26 +131,31 @@ function generateNode(
 				allowUnknownOptionalFields: schema.allowUnknownOptionalFields ?? false,
 			});
 		}
-		case NodeKind.Array:
+		case NodeKind.Array: {
 			return factory.arrayAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
 				metadata: schema.metadata,
 			});
-		case NodeKind.Map:
+		}
+		case NodeKind.Map: {
 			return factory.mapAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
 				metadata: schema.metadata,
 			});
-		case NodeKind.Record:
+		}
+		case NodeKind.Record: {
 			return factory.recordAlpha(
 				id,
 				generateAllowedTypes(schema.simpleAllowedTypes, context),
 				{ metadata: schema.metadata },
 			);
-		case NodeKind.Leaf:
+		}
+		case NodeKind.Leaf: {
 			return (
 				SchemaFactoryAlpha.leaves.find((leaf) => leaf.identifier === id) ??
 				fail(0xb5b /* Missing schema */)
 			);
-		default:
+		}
+		default: {
 			return unreachableCase(schema);
+		}
 	}
 }

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

@@ -111,16 +111,21 @@ export function decodeSchemaCompatibilitySnapshot(
 function encodeNodeSchema(schema: SimpleNodeSchema): Format.SimpleNodeSchemaUnionFormat {
 	const kind = schema.kind;
 	switch (kind) {
-		case NodeKind.Leaf:
+		case NodeKind.Leaf: {
 			return { leaf: encodeLeafNode(schema) };
-		case NodeKind.Array:
+		}
+		case NodeKind.Array: {
 			return { array: encodeContainerNode(schema) };
-		case NodeKind.Map:
+		}
+		case NodeKind.Map: {
 			return { map: encodeContainerNode(schema) };
-		case NodeKind.Record:
+		}
+		case NodeKind.Record: {
 			return { record: encodeContainerNode(schema) };
-		case NodeKind.Object:
+		}
+		case NodeKind.Object: {
 			return { object: encodeObjectNode(schema) };
+		}
 		default: {
 			unreachableCase(kind);
 		}

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

@@ -132,22 +132,28 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {
 	let type: JsonLeafSchemaType;
 	switch (schema.leafKind) {
-		case ValueSchema.String:
+		case ValueSchema.String: {
 			type = "string";
 			break;
-		case ValueSchema.Number:
+		}
+		case ValueSchema.Number: {
 			type = "number";
 			break;
-		case ValueSchema.Boolean:
+		}
+		case ValueSchema.Boolean: {
 			type = "boolean";
 			break;
-		case ValueSchema.Null:
+		}
+		case ValueSchema.Null: {
 			type = "null";
 			break;
-		case ValueSchema.FluidHandle:
+		}
+		case ValueSchema.FluidHandle: {
 			throw new UsageError("Fluid handles are not supported via JSON Schema.");
-		default:
+		}
+		default: {
 			unreachableCase(schema.leafKind);
+		}
 	}
 
 	return {
@@ -181,13 +187,11 @@ export function convertObjectNodeSchema(
 		copyProperty(fieldSchema.metadata, "description", output);
 		properties[key] = output;
 
-		if (fieldSchema.kind !== FieldKind.Optional) {
-			if (
-				options.requireFieldsWithDefaults ||
-				fieldSchema.props?.defaultProvider === undefined
-			) {
-				required.push(key);
-			}
+		if (
+			fieldSchema.kind !== FieldKind.Optional &&
+			(options.requireFieldsWithDefaults || fieldSchema.props?.defaultProvider === undefined)
+		) {
+			required.push(key);
 		}
 	}
 

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

@@ -148,14 +148,14 @@ export function createSimpleTreeIndex<
 	indexableSchema?: readonly TreeNodeSchema[],
 ): SimpleTreeIndex<TKey, TValue> {
 	const indexableSchemaMap = new Map();
-	if (indexableSchema !== undefined) {
-		for (const schemus of indexableSchema) {
-			indexableSchemaMap.set(schemus.identifier, schemus);
-		}
-	} else {
+	if (indexableSchema === undefined) {
 		walkFieldSchema(view.schema, {
 			node: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),
 		});
+	} else {
+		for (const schemus of indexableSchema) {
+			indexableSchemaMap.set(schemus.identifier, schemus);
+		}
 	}
 
 	const schemaIndexer =
@@ -163,14 +163,14 @@ export function createSimpleTreeIndex<
 			? (schemaIdentifier: TreeNodeSchemaIdentifier) => {
 					// if indexable schema isn't provided, we check if the node is in schema
 					const schemus = indexableSchemaMap.get(schemaIdentifier);
-					if (schemus !== undefined) {
+					if (schemus === undefined) {
+						fail(0xb32 /* node is out of schema */);
+					} else {
 						const keyLocation =
 							typeof indexer === "function" ? indexer(schemus) : indexer.get(schemus);
 						if (keyLocation !== undefined) {
 							return makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);
 						}
-					} else {
-						fail(0xb32 /* node is out of schema */);
 					}
 				}
 			: (schemaIdentifier: TreeNodeSchemaIdentifier) => {

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

@@ -4,15 +4,18 @@
  */
 
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
-import { FluidClientVersion, type ICodecOptions } from "../../codec/index.js";
-import { SchemaFormatVersion } from "../../core/index.js";
-import { encodeTreeSchema, makeSchemaCodec } from "../../feature-libraries/index.js";
 import {
-	clientVersionToSchemaVersion,
-	type FormatV1,
+	FluidClientVersion,
+	FormatValidatorNoOp,
+	type ICodecOptions,
+} from "../../codec/index.js";
+import { SchemaFormatVersion } from "../../core/index.js";
+import { makeSchemaCodec } from "../../feature-libraries/index.js";
+import type {
+	FormatV1,
 	// eslint-disable-next-line import-x/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
-import { brand, type JsonCompatible } from "../../util/index.js";
+import type { JsonCompatible } from "../../util/index.js";
 import type { SchemaUpgrade } from "../core/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import { toStoredSchema } from "../toStoredSchema.js";
@@ -59,8 +62,8 @@ export function extractPersistedSchema(
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
 	const stored = toStoredSchema(schema, { includeStaged });
-	const schemaWriteVersion = clientVersionToSchemaVersion(minVersionForCollab);
-	return encodeTreeSchema(stored, schemaWriteVersion);
+	const codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });
+	return codec.encode(stored) as JsonCompatible;
 }
 
 /**
@@ -102,7 +105,7 @@ export function comparePersistedSchema(
 	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
 	const schemaCodec = makeSchemaCodec(
 		{ ...options, minVersionForCollab: FluidClientVersion.v2_0 },
-		brand(SchemaFormatVersion.v1),
+		SchemaFormatVersion.v1,
 	);
 	const stored = schemaCodec.decode(persisted as FormatV1);
 	const config = new TreeViewConfigurationAlpha({

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

@@ -23,6 +23,12 @@ export const rollback = Symbol("SharedTree Transaction Rollback");
  */
 export type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here
 
+/**
+ * Type for alpha version {@link TransactionConstraint | constraint}s
+ * @sealed @alpha
+ */
+export type TransactionConstraintAlpha = TransactionConstraint | NoChangeConstraint; // TODO: Add more constraint types here
+
 /**
  * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.
  * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as "existing".
@@ -33,6 +39,15 @@ export interface NodeInDocumentConstraint {
 	readonly node: TreeNode;
 }
 
+/**
+ * A {@link TransactionConstraintAlpha | constraint} which requires that, for this transaction to apply, the document must be in the same state immediately before the transaction is applied as it was before the transaction was authored.
+ * When used as a revert precondition it requires that, for the revert to apply, the document must be in the same state immediately before the revert is applied as it was after the transaction was applied.
+ * @alpha
+ */
+export interface NoChangeConstraint {
+	readonly type: "noChange";
+}
+
 /**
  * The status of the transaction callback in the {@link RunTransaction | RunTransaction} API.
  * @alpha
@@ -52,13 +67,13 @@ export type TransactionCallbackStatus<TSuccessValue, TFailureValue> = (
 	  }
 ) & {
 	/**
-	 * An optional list of {@link TransactionConstraint | constraints} that will be checked when the commit corresponding
+	 * An optional list of {@link TransactionConstraintAlpha | constraints} that will be checked when the commit corresponding
 	 * to this transaction is reverted. If any of these constraints are not met when the revert is being applied either
 	 * locally or on remote clients, the revert will be ignored.
 	 * These constraints must also be met at the time they are first introduced. If they are not met after the transaction
 	 * callback returns, then `runTransaction` (which invokes the transaction callback) will throw a `UsageError`.
 	 */
-	preconditionsOnRevert?: readonly TransactionConstraint[];
+	preconditionsOnRevert?: readonly TransactionConstraintAlpha[];
 };
 
 /**
@@ -117,10 +132,10 @@ export type TransactionResult =
  */
 export interface RunTransactionParams {
 	/**
-	 * An optional list of {@link TransactionConstraint | constraints} that are checked just before the transaction begins.
+	 * An optional list of {@link TransactionConstraintAlpha | constraints} that are checked just before the transaction begins.
 	 * If any of the constraints are not met when `runTransaction` is called, an error will be thrown.
 	 * If any of the constraints are not met after the transaction has been ordered by the service, it will be rolled back on
 	 * this client and ignored by all other clients.
 	 */
-	readonly preconditions?: readonly TransactionConstraint[];
+	readonly preconditions?: readonly TransactionConstraintAlpha[];
 }

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

@@ -7,6 +7,7 @@ import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/co
 
 import type {
 	CommitMetadata,
+	ChangeMetadata,
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
@@ -35,6 +36,7 @@ import type {
 	VoidTransactionCallbackStatus,
 } from "./transactionTypes.js";
 import type { VerboseTree } from "./verboseTree.js";
+import type { JsonCompatibleReadOnly } from "../../util/index.js";
 
 /**
  * A tree from which a {@link TreeView} can be created.
@@ -282,6 +284,19 @@ export interface TreeBranchAlpha extends TreeBranch {
 		transaction: () => VoidTransactionCallbackStatus | void,
 		params?: RunTransactionParams,
 	): TransactionResult;
+
+	/**
+	 * Apply a serialized change to this branch.
+	 * @param change - the change to apply.
+	 * Changes are acquired via `getChange` in a branch's {@link TreeBranchEvents.changed | "changed"} event.
+	 * @remarks Changes may only be applied to a SharedTree with the same IdCompressor instance and branch state from which they were generated.
+	 * They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application.
+	 *
+	 * @privateRemarks
+	 * TODO: This method will support applying changes from different IdCompressor instances as long as they have the same local session ID.
+	 * Update the tests and docs to match when that is done.
+	 */
+	applyChange(change: JsonCompatibleReadOnly): void;
 }
 
 /**
@@ -508,7 +523,7 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,
 	 * this change is not revertible.
 	 */
-	changed(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
+	changed(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
 
 	/**
 	 * Fired when:

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

@@ -203,8 +203,9 @@ export const treeNodeApi: TreeNodeApi = {
 			case "treeChanged": {
 				return kernel.events.on("subtreeChangedAfterBatch", () => listener({}));
 			}
-			default:
+			default: {
 				throw new UsageError(`No event named ${JSON.stringify(eventName)}.`);
+			}
 		}
 	},
 	status(node: TreeNode): TreeStatus {
@@ -238,12 +239,15 @@ export const treeNodeApi: TreeNodeApi = {
  */
 export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
 	switch (typeof value) {
-		case "string":
+		case "string": {
 			return stringSchema;
-		case "number":
+		}
+		case "number": {
 			return numberSchema;
-		case "boolean":
+		}
+		case "boolean": {
 			return booleanSchema;
+		}
 		case "object": {
 			if (isTreeNode(value)) {
 				// TODO: This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
@@ -256,8 +260,9 @@ export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
 				return handleSchema;
 			}
 		}
-		default:
+		default: {
 			return undefined;
+		}
 	}
 }
 
@@ -310,8 +315,9 @@ export function getIdentifierFromNode(
 	const identifierFieldKeys = schema.identifierFieldKeys;
 
 	switch (identifierFieldKeys.length) {
-		case 0:
+		case 0: {
 			return undefined;
+		}
 		case 1: {
 			const key = identifierFieldKeys[0] ?? oob();
 			const identifierField = flexNode.tryGetField(key);
@@ -325,9 +331,9 @@ export function getIdentifierFromNode(
 					if (context.isHydrated()) {
 						const localNodeKey =
 							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-						return localNodeKey !== undefined
-							? extractFromOpaque(localNodeKey)
-							: identifierValue;
+						return localNodeKey === undefined
+							? identifierValue
+							: extractFromOpaque(localNodeKey);
 					} else {
 						return identifierValue;
 					}
@@ -336,7 +342,7 @@ export function getIdentifierFromNode(
 					if (context.isHydrated()) {
 						const localNodeKey =
 							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-						return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+						return localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);
 					} else {
 						return undefined;
 					}
@@ -344,14 +350,16 @@ export function getIdentifierFromNode(
 				case "uncompressed": {
 					return identifierValue;
 				}
-				default:
+				default: {
 					unreachableCase(compression);
+				}
 			}
 		}
-		default:
+		default: {
 			throw new UsageError(
-				"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
+				"The node has more than one identifier. Retrieve identifiers individually via their fields instead.",
 			);
+		}
 	}
 }
 

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

@@ -127,9 +127,8 @@ export function applySchemaToParserOptions(
 
 	return {
 		keyConverter:
-			config.keys !== KeyEncodingOptions.usePropertyKeys
-				? undefined
-				: {
+			config.keys === KeyEncodingOptions.usePropertyKeys
+				? {
 						encode: (type, key: FieldKey): string => {
 							// translate stored key into property key.
 							const simpleNodeSchema =
@@ -167,7 +166,8 @@ export function applySchemaToParserOptions(
 							}
 							return brand(inputKey);
 						},
-					},
+					}
+				: undefined,
 	};
 }
 
@@ -206,13 +206,16 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 		},
 		type: (node: VerboseTree) => {
 			switch (typeof node) {
-				case "number":
+				case "number": {
 					return brand(numberSchema.identifier);
-				case "string":
+				}
+				case "string": {
 					return brand(stringSchema.identifier);
-				case "boolean":
+				}
+				case "boolean": {
 					return brand(booleanSchema.identifier);
-				default:
+				}
+				default: {
 					if (node === null) {
 						return brand(nullSchema.identifier);
 					}
@@ -220,6 +223,7 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 						return brand(handleSchema.identifier);
 					}
 					return brand(node.type);
+				}
 			}
 		},
 		keysFromNode: (node: VerboseTree): readonly FieldKey[] => {
@@ -242,8 +246,9 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 					}
 					return inputKeys.map((k) => converter.parse(node.type, k));
 				}
-				default:
+				default: {
 					return [];
+				}
 			}
 		},
 		getFieldFromNode: (node: VerboseTree, key: FieldKey): readonly VerboseTree[] => {

package/src/simple-tree/core/treeNode.ts

@@ -72,6 +72,7 @@ export abstract class TreeNode implements WithType {
 	 * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
 	 * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
 	 */
+	// eslint-disable-next-line no-unused-private-class-members
 	readonly #brand!: unknown;
 
 	/**

package/src/simple-tree/core/treeNodeKernel.ts

@@ -448,13 +448,16 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	): void {
 		this.#assertNotDisposed();
 		switch (eventName) {
-			case "childrenChangedAfterBatch":
+			case "childrenChangedAfterBatch": {
 				assert(arg !== undefined, 0xc50 /* childrenChangedAfterBatch should have arg */);
 				return this.#handleChildrenChangedAfterBatch(arg.changedFields);
-			case "subtreeChangedAfterBatch":
+			}
+			case "subtreeChangedAfterBatch": {
 				return this.#handleSubtreeChangedAfterBatch();
-			default:
+			}
+			default: {
 				unreachableCase(eventName);
+			}
 		}
 	}