@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/class-tree/toFlexSchema.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setFlexSchemaFromClassSchema = exports.cachedFlexSchemaFromClassSchema = exports.flexSchemaSymbol = exports.convertNodeSchema = exports.convertAllowedTypes = exports.convertField = exports.getFlexSchema = exports.toFlexSchema = exports.toFlexConfig = exports.cursorFromUnhydratedRoot = void 0;
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-internal-modules */
+const core_utils_1 = require("@fluidframework/core-utils");
+const feature_libraries_1 = require("../feature-libraries");
+const util_1 = require("../util");
+const flexList_1 = require("../feature-libraries/typed-schema/flexList");
+const proxies_1 = require("../simple-tree/proxies");
+const core_1 = require("../core");
+const toMapTree_1 = require("../simple-tree/toMapTree");
+const schemaTypes_1 = require("./schemaTypes");
+/**
+ * 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.
+ */
+function cursorFromUnhydratedRoot(schema, tree) {
+    const data = (0, proxies_1.extractFactoryContent)(tree);
+    return ((0, toMapTree_1.cursorFromNodeData)(data.content, schema, schema.rootFieldSchema.allowedTypeSet) ??
+        (0, util_1.fail)("failed to decode tree"));
+}
+exports.cursorFromUnhydratedRoot = cursorFromUnhydratedRoot;
+function toFlexConfig(config) {
+    const schema = toFlexSchema(config.schema);
+    const unhydrated = config.initialTree();
+    const initialTree = unhydrated === undefined ? undefined : [cursorFromUnhydratedRoot(schema, unhydrated)];
+    return {
+        allowedSchemaModifications: core_1.AllowedUpdateType.None,
+        schema,
+        initialTree,
+    };
+}
+exports.toFlexConfig = toFlexConfig;
+/**
+ * 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.
+ */
+function toFlexSchema(root) {
+    const schemaMap = new Map();
+    const field = convertField(schemaMap, root);
+    const nodeSchema = new Map((0, util_1.mapIterable)(schemaMap, ([key, value]) => {
+        const schema = value.toFlex();
+        const classSchema = (0, proxies_1.getClassSchema)(schema);
+        if (classSchema === undefined) {
+            (0, core_utils_1.assert)((0, feature_libraries_1.schemaIsLeaf)(schema), 0x83e /* invalid leaf */);
+        }
+        else {
+            (0, core_utils_1.assert)(cachedFlexSchemaFromClassSchema(classSchema) === schema, 0x83f /* mismatched schema */);
+        }
+        return [key, schema];
+    }));
+    const typed = {
+        nodeSchema,
+        adapters: {},
+        rootFieldSchema: field,
+        policy: feature_libraries_1.defaultSchemaPolicy,
+    };
+    return typed;
+}
+exports.toFlexSchema = toFlexSchema;
+/**
+ * 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.
+ */
+function getFlexSchema(root) {
+    const treeSchema = toFlexSchema(root);
+    return treeSchema.rootFieldSchema.monomorphicChildType ?? (0, util_1.fail)("root should be monomorphic");
+}
+exports.getFlexSchema = getFlexSchema;
+/**
+ * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
+ */
+function convertField(schemaMap, schema) {
+    let kind;
+    let types;
+    if (schema instanceof schemaTypes_1.FieldSchema) {
+        kind = convertFieldKind.get(schema.kind) ?? (0, util_1.fail)("Invalid field kind");
+        types = schema.allowedTypes;
+    }
+    else {
+        kind = feature_libraries_1.FieldKinds.required;
+        types = schema;
+    }
+    const allowedTypes = convertAllowedTypes(schemaMap, types);
+    return feature_libraries_1.TreeFieldSchema.create(kind, allowedTypes);
+}
+exports.convertField = convertField;
+const convertFieldKind = new Map([
+    [schemaTypes_1.FieldKind.Optional, feature_libraries_1.FieldKinds.optional],
+    [schemaTypes_1.FieldKind.Required, feature_libraries_1.FieldKinds.required],
+]);
+/**
+ * Normalizes an {@link ImplicitAllowedTypes} into an {@link AllowedTypes}.
+ */
+function convertAllowedTypes(schemaMap, schema) {
+    if ((0, util_1.isReadonlyArray)(schema)) {
+        return (0, flexList_1.normalizeFlexListEager)(schema).map((item) => convertNodeSchema(schemaMap, item));
+    }
+    return [convertNodeSchema(schemaMap, schema)];
+}
+exports.convertAllowedTypes = convertAllowedTypes;
+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.
+ */
+function convertNodeSchema(schemaMap, schema) {
+    const fromMap = schemaMap.get((0, util_1.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;
+        const kind = schema.kind;
+        switch (kind) {
+            case schemaTypes_1.NodeKind.Leaf: {
+                const cached = cachedFlexSchemaFromClassSchema(schema) ??
+                    (0, util_1.fail)("leaf schema should be pre-cached");
+                (0, core_utils_1.assert)((0, feature_libraries_1.schemaIsLeaf)(cached), 0x840 /* expected leaf */);
+                return cached;
+            }
+            case schemaTypes_1.NodeKind.Map: {
+                const fieldInfo = schema.info;
+                const field = feature_libraries_1.TreeFieldSchema.create(feature_libraries_1.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 ?? feature_libraries_1.MapNodeSchema.create(builder, (0, util_1.brand)(schema.identifier), field);
+                break;
+            }
+            case schemaTypes_1.NodeKind.Array: {
+                const fieldInfo = schema.info;
+                const field = feature_libraries_1.TreeFieldSchema.create(feature_libraries_1.FieldKinds.sequence, convertAllowedTypes(schemaMap, fieldInfo));
+                const cached = cachedFlexSchemaFromClassSchema(schema);
+                out =
+                    cached ?? feature_libraries_1.FieldNodeSchema.create(builder, (0, util_1.brand)(schema.identifier), field);
+                break;
+            }
+            case schemaTypes_1.NodeKind.Object: {
+                const info = schema.info;
+                const fields = 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 ??
+                        feature_libraries_1.ObjectNodeSchema.create(builder, (0, util_1.brand)(schema.identifier), fields);
+                break;
+            }
+            default:
+                (0, core_utils_1.unreachableCase)(kind);
+        }
+        (0, core_utils_1.assert)(out instanceof feature_libraries_1.TreeNodeSchemaBase, 0x841 /* invalid schema produced */);
+        {
+            const cached = cachedFlexSchemaFromClassSchema(schema);
+            if (cached !== undefined) {
+                (0, core_utils_1.assert)(cachedFlexSchemaFromClassSchema(schema) === out, 0x842 /* incorrect flexSchemaSymbol */);
+            }
+            else {
+                setFlexSchemaFromClassSchema(schema, out);
+            }
+        }
+        out[proxies_1.simpleSchemaSymbol] = schema;
+        return out;
+    };
+    schemaMap.set((0, util_1.brand)(schema.identifier), { original: schema, toFlex });
+    return toFlex;
+}
+exports.convertNodeSchema = convertNodeSchema;
+/**
+ * A symbol for storing FlexTreeSchema on TreeNodeSchema.
+ * Eagerly set on leaves, and lazily set for other cases.
+ */
+exports.flexSchemaSymbol = Symbol(`flexSchema`);
+function cachedFlexSchemaFromClassSchema(schema) {
+    return schema[exports.flexSchemaSymbol];
+}
+exports.cachedFlexSchemaFromClassSchema = cachedFlexSchemaFromClassSchema;
+function setFlexSchemaFromClassSchema(simple, flex) {
+    simple[exports.flexSchemaSymbol] = flex;
+}
+exports.setFlexSchemaFromClassSchema = setFlexSchemaFromClassSchema;
+//# sourceMappingURL=toFlexSchema.js.map

package/dist/class-tree/toFlexSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFlexSchema.js","sourceRoot":"","sources":["../../src/class-tree/toFlexSchema.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n/* eslint-disable import/no-internal-modules */\nimport { assert, unreachableCase } from \"@fluidframework/core-utils\";\nimport {\n\tFlexTreeSchema,\n\tTreeFieldSchema as FlexTreeFieldSchema,\n\tFieldKind as FlexFieldKind,\n\tFieldKinds,\n\tAllowedTypes as FlexAllowedTypes,\n\tTreeNodeSchemaBase as FlexTreeNodeSchemaBase,\n\tTreeNodeSchema as FlexTreeNodeSchema,\n\tdefaultSchemaPolicy,\n\tMapNodeSchema as FlexMapNodeSchema,\n\tFieldNodeSchema as FlexFieldNodeSchema,\n\tObjectNodeSchema as FlexObjectNodeSchema,\n\tschemaIsLeaf,\n} from \"../feature-libraries\";\nimport { brand, fail, isReadonlyArray, mapIterable } from \"../util\";\nimport { normalizeFlexListEager } from \"../feature-libraries/typed-schema/flexList\";\nimport {\n\tInsertableContent,\n\textractFactoryContent,\n\tgetClassSchema,\n\tsimpleSchemaSymbol,\n} from \"../simple-tree/proxies\";\nimport { AllowedUpdateType, ITreeCursorSynchronous, TreeNodeSchemaIdentifier } from \"../core\";\nimport { type InitializeAndSchematizeConfiguration } from \"../shared-tree\";\nimport { cursorFromNodeData } from \"../simple-tree/toMapTree\";\nimport {\n\tFieldKind,\n\tFieldSchema,\n\tImplicitAllowedTypes,\n\tImplicitFieldSchema,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n\tNodeKind,\n\tTreeNodeSchema,\n} from \"./schemaTypes\";\nimport { TreeConfiguration } from \"./tree\";\n\n/**\n * Returns a cursor (in nodes mode) for the root node.\n *\n * @privateRemarks\n * Ideally this would work on any node, not just the root,\n * and the schema would come from the unhydrated node.\n * 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.\n */\nexport function cursorFromUnhydratedRoot(\n\tschema: FlexTreeSchema,\n\ttree: InsertableTreeNodeFromImplicitAllowedTypes,\n): ITreeCursorSynchronous {\n\tconst data = extractFactoryContent(tree as InsertableContent);\n\treturn (\n\t\tcursorFromNodeData(data.content, schema, schema.rootFieldSchema.allowedTypeSet) ??\n\t\tfail(\"failed to decode tree\")\n\t);\n}\n\nexport function toFlexConfig(config: TreeConfiguration): InitializeAndSchematizeConfiguration {\n\tconst schema = toFlexSchema(config.schema);\n\tconst unhydrated = config.initialTree();\n\tconst initialTree =\n\t\tunhydrated === undefined ? undefined : [cursorFromUnhydratedRoot(schema, unhydrated)];\n\treturn {\n\t\tallowedSchemaModifications: AllowedUpdateType.None,\n\t\tschema,\n\t\tinitialTree,\n\t};\n}\n\ninterface SchemaInfo {\n\ttoFlex: () => FlexTreeNodeSchema;\n\toriginal: TreeNodeSchema;\n}\n\ntype SchemaMap = Map<TreeNodeSchemaIdentifier, SchemaInfo>;\n\n/**\n * Generate a {@link FlexTreeSchema} with `root` as the root field.\n *\n * This also has the side effect of populating the cached view schema on the class based schema.\n */\nexport function toFlexSchema(root: ImplicitFieldSchema): FlexTreeSchema {\n\tconst schemaMap: SchemaMap = new Map();\n\tconst field = convertField(schemaMap, root);\n\tconst nodeSchema = new Map(\n\t\tmapIterable(schemaMap, ([key, value]) => {\n\t\t\tconst schema = value.toFlex();\n\t\t\tconst classSchema = getClassSchema(schema);\n\t\t\tif (classSchema === undefined) {\n\t\t\t\tassert(schemaIsLeaf(schema), 0x83e /* invalid leaf */);\n\t\t\t} else {\n\t\t\t\tassert(\n\t\t\t\t\tcachedFlexSchemaFromClassSchema(classSchema) === schema,\n\t\t\t\t\t0x83f /* mismatched schema */,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn [key, schema];\n\t\t}),\n\t);\n\n\tconst typed: FlexTreeSchema = {\n\t\tnodeSchema,\n\t\tadapters: {},\n\t\trootFieldSchema: field,\n\t\tpolicy: defaultSchemaPolicy,\n\t};\n\treturn typed;\n}\n\n/**\n * Return a flex schema for the provided class schema.\n *\n * This also has the side effect of populating the cached view schema on the class based schema.\n */\nexport function getFlexSchema(root: TreeNodeSchema): FlexTreeNodeSchema {\n\tconst treeSchema = toFlexSchema(root);\n\treturn treeSchema.rootFieldSchema.monomorphicChildType ?? fail(\"root should be monomorphic\");\n}\n\n/**\n * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.\n */\nexport function convertField(\n\tschemaMap: SchemaMap,\n\tschema: ImplicitFieldSchema,\n): FlexTreeFieldSchema {\n\tlet kind: FlexFieldKind;\n\tlet types: ImplicitAllowedTypes;\n\tif (schema instanceof FieldSchema) {\n\t\tkind = convertFieldKind.get(schema.kind) ?? fail(\"Invalid field kind\");\n\t\ttypes = schema.allowedTypes;\n\t} else {\n\t\tkind = FieldKinds.required;\n\t\ttypes = schema;\n\t}\n\tconst allowedTypes = convertAllowedTypes(schemaMap, types);\n\treturn FlexTreeFieldSchema.create(kind, allowedTypes);\n}\n\nconst convertFieldKind = new Map<FieldKind, FlexFieldKind>([\n\t[FieldKind.Optional, FieldKinds.optional],\n\t[FieldKind.Required, FieldKinds.required],\n]);\n\n/**\n * Normalizes an {@link ImplicitAllowedTypes} into an {@link AllowedTypes}.\n */\nexport function convertAllowedTypes(\n\tschemaMap: SchemaMap,\n\tschema: ImplicitAllowedTypes,\n): FlexAllowedTypes {\n\tif (isReadonlyArray(schema)) {\n\t\treturn normalizeFlexListEager(schema).map((item) => convertNodeSchema(schemaMap, item));\n\t}\n\treturn [convertNodeSchema(schemaMap, schema)];\n}\n\nconst builder = { name: \"simple schema\" };\n\n/**\n * Converts a {@link TreeNodeSchema} into a {@link FlexTreeNodeSchema}.\n * Ensures all types reachable from `schema` are included in `schemaMap`.\n *\n * Return value (and entries in map) are lazy to allow recursive types to work.\n * This laziness does NOT extend to adding entries to `schemaMap`:\n * all referenced types are added to it before this function returns.\n */\nexport function convertNodeSchema(\n\tschemaMap: SchemaMap,\n\tschema: TreeNodeSchema,\n): () => FlexTreeNodeSchema {\n\tconst fromMap = schemaMap.get(brand(schema.identifier));\n\tif (fromMap !== undefined) {\n\t\tif (fromMap.original !== schema) {\n\t\t\t// Use JSON.stringify to quote and escape string.\n\t\t\tthrow new Error(\n\t\t\t\t`Multiple schema encountered with the identifier ${JSON.stringify(\n\t\t\t\t\tschema.identifier,\n\t\t\t\t)}. Remove or rename them to avoid the collision.`,\n\t\t\t);\n\t\t}\n\t\treturn fromMap.toFlex;\n\t}\n\n\tconst toFlex = () => {\n\t\tlet out: FlexTreeNodeSchema;\n\t\tconst kind = schema.kind;\n\t\tswitch (kind) {\n\t\t\tcase NodeKind.Leaf: {\n\t\t\t\tconst cached =\n\t\t\t\t\tcachedFlexSchemaFromClassSchema(schema) ??\n\t\t\t\t\tfail(\"leaf schema should be pre-cached\");\n\t\t\t\tassert(schemaIsLeaf(cached), 0x840 /* expected leaf */);\n\t\t\t\treturn cached;\n\t\t\t}\n\t\t\tcase NodeKind.Map: {\n\t\t\t\tconst fieldInfo = schema.info as ImplicitAllowedTypes;\n\t\t\t\tconst field = FlexTreeFieldSchema.create(\n\t\t\t\t\tFieldKinds.optional,\n\t\t\t\t\tconvertAllowedTypes(schemaMap, fieldInfo),\n\t\t\t\t);\n\t\t\t\t// Lookup of cached schema is done here instead of before since walking the schema recursively to populate schemaMap is still required.\n\t\t\t\tconst cached = cachedFlexSchemaFromClassSchema(schema);\n\t\t\t\tout = cached ?? FlexMapNodeSchema.create(builder, brand(schema.identifier), field);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase NodeKind.Array: {\n\t\t\t\tconst fieldInfo = schema.info as ImplicitAllowedTypes;\n\t\t\t\tconst field = FlexTreeFieldSchema.create(\n\t\t\t\t\tFieldKinds.sequence,\n\t\t\t\t\tconvertAllowedTypes(schemaMap, fieldInfo),\n\t\t\t\t);\n\t\t\t\tconst cached = cachedFlexSchemaFromClassSchema(schema);\n\t\t\t\tout =\n\t\t\t\t\tcached ?? FlexFieldNodeSchema.create(builder, brand(schema.identifier), field);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase NodeKind.Object: {\n\t\t\t\tconst info = schema.info as Record<string, ImplicitFieldSchema>;\n\t\t\t\tconst fields: Record<string, FlexTreeFieldSchema> = Object.create(null);\n\t\t\t\tfor (const [key, value] of Object.entries(info)) {\n\t\t\t\t\t// This code has to be careful to avoid assigning to __proto__ or similar built-in fields.\n\t\t\t\t\tObject.defineProperty(fields, key, {\n\t\t\t\t\t\tenumerable: true,\n\t\t\t\t\t\tconfigurable: false,\n\t\t\t\t\t\twritable: false,\n\t\t\t\t\t\tvalue: convertField(schemaMap, value),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst cached = cachedFlexSchemaFromClassSchema(schema);\n\t\t\t\tout =\n\t\t\t\t\tcached ??\n\t\t\t\t\tFlexObjectNodeSchema.create(builder, brand(schema.identifier), fields);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\tunreachableCase(kind);\n\t\t}\n\t\tassert(out instanceof FlexTreeNodeSchemaBase, 0x841 /* invalid schema produced */);\n\t\t{\n\t\t\tconst cached = cachedFlexSchemaFromClassSchema(schema);\n\t\t\tif (cached !== undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tcachedFlexSchemaFromClassSchema(schema) === out,\n\t\t\t\t\t0x842 /* incorrect flexSchemaSymbol */,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tsetFlexSchemaFromClassSchema(schema, out);\n\t\t\t}\n\t\t}\n\t\t(out as any)[simpleSchemaSymbol] = schema;\n\t\treturn out;\n\t};\n\tschemaMap.set(brand(schema.identifier), { original: schema, toFlex });\n\treturn toFlex;\n}\n\n/**\n * A symbol for storing FlexTreeSchema on TreeNodeSchema.\n * Eagerly set on leaves, and lazily set for other cases.\n */\nexport const flexSchemaSymbol: unique symbol = Symbol(`flexSchema`);\n\nexport function cachedFlexSchemaFromClassSchema(\n\tschema: TreeNodeSchema,\n): FlexTreeNodeSchemaBase | undefined {\n\treturn (schema as any)[flexSchemaSymbol] as FlexTreeNodeSchemaBase | undefined;\n}\n\nexport function setFlexSchemaFromClassSchema(\n\tsimple: TreeNodeSchema,\n\tflex: FlexTreeNodeSchemaBase,\n): void {\n\t(simple as any)[flexSchemaSymbol] = flex;\n}\n"]}

