@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/class-tree/toFlexSchema.ts

@@ -0,0 +1,279 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-internal-modules */
+import { assert, unreachableCase } from "@fluidframework/core-utils";
+import {
+	FlexTreeSchema,
+	TreeFieldSchema as FlexTreeFieldSchema,
+	FieldKind as FlexFieldKind,
+	FieldKinds,
+	AllowedTypes as FlexAllowedTypes,
+	TreeNodeSchemaBase as FlexTreeNodeSchemaBase,
+	TreeNodeSchema as FlexTreeNodeSchema,
+	defaultSchemaPolicy,
+	MapNodeSchema as FlexMapNodeSchema,
+	FieldNodeSchema as FlexFieldNodeSchema,
+	ObjectNodeSchema as FlexObjectNodeSchema,
+	schemaIsLeaf,
+} from "../feature-libraries";
+import { brand, fail, isReadonlyArray, mapIterable } from "../util";
+import { normalizeFlexListEager } from "../feature-libraries/typed-schema/flexList";
+import {
+	InsertableContent,
+	extractFactoryContent,
+	getClassSchema,
+	simpleSchemaSymbol,
+} from "../simple-tree/proxies";
+import { AllowedUpdateType, ITreeCursorSynchronous, TreeNodeSchemaIdentifier } from "../core";
+import { type InitializeAndSchematizeConfiguration } from "../shared-tree";
+import { cursorFromNodeData } from "../simple-tree/toMapTree";
+import {
+	FieldKind,
+	FieldSchema,
+	ImplicitAllowedTypes,
+	ImplicitFieldSchema,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+	NodeKind,
+	TreeNodeSchema,
+} from "./schemaTypes";
+import { TreeConfiguration } from "./tree";
+
+/**
+ * Returns a cursor (in nodes mode) for the root node.
+ *
+ * @privateRemarks
+ * Ideally this would work on any node, not just the root,
+ * and the schema would come from the unhydrated node.
+ * For now though, this is the only case that's needed, and we do have the data to make it work, so this is fine.
+ */
+export function cursorFromUnhydratedRoot(
+	schema: FlexTreeSchema,
+	tree: InsertableTreeNodeFromImplicitAllowedTypes,
+): ITreeCursorSynchronous {
+	const data = extractFactoryContent(tree as InsertableContent);
+	return (
+		cursorFromNodeData(data.content, schema, schema.rootFieldSchema.allowedTypeSet) ??
+		fail("failed to decode tree")
+	);
+}
+
+export function toFlexConfig(config: TreeConfiguration): InitializeAndSchematizeConfiguration {
+	const schema = toFlexSchema(config.schema);
+	const unhydrated = config.initialTree();
+	const initialTree =
+		unhydrated === undefined ? undefined : [cursorFromUnhydratedRoot(schema, unhydrated)];
+	return {
+		allowedSchemaModifications: AllowedUpdateType.None,
+		schema,
+		initialTree,
+	};
+}
+
+interface SchemaInfo {
+	toFlex: () => FlexTreeNodeSchema;
+	original: TreeNodeSchema;
+}
+
+type SchemaMap = Map<TreeNodeSchemaIdentifier, SchemaInfo>;
+
+/**
+ * Generate a {@link FlexTreeSchema} with `root` as the root field.
+ *
+ * This also has the side effect of populating the cached view schema on the class based schema.
+ */
+export function toFlexSchema(root: ImplicitFieldSchema): FlexTreeSchema {
+	const schemaMap: SchemaMap = new Map();
+	const field = convertField(schemaMap, root);
+	const nodeSchema = new Map(
+		mapIterable(schemaMap, ([key, value]) => {
+			const schema = value.toFlex();
+			const classSchema = getClassSchema(schema);
+			if (classSchema === undefined) {
+				assert(schemaIsLeaf(schema), 0x83e /* invalid leaf */);
+			} else {
+				assert(
+					cachedFlexSchemaFromClassSchema(classSchema) === schema,
+					0x83f /* mismatched schema */,
+				);
+			}
+			return [key, schema];
+		}),
+	);
+
+	const typed: FlexTreeSchema = {
+		nodeSchema,
+		adapters: {},
+		rootFieldSchema: field,
+		policy: defaultSchemaPolicy,
+	};
+	return typed;
+}
+
+/**
+ * Return a flex schema for the provided class schema.
+ *
+ * This also has the side effect of populating the cached view schema on the class based schema.
+ */
+export function getFlexSchema(root: TreeNodeSchema): FlexTreeNodeSchema {
+	const treeSchema = toFlexSchema(root);
+	return treeSchema.rootFieldSchema.monomorphicChildType ?? fail("root should be monomorphic");
+}
+
+/**
+ * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
+ */
+export function convertField(
+	schemaMap: SchemaMap,
+	schema: ImplicitFieldSchema,
+): FlexTreeFieldSchema {
+	let kind: FlexFieldKind;
+	let types: ImplicitAllowedTypes;
+	if (schema instanceof FieldSchema) {
+		kind = convertFieldKind.get(schema.kind) ?? fail("Invalid field kind");
+		types = schema.allowedTypes;
+	} else {
+		kind = FieldKinds.required;
+		types = schema;
+	}
+	const allowedTypes = convertAllowedTypes(schemaMap, types);
+	return FlexTreeFieldSchema.create(kind, allowedTypes);
+}
+
+const convertFieldKind = new Map<FieldKind, FlexFieldKind>([
+	[FieldKind.Optional, FieldKinds.optional],
+	[FieldKind.Required, FieldKinds.required],
+]);
+
+/**
+ * Normalizes an {@link ImplicitAllowedTypes} into an {@link AllowedTypes}.
+ */
+export function convertAllowedTypes(
+	schemaMap: SchemaMap,
+	schema: ImplicitAllowedTypes,
+): FlexAllowedTypes {
+	if (isReadonlyArray(schema)) {
+		return normalizeFlexListEager(schema).map((item) => convertNodeSchema(schemaMap, item));
+	}
+	return [convertNodeSchema(schemaMap, schema)];
+}
+
+const builder = { name: "simple schema" };
+
+/**
+ * Converts a {@link TreeNodeSchema} into a {@link FlexTreeNodeSchema}.
+ * Ensures all types reachable from `schema` are included in `schemaMap`.
+ *
+ * Return value (and entries in map) are lazy to allow recursive types to work.
+ * This laziness does NOT extend to adding entries to `schemaMap`:
+ * all referenced types are added to it before this function returns.
+ */
+export function convertNodeSchema(
+	schemaMap: SchemaMap,
+	schema: TreeNodeSchema,
+): () => FlexTreeNodeSchema {
+	const fromMap = schemaMap.get(brand(schema.identifier));
+	if (fromMap !== undefined) {
+		if (fromMap.original !== schema) {
+			// Use JSON.stringify to quote and escape string.
+			throw new Error(
+				`Multiple schema encountered with the identifier ${JSON.stringify(
+					schema.identifier,
+				)}. Remove or rename them to avoid the collision.`,
+			);
+		}
+		return fromMap.toFlex;
+	}
+
+	const toFlex = () => {
+		let out: FlexTreeNodeSchema;
+		const kind = schema.kind;
+		switch (kind) {
+			case NodeKind.Leaf: {
+				const cached =
+					cachedFlexSchemaFromClassSchema(schema) ??
+					fail("leaf schema should be pre-cached");
+				assert(schemaIsLeaf(cached), 0x840 /* expected leaf */);
+				return cached;
+			}
+			case NodeKind.Map: {
+				const fieldInfo = schema.info as ImplicitAllowedTypes;
+				const field = FlexTreeFieldSchema.create(
+					FieldKinds.optional,
+					convertAllowedTypes(schemaMap, fieldInfo),
+				);
+				// Lookup of cached schema is done here instead of before since walking the schema recursively to populate schemaMap is still required.
+				const cached = cachedFlexSchemaFromClassSchema(schema);
+				out = cached ?? FlexMapNodeSchema.create(builder, brand(schema.identifier), field);
+				break;
+			}
+			case NodeKind.Array: {
+				const fieldInfo = schema.info as ImplicitAllowedTypes;
+				const field = FlexTreeFieldSchema.create(
+					FieldKinds.sequence,
+					convertAllowedTypes(schemaMap, fieldInfo),
+				);
+				const cached = cachedFlexSchemaFromClassSchema(schema);
+				out =
+					cached ?? FlexFieldNodeSchema.create(builder, brand(schema.identifier), field);
+				break;
+			}
+			case NodeKind.Object: {
+				const info = schema.info as Record<string, ImplicitFieldSchema>;
+				const fields: Record<string, FlexTreeFieldSchema> = Object.create(null);
+				for (const [key, value] of Object.entries(info)) {
+					// This code has to be careful to avoid assigning to __proto__ or similar built-in fields.
+					Object.defineProperty(fields, key, {
+						enumerable: true,
+						configurable: false,
+						writable: false,
+						value: convertField(schemaMap, value),
+					});
+				}
+				const cached = cachedFlexSchemaFromClassSchema(schema);
+				out =
+					cached ??
+					FlexObjectNodeSchema.create(builder, brand(schema.identifier), fields);
+				break;
+			}
+			default:
+				unreachableCase(kind);
+		}
+		assert(out instanceof FlexTreeNodeSchemaBase, 0x841 /* invalid schema produced */);
+		{
+			const cached = cachedFlexSchemaFromClassSchema(schema);
+			if (cached !== undefined) {
+				assert(
+					cachedFlexSchemaFromClassSchema(schema) === out,
+					0x842 /* incorrect flexSchemaSymbol */,
+				);
+			} else {
+				setFlexSchemaFromClassSchema(schema, out);
+			}
+		}
+		(out as any)[simpleSchemaSymbol] = schema;
+		return out;
+	};
+	schemaMap.set(brand(schema.identifier), { original: schema, toFlex });
+	return toFlex;
+}
+
+/**
+ * A symbol for storing FlexTreeSchema on TreeNodeSchema.
+ * Eagerly set on leaves, and lazily set for other cases.
+ */
+export const flexSchemaSymbol: unique symbol = Symbol(`flexSchema`);
+
+export function cachedFlexSchemaFromClassSchema(
+	schema: TreeNodeSchema,
+): FlexTreeNodeSchemaBase | undefined {
+	return (schema as any)[flexSchemaSymbol] as FlexTreeNodeSchemaBase | undefined;
+}
+
+export function setFlexSchemaFromClassSchema(
+	simple: TreeNodeSchema,
+	flex: FlexTreeNodeSchemaBase,
+): void {
+	(simple as any)[flexSchemaSymbol] = flex;
+}

