@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/core/tree/treeTextFormat.ts

@@ -0,0 +1,179 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FieldKey } from "../schema-stored";
+import { NodeData } from "./types";
+
+/**
+ * This modules provides a simple human readable (and editable) tree format.
+ *
+ * This implementation can handle all trees (so it does not need a fallback for any special cases),
+ * and is not optimized.
+ *
+ * It's suitable for testing and debugging,
+ * though it could also reasonably be used as a fallback for edge cases or for small trees.
+ *
+ * The serialized format is valid utf-8, and also includes a json compatible intermediate in memory format.
+ *
+ * This format is currently not stable: its internal contents are not considered public APIs and may change.
+ * There is currently no guarantee that data serialized with this library will
+ * be loadable with a different version of this library.
+ *
+ * TODO: stabilize this format (probably after schema are more stable).
+ *
+ * This format does not include schema: typically schema would be stored alongside data in this format.
+ *
+ * @privateRemarks A forked version of these types is available at `persistedTreeTextFormat.ts`.
+ * Changes to them might necessitate changes to the analogous forked types, or codecs which transcode between
+ * them.
+ * See persistedTreeTextFormat's module documentation for more details.
+ */
+
+/**
+ * Json compatible map as object.
+ * Keys are FieldKey strings.
+ * Values are the content of the field specified by the key.
+ *
+ * WARNING:
+ * Be very careful when using objects as maps:
+ * Use `Object.prototype.hasOwnProperty.call(fieldMap, key)` to safely check for keys.
+ * Do NOT simply read the field and check for undefined as this will return values for `__proto__`
+ * and various methods on Object.prototype, like `hasOwnProperty` and `toString`.
+ * This exposes numerous bug possibilities, including prototype pollution.
+ *
+ * Due to the above issue, try to avoid this type (and the whole object as map pattern).
+ * Only use this type when needed for json compatible maps,
+ * but even in those cases consider lists of key value pairs for serialization and using `Map`
+ * for runtime.
+ *
+ * @internal
+ */
+export interface FieldMapObject<TChild> {
+	[key: string]: TChild[];
+}
+
+/**
+ * Json comparable tree node, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ * @internal
+ */
+export interface GenericTreeNode<TChild> extends GenericFieldsNode<TChild>, NodeData {}
+
+/**
+ * Json comparable field collection, generic over child type.
+ * Json compatibility assumes `TChild` is also json compatible.
+ * @internal
+ */
+export interface GenericFieldsNode<TChild> {
+	fields?: FieldMapObject<TChild>;
+}
+
+/**
+ * A tree represented using plain JavaScript objects.
+ * Can be passed to `JSON.stringify()` to produce a human-readable/editable JSON tree.
+ *
+ * JsonableTrees should not store empty fields.
+ * @internal
+ */
+export interface JsonableTree extends GenericTreeNode<JsonableTree> {}
+
+/**
+ * Get a field from `node`, optionally modifying the tree to create it if missing.
+ */
+export function getGenericTreeField<T>(
+	node: GenericFieldsNode<T>,
+	key: FieldKey,
+	createIfMissing: boolean,
+): T[] {
+	const children = getGenericTreeFieldMap(node, createIfMissing);
+
+	// Do not just read field and check for undefined: see warning on FieldMapObject.
+	if (Object.prototype.hasOwnProperty.call(children, key)) {
+		return children[key];
+	}
+	// Handle missing field:
+	if (createIfMissing === false) {
+		return [];
+	}
+	const newField: T[] = [];
+	children[key] = newField;
+	return newField;
+}
+
+/**
+ * Get a FieldMap from `node`, optionally modifying the tree to create it if missing.
+ */
+function getGenericTreeFieldMap<T>(
+	node: GenericFieldsNode<T>,
+	createIfMissing: boolean,
+): FieldMapObject<T> {
+	let children = node.fields;
+	if (children === undefined) {
+		children = {};
+		// Handle missing fields:
+		if (createIfMissing) {
+			node.fields = children;
+		}
+	}
+
+	return children;
+}
+
+/**
+ * Sets a field on `node`.
+ */
+export function setGenericTreeField<T>(
+	node: GenericFieldsNode<T>,
+	key: FieldKey,
+	content: T[],
+): void {
+	const children = getGenericTreeFieldMap(node, true);
+	// like `children[keyString] = content;` except safe when keyString == "__proto__".
+	Object.defineProperty(children, key, {
+		enumerable: true,
+		configurable: true,
+		writable: true,
+		value: content,
+	});
+}
+
+/**
+ * @returns keys for fields of `tree`.
+ */
+export function genericTreeKeys<T>(tree: GenericFieldsNode<T>): readonly FieldKey[] {
+	const fields = tree.fields;
+	// This function is used when iterating through a tree.
+	// This means that this is often called on nodes with no keys
+	// (most trees are a large portion leaf nodes).
+	// Therefore this function special cases empty fields objects as an optimization.
+	if (fields === undefined) {
+		return [];
+	}
+
+	return Object.keys(fields) as FieldKey[];
+}
+
+/**
+ * Delete a field if empty.
+ * Optionally delete FieldMapObject if empty as well.
+ */
+export function genericTreeDeleteIfEmpty<T>(
+	node: GenericFieldsNode<T>,
+	key: FieldKey,
+	removeMapObject: boolean,
+): void {
+	const children = getGenericTreeFieldMap(node, false);
+	if (Object.prototype.hasOwnProperty.call(children, key)) {
+		if (children[key].length === 0) {
+			// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+			delete children[key];
+			if (removeMapObject) {
+				if (Object.keys(children).length === 0) {
+					delete node.fields;
+				}
+			}
+		}
+	}
+}

