@fluidframework/tree 2.10.0 → 2.12.0

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

@@ -18,6 +18,9 @@ import {
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
+// This import is required for intellisense in @link doc comments on mouseover in VSCode.
+// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 import {
 	booleanSchema,
@@ -74,6 +77,7 @@ import type {
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
 import { TreeNodeValid } from "../treeNodeValid.js";
 import { isLazy } from "../flexList.js";
+
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
@@ -97,6 +101,58 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 	}
 }
 
+/**
+ * Options when declaring an {@link SchemaFactory.object|object node}'s schema
+ */
+export interface SchemaFactoryObjectOptions {
+	/**
+	 * Opt in to viewing documents which have unknown optional fields for this object's identifier, i.e. optional fields
+	 * in the document schema which are not present in this object schema declaration.
+	 *
+	 * @defaultValue `false`
+	 * @remarks
+	 * The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly
+	 * upgrade documents to include schema for new optional features.
+	 *
+	 * However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between
+	 * code and documents.
+	 * When opening such documents, the API presented is still determined by the view schema.
+	 * This can have implications on the behavior of edits or code which uses portions of the view schema,
+	 * since this may inadvertently drop data which is present in those optional fields in the document schema.
+	 *
+	 * Consider the following example:
+	 *
+	 * ```typescript
+	 * const sf = new SchemaFactory("com.example");
+	 * class PersonView extends sf.object("Person", { name: sf.string }, { allowUnknownOptionalFields: true }) {}
+	 * class PersonStored extends sf.object("Person", { name: sf.string, nickname: sf.optional(sf.string) }) {}
+	 *
+	 * // Say we have a document which uses `PersonStored` in its schema, and application code constructs
+	 * // a tree view using `PersonView`. If the application for some reason had implemented a function like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 * 	return new PersonView({ name: a.name });
+	 * }
+	 * // ...or even like this:
+	 * function clonePerson(a: PersonView): PersonView {
+	 *  return new PersonView({ ...a})
+	 * }
+	 * // Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.
+	 * ```
+	 *
+	 * If an application wants to be particularly careful to preserve all data on a node when editing it, it can use
+	 * {@link TreeAlpha.(importVerbose:2)|import}/{@link TreeAlpha.(exportVerbose:2)|export} APIs with persistent keys.
+	 *
+	 * Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter
+	 * this problem as SharedTree's implementation stores the entire node in its lower layers. It's only when application code
+	 * reaches into a node (either by accessing its fields, spreading it, or some other means) that this problem arises.
+	 */
+	allowUnknownOptionalFields?: boolean;
+}
+
+export const defaultSchemaFactoryObjectOptions: Required<SchemaFactoryObjectOptions> = {
+	allowUnknownOptionalFields: false,
+};
+
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
@@ -333,7 +389,12 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(this.scoped(name), fields, true);
+		return objectSchema(
+			this.scoped(name),
+			fields,
+			true,
+			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
+		);
 	}
 
 	/**

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

@@ -30,7 +30,9 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
 	/**
-	 * Schemas for each of the object's fields, keyed off of schema's property keys.
+	 * Schemas for each of the object's fields, keyed off of schema's keys.
+	 * @remarks
+	 * Depending on how this schema was exported, the string keys may be either the property keys or the stored keys.
 	 */
 	readonly fields: Record<string, SimpleFieldSchema>;
 }

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

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { oob, unreachableCase } from "@fluidframework/core-utils/internal";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { getOrCreate, type Mutable } from "../../util/index.js";
+import { getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -42,9 +42,9 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
-	return allowedTypes.length === 1
+	return hasSingle(allowedTypes)
 		? {
-				...(allowedTypes[0] ?? oob()),
+				...allowedTypes[0],
 				$defs: definitions,
 			}
 		: {
@@ -96,8 +96,9 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 		allowedTypes.push(createSchemaRef(type));
 	});
 
-	const items: JsonFieldSchema =
-		allowedTypes.length === 1 ? (allowedTypes[0] ?? oob()) : { anyOf: allowedTypes };
+	const items: JsonFieldSchema = hasSingle(allowedTypes)
+		? allowedTypes[0]
+		: { anyOf: allowedTypes };
 
 	return {
 		type: "array",
@@ -142,12 +143,11 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 			allowedTypes.push(createSchemaRef(allowedType));
 		}
 
