@fluidframework/tree 2.82.0 → 2.83.0

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

@@ -425,7 +425,7 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 	 * @remarks
 	 * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.
 	 * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution} for more guidance on how to change schema while maintaining compatibility.
-	 * Use {@link checkSchemaCompatibilitySnapshots} to write tests to validate that this compatibility behaves as desired across schema changes.
+	 * Use {@link snapshotSchemaCompatibility} to write tests to validate that this compatibility behaves as desired across schema changes.
 	 */
 	readonly compatibility: SchemaCompatibilityStatus;
 

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

@@ -120,7 +120,7 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
  * Extensions to {@link (Tree:interface)} which are not yet stable.
  * @remarks
  * Use via the {@link (TreeBeta:variable)} singleton.
- * @system @sealed @beta
+ * @sealed @beta
  */
 export interface TreeBeta {
 	/**

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

@@ -650,7 +650,7 @@ export type TreeNodeFromImplicitAllowedTypes<
  * This type exists only to be linked from documentation to provide a single linkable place to document some details of
  * "Input" types and how they handle schema.
  *
- * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant}) over the schema.
+ * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant} over the schema.
  * (See also {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations | TypeScript Variance Annotations}).
  *
  * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.

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

@@ -59,7 +59,22 @@ import type { Context } from "./context.js";
 import type { TreeNode } from "./treeNode.js";
 
 interface UnhydratedTreeSequenceFieldEditBuilder
-	extends SequenceFieldEditBuilder<FlexibleFieldContent, UnhydratedFlexTreeNode[]> {}
+	extends SequenceFieldEditBuilder<FlexibleFieldContent, UnhydratedFlexTreeNode[]> {
+	/**
+	 * Moves elements from a source position to a destination position.
+	 * Can move within the same field or from another unhydrated sequence field.
+	 * @param sourceIndex - The index of the first element to move.
+	 * @param count - The number of elements to move.
+	 * @param destIndex - The index at which to insert the moved elements.
+	 * @param source - The source field to move from (defaults to this field for within-field moves).
+	 */
+	move(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		source?: UnhydratedSequenceField,
+	): void;
+}
 
 type UnhydratedFlexTreeNodeEvents = Pick<
 	AnchorEvents,
@@ -543,6 +558,33 @@ export class UnhydratedSequenceField
 			});
 			return removed ?? fail(0xb4a /* Expected removed to be set by edit */);
 		},
+		move: (sourceIndex, count, destIndex, source?): void => {
+			const sourceField = source ?? this;
+			if (sourceField === this) {
+				// Within-field move: do both operations in a single edit to emit only one event
+				this.edit((mapTrees) => {
+					const removed = mapTrees.splice(sourceIndex, count);
+					// Adjust destination index if it comes after the source
+					const adjustedDest = destIndex > sourceIndex ? destIndex - count : destIndex;
+					if (removed.length < 1000) {
+						// For "smallish arrays" (`1000` is not empirically derived), the `splice` function is appropriate...
+						mapTrees.splice(adjustedDest, 0, ...removed);
+					} else {
+						// ...but we avoid using `splice` + spread for very large arrays since there is a limit on how many elements can be spread (too many will overflow the stack).
+						return [
+							...mapTrees.slice(0, adjustedDest),
+							...removed,
+							...mapTrees.slice(adjustedDest),
+						];
+					}
+				});
+			} else {
+				// Cross-field move: remove from source, insert into destination
+				// Each field emits one event (correct behavior for different fields)
+				const removed = sourceField.editor.remove(sourceIndex, count);
+				this.editor.insert(destIndex, removed);
+			}
+		},
 	} satisfies UnhydratedTreeSequenceFieldEditBuilder;
 
 	public at(index: number): FlexTreeUnknownUnboxed | undefined {

package/src/simple-tree/index.ts

@@ -197,9 +197,9 @@ export {
 	checkCompatibility,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
-	checkSchemaCompatibilitySnapshots,
+	snapshotSchemaCompatibility,
 	type SnapshotFileSystem,
-	type SchemaCompatibilitySnapshotsOptions,
+	type SnapshotSchemaCompatibilityOptions,
 	createCustomizedFluidFrameworkScopedFactory,
 } from "./api/index.js";
 export type {

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -52,7 +52,6 @@ import {
 	createTreeNodeSchemaPrivateData,
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
-	withBufferedTreeEvents,
 	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
@@ -1121,24 +1120,19 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 				);
 			}
 
-			// We implement move here via subsequent `remove` and `insert`.
-			// This is strictly an implementation detail and should not be observable by the user.
-			// TODO:AB#47457: Implement proper move support for unhydrated trees.
-			// As a temporary mitigation, we will pause tree events until both edits have been completed.
-			// That way, users will only see a single change event for the array instead of 2.
-			withBufferedTreeEvents(() => {
-				if (sourceField !== destinationField || destinationGap < sourceStart) {
-					destinationField.editor.insert(
-						destinationGap,
-						sourceField.editor.remove(sourceStart, movedCount),
-					);
-				} else if (destinationGap > sourceStart + movedCount) {
-					destinationField.editor.insert(
-						destinationGap - movedCount,
-						sourceField.editor.remove(sourceStart, movedCount),
-					);
-				}
-			});
+			assert(
+				destinationField instanceof UnhydratedSequenceField,
+				0xcd5 /* destinationField should be unhydrated since we're in the else branch of isHydrated() check */,
+			);
+
+			// Use native move which handles the operation atomically for within-field moves
+			// to ensure only a single event is emitted per affected field.
+			destinationField.editor.move(
+				sourceStart,
+				movedCount,
+				destinationGap,
+				sourceField === destinationField ? undefined : sourceField,
+			);
 		}
 	}
 

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -4,7 +4,7 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
@@ -58,7 +58,9 @@ export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent |
 	if (data === undefined) {
 		// TODO: this code-path should support defaults
 		if (normalizedFieldSchema.kind !== FieldKind.Optional) {
-			throw new UsageError("Got undefined for non-optional field.");
+			throw new UsageError(
+				`Got undefined for non-optional field expecting one of ${quotedAllowedTypesWithNames(normalizedFieldSchema.allowedTypeSet)}`,
+			);
 		}
 		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 	}
