@fluidframework/tree 2.12.0 → 2.20.0

package/src/simple-tree/arrayNode.ts

@@ -18,6 +18,7 @@ import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type NodeSchemaMetadata,
 	type TreeLeafValue,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
@@ -992,7 +993,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		if (!destinationField.context.isHydrated()) {
 			if (!(sourceField instanceof UnhydratedTreeSequenceField)) {
 				throw new UsageError(
-					"Cannot move elements from an unhydrated array to a hydrated array.",
+					"Cannot move elements from a hydrated array to an unhydrated array.",
 				);
 			}
 
@@ -1062,11 +1063,13 @@ export function arraySchema<
 	TName extends string,
 	const T extends ImplicitAllowedTypes,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	customizable: boolean,
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ) {
 	type Output = TreeNodeSchemaBoth<
 		TName,
@@ -1075,7 +1078,8 @@ export function arraySchema<
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	>;
 
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
@@ -1157,6 +1161,8 @@ export function arraySchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
+			metadata;
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeLeafValue } from "../schemaTypes.js";
+import type { NodeSchemaMetadata, TreeLeafValue } from "../schemaTypes.js";
 import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
@@ -27,11 +27,30 @@ export type TreeNodeSchema<
 	TBuild = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
+	TCustomMetadata = unknown,
 > =
 	| (TNode extends TreeNode
-			? TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+			? TreeNodeSchemaClass<
+					Name,
+					Kind,
+					TNode,
+					TBuild,
+					ImplicitlyConstructable,
+					Info,
+					never,
+					TCustomMetadata
+				>
 			: never)
-	| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
+	| TreeNodeSchemaNonClass<
+			Name,
+			Kind,
+			TNode,
+			TBuild,
+			ImplicitlyConstructable,
+			Info,
+			never,
+			TCustomMetadata
+	  >;
 
 /**
  * Schema which is not a class.
@@ -49,7 +68,15 @@ export type TreeNodeSchemaNonClass<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
-> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	TCustomMetadata = unknown,
+> = TreeNodeSchemaCore<
+	Name,
+	Kind,
+	ImplicitlyConstructable,
+	Info,
+	TInsertable,
+	TCustomMetadata
+> &
 	(undefined extends TConstructorExtra
 		? {
 				/**
@@ -119,7 +146,15 @@ export type TreeNodeSchemaClass<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
-> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	TCustomMetadata = unknown,
+> = TreeNodeSchemaCore<
+	Name,
+	Kind,
+	ImplicitlyConstructable,
+	Info,
+	TInsertable,
+	TCustomMetadata
+> &
 	(undefined extends TConstructorExtra
 		? {
 				/**
@@ -157,6 +192,7 @@ export type TreeNodeSchemaBoth<
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 	TConstructorExtra = never,
+	TCustomMetadata = unknown,
 > = TreeNodeSchemaClass<
 	Name,
 	Kind,
@@ -164,7 +200,8 @@ export type TreeNodeSchemaBoth<
 	TInsertable,
 	ImplicitlyConstructable,
 	Info,
-	TConstructorExtra
+	TConstructorExtra,
+	TCustomMetadata
 > &
 	TreeNodeSchemaNonClass<
 		Name,
@@ -173,7 +210,8 @@ export type TreeNodeSchemaBoth<
 		TInsertable,
 		ImplicitlyConstructable,
 		Info,
-		TConstructorExtra
+		TConstructorExtra,
+		TCustomMetadata
 	>;
 
 /**
@@ -188,6 +226,7 @@ export interface TreeNodeSchemaCore<
 	out ImplicitlyConstructable extends boolean,
 	out Info = unknown,
 	out TInsertable = never,
+	out TCustomMetadata = unknown,
 > {
 	/**
 	 * Unique (within a document's schema) identifier used to associate nodes with their schema.
@@ -244,6 +283,11 @@ export interface TreeNodeSchemaCore<
 	 */
 	readonly childTypes: ReadonlySet<TreeNodeSchema>;
 