-		const output: Mutable<JsonFieldSchema> =
-			allowedTypes.length === 1
-				? (allowedTypes[0] ?? oob())
-				: {
-						anyOf: allowedTypes,
-					};
+		const output: Mutable<JsonFieldSchema> = hasSingle(allowedTypes)
+			? allowedTypes[0]
+			: {
+					anyOf: allowedTypes,
+				};
 
 		// Don't include "description" property at all if it's not present in the input.
 		if (value.metadata?.description !== undefined) {
@@ -178,12 +178,11 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Map,
 		patternProperties: {
-			"^.*$":
-				allowedTypes.length === 1
-					? (allowedTypes[0] ?? oob())
-					: {
-							anyOf: allowedTypes,
-						},
+			"^.*$": hasSingle(allowedTypes)
+				? allowedTypes[0]
+				: {
+						anyOf: allowedTypes,
+					},
 		},
 	};
 }

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

@@ -0,0 +1,233 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	AnchorNode,
+	FieldKey,
+	ITreeSubscriptionCursor,
+	TreeNodeSchemaIdentifier,
+} from "../../core/index.js";
+import {
+	AnchorTreeIndex,
+	isTreeValue,
+	type TreeIndexNodes,
+	hasElement,
+	type TreeIndex,
+	type TreeIndexKey,
+	type KeyFinder,
+} from "../../feature-libraries/index.js";
+import { brand, fail } from "../../util/index.js";
+import type { ImplicitFieldSchema, NodeFromSchema } from "../schemaTypes.js";
+import { treeNodeFromAnchor, type TreeNode, type TreeNodeSchema } from "../core/index.js";
+import { treeNodeApi } from "./treeNodeApi.js";
+import type { TreeView } from "./tree.js";
+import { walkFieldSchema } from "../walkFieldSchema.js";
+import type { SchematizingSimpleTreeView } from "../../shared-tree/index.js";
+
+/**
+ * A {@link TreeIndex} that returns tree nodes given their associated keys.
+ *
+ * @alpha
+ */
+export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
+
+/**
+ * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ *
+ * @param view - the view for the tree being indexed
+ * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
+ * should be keyed on, must be pure and functional
+ * @param getValue - given at least one {@link TreeNode}, returns an associated value
+ * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
+ *
+ * @alpha
+ */
+export function createSimpleTreeIndex<
+	TFieldSchema extends ImplicitFieldSchema,
+	TKey extends TreeIndexKey,
+	TValue,
+>(
+	view: TreeView<TFieldSchema>,
+	indexer: (schema: TreeNodeSchema) => string | undefined,
+	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+): SimpleTreeIndex<TKey, TValue>;
+/**
+ * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ *
+ * @param view - the view for the tree being indexed
+ * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
+ * should be keyed on, must be pure and functional
+ * @param getValue - given at least one {@link TreeNode}, returns an associated value
+ * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
+ * @param indexableSchema - a list of all the schema types that can be indexed
+ *
+ * @alpha
+ */
+export function createSimpleTreeIndex<
+	TFieldSchema extends ImplicitFieldSchema,
+	TKey extends TreeIndexKey,
+	TValue,
+	TSchema extends TreeNodeSchema,
+>(
+	view: TreeView<TFieldSchema>,
+	indexer: (schema: TSchema) => string | undefined,
+	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+	indexableSchema: readonly TSchema[],
+): SimpleTreeIndex<TKey, TValue>;
+/**
+ * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ *
+ * @param view - the view for the tree being indexed
+ * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
+ * should be keyed on
+ * @param getValue - given at least one {@link TreeNode}, returns an associated value
+ * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
+ *
+ * @alpha
+ */
+export function createSimpleTreeIndex<
+	TFieldSchema extends ImplicitFieldSchema,
+	TKey extends TreeIndexKey,
+	TValue,
+>(
+	view: TreeView<TFieldSchema>,
+	indexer: Map<TreeNodeSchema, string>,
+	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+): SimpleTreeIndex<TKey, TValue>;
+/**
+ * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ *
+ * @param view - the view for the tree being indexed
+ * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
+ * should be keyed on
+ * @param getValue - given at least one {@link TreeNode}, returns an associated value
+ * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
+ * @param indexableSchema - a list of all the schema types that can be indexed
+ *
+ * @alpha
+ */
+export function createSimpleTreeIndex<
+	TFieldSchema extends ImplicitFieldSchema,
+	TKey extends TreeIndexKey,
+	TValue,
+	TSchema extends TreeNodeSchema,
+>(
+	view: TreeView<TFieldSchema>,
+	indexer: Map<TreeNodeSchema, string>,
+	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+	indexableSchema: readonly TSchema[],
+): SimpleTreeIndex<TKey, TValue>;
+/**
+ * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ *
+ * @alpha
+ */
+export function createSimpleTreeIndex<
+	TFieldSchema extends ImplicitFieldSchema,
+	TKey extends TreeIndexKey,
+	TValue,
+>(
+	view: TreeView<TFieldSchema>,
+	indexer: ((schema: TreeNodeSchema) => string | undefined) | Map<TreeNodeSchema, string>,
+	getValue:
+		| ((nodes: TreeIndexNodes<TreeNode>) => TValue)
+		| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+	indexableSchema?: readonly TreeNodeSchema[],
+): SimpleTreeIndex<TKey, TValue> {
+	const indexableSchemaMap = new Map();
+	if (indexableSchema !== undefined) {
+		for (const schemus of indexableSchema) {
+			indexableSchemaMap.set(schemus.identifier, schemus);
+		}
+	} else {
+		walkFieldSchema(view.schema, {
+			node: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),
+		});
+	}
+
+	const schemaIndexer =
+		indexableSchema === undefined
+			? (schemaIdentifier: TreeNodeSchemaIdentifier) => {
+					// if indexable schema isn't provided, we check if the node is in schema
+					const schemus = indexableSchemaMap.get(schemaIdentifier);
+					if (schemus !== undefined) {
+						const keyLocation =
+							typeof indexer === "function" ? indexer(schemus) : indexer.get(schemus);
+						if (keyLocation !== undefined) {
+							return makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);
+						}
+					} else {
+						fail("node is out of schema");
+					}
+				}
+			: (schemaIdentifier: TreeNodeSchemaIdentifier) => {
+					const schemus = indexableSchemaMap.get(schemaIdentifier);
+					if (schemus !== undefined) {
+						const keyLocation =
+							typeof indexer === "function" ? indexer(schemus) : indexer.get(schemus);
+						if (keyLocation !== undefined) {
+							return makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);
+						}
+					}
+				};
+
+	const index = new AnchorTreeIndex<TKey, TValue>(
+		(view as SchematizingSimpleTreeView<TFieldSchema>).getView().checkout.forest,
+		schemaIndexer,
+		(anchorNodes) => {
+			const simpleTreeNodes: TreeNode[] = [];
+			for (const anchorNode of anchorNodes) {
+				const simpleTree = treeNodeFromAnchor(anchorNode);
+				if (!isTreeValue(simpleTree)) {
+					simpleTreeNodes.push(simpleTree);
+				}
+			}
+
+			if (hasElement(simpleTreeNodes)) {
+				return getValue(simpleTreeNodes);
+			}
+		},
+		(anchorNode: AnchorNode) => {
+			const simpleTree = treeNodeFromAnchor(anchorNode);
+			if (!isTreeValue(simpleTree)) {
+				return treeNodeApi.status(simpleTree);
+			}
+		},
+		// simple tree indexes are shallow indexes, indicating so allows for a performance optimization
+		true,
+	);
+
+	// all the type checking guarantees that we put nodes of the correct type in the index
+	// but it's not captured in the type system
+	return index as SimpleTreeIndex<TKey, TValue>;
+}
+
+function makeGenericKeyFinder<TKey extends TreeIndexKey>(
+	keyField: FieldKey,
+	isKeyValid: (key: TreeIndexKey) => key is TKey,
+): KeyFinder<TKey> {
+	return (cursor: ITreeSubscriptionCursor) => {
+		cursor.enterField(keyField);
+		cursor.firstNode();
+		const value = cursor.value;
+		cursor.exitNode();
+		cursor.exitField();
+
+		if (value === undefined) {
+			fail("a value for the key does not exist");
+		}
+
+		if (!isKeyValid(value)) {
+			fail("the key is an unexpected type");
+		}
+
+		return value;
+	};
+}

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