package/src/core/tree/types.ts

@@ -0,0 +1,170 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IFluidHandle } from "@fluidframework/core-interfaces";
+import { FieldKey, TreeNodeSchemaIdentifier, ValueSchema } from "../schema-stored";
+import { _InlineTrick, brand, Brand, extractFromOpaque, Opaque } from "../../util";
+
+/**
+ * @internal
+ */
+export type TreeType = TreeNodeSchemaIdentifier;
+
+/**
+ * The empty key ("") is used for unnamed relationships, such as the indexer
+ * of an explicit array node.
+ *
+ * This key is a hint that this field is the primary function of the node,
+ * and in some abstractions the APIs for this field should be inlined onto the node.
+ *
+ * TODO:
+ * This has to be a FieldKey since different nodes will have different TreeFieldStoredSchema for it.
+ * This makes it prone to collisions and suggests
+ * that this intention may be better conveyed by metadata on the ITreeSchema.
+ * @internal
+ */
+export const EmptyKey: FieldKey = brand("");
+
+/**
+ * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.
+ * TODO: if we do want to standardize on a single value for this,
+ * it likely should be namespaced or a UUID to avoid risk of collisions.
+ * @internal
+ */
+export const rootFieldKey: FieldKey = brand("rootFieldKey");
+
+/**
+ * @internal
+ */
+export const rootField = keyAsDetachedField(rootFieldKey);
+
+/**
+ * Location of a tree relative to is parent container (which can be a tree or forest).
+ *
+ * @internal
+ */
+export interface ChildLocation {
+	readonly container: ChildCollection;
+	readonly index: number;
+}
+
+/**
+ * Wrapper around DetachedField that can be detected at runtime.
+ * @internal
+ */
+export interface RootField {
+	readonly key: DetachedField;
+}
+
+/**
+ * Identifier for a child collection, either on a node/tree or at the root of a forest.
+ * @internal
+ */
+export type ChildCollection = FieldKey | RootField;
+
+// TODO: its not clear how much DetachedField belongs here in tree,
+// but for now as its needed in Rebase and Forest,
+// it makes sense to have it here for reasoning about the roots of trees.
+/**
+ * A root in the forest.
+ *
+ * The range is a "container" like a field:
+ * any additional content inserted before or after contents of this range will be included in the range.
+ * This also means that moving the content from this range elsewhere will leave this range valid, but empty.
+ *
+ * In some APIs DetachedFields are used as FieldKeys on a special implicit root node
+ * to simplify the APIs and implementation.
+ * @internal
+ */
+export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField">> {}
+
+/**
+ * Some code abstracts the root as a node with detached fields as its fields.
+ * This maps detached field to field keys for thus use.
+ *
+ * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.
+ * @internal
+ */
+export function detachedFieldAsKey(field: DetachedField): FieldKey {
+	return brand(extractFromOpaque(field));
+}
+
+/**
+ * The inverse of {@link detachedFieldAsKey}.
+ * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},
+ * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.
+ * @internal
+ */
+export function keyAsDetachedField(key: FieldKey): DetachedField {
+	return brand(key);
+}
+
+/**
+ * TODO: integrate this into Schema. Decide how to persist them (need stable Id?). Maybe allow updating field kinds?.
+ * TODO: make families of changes per field kind. Build editing APIs from that.
+ * TODO: factor ChangeRebaser implementations to support adding new field kinds.
+ * @internal
+ */
+export interface FieldKind {
+	readonly name: string;
+	readonly description: string;
+	readonly minimumChildren: number;
+	readonly maximumChildren: number;
+}
+
+/**
+ * Value that may be stored on a leaf node.
+ * @internal
+ */
+export type TreeValue<TSchema extends ValueSchema = ValueSchema> = [
+	{
+		[ValueSchema.Number]: number;
+		[ValueSchema.String]: string;
+		[ValueSchema.Boolean]: boolean;
+		[ValueSchema.FluidHandle]: IFluidHandle;
+		// eslint-disable-next-line @rushstack/no-new-null
+		[ValueSchema.Null]: null;
+	}[TSchema],
+][_InlineTrick];
+
+/**
+ * Value stored on a node.
+ * @internal
+ */
+export type Value = undefined | TreeValue;
+
+/**
+ * The fields required by a node in a tree.
+ *
+ * @privateRemarks A forked version of this type is used in `persistedTreeTextFormat.ts`.
+ * Changes to this type might necessitate changes to `EncodedNodeData` or codecs.
+ * See persistedTreeTextFormat's module documentation for more details.
+ *
+ * @internal
+ */
+export interface NodeData {
+	/**
+	 * A payload of arbitrary serializable data.
+	 *
+	 * TODO: clarify rules for mutating this value.
+	 * For now, avoid mutating the TreeValue itself.
+	 * For example, if its an object, make a modified copy of the object instead of mutating it.
+	 */
+	value?: TreeValue;
+
+	/**
+	 * The meaning of this node.
+	 * Provides contexts/semantics for this node and its content.
+	 * Typically used to associate a node with metadata (including a schema) and source code (types, behaviors, etc).
+	 */
+	readonly type: TreeNodeSchemaIdentifier;
+}
+
+/**
+ * Use this type to indicate that a node sits above the detached fields, and thus is not a real node and who's type should not matter.
+ */
+export const aboveRootPlaceholder: TreeNodeSchemaIdentifier = brand(
+	"com.fluidframework.placeholder.aboveRoot",
+);