package/src/class-tree/tree.ts

@@ -0,0 +1,123 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IChannel } from "@fluidframework/datastore-definitions";
+import { ISubscribable } from "../events";
+import { IDisposable, disposeSymbol } from "../util";
+import { FlexTreeView, type CheckoutEvents } from "../shared-tree";
+import { getProxyForField } from "../simple-tree";
+import { TreeFieldSchema as FlexTreeFieldSchema } from "../feature-libraries";
+import {
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	TreeFieldFromImplicitField,
+} from "./schemaTypes";
+
+/**
+ * Channel for a Fluid Tree DDS.
+ * @remarks
+ * Allows storing and collaboratively editing schema-aware hierarchial data.
+ * @beta
+ */
+export interface ITree extends IChannel {
+	/**
+	 * Returns a tree that is known to be compatible with the provided schema. The returned tree exposes an API that is schema-aware.
+	 *
+	 * @remarks
+	 * If the tree is uninitialized (has no schema and no content), the tree is initialized with the `initialTree` and
+	 * view `schema` in the provided `config`.
+	 *
+	 * The tree (now known to have been initialized) has its stored schema checked against the provided view schema.
+	 *
+	 * If the schemas are compatible (including updating the stored schema if permitted via `allowedSchemaModifications`),
+	 * a {@link TreeView} is returned, with a schema-aware API based on the provided view schema.
+	 *
+	 * If the schemas are not compatible, an exception is thrown.
+	 *
+	 * @privateRemarks
+	 * TODO: make the mismatch case recoverable.
+	 * - Provide a way to make a generic view schema for any document.
+	 * - Produce/throw the error in a document-recoverable way (ex: specific exception type or return value).
+	 * TODO: Document and handle what happens when the stored schema changes after schematize has returned. Is some invalidation contract needed? How does editable tree behave?
+	 * TODO: Clarify lifetimes. Ensure calling schematize multiple times does not leak.
+	 * TODO: Support adapters for handling out-of-schema data.
+	 *
+	 * Doing initialization here, regardless of `AllowedUpdateType`, allows a small API that is hard to use incorrectly.
+	 * Other approaches tend to have easy-to-make mistakes.
+	 * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,
+	 * or call it unconditionally leaving an app that can only create new documents.
+	 * It also would require the schema to be passed into separate places and could cause issues if they didn't match.
+	 * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.
+	 * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function
+	 * on the create code-path (for example how a schematized factory might do it),
+	 * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).
+	 * Additionally, once out of schema content adapters are properly supported (with lazy document updates),
+	 * this initialization could become just another out of schema content adapter: at that point it clearly belongs here in schematize.
+	 */
+	schematize<TRoot extends ImplicitFieldSchema>(
+		config: TreeConfiguration<TRoot>,
+	): TreeView<TreeFieldFromImplicitField<TRoot>>;
+}
+
+/**
+ * Configuration for how to {@link ITree.schematize|schematize} a tree.
+ * @beta
+ */
+export class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {
+	/**
+	 * @param schema - The schema which the application wants to view the tree with.
+	 * @param initialTree - A function that returns the default tree content to initialize the tree with iff the tree is uninitialized
+	 * (meaning it does not even have any schema set at all).
+	 * If `initialTree` returns any actual node instances, they should be recreated each time `initialTree` runs.
+	 * This is because if the config is used a second time any nodes that were not recreated could error since nodes cannot be inserted into the tree multiple times.
+	 */
+	public constructor(
+		public readonly schema: TSchema,
+		public readonly initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,
+	) {}
+}
+
+/**
+ * An editable view of a (version control style) branch of a shared tree.
+ * @privateRemarks
+ * This is a wrapper around ITreeView that adjusted it for the public package API.
+ * TODO:
+ * Establish a naming conversion between these internal and wrapper types.
+ * @beta
+ */
+export interface TreeView<in out TRoot> extends IDisposable {
+	/**
+	 * The current root of the tree.
+	 */
+	readonly root: TRoot;
+
+	/**
+	 * Events for the tree.
+	 */
+	readonly events: ISubscribable<CheckoutEvents>;
+}
+
+/**
+ * Implementation of TreeView wrapping a FlexTreeView.
+ */
+export class WrapperTreeView<
+	in out TSchema extends ImplicitFieldSchema,
+	TView extends FlexTreeView<FlexTreeFieldSchema>,
+> implements TreeView<TreeFieldFromImplicitField<TSchema>>
+{
+	public constructor(public readonly view: TView) {}
+
+	public [disposeSymbol](): void {
+		this.view[disposeSymbol]();
+	}
+
+	public get events(): ISubscribable<CheckoutEvents> {
+		return this.view.checkout.events;
+	}
+
+	public get root(): TreeFieldFromImplicitField<TSchema> {
+		return getProxyForField(this.view.editableTree) as TreeFieldFromImplicitField<TSchema>;
+	}
+}