@@ -4,7 +4,7 @@
  */
 
 import type { ICodecOptions } from "../../codec/index.js";
-import { Compatibility, type TreeStoredSchema } from "../../core/index.js";
+import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
@@ -59,7 +59,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.
  *
  * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.
- * @param view - Schema which would be used to view persisted content. Use {@link extractPersistedSchema} to convert the view schema into this format.
+ * @param view - Schema which would be used to view persisted content.
  * @param options - {@link ICodecOptions} used when parsing the provided schema.
  * @param canInitialize - Passed through to the return value unchanged and otherwise unused.
  * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.
@@ -75,7 +75,7 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  * assert(
  * 	comparePersistedSchema(
  * 		require("./schema.json"),
- * 		extractPersistedSchema(MySchema),
+ * 		MySchema,
  * 		{ jsonValidator: typeboxValidator },
  * 		false,
  * 	).canUpgrade,
@@ -85,14 +85,13 @@ export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompati
  */
 export function comparePersistedSchema(
 	persisted: JsonCompatible,
-	view: JsonCompatible,
+	view: ImplicitFieldSchema,
 	options: ICodecOptions,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
 	const schemaCodec = makeSchemaCodec(options);
 	const stored = schemaCodec.decode(persisted as Format);
-	const viewParsed = schemaCodec.decode(view as Format);
-	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);
+	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, view);
 	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
 }
 
