@fluidframework/tree 2.82.0 → 2.90.0-378676

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -4,9 +4,10 @@
  */
 
 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 type { FlexTreeNode } from "../feature-libraries/index.js";
 import { filterIterable, hasSingle, oneFromIterable } from "../util/index.js";
 
 import {
@@ -24,7 +25,7 @@ import { getUnhydratedContext } from "./createContext.js";
 import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fieldSchema.js";
 
 /**
- * Transforms an input {@link TypedNode} tree to an {@link UnhydratedFlexTreeNode}.
+ * Transforms an input {@link TypedNode} tree to a {@link FlexTreeNode}.
  * @param data - The input tree to be converted.
  * If the data is an unsupported value (e.g. NaN), a fallback value will be used when supported,
  * otherwise an error will be thrown.
@@ -49,46 +50,110 @@ import { normalizeFieldSchema, FieldKind, type ImplicitFieldSchema } from "./fie
  * Output should comply with the provided view schema, but this is not explicitly validated:
  * validation against stored schema (to guard against document corruption) is done elsewhere.
  */
-export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
+export function flexTreeFromInsertable<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	allowedTypes: ImplicitFieldSchema,
-): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
+): TIn extends undefined ? undefined : FlexTreeNode {
 	const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
 
 	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;
+		return undefined as TIn extends undefined ? undefined : FlexTreeNode;
 	}
 
-	const flexTree: UnhydratedFlexTreeNode = unhydratedFlexTreeFromInsertableNode(
+	const flexTree: FlexTreeNode = flexTreeFromInsertableNode(
 		data,
 		normalizedFieldSchema.allowedTypeSet,
 	);
 
-	return flexTree as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
+	return flexTree as TIn extends undefined ? undefined : FlexTreeNode;
+}
+
+/**
+ * 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.
  */