@@ -71,6 +73,47 @@ export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent |
 	return flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
 }
 
+/**
+ * Throw a usage error with a helpful message about `schema` not being in `allowedTypes` for insertable content.
+ */
+function allowedTypesInsertableSchemaError(
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+	schema: TreeNodeSchema,
+): never {
+	debugAssert(
+		() =>
+			!allowedTypes.has(schema) ||
+			"This function should only be called if the schema is not in the allowed types.",
+	);
+	const map = new Map([...allowedTypes].map((s) => [s.identifier, s]));
+	const expected = map.get(schema.identifier);
+	if (expected !== undefined) {
+		throw new UsageError(
+			`A node with schema ${quotedSchemaIdentifierWithName(schema)} was provided where a node with that identifier is allowed, but the actual schema required (${quotedSchemaIdentifierWithName(expected)}) is not the same schema object.
+TreeNodeSchema have significant object identity and thus the exact same object must be used as the schema when defining what nodes are allowed and when constructing the node to use.`,
+		);
+	}
+	throw new UsageError(
+		`Expected insertable for one of ${quotedAllowedTypesWithNames(allowedTypes)}. Got node with schema ${quotedSchemaIdentifierWithName(schema)}.
+Nodes are valid insertable objects, but only if their schema are in the allowed list.`,
+	);
+}
+
+/**
+ * Gets a description of a schema for use in error messages.
+ */
+function quotedSchemaIdentifierWithName(schema: TreeNodeSchema): string {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	return `${JSON.stringify(schema.identifier)} (name: ${JSON.stringify((schema as Function).name)})`;
+}
+
+/**
+ * Gets a description of an allowedTypes for use in error messages.
+ */
+function quotedAllowedTypesWithNames(allowedTypes: Iterable<TreeNodeSchema>): string {
+	return `[${[...allowedTypes].map(quotedSchemaIdentifierWithName).join(", ")}]`;
+}
+
 /**
  * Copy content from `data` into a UnhydratedFlexTreeNode.
  */