@@ -105,22 +104,8 @@ export function comparePersistedSchemaInternal(
 	viewSchema: ViewSchema,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
-	const result = viewSchema.checkCompatibility(stored);
-
-	// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
-	// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
-	// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
-	// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
-	const canView =
-		result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
-	const canUpgrade = result.read === Compatibility.Compatible;
-	const isEquivalent = canView && canUpgrade;
-	const compatibility: SchemaCompatibilityStatus = {
-		canView,
-		canUpgrade,
-		isEquivalent,
+	return {
+		...viewSchema.checkCompatibility(stored),
 		canInitialize,
 	};
-
-	return compatibility;
 }

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

@@ -3,11 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import type { IFluidLoadable, IDisposable } from "@fluidframework/core-interfaces";
+import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { CommitMetadata, RevertibleFactory } from "../../core/index.js";
-import type { Listenable } from "../../events/index.js";
+import type {
+	CommitMetadata,
+	RevertibleAlphaFactory,
+	RevertibleFactory,
+} from "../../core/index.js";
+
+// This is referenced by doc comments.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 import {
 	type ImplicitFieldSchema,
@@ -28,6 +35,7 @@ import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
+
 /**
  * A tree from which a {@link TreeView} can be created.
  *
@@ -38,6 +46,7 @@ import { walkFieldSchema } from "../walkFieldSchema.js";
  * Maybe rename "exportJsonSchema" to align on "concise" terminology.
  * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
  * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
+ * Some of these APIs are on ISharedTree and can get moved here.
  * @system @sealed @public
  */
 export interface ViewableTree {
@@ -629,7 +638,7 @@ export interface TreeBranchEvents {
 	 * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,
 	 * this change is not revertible.
 	 */
-	changed(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+	changed(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
 
 	/**
 	 * Fired when:
@@ -644,7 +653,7 @@ export interface TreeBranchEvents {
 	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
 	 * this commit is not revertible.
 	 */
-	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+	commitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
 }
 
 /**

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

@@ -24,7 +24,7 @@ import {
 } from "../leafNodeSchema.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { Off } from "../../events/index.js";
+import type { Off } from "@fluidframework/core-interfaces";
 import {
 	getKernel,
 	isTreeNode,

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

@@ -38,7 +38,7 @@ import {
 } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import {
-	customFromCursorInner,
+	customFromCursor,
 	type CustomTreeNode,
 	type CustomTreeValue,
 	type EncodeOptions,
@@ -344,7 +344,7 @@ function verboseFromCursorInner<TCustom>(
 	options: Required<EncodeOptions<TCustom>>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
-	const fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);
+	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
 	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
 	if (nodeSchema.kind === NodeKind.Leaf) {
 		return fields as CustomTreeValue<TCustom>;