@fluidframework/tree 2.50.0 → 2.51.0-347100

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

@@ -13,11 +13,13 @@ import type { TreeValue } from "../../core/index.js";
 // eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
 import type { TreeAlpha } from "../../shared-tree/index.js";
 import {
+	type JsonCompatibleReadOnlyObject,
 	type RestrictiveStringRecord,
 	compareSets,
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
+import { normalizeAllowedTypes, markSchemaMostDerived, isLazy } from "../core/index.js";
 import type {
 	NodeKind,
 	WithType,
@@ -26,8 +28,12 @@ import type {
 	TreeNodeSchemaNonClass,
 	TreeNodeSchemaBoth,
 	UnhydratedFlexTreeNode,
+	NodeSchemaMetadata,
+	ImplicitAnnotatedAllowedTypes,
+	UnannotateImplicitAllowedTypes,
+	ImplicitAllowedTypes,
+	InsertableTreeNodeFromImplicitAllowedTypes,
 } from "../core/index.js";
-import { isLazy } from "../flexList.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -45,26 +51,19 @@ import {
 	type InsertableObjectFromSchemaRecord,
 	type TreeMapNode,
 	type TreeObjectNode,
+	type UnannotateSchemaRecord,
 } from "../node-kinds/index.js";
 import {
 	FieldKind,
 	type FieldSchema,
-	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
 	type FieldProps,
 	createFieldSchema,
 	type DefaultProvider,
 	getDefaultProvider,
-	markSchemaMostDerived,
 	type FieldSchemaAlpha,
-	type ImplicitAnnotatedAllowedTypes,
-	type UnannotateImplicitAllowedTypes,
-	type UnannotateSchemaRecord,
-	type NodeSchemaOptionsAlpha,
-	normalizeAllowedTypes,
 	type FieldPropsAlpha,
-} from "../schemaTypes.js";
+} from "../fieldSchema.js";
 
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
@@ -1312,3 +1311,39 @@ export function structuralName<const T extends string>(
  * Using this is only better than creating fully random V4 UUIDs because it reduces the entropy making it possible for things like text compression to work slightly better.
  */
 const globalIdentifierAllocator: IIdCompressor = createIdCompressor();
+
+/**
+ * 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;
+}
+
+/**
+ * Additional information to provide to Node Schema creation. Includes fields for alpha features.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
+ * See {@link NodeSchemaMetadata.custom}.
+ *
+ * @alpha
+ */
+export interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown>
+	extends NodeSchemaOptions<TCustomMetadata> {
+	/**
+	 * The persisted metadata for this schema element.
+	 */
+	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+}

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

@@ -20,16 +20,11 @@ import {
 	SchemaFactory,
 	schemaStatics,
 	structuralName,
+	type NodeSchemaOptionsAlpha,
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
-import type {
-	ImplicitAllowedTypes,
-	ImplicitAnnotatedAllowedTypes,
-	ImplicitAnnotatedFieldSchema,
-	ImplicitFieldSchema,
-	NodeSchemaOptionsAlpha,
-} from "../schemaTypes.js";
+import type { ImplicitAnnotatedFieldSchema, ImplicitFieldSchema } from "../fieldSchema.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type {
 	NodeKind,
@@ -38,6 +33,8 @@ import type {
 	TreeNodeSchemaClass,
 	TreeNodeSchemaNonClass,
 	WithType,
+	ImplicitAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
 } from "../core/index.js";
 import type {
 	ArrayNodeCustomizableSchemaUnsafe,

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

@@ -4,16 +4,21 @@
  */
 
 import type { RestrictiveStringRecord } from "../../util/index.js";
-import type { NodeKind, TreeNodeSchema, WithType, TreeNode } from "../core/index.js";
+import type {
+	NodeKind,
+	TreeNodeSchema,
+	WithType,
+	TreeNode,
+	ImplicitAllowedTypes,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+} from "../core/index.js";
 import type { InsertableObjectFromSchemaRecord } from "../node-kinds/index.js";
 import {
 	type FieldKind,
 	type FieldProps,
 	createFieldSchema,
-	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
-} from "../schemaTypes.js";
+} from "../fieldSchema.js";
 
 import type { FieldSchemaAlphaUnsafe, System_Unsafe } from "./typesUnsafe.js";
 

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

@@ -5,14 +5,13 @@
 
 import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import { NodeKind, type TreeNodeSchema, type AllowedTypes } from "../core/index.js";
 import {
 	type FieldSchema,
-	type AllowedTypes,
 	type FieldSchemaAlpha,
 	FieldKind,
 	type FieldProps,
-} from "../schemaTypes.js";
+} from "../fieldSchema.js";
 import type {
 	SimpleFieldSchema,
 	SimpleNodeSchema,

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

@@ -20,7 +20,7 @@ import type {
 	JsonLeafSchemaType,
 	JsonRecordNodeSchema,
 } from "./jsonSchema.js";
-import { FieldKind } from "../schemaTypes.js";
+import { FieldKind } from "../fieldSchema.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,

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

@@ -20,8 +20,13 @@ import {
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
 import { brand } from "../../util/index.js";
-import type { ImplicitFieldSchema, NodeFromSchema } from "../schemaTypes.js";
-import { treeNodeFromAnchor, type TreeNode, type TreeNodeSchema } from "../core/index.js";
+import type { ImplicitFieldSchema } from "../fieldSchema.js";
+import {
+	treeNodeFromAnchor,
+	type TreeNode,
+	type TreeNodeSchema,
+	type NodeFromSchema,
+} from "../core/index.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 import type { TreeView } from "./tree.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -180,7 +185,7 @@ export function createSimpleTreeIndex<
 				};
 
 	const index = new AnchorTreeIndex<TKey, TValue>(
-		(view as SchematizingSimpleTreeView<TFieldSchema>).getView().checkout.forest,
+		(view as SchematizingSimpleTreeView<TFieldSchema>).checkout.forest,
 		schemaIndexer,
 		(anchorNodes) => {
 			const simpleTreeNodes: TreeNode[] = [];

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

@@ -16,7 +16,7 @@ import {
 	// eslint-disable-next-line import/no-internal-modules
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
-import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
 import { simpleToStoredSchema } from "../toStoredSchema.js";
 

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

@@ -22,8 +22,8 @@ import type {
 	ReadableField,
 	ReadSchema,
 	TreeFieldFromImplicitField,
-	UnsafeUnknownSchema,
-} from "../schemaTypes.js";
+} from "../fieldSchema.js";
+import type { UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
 
 import type { TreeViewConfiguration } from "./configuration.js";

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

@@ -11,7 +11,7 @@ import {
 	type Unhydrated,
 	type WithType,
 } from "../core/index.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
 
 import { createFromCursor } from "./create.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
@@ -127,6 +127,9 @@ export interface TreeBeta {
 	 * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.
 	 *
 	 * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.
+	 *
+	 * @privateRemarks
+	 * TODO: AB#43548: How this handles unknown optional fields needs to be figured out, tested and documented.
 	 */
 	clone<const TSchema extends ImplicitFieldSchema>(
 		node: TreeFieldFromImplicitField<TSchema>,

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

@@ -8,14 +8,7 @@ import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/i
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
 import { extractFromOpaque } from "../../util/index.js";
-import {
-	type TreeLeafValue,
-	type ImplicitFieldSchema,
-	FieldSchema,
-	type ImplicitAllowedTypes,
-	type TreeNodeFromImplicitAllowedTypes,
-	normalizeAllowedTypes,
-} from "../schemaTypes.js";
+import { type ImplicitFieldSchema, FieldSchema } from "../fieldSchema.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -36,6 +29,10 @@ import {
 	getOrCreateNodeFromInnerNode,
 	typeSchemaSymbol,
 	getOrCreateInnerNode,
+	type TreeLeafValue,
+	type ImplicitAllowedTypes,
+	type TreeNodeFromImplicitAllowedTypes,
+	normalizeAllowedTypes,
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";

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

@@ -15,9 +15,7 @@ import type {
 	FieldKind,
 	FieldSchema,
 	FieldSchemaAlpha,
-	ImplicitAllowedTypes,
-	TreeLeafValue,
-} from "../schemaTypes.js";
+} from "../fieldSchema.js";
 import type {
 	NodeKind,
 	WithType,
@@ -27,9 +25,12 @@ import type {
 	TreeNodeSchema,
 	TreeNodeSchemaCore,
 	TreeNodeSchemaClass,
+	ImplicitAllowedTypes,
+	TreeLeafValue,
+	FlexListToUnion,
+	LazyItem,
 } from "../core/index.js";
 import type { TreeArrayNode } from "../node-kinds/index.js";
-import type { FlexListToUnion, LazyItem } from "../flexList.js";
 import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";
 
 /*

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

@@ -17,12 +17,9 @@ import {
 	type ITreeCursorSynchronous,
 } from "../../core/index.js";
 import { brand } from "../../util/index.js";
-import type {
-	TreeLeafValue,
-	ImplicitFieldSchema,
-	ImplicitAllowedTypes,
-} from "../schemaTypes.js";
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import type { ImplicitFieldSchema } from "../fieldSchema.js";
+import { NodeKind } from "../core/index.js";
+import type { TreeNodeSchema, ImplicitAllowedTypes, TreeLeafValue } from "../core/index.js";
 import {
 	isTreeValue,
 	stackTreeFieldCursor,

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

@@ -4,7 +4,7 @@
  */
 
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
-import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleFieldSchema,

package/src/simple-tree/core/README.md

@@ -8,4 +8,4 @@ This specifically does not contain any logic specific to field kinds or node kin
 ## Status
 
 More content should be moved into this directory as its disentangled from node kind specific logic.
-`proxyBinding.ts` is a good candidate to work toward moving here to.
+