package/src/class-tree/treeApi.ts

@@ -0,0 +1,147 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TreeValue } from "../core";
+import {
+	EditableTreeEvents,
+	LeafNodeSchema,
+	Multiplicity,
+	TreeStatus,
+	isTreeValue,
+	valueSchemaAllows,
+} from "../feature-libraries";
+import { TreeNode } from "../simple-tree";
+// eslint-disable-next-line import/no-internal-modules
+import { getFlexNode, tryGetFlexNode } from "../simple-tree/flexNode";
+// eslint-disable-next-line import/no-internal-modules
+import { getClassSchema, getOrCreateNodeProxy } from "../simple-tree/proxies";
+import { schemaFromValue } from "./schemaFactory";
+import { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from "./schemaTypes";
+import { getFlexSchema } from "./toFlexSchema";
+
+/**
+ * Provides various functions for analyzing {@link TreeNode}s.
+ *
+ * @privateRemarks
+ * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,
+ * which avoids typescript expanding the type of TreeNodeSchema and thus encountering
+ * https://github.com/microsoft/rushstack/issues/1958.
+ * @beta
+ */
+export interface TreeApi {
+	/**
+	 * The schema information for this node.
+	 */
+	schema<T extends TreeNode | TreeLeafValue>(
+		node: T,
+	): TreeNodeSchema<string, NodeKind, unknown, T>;
+	/**
+	 * Narrow the type of the given value if it satisfies the given schema.
+	 * @example
+	 * ```ts
+	 * if (node.is(myNode, point)) {
+	 *     const y = myNode.y; // `myNode` is now known to satisfy the `point` schema and therefore has a `y` coordinate.
+	 * }
+	 * ```
+	 */
+	is<TSchema extends TreeNodeSchema>(
+		value: unknown,
+		schema: TSchema,
+	): value is NodeFromSchema<TSchema>;
+	/**
+	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
+	 */
+	parent(node: TreeNode): TreeNode | undefined;
+	/**
+	 * The key of the given node under its parent.
+	 * @remarks
+	 * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the list (a `number`).
+	 * Otherwise, this returns the key of the field that it is under (a `string`).
+	 */
+	key(node: TreeNode): string | number;
+	/**
+	 * Register an event listener on the given node.
+	 * @returns A callback function which will deregister the event.
+	 * This callback should be called only once.
+	 */
+	on<K extends keyof TreeNodeEvents>(
+		node: TreeNode,
+		eventName: K,
+		listener: TreeNodeEvents[K],
+	): () => void;
+	/**
+	 * Returns the {@link TreeStatus} of the given node.
+	 */
+	readonly status: (node: TreeNode) => TreeStatus;
+}
+
+/**
+ * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
+ * @beta
+ */
+export const nodeApi: TreeApi = {
+	parent: (node: TreeNode) => {
+		const editNode = getFlexNode(node).parentField.parent.parent;
+		if (editNode !== undefined) {
+			return getOrCreateNodeProxy(editNode);
+		}
+
+		return undefined;
+	},
+	key: (node: TreeNode) => {
+		const parentField = getFlexNode(node).parentField;
+		if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
+			// The parent of `node` is a list
+			return parentField.index;
+		}
+
+		// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
+		return parentField.parent.key;
+	},
+	on: <K extends keyof EditableTreeEvents>(
+		node: TreeNode,
+		eventName: K,
+		listener: EditableTreeEvents[K],
+	) => {
+		return getFlexNode(node).on(eventName, listener);
+	},
+	status: (node: TreeNode) => {
+		return getFlexNode(node).treeStatus();
+	},
+	is: <TSchema extends TreeNodeSchema>(
+		value: unknown,
+		schema: TSchema,
+	): value is NodeFromSchema<TSchema> => {
+		const flexSchema = getFlexSchema(schema);
+		if (isTreeValue(value)) {
+			return (
+				flexSchema instanceof LeafNodeSchema && valueSchemaAllows(flexSchema.info, value)
+			);
+		}
+		return tryGetFlexNode(value)?.is(flexSchema) ?? false;
+	},
+	schema<T extends TreeNode | TreeValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T> {
+		if (isTreeValue(node)) {
+			return schemaFromValue(node) as TreeNodeSchema<string, NodeKind, unknown, T>;
+		}
+		return getClassSchema(getFlexNode(node).schema) as TreeNodeSchema<
+			string,
+			NodeKind,
+			unknown,
+			T
+		>;
+	},
+};
+
+/**
+ * A collection of events that can be raised by a {@link TreeNode}.
+ * @beta
+ */
+export interface TreeNodeEvents {
+	/**
+	 * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.
+	 */
+	afterChange(): void;
+}

package/src/codec/README.md

@@ -0,0 +1,15 @@
+# Codec
+
+This library defines types and constructs for organizing code that works with persisted data.
+Its fundamental building block is a codec--a bit of code capable of transcoding between a stable format used for persistence and a potentially less stable format only used in memory.
+Typically, for compatibility reasons, aspects of `SharedTree` should work with `ICodecFamily`s (which can do the above for multiple supported formats).
+
+## JSON Validators
+
+Codecs can define draft 6 JSON schema for their encoded data.
+
+One policy choice is whether or not encoded data should be validated, and if so, how.
+Since some `SharedTree` users might not want to pay the bundle-size cost to perform this validation in all environments,
+this policy is injectable using `ICodecOptions` by providing a `JsonValidator`.
+
+This package exports and runs encoding tests using `typeboxValidator`, but any JSON schema draft 6-compliant schema validator can be used.