package/dist/class-tree/tree.d.ts

@@ -0,0 +1,98 @@
+/*!
+ * 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 { 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 declare class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {
+    readonly schema: TSchema;
+    readonly initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>;
+    /**
+     * @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.
+     */
+    constructor(schema: TSchema, 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 declare class WrapperTreeView<in out TSchema extends ImplicitFieldSchema, TView extends FlexTreeView<FlexTreeFieldSchema>> implements TreeView<TreeFieldFromImplicitField<TSchema>> {
+    readonly view: TView;
+    constructor(view: TView);
+    [disposeSymbol](): void;
+    get events(): ISubscribable<CheckoutEvents>;
+    get root(): TreeFieldFromImplicitField<TSchema>;
+}
+//# sourceMappingURL=tree.d.ts.map

package/dist/class-tree/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/class-tree/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,eAAe,IAAI,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EACN,mBAAmB,EACnB,oCAAoC,EACpC,0BAA0B,EAC1B,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,KAAM,SAAQ,QAAQ;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,UAAU,CAAC,KAAK,SAAS,mBAAmB,EAC3C,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC9B,QAAQ,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB;aAStE,MAAM,EAAE,OAAO;aACf,WAAW,EAAE,MAAM,oCAAoC,CAAC,OAAO,CAAC;IATjF;;;;;;OAMG;gBAEc,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,oCAAoC,CAAC,OAAO,CAAC;CAEjF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAE,SAAQ,WAAW;IAC1D;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,qBAAa,eAAe,CAC3B,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,EAC1C,KAAK,SAAS,YAAY,CAAC,mBAAmB,CAAC,CAC9C,YAAW,QAAQ,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC;aAEtB,IAAI,EAAE,KAAK;gBAAX,IAAI,EAAE,KAAK;IAEvC,CAAC,aAAa,CAAC,IAAI,IAAI;IAI9B,IAAW,MAAM,IAAI,aAAa,CAAC,cAAc,CAAC,CAEjD;IAED,IAAW,IAAI,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAErD;CACD"}

package/dist/class-tree/tree.js

@@ -0,0 +1,46 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrapperTreeView = exports.TreeConfiguration = void 0;
+const util_1 = require("../util");
+const simple_tree_1 = require("../simple-tree");
+/**
+ * Configuration for how to {@link ITree.schematize|schematize} a tree.
+ * @beta
+ */
+class TreeConfiguration {
+    /**
+     * @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.
+     */
+    constructor(schema, initialTree) {
+        this.schema = schema;
+        this.initialTree = initialTree;
+    }
+}
+exports.TreeConfiguration = TreeConfiguration;
+/**
+ * Implementation of TreeView wrapping a FlexTreeView.
+ */
+class WrapperTreeView {
+    constructor(view) {
+        this.view = view;
+    }
+    [util_1.disposeSymbol]() {
+        this.view[util_1.disposeSymbol]();
+    }
+    get events() {
+        return this.view.checkout.events;
+    }
+    get root() {
+        return (0, simple_tree_1.getProxyForField)(this.view.editableTree);
+    }
+}
+exports.WrapperTreeView = WrapperTreeView;
+//# sourceMappingURL=tree.js.map

package/dist/class-tree/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/class-tree/tree.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH,kCAAqD;AAErD,gDAAkD;AAsDlD;;;GAGG;AACH,MAAa,iBAAiB;IAC7B;;;;;;OAMG;IACH,YACiB,MAAe,EACf,WAAgE;QADhE,WAAM,GAAN,MAAM,CAAS;QACf,gBAAW,GAAX,WAAW,CAAqD;IAC9E,CAAC;CACJ;AAZD,8CAYC;AAsBD;;GAEG;AACH,MAAa,eAAe;IAK3B,YAAmC,IAAW;QAAX,SAAI,GAAJ,IAAI,CAAO;IAAG,CAAC;IAE3C,CAAC,oBAAa,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,oBAAa,CAAC,EAAE,CAAC;IAC5B,CAAC;IAED,IAAW,MAAM;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAClC,CAAC;IAED,IAAW,IAAI;QACd,OAAO,IAAA,8BAAgB,EAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAwC,CAAC;IACxF,CAAC;CACD;AAlBD,0CAkBC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IChannel } from \"@fluidframework/datastore-definitions\";\nimport { ISubscribable } from \"../events\";\nimport { IDisposable, disposeSymbol } from \"../util\";\nimport { FlexTreeView, type CheckoutEvents } from \"../shared-tree\";\nimport { getProxyForField } from \"../simple-tree\";\nimport { TreeFieldSchema as FlexTreeFieldSchema } from \"../feature-libraries\";\nimport {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"./schemaTypes\";\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @beta\n */\nexport interface ITree extends IChannel {\n\t/**\n\t * Returns a tree that is known to be compatible with the provided schema. The returned tree exposes an API that is schema-aware.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), the tree is initialized with the `initialTree` and\n\t * view `schema` in the provided `config`.\n\t *\n\t * The tree (now known to have been initialized) has its stored schema checked against the provided view schema.\n\t *\n\t * If the schemas are compatible (including updating the stored schema if permitted via `allowedSchemaModifications`),\n\t * a {@link TreeView} is returned, with a schema-aware API based on the provided view schema.\n\t *\n\t * If the schemas are not compatible, an exception is thrown.\n\t *\n\t * @privateRemarks\n\t * TODO: make the mismatch case recoverable.\n\t * - Provide a way to make a generic view schema for any document.\n\t * - Produce/throw the error in a document-recoverable way (ex: specific exception type or return value).\n\t * 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?\n\t * TODO: Clarify lifetimes. Ensure calling schematize multiple times does not leak.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t *\n\t * Doing initialization here, regardless of `AllowedUpdateType`, allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter: at that point it clearly belongs here in schematize.\n\t */\n\tschematize<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeConfiguration<TRoot>,\n\t): TreeView<TreeFieldFromImplicitField<TRoot>>;\n}\n\n/**\n * Configuration for how to {@link ITree.schematize|schematize} a tree.\n * @beta\n */\nexport class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {\n\t/**\n\t * @param schema - The schema which the application wants to view the tree with.\n\t * @param initialTree - A function that returns the default tree content to initialize the tree with iff the tree is uninitialized\n\t * (meaning it does not even have any schema set at all).\n\t * If `initialTree` returns any actual node instances, they should be recreated each time `initialTree` runs.\n\t * 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.\n\t */\n\tpublic constructor(\n\t\tpublic readonly schema: TSchema,\n\t\tpublic readonly initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,\n\t) {}\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree.\n * @privateRemarks\n * This is a wrapper around ITreeView that adjusted it for the public package API.\n * TODO:\n * Establish a naming conversion between these internal and wrapper types.\n * @beta\n */\nexport interface TreeView<in out TRoot> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t */\n\treadonly root: TRoot;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: ISubscribable<CheckoutEvents>;\n}\n\n/**\n * Implementation of TreeView wrapping a FlexTreeView.\n */\nexport class WrapperTreeView<\n\tin out TSchema extends ImplicitFieldSchema,\n\tTView extends FlexTreeView<FlexTreeFieldSchema>,\n> implements TreeView<TreeFieldFromImplicitField<TSchema>>\n{\n\tpublic constructor(public readonly view: TView) {}\n\n\tpublic [disposeSymbol](): void {\n\t\tthis.view[disposeSymbol]();\n\t}\n\n\tpublic get events(): ISubscribable<CheckoutEvents> {\n\t\treturn this.view.checkout.events;\n\t}\n\n\tpublic get root(): TreeFieldFromImplicitField<TSchema> {\n\t\treturn getProxyForField(this.view.editableTree) as TreeFieldFromImplicitField<TSchema>;\n\t}\n}\n"]}

