@fluidframework/tree 2.10.0 → 2.11.0

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

@@ -0,0 +1,231 @@
+/*!
+ * 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);
+			}
+		},
+	);
+
+	// 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/tree.ts

@@ -3,11 +3,14 @@
  * 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";
 
 import {
 	type ImplicitFieldSchema,
@@ -629,7 +632,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 +647,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/core/index.ts

@@ -12,6 +12,7 @@ export {
 	tryDisposeTreeNode,
 	tryGetTreeNodeFromMapNode,
 	getOrCreateInnerNode,
+	treeNodeFromAnchor,
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {

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

@@ -4,13 +4,15 @@
  */
 
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
-import { createEmitter, type Listenable, type Off } from "../../events/index.js";
-import type { TreeNode, Unhydrated } from "./types.js";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable, Off } from "@fluidframework/core-interfaces";
+import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 import {
 	anchorSlot,
 	type AnchorEvents,
 	type AnchorNode,
 	type AnchorSet,
+	type TreeValue,
 	type UpPath,
 } from "../../core/index.js";
 import {
@@ -447,3 +449,36 @@ export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): In
 	const kernel = getKernel(treeNode);
 	return kernel.getOrCreateInnerNode(allowFreed);
 }
+
+/**
+ * Gets a flex node from an anchor node
+ */
+function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
+	// the proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+	const flexNode = anchorNode.slots.get(flexTreeSlot);
+	if (flexNode !== undefined) {
+		return flexNode; // If it does have a flex node, return it...
+	} // ...otherwise, the flex node must be created
+	const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+	const cursor = context.checkout.forest.allocateCursor("getFlexNode");
+	context.checkout.forest.moveCursorToPath(anchorNode, cursor);
+	const newFlexNode = makeTree(context, cursor);
+	cursor.free();
+	return newFlexNode;
+}
+
+/**
+ * Gets a tree node from an anchor node
+ */
+export function treeNodeFromAnchor(anchorNode: AnchorNode): TreeNode | TreeValue {
+	const cached = anchorNode.slots.get(proxySlot);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	const flexNode = flexNodeFromAnchor(anchorNode);
+	const classSchema = getTreeNodeSchemaFromHydratedFlexNode(flexNode);
+	return typeof classSchema === "function"
+		? new classSchema(flexNode as unknown as InternalTreeNode)
+		: (classSchema as { create(data: FlexTreeNode): TreeValue }).create(flexNode);
+}

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

@@ -4,6 +4,8 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -43,7 +45,6 @@ import {
 	cursorForMapTreeNode,
 } from "../../feature-libraries/index.js";
 import type { Context } from "./context.js";
-import { createEmitter, type Listenable } from "../../events/index.js";
 
 interface UnhydratedTreeSequenceFieldEditBuilder
 	extends SequenceFieldEditBuilder<ExclusiveMapTree[]> {

package/src/simple-tree/index.ts

@@ -51,6 +51,10 @@ export {
 	type NodeChangedData,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type SimpleTreeIndex,
+	type IdentifierIndex,
+	createSimpleTreeIndex,
+	createIdentifierIndex,
 	type SimpleNodeSchemaBase,
 	type SimpleTreeSchema,
 	type SimpleNodeSchema,

package/src/simple-tree/objectNode.ts

@@ -100,24 +100,31 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = T extends FieldSche
  *
  * @see {@link Input}
  *
- * @privateRemarks TODO: consider separating these cases into different types.
+ * @privateRemarks
+ * TODO: consider separating these cases into different types.
+ *
+ * Empty objects don't get "no excess property" checks in literals.
+ * To prevent extraneous properties in literals for the fields of an empty object from compiling, the empty case is special cased to produce `Record<string, never>`.
+ * More details at {@link https://mercury.com/blog/creating-an-emptyobject-type-in-typescript}.
  *
  * @system @public
  */
 export type InsertableObjectFromSchemaRecord<
 	T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-> = FlattenKeys<
-	{
-		readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
-			T[Property & string]
+> = Record<string, never> extends T
+	? Record<string, never>
+	: FlattenKeys<
+			{
+				readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
+					T[Property & string]
+				>;
+			} & {
+				// Field does not have a known default, make it required:
+				readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
+					? Property
+					: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+			}
 		>;
-	} & {
-		// Field does not have a known default, make it required:
-		readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
-			? Property
-			: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
-	}
->;
 
 /**
  * Maps from simple field keys ("property" keys) to information about the field.

package/src/simple-tree/toMapTree.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
@@ -21,7 +21,7 @@ import {
 	valueSchemaAllows,
 	type NodeKeyManager,
 } from "../feature-libraries/index.js";
-import { brand, fail, isReadonlyArray, find } from "../util/index.js";
+import { brand, fail, isReadonlyArray, find, hasSome, hasSingle } from "../util/index.js";
 
 import { nullSchema } from "./leafNodeSchema.js";
 import {
@@ -465,10 +465,10 @@ function getType(
 		);
 	}
 	assert(
-		possibleTypes.length !== 0,
+		hasSome(possibleTypes),
 		0x84e /* data is incompatible with all types allowed by the schema */,
 	);
-	if (possibleTypes.length !== 1) {
+	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([
@@ -478,7 +478,7 @@ 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})".`,
 		);
 	}
-	return possibleTypes[0] ?? oob();
+	return possibleTypes[0];
 }
 
 /**

package/src/util/index.ts

@@ -37,7 +37,6 @@ export {
 } from "./nestedMap.js";
 export { addToNestedSet, type NestedSet, nestedSetContains } from "./nestedSet.js";
 export { type OffsetList, OffsetListFactory } from "./offsetList.js";
-export { TransactionResult } from "./transactionResult.js";
 export type {
 	areSafelyAssignable,
 	Contravariant,
@@ -91,6 +90,9 @@ export {
 	compareStrings,
 	find,
 	count,
+	getLast,
+	hasSome,
+	hasSingle,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 

package/src/util/typeCheck.ts

@@ -193,6 +193,11 @@ export type requireAssignableTo<_A extends B, B> = true;
 
 /**
  * Returns a type parameter that is true iff the `Keys` union includes all the keys of `T`.
+ *
+ * @remarks
+ * This does not handle when the T has an index signature permitting keys like `string` which
+ * TypeScript cannot omit members from.
+ *
  * @example
  * ```ts
  * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a' | 'b'>> // true`
@@ -201,5 +206,5 @@ export type requireAssignableTo<_A extends B, B> = true;
  */
 export type areOnlyKeys<T, Keys extends keyof T> = isAssignableTo<
 	Record<string, never>,