+	/**
+	 * User-provided {@link NodeSchemaMetadata} for this schema.
+	 */
+	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
+
 	/**
 	 * Constructs an instance of this node type.
 	 * @remarks

package/src/simple-tree/index.ts

@@ -35,6 +35,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	SchemaFactoryAlpha,
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 	type ValidateRecursiveSchema,
@@ -155,6 +156,8 @@ export {
 	type Input,
 	type ReadableField,
 	type ReadSchema,
+	type NodeSchemaOptions,
+	type NodeSchemaMetadata,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,

package/src/simple-tree/mapNode.ts

@@ -17,6 +17,7 @@ import {
 	normalizeAllowedTypes,
 	type ImplicitAllowedTypes,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type NodeSchemaMetadata,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
@@ -235,11 +236,13 @@ export function mapSchema<
 	TName extends string,
 	const T extends ImplicitAllowedTypes,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	useMapPrototype: boolean,
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
 ) {
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));
 
@@ -283,6 +286,8 @@ export function mapSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
+			metadata;
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
@@ -299,7 +304,8 @@ export function mapSchema<
 		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	> = Schema;
 	return schemaErased;
 }

package/src/simple-tree/objectNode.ts

@@ -26,6 +26,7 @@ import {
 	normalizeFieldSchema,
 	type ImplicitAllowedTypes,
 	FieldKind,
+	type NodeSchemaMetadata,
 } from "./schemaTypes.js";
 import {
 	type TreeNodeSchema,
@@ -330,12 +331,15 @@ export function objectSchema<
 	TName extends string,
 	const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
 	const ImplicitlyConstructable extends boolean,
+	const TCustomMetadata = unknown,
 >(
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	allowUnknownOptionalFields: boolean,
-): ObjectNodeSchema<TName, T, ImplicitlyConstructable> & ObjectNodeSchemaInternalData {
+	metadata?: NodeSchemaMetadata<TCustomMetadata>,
+): ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
+	ObjectNodeSchemaInternalData {
 	// Ensure no collisions between final set of property keys, and final set of stored keys (including those
 	// implicitly derived from property keys)
 	assertUniqueKeys(identifier, info);
@@ -460,6 +464,8 @@ export function objectSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> | undefined =
+			metadata;
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {

package/src/simple-tree/objectNodeTypes.ts

@@ -23,13 +23,16 @@ export interface ObjectNodeSchema<
 	T extends
 		RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>,
 	ImplicitlyConstructable extends boolean = boolean,
+	TCustomMetadata = unknown,
 > extends TreeNodeSchemaClass<
 		TName,
 		NodeKind.Object,
 		TreeObjectNode<T, TName>,
 		object & InsertableObjectFromSchemaRecord<T>,
 		ImplicitlyConstructable,
-		T
+		T,
+		never,
+		TCustomMetadata
 	> {
 	/**
 	 * From property keys to the associated schema.

package/src/simple-tree/schemaTypes.ts

@@ -190,7 +190,10 @@ export interface FieldProps<TCustomMetadata = unknown> {
 
 	/**
 	 * Optional metadata to associate with the field.
-	 * @remarks Note: this metadata is not persisted in the document.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
 	 */
 	readonly metadata?: FieldSchemaMetadata<TCustomMetadata>;
 }
@@ -824,3 +827,49 @@ export type NodeBuilderData<T extends TreeNodeSchemaCore<string, NodeKind, boole
  */
 // eslint-disable-next-line @rushstack/no-new-null
 export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