package/dist/class-tree/treeApi.d.ts

@@ -0,0 +1,69 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TreeStatus } from "../feature-libraries";
+import { TreeNode } from "../simple-tree";
+import { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from "./schemaTypes";
+/**
+ * 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 declare const nodeApi: TreeApi;
+/**
+ * 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;
+}
+//# sourceMappingURL=treeApi.d.ts.map

package/dist/class-tree/treeApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeApi.d.ts","sourceRoot":"","sources":["../../src/class-tree/treeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAIN,UAAU,EAGV,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM1C,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGxF;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACvB;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,aAAa,EACxC,IAAI,EAAE,CAAC,GACL,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,cAAc,EAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACpC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAChC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,MAAM,IAAI,CAAC;IACd;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC;CAChD;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,OAoDrB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}

package/dist/class-tree/treeApi.js

@@ -0,0 +1,56 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeApi = void 0;
+const feature_libraries_1 = require("../feature-libraries");
+// eslint-disable-next-line import/no-internal-modules
+const flexNode_1 = require("../simple-tree/flexNode");
+// eslint-disable-next-line import/no-internal-modules
+const proxies_1 = require("../simple-tree/proxies");
+const schemaFactory_1 = require("./schemaFactory");
+const toFlexSchema_1 = require("./toFlexSchema");
+/**
+ * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
+ * @beta
+ */
+exports.nodeApi = {
+    parent: (node) => {
+        const editNode = (0, flexNode_1.getFlexNode)(node).parentField.parent.parent;
+        if (editNode !== undefined) {
+            return (0, proxies_1.getOrCreateNodeProxy)(editNode);
+        }
+        return undefined;
+    },
+    key: (node) => {
+        const parentField = (0, flexNode_1.getFlexNode)(node).parentField;
+        if (parentField.parent.schema.kind.multiplicity === feature_libraries_1.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: (node, eventName, listener) => {
+        return (0, flexNode_1.getFlexNode)(node).on(eventName, listener);
+    },
+    status: (node) => {
+        return (0, flexNode_1.getFlexNode)(node).treeStatus();
+    },
+    is: (value, schema) => {
+        const flexSchema = (0, toFlexSchema_1.getFlexSchema)(schema);
+        if ((0, feature_libraries_1.isTreeValue)(value)) {
+            return (flexSchema instanceof feature_libraries_1.LeafNodeSchema && (0, feature_libraries_1.valueSchemaAllows)(flexSchema.info, value));
+        }
+        return (0, flexNode_1.tryGetFlexNode)(value)?.is(flexSchema) ?? false;
+    },
+    schema(node) {
+        if ((0, feature_libraries_1.isTreeValue)(node)) {
+            return (0, schemaFactory_1.schemaFromValue)(node);
+        }
+        return (0, proxies_1.getClassSchema)((0, flexNode_1.getFlexNode)(node).schema);
+    },
+};
+//# sourceMappingURL=treeApi.js.map

package/dist/class-tree/treeApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeApi.js","sourceRoot":"","sources":["../../src/class-tree/treeApi.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,4DAO8B;AAE9B,sDAAsD;AACtD,sDAAsE;AACtE,sDAAsD;AACtD,oDAA8E;AAC9E,mDAAkD;AAElD,iDAA+C;AA0D/C;;;GAGG;AACU,QAAA,OAAO,GAAY;IAC/B,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC7D,IAAI,QAAQ,KAAK,SAAS,EAAE;YAC3B,OAAO,IAAA,8BAAoB,EAAC,QAAQ,CAAC,CAAC;SACtC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,GAAG,EAAE,CAAC,IAAc,EAAE,EAAE;QACvB,MAAM,WAAW,GAAG,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,WAAW,CAAC;QAClD,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,KAAK,gCAAY,CAAC,QAAQ,EAAE;YAC1E,iCAAiC;YACjC,OAAO,WAAW,CAAC,KAAK,CAAC;SACzB;QAED,yGAAyG;QACzG,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC;IAC/B,CAAC;IACD,EAAE,EAAE,CACH,IAAc,EACd,SAAY,EACZ,QAA+B,EAC9B,EAAE;QACH,OAAO,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE;QAC1B,OAAO,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IACD,EAAE,EAAE,CACH,KAAc,EACd,MAAe,EACoB,EAAE;QACrC,MAAM,UAAU,GAAG,IAAA,4BAAa,EAAC,MAAM,CAAC,CAAC;QACzC,IAAI,IAAA,+BAAW,EAAC,KAAK,CAAC,EAAE;YACvB,OAAO,CACN,UAAU,YAAY,kCAAc,IAAI,IAAA,qCAAiB,EAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CACjF,CAAC;SACF;QACD,OAAO,IAAA,yBAAc,EAAC,KAAK,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;IACvD,CAAC;IACD,MAAM,CAAiC,IAAO;QAC7C,IAAI,IAAA,+BAAW,EAAC,IAAI,CAAC,EAAE;YACtB,OAAO,IAAA,+BAAe,EAAC,IAAI,CAAiD,CAAC;SAC7E;QACD,OAAO,IAAA,wBAAc,EAAC,IAAA,sBAAW,EAAC,IAAI,CAAC,CAAC,MAAM,CAK7C,CAAC;IACH,CAAC;CACD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { TreeValue } from \"../core\";\nimport {\n\tEditableTreeEvents,\n\tLeafNodeSchema,\n\tMultiplicity,\n\tTreeStatus,\n\tisTreeValue,\n\tvalueSchemaAllows,\n} from \"../feature-libraries\";\nimport { TreeNode } from \"../simple-tree\";\n// eslint-disable-next-line import/no-internal-modules\nimport { getFlexNode, tryGetFlexNode } from \"../simple-tree/flexNode\";\n// eslint-disable-next-line import/no-internal-modules\nimport { getClassSchema, getOrCreateNodeProxy } from \"../simple-tree/proxies\";\nimport { schemaFromValue } from \"./schemaFactory\";\nimport { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from \"./schemaTypes\";\nimport { getFlexSchema } from \"./toFlexSchema\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @privateRemarks\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @beta\n */\nexport interface TreeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema>;\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the list (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\t/**\n\t * Register an event listener on the given node.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeNodeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeNodeEvents[K],\n\t): () => void;\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\treadonly status: (node: TreeNode) => TreeStatus;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n * @beta\n */\nexport const nodeApi: TreeApi = {\n\tparent: (node: TreeNode) => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode !== undefined) {\n\t\t\treturn getOrCreateNodeProxy(editNode);\n\t\t}\n\n\t\treturn undefined;\n\t},\n\tkey: (node: TreeNode) => {\n\t\tconst parentField = getFlexNode(node).parentField;\n\t\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t\t// The parent of `node` is a list\n\t\t\treturn parentField.index;\n\t\t}\n\n\t\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\t\treturn parentField.parent.key;\n\t},\n\ton: <K extends keyof EditableTreeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: EditableTreeEvents[K],\n\t) => {\n\t\treturn getFlexNode(node).on(eventName, listener);\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node).treeStatus();\n\t},\n\tis: <TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema> => {\n\t\tconst flexSchema = getFlexSchema(schema);\n\t\tif (isTreeValue(value)) {\n\t\t\treturn (\n\t\t\t\tflexSchema instanceof LeafNodeSchema && valueSchemaAllows(flexSchema.info, value)\n\t\t\t);\n\t\t}\n\t\treturn tryGetFlexNode(value)?.is(flexSchema) ?? false;\n\t},\n\tschema<T extends TreeNode | TreeValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\tif (isTreeValue(node)) {\n\t\t\treturn schemaFromValue(node) as TreeNodeSchema<string, NodeKind, unknown, T>;\n\t\t}\n\t\treturn getClassSchema(getFlexNode(node).schema) as TreeNodeSchema<\n\t\t\tstring,\n\t\t\tNodeKind,\n\t\t\tunknown,\n\t\t\tT\n\t\t>;\n\t},\n};\n\n/**\n * A collection of events that can be raised by a {@link TreeNode}.\n * @beta\n */\nexport interface TreeNodeEvents {\n\t/**\n\t * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.\n\t */\n\tafterChange(): void;\n}\n"]}