-export function unhydratedFlexTreeFromInsertableNode(
+export function unhydratedFlexTreeFromInsertable<TIn extends InsertableContent | undefined>(
+	data: TIn,
+	allowedTypes: ImplicitFieldSchema,
+): TIn extends undefined ? undefined : UnhydratedFlexTreeNode {
+	const result = flexTreeFromInsertable(data, allowedTypes);
+	if (result === undefined) {
+		return undefined as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
+	}
+	assert(result instanceof UnhydratedFlexTreeNode, "expected unhydrated node");
+	return result as TIn extends undefined ? undefined : UnhydratedFlexTreeNode;
+}
+
+/**
+ * Copy content from `data` into a UnhydratedFlexTreeNode or return an existing node if `data` is a TreeNode.
+ */
+export function flexTreeFromInsertableNode(
 	data: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-): UnhydratedFlexTreeNode {
+): FlexTreeNode {
 	if (isTreeNode(data)) {
 		const kernel = getKernel(data);
-		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");
-		} else {
+		const inner = kernel.getInnerNode();
+		if (inner.parentField.parent.parent === undefined) {
 			if (!allowedTypes.has(kernel.schema)) {
-				throw new UsageError("Invalid schema for this context.");
+				allowedTypesInsertableSchemaError(allowedTypes, kernel.schema);
 			}
+
+			if (inner.isHydrated()) {
+				// TODO: hook up event bubbling from hydrated to unhydrated tree.
+			}
+
 			return inner;
+		} else {
+			throw new UsageError(
+				"A node which already has a parent may not be used as part of a new tree.",
+			);
 		}
 	}
 
@@ -112,17 +177,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/treeFactory.ts

@@ -26,7 +26,9 @@ import {
 	type SharedTreeKernelView,
 } from "./shared-tree/index.js";
 import {
+	editManagerFormatVersionSelectorForDetachedRootEditing,
 	editManagerFormatVersionSelectorForSharedBranches,
+	messageFormatVersionSelectorForDetachedRootEditing,
 	messageFormatVersionSelectorForSharedBranches,
 } from "./shared-tree-core/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
@@ -212,12 +214,17 @@ export function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInt
 }
 
 function resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {
-	const enableSharedBranches = options.enableSharedBranches ?? false;
-
-	if (enableSharedBranches) {
+	if (options.enableSharedBranches === true && options.enableDetachedRootEditing === true) {
+		throw new UsageError(
+			"enableDetachedRootEditing cannot be used with enableSharedBranches.",
+		);
+	}
+	if (options.enableSharedBranches === true) {
 		return sharedBranchesOptions;
 	}
-
+	if (options.enableDetachedRootEditing === true) {
+		return detachRootEditingOptions;
+	}
 	return {};
 }
 
@@ -225,3 +232,8 @@ const sharedBranchesOptions: SharedTreeOptionsInternal = {
 	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
 	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
 };
+const detachRootEditingOptions: SharedTreeOptionsInternal = {
+	messageFormatSelector: messageFormatVersionSelectorForDetachedRootEditing,
+	editManagerFormatSelector: editManagerFormatVersionSelectorForDetachedRootEditing,
+	enableDetachedRootEditing: true,
+};

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/index.ts

@@ -135,7 +135,10 @@ export {
 export {
 	RangeMap,
 	type RangeQueryResult,
+	type RangeQueryResultFragment,
+	type RangeQueryEntry,
 	newIntegerRangeMap,
+	areAdjacentIntegerRanges,
 } from "./rangeMap.js";
 
 export {

package/src/util/rangeMap.ts

@@ -34,8 +34,8 @@ export class RangeMap<K, V> {
 	 * If `offsetValue` is left unspecified, all keys in a block will be given the same value.
 	 */
 	public constructor(
-		private readonly offsetKey: (key: K, offset: number) => K,
-		private readonly subtractKeys: (a: K, b: K) => number,
+		public readonly offsetKey: (key: K, offset: number) => K,
+		public readonly subtractKeys: (a: K, b: K) => number,
 		public readonly offsetValue: (value: V, offset: number) => V = defaultValueOffsetFn,
 	) {
 		this.tree = new BTree(undefined, subtractKeys);
@@ -92,6 +92,34 @@ export class RangeMap<K, V> {
 		return entries;
 	}
 
+	// XXX: Merge with getAll
+	/**
+	 * Like getAll, but includes entries where the value is undefined.
+	 */
+	public getAll2(start: K, length: number): RangeQueryResultFragment<V | undefined>[] {
+		let nextKey = start;
+		let offset = 0;
+		const result: RangeQueryResultFragment<V | undefined>[] = [];
+		for (const entry of this.getAll(start, length)) {
+			const lengthBefore = this.subtractKeys(entry.start, nextKey);
+			if (lengthBefore > 0) {
+				result.push({ offset, length: lengthBefore, value: undefined });
+				offset += lengthBefore;
+			}
+
+			result.push({ offset, length: entry.length, value: entry.value });
+			nextKey = this.offsetKey(entry.start, entry.length);
+			offset += entry.length;
+		}
+
+		const lengthRemaining = length - offset;
+		if (lengthRemaining > 0) {
+			result.push({ offset, length: lengthRemaining, value: undefined });
+		}
+
+		return result;
+	}
+
 	/**
 	 * Retrieves the value for some prefix of the query range.
 	 *
@@ -100,7 +128,7 @@ export class RangeMap<K, V> {
 	 * @returns A RangeQueryResult containing the value associated with `start`,
 	 * and the number of consecutive keys with that same value (at least 1, at most `length`).
 	 */
-	public getFirst(start: K, length: number): RangeQueryResult<K, V> {
+	public getFirst(start: K, length: number): RangeQueryResult<V | undefined> {
 		{
 			// We first check for an entry with a key less than or equal to `start`.
 			const entry = this.tree.getPairOrNextLower(start);
@@ -114,7 +142,6 @@ export class RangeMap<K, V> {
 				if (overlappingLength > 0) {
 					return {
 						value: this.offsetValue(value, lengthBeforeQuery),
-						start,
 						length: overlappingLength,
 					};
 				}
@@ -130,11 +157,11 @@ export class RangeMap<K, V> {
 
 				const lastQueryKey = this.offsetKey(start, length - 1);
 				if (this.le(entryKey, lastQueryKey)) {
-					return { value: undefined, start, length: this.subtractKeys(entryKey, start) };
+					return { value: undefined, length: this.subtractKeys(entryKey, start) };
 				}
 			}
 
-			return { value: undefined, start, length };
+			return { value: undefined, length };
 		}
 	}
 
@@ -211,8 +238,17 @@ export class RangeMap<K, V> {
 		return cloned;
 	}
 
+	public mapEntries(mapKey: (key: K) => K, mapValue: (value: V) => V): RangeMap<K, V> {
+		const result = new RangeMap<K, V>(this.offsetKey, this.subtractKeys, this.offsetValue);
+		for (const entry of this.entries()) {
+			result.set(mapKey(entry.start), entry.length, mapValue(entry.value));
+		}
+		return result;
+	}
+
 	/**
 	 * Returns a new map which contains the entries from both input maps.
+	 * Whenever both maps contain entires for the same keys, the value from map `b` is used in the returned map.
 	 */
 	public static union<K, V>(a: RangeMap<K, V>, b: RangeMap<K, V>): RangeMap<K, V> {
 		assert(
@@ -222,13 +258,9 @@ export class RangeMap<K, V> {
 			0xaae /* Maps should have the same behavior */,
 		);
 
-		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);
+		const merged = a.clone();
+		for (const entry of b.entries()) {
+			merged.set(entry.start, entry.length, entry.value);
 		}
 
 		return merged;
@@ -303,17 +335,11 @@ interface RangeEntry<V> {
 /**
  * Describes the result of a range query, including the value and length of the matching prefix.
  */
-export interface RangeQueryResult<K, V> {
-	/**
-	 * The key for the first element in the range.
-	 */
-	readonly start: K;
-
+export interface RangeQueryResult<V> {
 	/**
 	 * The value of the first key in the query range.
-	 * If no matching range is found, this will be undefined.
 	 */
-	readonly value: V | undefined;
+	readonly value: V;
 
 	/**
 	 * The length of the prefix of the query range which has the same value.
@@ -323,8 +349,19 @@ export interface RangeQueryResult<K, V> {
 	readonly length: number;
 }
 
-export interface RangeQueryEntry<K, V> extends RangeQueryResult<K, V> {
+export interface RangeQueryResultFragment<V> extends RangeQueryResult<V> {
+	/**
+	 * The offset from the query key to the key this result is associated with.
+	 * This is useful in the case where a query returns multiple `RangeQueryResults`
+	 * addressing the key range.
+	 */
+	readonly offset: number;
+}
+
+export interface RangeQueryEntry<K, V> {
+	readonly start: K;
 	readonly value: V;
+	readonly length: number;
 }
 
 export function newIntegerRangeMap<V, K extends number = number>(): RangeMap<K, V> {
@@ -342,3 +379,11 @@ function subtractIntegers<K extends number>(a: K, b: K): number {
 function defaultValueOffsetFn<T>(value: T, offset: number): T {
 	return value;
 }
+
+export function areAdjacentIntegerRanges(
+	firstStart: number,
+	firstLength: number,
+	secondStart: number,
+): boolean {
+	return firstStart + firstLength === secondStart;
+}

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/dist/feature-libraries/sequence-field/relevantRemovedRoots.d.ts

@@ -1,9 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import { type DeltaDetachedNodeId } from "../../core/index.js";
-import type { RelevantRemovedRootsFromChild } from "../modular-schema/index.js";
-import type { Changeset } from "./types.js";
-export declare function relevantRemovedRoots(change: Changeset, relevantRemovedRootsFromChild: RelevantRemovedRootsFromChild): Iterable<DeltaDetachedNodeId>;
-//# sourceMappingURL=relevantRemovedRoots.d.ts.map

package/dist/feature-libraries/sequence-field/relevantRemovedRoots.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"relevantRemovedRoots.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/sequence-field/relevantRemovedRoots.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,qBAAqB,CAAC;AAE/E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAQ,MAAM,YAAY,CAAC;AAGlD,wBAAiB,oBAAoB,CACpC,MAAM,EAAE,SAAS,EACjB,6BAA6B,EAAE,6BAA6B,GAC1D,QAAQ,CAAC,mBAAmB,CAAC,CAgB/B"}

package/dist/feature-libraries/sequence-field/relevantRemovedRoots.js

@@ -1,50 +0,0 @@
-"use strict";
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.relevantRemovedRoots = void 0;
-const internal_1 = require("@fluidframework/core-utils/internal");
-const index_js_1 = require("../../core/index.js");
-const deltaUtils_js_1 = require("../deltaUtils.js");
-const utils_js_1 = require("./utils.js");
-function* relevantRemovedRoots(change, relevantRemovedRootsFromChild) {
-    for (const mark of change) {
-        if (refersToRelevantRemovedRoots(mark)) {
-            (0, internal_1.assert)(mark.cellId !== undefined, 0x81d /* marks referring to removed trees must have an assigned cell ID */);
-            const nodeId = (0, deltaUtils_js_1.nodeIdFromChangeAtom)(mark.cellId);
-            for (let i = 0; i < mark.count; i += 1) {
-                yield (0, index_js_1.offsetDetachId)(nodeId, i);
-            }
-        }
-        if (mark.changes !== undefined) {
-            yield* relevantRemovedRootsFromChild(mark.changes);
-        }
-    }
-}
-exports.relevantRemovedRoots = relevantRemovedRoots;
-function refersToRelevantRemovedRoots(mark) {
-    if (mark.cellId !== undefined) {
-        const effect = (0, utils_js_1.isAttachAndDetachEffect)(mark) ? mark.attach : mark;
-        if ((0, utils_js_1.isInsert)(effect)) {
-            // This tree is being inserted or restored.
-            return true;
-        }
-        else if ((0, utils_js_1.isDetachOfRemovedNodes)(mark)) {
-            // This removed tree is being restored as part of a detach.
-            return true;
-        }
-        if (mark.changes !== undefined) {
-            // This removed tree is being edited.
-            // Note: there is a possibility that the child changes only affect a distant descendant
-            // which may have been removed from this (removed) subtree. In such a case, this tree is not truly
-            // relevant, but including it is the conservative thing to do.
-            // In the future, we may represent changes to removed trees using the ID of the lowest removed
-            // ancestor, which would allow us to avoid including such trees when they truly are not needed.
-            return true;
-        }
-    }
-    return false;
-}
-//# sourceMappingURL=relevantRemovedRoots.js.map

package/dist/feature-libraries/sequence-field/relevantRemovedRoots.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"relevantRemovedRoots.js","sourceRoot":"","sources":["../../../src/feature-libraries/sequence-field/relevantRemovedRoots.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,kDAA+E;AAC/E,oDAAwD;AAIxD,yCAAuF;AAEvF,QAAe,CAAC,CAAC,oBAAoB,CACpC,MAAiB,EACjB,6BAA4D;IAE5D,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,IAAA,iBAAM,EACL,IAAI,CAAC,MAAM,KAAK,SAAS,EACzB,KAAK,CAAC,oEAAoE,CAC1E,CAAC;YACF,MAAM,MAAM,GAAG,IAAA,oCAAoB,EAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAA,yBAAc,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACjC,CAAC;QACF,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,KAAK,CAAC,CAAC,6BAA6B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;AACF,CAAC;AAnBD,oDAmBC;AAED,SAAS,4BAA4B,CAAC,IAAU;IAC/C,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAA,kCAAuB,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAClE,IAAI,IAAA,mBAAQ,EAAC,MAAM,CAAC,EAAE,CAAC;YACtB,2CAA2C;YAC3C,OAAO,IAAI,CAAC;QACb,CAAC;aAAM,IAAI,IAAA,iCAAsB,EAAC,IAAI,CAAC,EAAE,CAAC;YACzC,2DAA2D;YAC3D,OAAO,IAAI,CAAC;QACb,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,qCAAqC;YACrC,uFAAuF;YACvF,kGAAkG;YAClG,8DAA8D;YAC9D,8FAA8F;YAC9F,+FAA+F;YAC/F,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { type DeltaDetachedNodeId, offsetDetachId } from \"../../core/index.js\";\nimport { nodeIdFromChangeAtom } from \"../deltaUtils.js\";\nimport type { RelevantRemovedRootsFromChild } from \"../modular-schema/index.js\";\n\nimport type { Changeset, Mark } from \"./types.js\";\nimport { isAttachAndDetachEffect, isDetachOfRemovedNodes, isInsert } from \"./utils.js\";\n\nexport function* relevantRemovedRoots(\n\tchange: Changeset,\n\trelevantRemovedRootsFromChild: RelevantRemovedRootsFromChild,\n): Iterable<DeltaDetachedNodeId> {\n\tfor (const mark of change) {\n\t\tif (refersToRelevantRemovedRoots(mark)) {\n\t\t\tassert(\n\t\t\t\tmark.cellId !== undefined,\n\t\t\t\t0x81d /* marks referring to removed trees must have an assigned cell ID */,\n\t\t\t);\n\t\t\tconst nodeId = nodeIdFromChangeAtom(mark.cellId);\n\t\t\tfor (let i = 0; i < mark.count; i += 1) {\n\t\t\t\tyield offsetDetachId(nodeId, i);\n\t\t\t}\n\t\t}\n\t\tif (mark.changes !== undefined) {\n\t\t\tyield* relevantRemovedRootsFromChild(mark.changes);\n\t\t}\n\t}\n}\n\nfunction refersToRelevantRemovedRoots(mark: Mark): boolean {\n\tif (mark.cellId !== undefined) {\n\t\tconst effect = isAttachAndDetachEffect(mark) ? mark.attach : mark;\n\t\tif (isInsert(effect)) {\n\t\t\t// This tree is being inserted or restored.\n\t\t\treturn true;\n\t\t} else if (isDetachOfRemovedNodes(mark)) {\n\t\t\t// This removed tree is being restored as part of a detach.\n\t\t\treturn true;\n\t\t}\n\t\tif (mark.changes !== undefined) {\n\t\t\t// This removed tree is being edited.\n\t\t\t// Note: there is a possibility that the child changes only affect a distant descendant\n\t\t\t// which may have been removed from this (removed) subtree. In such a case, this tree is not truly\n\t\t\t// relevant, but including it is the conservative thing to do.\n\t\t\t// In the future, we may represent changes to removed trees using the ID of the lowest removed\n\t\t\t// ancestor, which would allow us to avoid including such trees when they truly are not needed.\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n"]}