+
+/**
+ * Additional information to provide to Node Schema creation.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
+ * See {@link NodeSchemaMetadata.custom}.
+ *
+ * @sealed
+ * @public
+ */
+export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
+	/**
+	 * Optional metadata to associate with the Node Schema.
+	 *
+	 * @remarks
+	 * Note: this metadata is not persisted nor made part of the collaborative state; it is strictly client-local.
+	 * Different clients in the same collaborative session may see different metadata for the same field.
+	 */
+	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
+}
+
+/**
+ * Metadata associated with a Node Schema.
+ *
+ * @remarks Specified via {@link NodeSchemaOptions.metadata}.
+ *
+ * @sealed
+ * @public
+ */
+export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
+	/**
+	 * User-defined metadata.
+	 */
+	readonly custom?: TCustomMetadata | undefined;
+
+	/**
+	 * The description of the Node Schema.
+	 *
+	 * @remarks
+	 *
+	 * If provided, will be used by the system in scenarios where a description of the kind of node is useful.
+	 * E.g., when converting a Node Schema to {@link https://json-schema.org/ | JSON Schema}, this description will be
+	 * used as the `description` property.
+	 */
+	readonly description?: string | undefined;
+}

package/src/simple-tree/toMapTree.ts

@@ -196,7 +196,7 @@ function nodeDataToMapTree(
 			result = objectToMapTree(data, schema);
 			break;
 		default:
-			fail(`Unrecognized schema kind: ${schema.kind}.`);
+			fail("Unrecognized schema kind");
 	}
 
 	return result;

package/src/util/bTreeUtils.ts

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BTree } from "@tylerbu/sorted-btree-es6";
+import { brand, type Brand } from "./brand.js";
+
+export type TupleBTree<K, V> = Brand<BTree<K, V>, "TupleBTree">;
+
+export function newTupleBTree<K extends readonly unknown[], V>(
+	entries?: [K, V][],
+): TupleBTree<K, V> {
+	return brand(new BTree<K, V>(entries, compareTuples));
+}
+
+// This assumes that the arrays are the same length.
+function compareTuples(arrayA: readonly unknown[], arrayB: readonly unknown[]): number {
+	for (let i = 0; i < arrayA.length; i++) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const a = arrayA[i] as any;
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const b = arrayB[i] as any;
+
+		// Less-than and greater-than always return false if either value is undefined,
+		// so we handle undefined separately, treating it as less than all other values.
+		if (a === undefined && b !== undefined) {
+			return -1;
+		} else if (b === undefined && a !== undefined) {
+			return 1;
+		} else if (a < b) {
+			return -1;
+		} else if (a > b) {
+			return 1;
+		}
+	}
+
+	return 0;
+}
+
+export function mergeTupleBTrees<K extends readonly unknown[], V>(
+	tree1: TupleBTree<K, V> | undefined,
+	tree2: TupleBTree<K, V> | undefined,
+	preferLeft = true,
+): TupleBTree<K, V> {
+	if (tree1 === undefined) {
+		return tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree<K, V>();
+	}
+
+	const result: TupleBTree<K, V> = brand(tree1.clone());
+	if (tree2 === undefined) {
+		return result;
+	}
+
+	for (const [key, value] of tree2.entries()) {
+		result.set(key, value, !preferLeft);
+	}
+
+	return result;
+}

package/src/util/idAllocator.ts

@@ -26,8 +26,6 @@ export interface IdAllocationState {
 	maxId: number;
 }
 
-/**
- */
 export function idAllocatorFromMaxId(maxId: number | undefined = undefined): IdAllocator {
 	return idAllocatorFromState({ maxId: maxId ?? -1 });
 }

package/src/util/index.ts

@@ -94,6 +94,7 @@ export {
 	hasSome,
 	hasSingle,
 	defineLazyCachedProperty,
+	copyPropertyIfDefined as copyProperty,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 
@@ -120,13 +121,9 @@ export {
 } from "./brandedMap.js";
 
 export {
-	getFirstEntryFromRangeMap,
-	getFromRangeMap,
-	type RangeEntry,
-	type RangeMap,
+	RangeMap,
 	type RangeQueryResult,
-	setInRangeMap,
-	deleteFromRangeMap,
+	newIntegerRangeMap,
 } from "./rangeMap.js";
 
 export {
@@ -144,3 +141,5 @@ export {
 	throwIfBroken,
 	breakingClass,
 } from "./breakable.js";
+
+export { type TupleBTree, newTupleBTree, mergeTupleBTrees } from "./bTreeUtils.js";