@@ -83,10 +126,12 @@ export function unhydratedFlexTreeFromInsertableNode(
 		const inner = kernel.getInnerNodeIfUnhydrated();
 		if (inner === undefined) {
 			// The node is already hydrated, meaning that it already got inserted into the tree previously
-			throw new UsageError("A node may not be inserted into the tree more than once");
+			throw new UsageError(
+				`A node with schema ${quotedSchemaIdentifierWithName(kernel.schema)} was inserted into the tree more than once. This is not supported.`,
+			);
 		} else {
 			if (!allowedTypes.has(kernel.schema)) {
-				throw new UsageError("Invalid schema for this context.");
+				allowedTypesInsertableSchemaError(allowedTypes, kernel.schema);
 			}
 			return inner;
 		}
@@ -112,17 +157,13 @@ function getType(
 	const possibleTypes = getPossibleTypes(allowedTypes, data);
 	if (possibleTypes.length === 0) {
 		throw new UsageError(
-			`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${JSON.stringify(
-				[...allowedTypes].map((schema) => schema.identifier),
-			)}.`,
+			`The provided data is incompatible with all of the types allowed by the schema. The set of allowed types is: ${quotedAllowedTypesWithNames(allowedTypes)}.`,
 		);
 	}
 	if (!hasSingle(possibleTypes)) {
 		throw new UsageError(
 			`The provided data is compatible with more than one type allowed by the schema.
-The set of possible types is ${JSON.stringify([
-				...possibleTypes.map((schema) => schema.identifier),
-			])}.
+The set of possible types is ${quotedAllowedTypesWithNames(possibleTypes)}.
 Explicitly construct an unhydrated node of the desired type to disambiguate.
 For class-based schema, this can be done by replacing an expression like "{foo: 1}" with "new MySchema({foo: 1})".`,
 		);

package/src/text/textDomainFormatted.ts

@@ -7,6 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { EmptyKey } from "../core/index.js";
+import { TreeAlpha } from "../shared-tree/index.js";
 import {
 	enumFromStrings,
 	eraseSchemaDetails,
@@ -83,25 +84,44 @@ class TextNode
 		length: number,
 		format: Partial<FormattedTextAsTree.CharacterFormat>,
 	): void {
-		for (let i = startIndex; i < startIndex + length; i++) {
-			const atom = this.content[i];
-			if (atom === undefined) {
-				throw new UsageError("Index out of bounds while formatting text range.");
-			}
-			for (const [key, value] of Object.entries(format) as [
-				keyof FormattedTextAsTree.CharacterFormat,
-				unknown,
-			][]) {
-				// Object.entries should only return string keyed enumerable own properties.
-				// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
-				assert(typeof key === "string", 0xcc8 /* Object.entries returned a non-string key. */);
-				const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
-				if (f === undefined) {
-					throw new UsageError(`Unknown format key: ${key}`);
+		const branch = TreeAlpha.branch(this);
+
+		const applyFormatting = (): void => {
+			for (let i = startIndex; i < startIndex + length; i++) {
+				const atom = this.content[i];
+				if (atom === undefined) {
+					throw new UsageError("Index out of bounds while formatting text range.");
+				}
+				for (const [key, value] of Object.entries(format) as [
+					keyof FormattedTextAsTree.CharacterFormat,
+					unknown,
+				][]) {
+					// Object.entries should only return string keyed enumerable own properties.
+					// The TypeScript typing does not account for this, and thus this assertion is necessary for this code to compile.
+					assert(
+						typeof key === "string",
+						0xcc8 /* Object.entries returned a non-string key. */,
+					);
+					const f = FormattedTextAsTree.CharacterFormat.fields.get(key);
+					if (f === undefined) {
+						throw new UsageError(`Unknown format key: ${key}`);
+					}
+					// Ensures that if the input is a node, it is cloned before being inserted into the tree.
+					atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
 				}
-				// Ensures that if the input is a node, it is cloned before being inserted into the tree.
-				atom.format[key] = TreeBeta.clone(TreeBeta.create(f, value as never)) as never;
 			}
+		};
+
+		if (branch === undefined) {
+			// If this node does not have a corresponding branch, then it is unhydrated.
+			// I.e., it is not part of a collaborative session yet.
+			// Therefore, we don't need to run the edits as a transaction.
+			applyFormatting();
+		} else {
+			// Wrap all formatting operations in a single transaction for atomicity.
+			branch.runTransaction(() => {
+				applyFormatting();
+			});
 		}
 	}
 }

package/src/util/bTreeUtils.ts

@@ -5,6 +5,8 @@
 
 import { debugAssert } from "@fluidframework/core-utils/internal";
 import { BTree, defaultComparator, type DefaultComparable } from "@tylerbu/sorted-btree-es6";
+// eslint-disable-next-line import-x/no-internal-modules
+import { union } from "@tylerbu/sorted-btree-es6/extended/union";
 
 import { brand, type Brand } from "./brand.js";
 
@@ -78,14 +80,16 @@ export function mergeTupleBTrees<const K extends readonly DefaultComparable[], V
 	tree2: TupleBTree<K, V> | undefined,
 	preferLeft = true,
 ): TupleBTree<K, V> {
-	const result: TupleBTree<K, V> = brand(tree1.clone());
 	if (tree2 === undefined) {
-		return result;
+		return brand(tree1.clone());
 	}
 
-	for (const [key, value] of tree2.entries()) {
-		result.set(key, value, !preferLeft);
-	}
+	// Use efficient union operation from sorted-btree 2.x
+	const result = union<BTree<K, V>, K, V>(
+		tree1 as BTree<K, V>,
+		tree2 as BTree<K, V>,
+		(_key, val1, val2) => (preferLeft ? val1 : val2),
+	);
 
-	return result;
+	return brand(result);
 }

package/src/util/rangeMap.ts

@@ -5,6 +5,8 @@
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
+// eslint-disable-next-line import-x/no-internal-modules
+import { union } from "@tylerbu/sorted-btree-es6/extended/union";
 
 /**
  * RangeMap represents a mapping from keys of type K to values of type V or undefined.
@@ -224,12 +226,13 @@ export class RangeMap<K, V> {
 
 		const merged = new RangeMap<K, V>(a.offsetKey, a.subtractKeys, a.offsetValue);
 
-		// TODO: Is there a good pattern that lets us make `tree` readonly?
-		merged.tree = a.tree.clone();
-		for (const [key, value] of b.tree.entries()) {
-			// TODO: Handle key collisions
-			merged.tree.set(key, value);
-		}
+		merged.tree = union<BTree<K, RangeEntry<V>>, K, RangeEntry<V>>(
+			a.tree,
+			b.tree,
+			(_key, _val1, val2) => {
+				return val2;
+			},
+		);
 
 		return merged;
 	}

package/api-extractor-lint.json

@@ -1,4 +0,0 @@
-{
-	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-lint.esm.primary.json"
-}

package/dist/extensibleSchemaUnion.d.ts

@@ -1,72 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { TreeNodeSchema, TreeNodeFromImplicitAllowedTypes, TreeFieldFromImplicitField, SchemaFactoryBeta } from "./simple-tree/index.js";
-/**
- * Utilities for creating extensible schema unions.
- * @remarks
- * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
- *
- * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
- * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
- * This does mean however that old clients may see types they do not know about, which are simply exposed as `undefined` children.
- *
- * `staged` types are lower overhead, and might gain support for `unknown` types in the future, so prefer them when possible.
- * This is simply an alternative for when future compatibility with unknown types is required.
- * It is built on top of the existing {@link ObjectSchemaOptions.allowUnknownOptionalFields | allowUnknownOptionalFields} feature.
- *
- * @example
- * ```typescript
- * const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
- * class ItemA extends sf.object("A", { x: sf.string }) {}
- * class ItemB extends sf.object("B", { x: sf.number }) {}
- *
- * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
- * 	[ItemA, ItemB], // Future versions may add more members here
- * 	sf,
- * 	"ExtensibleUnion",
- * ) {}
- * // Instances of the union are created using `create`.
- * const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
- * // Reading the content from the union is done via `child`,
- * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
- * const childNode: ItemA | ItemB | undefined = anyItem.child;
- * // To determine which member of the union was present, its schema can be inspected:
- * const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
- * assert.equal(aSchema, ItemA);
- * ```
- * @alpha
- */
-export declare namespace ExtensibleSchemaUnion {
-    /**
-     * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-     * @alpha
-     */
-    interface Members<T> {
-        /**
-         * The child wrapped by this node, which is has one of the type allowed by the union,
-         * or `undefined` if the type is one which was added to the union by a future version of this schema.
-         */
-        readonly child: T | undefined;
-    }
-    /**
-     * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-     * @alpha
-     */
-    interface Statics<T extends readonly TreeNodeSchema[]> {
-        /**
-         * Create a {@link TreeNode} with `this` schema which wraps the provided child to create the union.
-         */
-        create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;
-    }
-    /**
-     * Create an extensible schema union which currently supports the types in `types`,
-     * but tolerates collaboration with future versions that may include additional types.
-     * @remarks
-     * See {@link ExtensibleSchemaUnion} for an example use.
-     * @alpha
-     */
-    function extensibleSchemaUnion<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, false, unknown, never, unknown> & (new (data: import("./simple-tree/index.js").InternalTreeNode) => Members<TreeNodeFromImplicitAllowedTypes<T>> & import("./simple-tree/index.js").TreeNode & import("./simple-tree/index.js").WithType<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>);
-}
-//# sourceMappingURL=extensibleSchemaUnion.d.ts.map

package/dist/extensibleSchemaUnion.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extensibleSchemaUnion.d.ts","sourceRoot":"","sources":["../src/extensibleSchemaUnion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACX,cAAc,EACd,gCAAgC,EAChC,0BAA0B,EAG1B,iBAAiB,EACjB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,yBAAiB,qBAAqB,CAAC;IACtC;;;OAGG;IACH,UAAiB,OAAO,CAAC,CAAC;QACzB;;;WAGG;QACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;KAC9B;IAED;;;OAGG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE;QAC3D;;WAEG;QACH,MAAM,CAAC,KAAK,SAAS,cAAc,EAClC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,gCAAgC,CAAC,CAAC,CAAC,GACxC,0BAA0B,CAAC,KAAK,CAAC,CAAC;KACrC;IAED;;;;;;OAMG;IAEH,SAAgB,qBAAqB,CACpC,KAAK,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EACzC,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,KAAK,SAAS,MAAM,EACzB,KAAK,EAAE,CAAC,EAAE,kBAAkB,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,+mBAqCrE;CACD"}

package/dist/extensibleSchemaUnion.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"extensibleSchemaUnion.js","sourceRoot":"","sources":["../src/extensibleSchemaUnion.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qDAAyD;AASzD,qDAKgC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,IAAiB,qBAAqB,CA6ErC;AA7ED,WAAiB,qBAAqB;IA2BrC;;;;;;OAMG;IACH,4EAA4E;IAC5E,SAAgB,qBAAqB,CAInC,KAAQ,EAAE,kBAA6C,EAAE,IAAW;QACrE,MAAM,MAAM,GAAwC,EAAE,CAAC;QACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,wBAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,MAAM,aAAa,GAAG,IAAA,sDAA2C,EAChE,kBAAkB,EAClB,uBAAuB,CACvB,CAAC;QACF,MAAM,KACL,SAAQ,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE,CAAC;YAGhF,IAAW,KAAK;gBACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,oBAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtD,OAAO,KAA4C,CAAC;gBACrD,CAAC;gBACD,OAAO,SAAS,CAAC;YAClB,CAAC;YAEM,MAAM,CAAC,MAAM,CAEnB,KAA0C;gBAE1C,MAAM,MAAM,GAAG,eAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClC,OAAO,mBAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;oBAC5B,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK;iBAIhC,CAAC,CAAC;YACJ,CAAC;SACD;QACD,OAAO,IAAA,yCAA8B,GAGlC,CAAC,KAAK,CAAC,CAAC;IACZ,CAAC;IAzCe,2CAAqB,wBAyCpC,CAAA;AACF,CAAC,EA7EgB,qBAAqB,qCAArB,qBAAqB,QA6ErC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { TreeAlpha, Tree } from \"./shared-tree/index.js\";\nimport type {\n\tTreeNodeSchema,\n\tTreeNodeFromImplicitAllowedTypes,\n\tTreeFieldFromImplicitField,\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tSchemaFactoryBeta,\n} from \"./simple-tree/index.js\";\nimport {\n\tcreateCustomizedFluidFrameworkScopedFactory,\n\teraseSchemaDetailsSubclassable,\n\tSchemaFactory,\n\tTreeBeta,\n} from \"./simple-tree/index.js\";\nimport type { UnionToIntersection } from \"./util/index.js\";\n\n/**\n * Utilities for creating extensible schema unions.\n * @remarks\n * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.\n *\n * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.\n * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.\n * This does mean however that old clients may see types they do not know about, which are simply exposed as `undefined` children.\n *\n * `staged` types are lower overhead, and might gain support for `unknown` types in the future, so prefer them when possible.\n * This is simply an alternative for when future compatibility with unknown types is required.\n * It is built on top of the existing {@link ObjectSchemaOptions.allowUnknownOptionalFields | allowUnknownOptionalFields} feature.\n *\n * @example\n * ```typescript\n * const sf = new SchemaFactoryBeta(\"extensibleSchemaUnionExample.items\");\n * class ItemA extends sf.object(\"A\", { x: sf.string }) {}\n * class ItemB extends sf.object(\"B\", { x: sf.number }) {}\n *\n * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(\n * \t[ItemA, ItemB], // Future versions may add more members here\n * \tsf,\n * \t\"ExtensibleUnion\",\n * ) {}\n * // Instances of the union are created using `create`.\n * const anyItem = AnyItem.create(new ItemA({ x: \"hello\" }));\n * // Reading the content from the union is done via `child`,\n * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.\n * const childNode: ItemA | ItemB | undefined = anyItem.child;\n * // To determine which member of the union was present, its schema can be inspected:\n * const aSchema = Tree.schema(childNode ?? assert.fail(\"No child\"));\n * assert.equal(aSchema, ItemA);\n * ```\n * @alpha\n */\nexport namespace ExtensibleSchemaUnion {\n\t/**\n\t * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.\n\t * @alpha\n\t */\n\texport interface Members<T> {\n\t\t/**\n\t\t * The child wrapped by this node, which is has one of the type allowed by the union,\n\t\t * or `undefined` if the type is one which was added to the union by a future version of this schema.\n\t\t */\n\t\treadonly child: T | undefined;\n\t}\n\n\t/**\n\t * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.\n\t * @alpha\n\t */\n\texport interface Statics<T extends readonly TreeNodeSchema[]> {\n\t\t/**\n\t\t * Create a {@link TreeNode} with `this` schema which wraps the provided child to create the union.\n\t\t */\n\t\tcreate<TThis extends TreeNodeSchema>(\n\t\t\tthis: TThis,\n\t\t\tchild: TreeNodeFromImplicitAllowedTypes<T>,\n\t\t): TreeFieldFromImplicitField<TThis>;\n\t}\n\n\t/**\n\t * Create an extensible schema union which currently supports the types in `types`,\n\t * but tolerates collaboration with future versions that may include additional types.\n\t * @remarks\n\t * See {@link ExtensibleSchemaUnion} for an example use.\n\t * @alpha\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\texport function extensibleSchemaUnion<\n\t\tconst T extends readonly TreeNodeSchema[],\n\t\tconst TScope extends string,\n\t\tconst TName extends string,\n\t>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName) {\n\t\tconst record: Record<string, ImplicitFieldSchema> = {};\n\t\tfor (const type of types) {\n\t\t\trecord[`_${type.identifier}`] = SchemaFactory.optional(type, { key: type.identifier });\n\t\t}\n\t\tconst schemaFactory = createCustomizedFluidFrameworkScopedFactory(\n\t\t\tinputSchemaFactory,\n\t\t\t\"extensibleSchemaUnion\",\n\t\t);\n\t\tclass Union\n\t\t\textends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })\n\t\t\timplements Members<TreeNodeFromImplicitAllowedTypes<T>>\n\t\t{\n\t\t\tpublic get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {\n\t\t\t\tfor (const [_key, child] of TreeAlpha.children(this)) {\n\t\t\t\t\treturn child as TreeNodeFromImplicitAllowedTypes<T>;\n\t\t\t\t}\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tpublic static create<TThis extends TreeNodeSchema>(\n\t\t\t\tthis: TThis,\n\t\t\t\tchild: TreeNodeFromImplicitAllowedTypes<T>,\n\t\t\t): TreeFieldFromImplicitField<TThis> {\n\t\t\t\tconst schema = Tree.schema(child);\n\t\t\t\treturn TreeBeta.create(this, {\n\t\t\t\t\t[`_${schema.identifier}`]: child,\n\t\t\t\t} as unknown as InsertableTreeFieldFromImplicitField<\n\t\t\t\t\tTThis,\n\t\t\t\t\tUnionToIntersection<TThis>\n\t\t\t\t>);\n\t\t\t}\n\t\t}\n\t\treturn eraseSchemaDetailsSubclassable<\n\t\t\tMembers<TreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\tStatics<T>\n\t\t>()(Union);\n\t}\n}\n"]}

package/lib/extensibleSchemaUnion.d.ts

@@ -1,72 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { TreeNodeSchema, TreeNodeFromImplicitAllowedTypes, TreeFieldFromImplicitField, SchemaFactoryBeta } from "./simple-tree/index.js";
-/**
- * Utilities for creating extensible schema unions.
- * @remarks
- * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
- *
- * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
- * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
- * This does mean however that old clients may see types they do not know about, which are simply exposed as `undefined` children.
- *
- * `staged` types are lower overhead, and might gain support for `unknown` types in the future, so prefer them when possible.
- * This is simply an alternative for when future compatibility with unknown types is required.
- * It is built on top of the existing {@link ObjectSchemaOptions.allowUnknownOptionalFields | allowUnknownOptionalFields} feature.
- *
- * @example
- * ```typescript
- * const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
- * class ItemA extends sf.object("A", { x: sf.string }) {}
- * class ItemB extends sf.object("B", { x: sf.number }) {}
- *
- * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
- * 	[ItemA, ItemB], // Future versions may add more members here
- * 	sf,
- * 	"ExtensibleUnion",
- * ) {}
- * // Instances of the union are created using `create`.
- * const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
- * // Reading the content from the union is done via `child`,
- * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
- * const childNode: ItemA | ItemB | undefined = anyItem.child;
- * // To determine which member of the union was present, its schema can be inspected:
- * const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
- * assert.equal(aSchema, ItemA);
- * ```
- * @alpha
- */
-export declare namespace ExtensibleSchemaUnion {
-    /**
-     * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-     * @alpha
-     */
-    interface Members<T> {
-        /**
-         * The child wrapped by this node, which is has one of the type allowed by the union,
-         * or `undefined` if the type is one which was added to the union by a future version of this schema.
-         */
-        readonly child: T | undefined;
-    }
-    /**
-     * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-     * @alpha
-     */
-    interface Statics<T extends readonly TreeNodeSchema[]> {
-        /**
-         * Create a {@link TreeNode} with `this` schema which wraps the provided child to create the union.
-         */
-        create<TThis extends TreeNodeSchema>(this: TThis, child: TreeNodeFromImplicitAllowedTypes<T>): TreeFieldFromImplicitField<TThis>;
-    }
-    /**
-     * Create an extensible schema union which currently supports the types in `types`,
-     * but tolerates collaboration with future versions that may include additional types.
-     * @remarks
-     * See {@link ExtensibleSchemaUnion} for an example use.
-     * @alpha
-     */
-    function extensibleSchemaUnion<const T extends readonly TreeNodeSchema[], const TScope extends string, const TName extends string>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName): Statics<T> & import("./simple-tree/index.js").TreeNodeSchemaCore<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, false, unknown, never, unknown> & (new (data: import("./simple-tree/index.js").InternalTreeNode) => Members<TreeNodeFromImplicitAllowedTypes<T>> & import("./simple-tree/index.js").TreeNode & import("./simple-tree/index.js").WithType<import("./simple-tree/index.js").ScopedSchemaName<`com.fluidframework.extensibleSchemaUnion<${TScope}>`, TName>, import("./simple-tree/index.js").NodeKind, unknown>);
-}
-//# sourceMappingURL=extensibleSchemaUnion.d.ts.map

package/lib/extensibleSchemaUnion.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extensibleSchemaUnion.d.ts","sourceRoot":"","sources":["../src/extensibleSchemaUnion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACX,cAAc,EACd,gCAAgC,EAChC,0BAA0B,EAG1B,iBAAiB,EACjB,MAAM,wBAAwB,CAAC;AAShC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,yBAAiB,qBAAqB,CAAC;IACtC;;;OAGG;IACH,UAAiB,OAAO,CAAC,CAAC;QACzB;;;WAGG;QACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;KAC9B;IAED;;;OAGG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE;QAC3D;;WAEG;QACH,MAAM,CAAC,KAAK,SAAS,cAAc,EAClC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,gCAAgC,CAAC,CAAC,CAAC,GACxC,0BAA0B,CAAC,KAAK,CAAC,CAAC;KACrC;IAED;;;;;;OAMG;IAEH,SAAgB,qBAAqB,CACpC,KAAK,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EACzC,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,KAAK,SAAS,MAAM,EACzB,KAAK,EAAE,CAAC,EAAE,kBAAkB,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,+mBAqCrE;CACD"}

package/lib/extensibleSchemaUnion.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"extensibleSchemaUnion.js","sourceRoot":"","sources":["../src/extensibleSchemaUnion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AASzD,OAAO,EACN,2CAA2C,EAC3C,8BAA8B,EAC9B,aAAa,EACb,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,KAAW,qBAAqB,CA6ErC;AA7ED,WAAiB,qBAAqB;IA2BrC;;;;;;OAMG;IACH,4EAA4E;IAC5E,SAAgB,qBAAqB,CAInC,KAAQ,EAAE,kBAA6C,EAAE,IAAW;QACrE,MAAM,MAAM,GAAwC,EAAE,CAAC;QACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,MAAM,aAAa,GAAG,2CAA2C,CAChE,kBAAkB,EAClB,uBAAuB,CACvB,CAAC;QACF,MAAM,KACL,SAAQ,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE,CAAC;YAGhF,IAAW,KAAK;gBACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBACtD,OAAO,KAA4C,CAAC;gBACrD,CAAC;gBACD,OAAO,SAAS,CAAC;YAClB,CAAC;YAEM,MAAM,CAAC,MAAM,CAEnB,KAA0C;gBAE1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClC,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;oBAC5B,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,KAAK;iBAIhC,CAAC,CAAC;YACJ,CAAC;SACD;QACD,OAAO,8BAA8B,EAGlC,CAAC,KAAK,CAAC,CAAC;IACZ,CAAC;IAzCe,2CAAqB,wBAyCpC,CAAA;AACF,CAAC,EA7EgB,qBAAqB,KAArB,qBAAqB,QA6ErC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { TreeAlpha, Tree } from \"./shared-tree/index.js\";\nimport type {\n\tTreeNodeSchema,\n\tTreeNodeFromImplicitAllowedTypes,\n\tTreeFieldFromImplicitField,\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tSchemaFactoryBeta,\n} from \"./simple-tree/index.js\";\nimport {\n\tcreateCustomizedFluidFrameworkScopedFactory,\n\teraseSchemaDetailsSubclassable,\n\tSchemaFactory,\n\tTreeBeta,\n} from \"./simple-tree/index.js\";\nimport type { UnionToIntersection } from \"./util/index.js\";\n\n/**\n * Utilities for creating extensible schema unions.\n * @remarks\n * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.\n *\n * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.\n * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.\n * This does mean however that old clients may see types they do not know about, which are simply exposed as `undefined` children.\n *\n * `staged` types are lower overhead, and might gain support for `unknown` types in the future, so prefer them when possible.\n * This is simply an alternative for when future compatibility with unknown types is required.\n * It is built on top of the existing {@link ObjectSchemaOptions.allowUnknownOptionalFields | allowUnknownOptionalFields} feature.\n *\n * @example\n * ```typescript\n * const sf = new SchemaFactoryBeta(\"extensibleSchemaUnionExample.items\");\n * class ItemA extends sf.object(\"A\", { x: sf.string }) {}\n * class ItemB extends sf.object(\"B\", { x: sf.number }) {}\n *\n * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(\n * \t[ItemA, ItemB], // Future versions may add more members here\n * \tsf,\n * \t\"ExtensibleUnion\",\n * ) {}\n * // Instances of the union are created using `create`.\n * const anyItem = AnyItem.create(new ItemA({ x: \"hello\" }));\n * // Reading the content from the union is done via `child`,\n * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.\n * const childNode: ItemA | ItemB | undefined = anyItem.child;\n * // To determine which member of the union was present, its schema can be inspected:\n * const aSchema = Tree.schema(childNode ?? assert.fail(\"No child\"));\n * assert.equal(aSchema, ItemA);\n * ```\n * @alpha\n */\nexport namespace ExtensibleSchemaUnion {\n\t/**\n\t * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.\n\t * @alpha\n\t */\n\texport interface Members<T> {\n\t\t/**\n\t\t * The child wrapped by this node, which is has one of the type allowed by the union,\n\t\t * or `undefined` if the type is one which was added to the union by a future version of this schema.\n\t\t */\n\t\treadonly child: T | undefined;\n\t}\n\n\t/**\n\t * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.\n\t * @alpha\n\t */\n\texport interface Statics<T extends readonly TreeNodeSchema[]> {\n\t\t/**\n\t\t * Create a {@link TreeNode} with `this` schema which wraps the provided child to create the union.\n\t\t */\n\t\tcreate<TThis extends TreeNodeSchema>(\n\t\t\tthis: TThis,\n\t\t\tchild: TreeNodeFromImplicitAllowedTypes<T>,\n\t\t): TreeFieldFromImplicitField<TThis>;\n\t}\n\n\t/**\n\t * Create an extensible schema union which currently supports the types in `types`,\n\t * but tolerates collaboration with future versions that may include additional types.\n\t * @remarks\n\t * See {@link ExtensibleSchemaUnion} for an example use.\n\t * @alpha\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\texport function extensibleSchemaUnion<\n\t\tconst T extends readonly TreeNodeSchema[],\n\t\tconst TScope extends string,\n\t\tconst TName extends string,\n\t>(types: T, inputSchemaFactory: SchemaFactoryBeta<TScope>, name: TName) {\n\t\tconst record: Record<string, ImplicitFieldSchema> = {};\n\t\tfor (const type of types) {\n\t\t\trecord[`_${type.identifier}`] = SchemaFactory.optional(type, { key: type.identifier });\n\t\t}\n\t\tconst schemaFactory = createCustomizedFluidFrameworkScopedFactory(\n\t\t\tinputSchemaFactory,\n\t\t\t\"extensibleSchemaUnion\",\n\t\t);\n\t\tclass Union\n\t\t\textends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })\n\t\t\timplements Members<TreeNodeFromImplicitAllowedTypes<T>>\n\t\t{\n\t\t\tpublic get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {\n\t\t\t\tfor (const [_key, child] of TreeAlpha.children(this)) {\n\t\t\t\t\treturn child as TreeNodeFromImplicitAllowedTypes<T>;\n\t\t\t\t}\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tpublic static create<TThis extends TreeNodeSchema>(\n\t\t\t\tthis: TThis,\n\t\t\t\tchild: TreeNodeFromImplicitAllowedTypes<T>,\n\t\t\t): TreeFieldFromImplicitField<TThis> {\n\t\t\t\tconst schema = Tree.schema(child);\n\t\t\t\treturn TreeBeta.create(this, {\n\t\t\t\t\t[`_${schema.identifier}`]: child,\n\t\t\t\t} as unknown as InsertableTreeFieldFromImplicitField<\n\t\t\t\t\tTThis,\n\t\t\t\t\tUnionToIntersection<TThis>\n\t\t\t\t>);\n\t\t\t}\n\t\t}\n\t\treturn eraseSchemaDetailsSubclassable<\n\t\t\tMembers<TreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\tStatics<T>\n\t\t>()(Union);\n\t}\n}\n"]}