-	Omit<T, Keys>
+	Omit<Required<T>, Keys>
 >;

package/src/util/typeCheckTests.ts

@@ -15,6 +15,7 @@ import type {
 	Covariant,
 	Invariant,
 	MakeNominal,
+	areOnlyKeys,
 	areSafelyAssignable,
 	eitherIsAny,
 	isAny,
@@ -221,10 +222,19 @@ export type EnforceTypeCheckTests =
 	| requireTrue<isStrictSubset<[1, true], [1 | 2, true | false]>>
 	| requireTrue<isStrictSubset<[1, true], [1, true | false]>>
 	| requireTrue<isStrictSubset<[1, true], [1, true] | [1 | false]>>
+	| requireTrue<isStrictSubset<1, number>>
 	| requireFalse<isStrictSubset<1, 1>>
 	| requireFalse<isStrictSubset<1, 2>>
 	| requireFalse<isStrictSubset<[1, true], [1, true]>>
-	| requireFalse<isStrictSubset<1 | 2, 1>>;
+	| requireFalse<isStrictSubset<1 | 2, 1>>
+
+	// areOnlyKeys
+	| requireTrue<areOnlyKeys<{ a: number; b: number }, "a" | "b">>
+	| requireTrue<areOnlyKeys<{ a?: number; b: number }, "a" | "b">>
+	| requireFalse<areOnlyKeys<{ a?: number; b: number }, "b">>
+	| requireFalse<areOnlyKeys<{ a: number; b: number }, "a">>;
+// This case is explicitly documented as unsupported.
+// | requireFalse<areOnlyKeys<Record<string, unknown>, "a">>;
 
 // negative tests (should not build)
 // @ts-expect-error negative test

package/src/util/utils.ts

@@ -79,6 +79,44 @@ export function makeArray<T>(size: number, filler: (index: number) => T): T[] {
 	return array;
 }
 
+/**
+ * Returns the last element of an array, or `undefined` if the array has no elements.
+ * @param array - The array to get the last element from.
+ * @remarks
+ * If the type of the array has been narrowed by e.g. {@link hasSome | hasSome(array)} or {@link hasSingle | hasOne(array)} then the return type will be `T` rather than `T | undefined`.
+ */
+export function getLast<T>(array: readonly [T, ...T[]]): T;
+export function getLast<T>(array: { [index: number]: T; length: number }): T | undefined;
+export function getLast<T>(array: { [index: number]: T; length: number }): T | undefined {
+	return array[array.length - 1];
+}
+
+/**
+ * Returns true if and only if the given array has at least one element.
+ * @param array - The array to check.
+ * @remarks
+ * If `array` contains at least one element, its type will be narrowed and can benefit from improved typing from e.g. `array[0]` and {@link getLast | getLast(array)}.
+ * This is especially useful when "noUncheckedIndexedAccess" is enabled in the TypeScript compiler options, since the return type of `array[0]` will be `T` rather than `T | undefined`.
+ */
+export function hasSome<T>(array: T[]): array is [T, ...T[]];
+export function hasSome<T>(array: readonly T[]): array is readonly [T, ...T[]];
+export function hasSome<T>(array: readonly T[]): array is [T, ...T[]] {
+	return array.length > 0;
+}
+
+/**
+ * Returns true if and only if the given array has exactly one element.
+ * @param array - The array to check.
+ * @remarks
+ * If `array` contains exactly one element, its type will be narrowed and can benefit from improved typing from e.g. `array[0]` and {@link getLast | getLast(array)}.
+ * This is especially useful when "noUncheckedIndexedAccess" is enabled in the TypeScript compiler options, since the return type of `array[0]` will be `T` rather than `T | undefined`.
+ */
+export function hasSingle<T>(array: T[]): array is [T];
+export function hasSingle<T>(array: readonly T[]): array is readonly [T];
+export function hasSingle<T>(array: readonly T[]): array is [T] {
+	return array.length === 1;
+}
+
 /**
  * Compares two sets using callbacks.
  * Early returns on first false comparison.