@fluidframework/tree 2.40.0-336023 → 2.40.0

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

@@ -4,13 +4,8 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { ErasedType } from "@fluidframework/core-interfaces";
 
-import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
-// eslint-disable-next-line import/no-deprecated
-import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
-import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { isFlexTreeNode, type FlexTreeNode } from "../../feature-libraries/index.js";
 
 /**
@@ -29,235 +24,6 @@ import { isFlexTreeNode, type FlexTreeNode } from "../../feature-libraries/index
  */
 export type Unhydrated<T> = T;
 
-/**
- * A collection of events that can be emitted by a {@link TreeNode}.
- *
- * @privateRemarks
- * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
- * Probably have object node and map node specific APIs for this.
- *
- * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
- *
- * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
- * Some ideas:
- *
- * - treeChanged, but with some subtrees/fields/paths excluded
- * - helper to batch several nodeChanged calls to a treeChanged scope
- * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
- * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
- * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
- * to allow efficiently searching for new content (and initial content) of a given type.
- *
- * @sealed @public
- */
-export interface TreeChangeEvents {
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
-	 *
-	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
-	 *
-	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
-	 *
-	 * - Map nodes define a change as when an entry is added, updated, or removed.
-	 *
-	 * @param unstable - Future versions of this API (such as the one in beta on TreeBeta) may use this argument to provide additional data to the event.
-	 * users of this event should ensure that they do not provide a listener callback which has an optional parameter in this position, since unexpected data might get provided to it.
-	 * This parameter exists to capture this fact in the type system.
-	 * Using an inline lambda expression as the listener callback is a good pattern to avoid cases like this were arguments are added from breaking due to optional arguments.
-	 *
-	 * @remarks
-	 * This event is not emitted when:
-	 *
-	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
-	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
-	 * array/map node as one of its properties.
-	 *
-	 * - The node is moved to a different location in the tree or removed from the tree.
-	 * In this case the event is emitted on the _parent_ node, not the node itself.
-	 *
-	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-	 * the client that made the original edit.
-	 *
-	 * When the event is emitted, the tree is guaranteed to be in-schema.
-	 *
-	 * @privateRemarks
-	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
-	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
-	 * node, or when the node has to be updated due to resolution of a merge conflict
-	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
-	 *
-	 * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
-	 */
-	nodeChanged(unstable?: unknown): void;
-
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-	 * subtree rooted at it.
-	 *
-	 * @remarks
-	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
-	 * In that case it is emitted on the _parent_ node, not the node itself.
-	 *
-	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
-	 * of the node itself.
-	 *
-	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-	 * the client that made the original edit.
-	 *
-	 * When it is emitted, the tree is guaranteed to be in-schema.
-	 */
-	treeChanged(): void;
-}
-
-/**
- * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
- *
- * @remarks
- * Base type which all nodes extend.
- *
- * This type can be used as a type to indicate/document values which should be tree nodes.
- * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.
- *
- * There are three ways to get instances of TreeNode:
- *
- * 1. From a {@link TreeView} loading nodes from an existing document, or creating local copies of nodes inserted by a remote collaborator.
- * This case provides an {@link InternalTreeNode} to the constructor: subclasses must not modify how the constructor handles this case.
- * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
- * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
- * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
- * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
- * Note that when constructing nodes, sometimes implicit construction is not allowed
- * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
- * in such cases, explicit construction must be used.
- *
- * @privateRemarks
- * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
- * and some runtime enforcement of schema class policy (see the the validation in the constructor).
- * This class is however only `type` exported not value exported, preventing the class object from being used,
- * similar to how interfaces work.
- *
- * Not all node implementations include this in their prototype chain (some hide it with a proxy),
- * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
- * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
- * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
- * @sealed @public
- */
-export abstract class TreeNode implements WithType {
-	/**
-	 * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.
-	 * @remarks
-	 * This field forces TypeScript to use nominal instead of structural typing,
-	 * preventing compiler error messages and tools like "add missing properties"
-	 * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.
-	 * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.
-	 *
-	 * @privateRemarks
-	 * This is a JavaScript private field, so is not accessible from outside this class.
-	 * This prevents it from having name collisions with object fields.
-	 * Since this is private, the type of this field is stripped in the d.ts file.
-	 * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.
-	 * To avoid this having any runtime impact, the field is uninitialized.
-	 *
-	 * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.
-	 * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.
-	 * To avoid all this mess, this field is required, not optional.
-	 *
-	 * Another option would be to use a symbol (possibly as a private field).
-	 * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
-	 *
-	 * The [type] symbol provides a lot of the value this private brand does, but is not all of it:
-	 * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
-	 * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
-	 */
-	readonly #brand!: unknown;
-
-	/**
-	 * Adds a type symbol for stronger typing.
-	 * @privateRemarks
-	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
-	 * @deprecated Use {@link typeSchemaSymbol} instead.
-	 */
-	// eslint-disable-next-line import/no-deprecated
-	public abstract get [typeNameSymbol](): string;
-
-	/**
-	 * Adds a type symbol for stronger typing.
-	 * @privateRemarks
-	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
-	 */
-	public abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;
-
-	/**
-	 * Provides `instanceof` support for testing if a value is a `TreeNode`.
-	 * @remarks
-	 * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
-	 * @privateRemarks
-	 * Due to type-only export, this functionality is not available outside the package.
-	 */
-	public static [Symbol.hasInstance](value: unknown): value is TreeNode;
-
-	/**
-	 * Provides `instanceof` support for all schema classes with public constructors.
-	 * @remarks
-	 * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
-	 * @privateRemarks
-	 * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.
-	 */
-	public static [Symbol.hasInstance]<
-		TSchema extends abstract new (
-			...args: any[]
-		) => TreeNode,
-	>(this: TSchema, value: unknown): value is InstanceType<TSchema>;
-
-	public static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {
-		const schema = tryGetTreeNodeSchema(value);
-
-		if (schema === undefined || schema.kind === NodeKind.Leaf) {
-			return false;
-		}
-
-		assert("prototype" in schema, 0x98a /* expected class based schema */);
-		return inPrototypeChain(schema.prototype, this.prototype);
-	}
-
-	/**
-	 * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
-	 * @privateRemarks
-	 * `token` must be the {@link privateToken} value, which is not package exported.
-	 * This is used to detect invalid subclasses.
-	 *
-	 * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
-	 */
-	protected constructor(token: unknown) {
-		if (token !== privateToken) {
-			throw new UsageError("TreeNodes must extend schema classes created by SchemaFactory");
-		}
-	}
-}
-
-/**
- * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
- */
-export const privateToken = {};
-
-/**
- * Check if the prototype derived's prototype chain contains `base`.
- * @param derived - prototype to check
- * @param base - prototype to search for
- * @returns true iff `base` is in the prototype chain starting at `derived`.
- */
-// eslint-disable-next-line @rushstack/no-new-null
-export function inPrototypeChain(derived: object | null, base: object): boolean {
-	let checking = derived;
-	while (checking !== null) {
-		if (base === checking) {
-			return true;
-		}
-		checking = Reflect.getPrototypeOf(checking);
-	}
-	return false;
-}
-
 /**
  * A node type internal to `@fluidframework/tree`.
  * @remarks

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

@@ -4,7 +4,7 @@
  */
 
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
-import type { TreeNode } from "./types.js";
+import type { TreeNode } from "./treeNode.js";
 
 /**
  * The type of a {@link TreeNode}.

package/src/simple-tree/index.ts

@@ -12,7 +12,6 @@ export {
 	type TreeNodeSchemaClass,
 	type TreeNodeSchemaNonClass,
 	type TreeNodeSchemaCore,
-	type TreeChangeEvents,
 	// TreeNode is only type exported, which prevents use of the class object for unsupported use-cases like direct sub-classing and instanceof.
 	// See docs on TreeNode for more details.
 	type TreeNode,
@@ -122,6 +121,8 @@ export {
 	type TreeSchema,
 	type ValidateRecursiveSchemaTemplate,
 	type FixRecursiveRecursionLimit,
+	schemaStatics,
+	type TreeChangeEvents,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,

package/src/simple-tree/schemaTypes.ts

@@ -1142,6 +1142,7 @@ export type TreeNodeFromImplicitAllowedTypes<
  * Consider a field with schema type of `A | B` (where A and B are types of schema).
  *
  * - Reading the field behaves covariantly so {@link NodeFromSchema} of `<A | B>` is the same as `NodeFromSchema<A> | NodeFromSchema<B>`, indicating that either type of node can be read from the field.
+ *
  * - Writing to the field behaves contravariantly. Since it is unknown if the node actually has a schema `A` or a schema `B`, the only legal values (known to be in schema regardless of which schema the underlying node has) are values which are legal for both `A & B`.
  *
  * Note that this is distinct from the case where the schema is `[A, B]`.

package/src/simple-tree/toStoredSchema.ts

@@ -21,17 +21,16 @@ import {
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
 import { brand, getOrCreate } from "../util/index.js";
-import { NodeKind, type TreeNodeSchema } from "./core/index.js";
-import {
-	FieldKind,
-	FieldSchema,
-	normalizeAllowedTypes,
-	type ImplicitAllowedTypes,
-	type ImplicitFieldSchema,
-} from "./schemaTypes.js";
+import { NodeKind } from "./core/index.js";
+import { FieldKind, normalizeFieldSchema, type ImplicitFieldSchema } from "./schemaTypes.js";
 import { walkFieldSchema } from "./walkFieldSchema.js";
 import { LeafNodeSchema } from "./leafNodeSchema.js";
-import { isObjectNodeSchema } from "./objectNodeTypes.js";
+import type {
+	SimpleFieldSchema,
+	SimpleNodeSchema,
+	SimpleNodeSchemaBase,
+	SimpleTreeSchema,
+} from "./simpleSchema.js";
 
 const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
 
@@ -40,8 +39,9 @@ const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
  */
 export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
 	return getOrCreate(viewToStoredCache, root, () => {
+		const normalized = normalizeFieldSchema(root);
 		const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
-		walkFieldSchema(root, {
+		walkFieldSchema(normalized, {
 			node(schema) {
 				if (nodeSchema.has(brand(schema.identifier))) {
 					// Use JSON.stringify to quote and escape identifier string.
@@ -51,34 +51,44 @@ export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
 						)}. Remove or rename them to avoid the collision.`,
 					);
 				}
-				nodeSchema.set(brand(schema.identifier), getStoredSchema(schema));
+				nodeSchema.set(
+					brand(schema.identifier),
+					getStoredSchema(schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema),
+				);
 			},
 		});
 
 		const result: TreeStoredSchema = {
 			nodeSchema,
-			rootFieldSchema: convertField(root),
+			rootFieldSchema: convertField(normalized),
 		};
-		viewToStoredCache.set(root, result);
 		return result;
 	});
 }
 
 /**
- * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
+ * Converts a {@link SimpleTreeSchema} into a {@link TreeStoredSchema}.
  */
-export function convertField(schema: ImplicitFieldSchema): TreeFieldStoredSchema {
-	let kind: FieldKindIdentifier;
-	let allowedTypes: ImplicitAllowedTypes;
-	if (schema instanceof FieldSchema) {
-		kind =
-			convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
-		allowedTypes = schema.allowedTypes;
-	} else {
-		kind = FieldKinds.required.identifier;
-		allowedTypes = schema;
+export function simpleToStoredSchema(root: SimpleTreeSchema): TreeStoredSchema {
+	const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
+	for (const [identifier, schema] of root.definitions) {
+		nodeSchema.set(brand(identifier), getStoredSchema(schema));
 	}
-	const types = convertAllowedTypes(allowedTypes);
+
+	const result: TreeStoredSchema = {
+		nodeSchema,
+		rootFieldSchema: convertField(root.root),
+	};
+	return result;
+}
+
+/**
+ * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
+ */
+export function convertField(schema: SimpleFieldSchema): TreeFieldStoredSchema {
+	const kind: FieldKindIdentifier =
+		convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
+	const types: TreeTypeSet = schema.allowedTypesIdentifiers as TreeTypeSet;
 	return { kind, types };
 }
 
@@ -88,42 +98,33 @@ const convertFieldKind = new Map<FieldKind, FlexFieldKind>([
 	[FieldKind.Identifier, FieldKinds.identifier],
 ]);
 
-/**
- * Normalizes an {@link ImplicitAllowedTypes} into an {@link TreeTypeSet}.
- */
-export function convertAllowedTypes(schema: ImplicitAllowedTypes): TreeTypeSet {
-	return new Set([...normalizeAllowedTypes(schema)].map((item) => brand(item.identifier)));
-}
-
 /**
  * Converts a {@link TreeNodeSchema} into a {@link TreeNodeStoredSchema}.
  */
-export function getStoredSchema(schema: TreeNodeSchema): TreeNodeStoredSchema {
+export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema {
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf: {
 			assert(schema instanceof LeafNodeSchema, 0xa4a /* invalid kind */);
-			return new LeafNodeStoredSchema(schema.info);
+			return new LeafNodeStoredSchema(schema.leafKind);
 		}
 		case NodeKind.Map: {
-			const fieldInfo = schema.info as ImplicitAllowedTypes;
-			const types = convertAllowedTypes(fieldInfo);
+			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
 			return new MapNodeStoredSchema({ kind: FieldKinds.optional.identifier, types });
 		}
 		case NodeKind.Array: {
-			const fieldInfo = schema.info as ImplicitAllowedTypes;
+			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
 			const field = {
 				kind: FieldKinds.sequence.identifier,
-				types: convertAllowedTypes(fieldInfo),
+				types,
 			};
 			const fields = new Map([[EmptyKey, field]]);
 			return new ObjectNodeStoredSchema(fields);
 		}
 		case NodeKind.Object: {
-			assert(isObjectNodeSchema(schema), 0xa4b /* invalid kind */);
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
-			for (const field of schema.flexKeyMap.values()) {
-				fields.set(field.storedKey, convertField(field.schema));
+			for (const fieldSchema of schema.fields.values()) {
+				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema));
 			}
 			return new ObjectNodeStoredSchema(fields);
 		}