@fluidframework/tree 2.91.0 → 2.92.0

package/dist/simple-tree/api/treeBeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.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\nimport type { ITreeCursorSynchronous, TreeFieldStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tFieldKinds,\n\tisTreeValue,\n} from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tgetOrCreateNodeFromInnerNode,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport {\n\tunhydratedFlexTreeFromInsertable,\n\ttype InsertableContent,\n} from \"../unhydratedFlexTreeFromInsertable.js\";\nimport type { InsertableField, UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport { conciseFromCursor, type ConciseTree } from \"./conciseTree.js\";\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeEncodingOptions } from \"./customTree.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\nimport { cursorFromVerbose } from \"./verboseTree.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/**\n * Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n */\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t *\n\t * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t *\n\t * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t */\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/**\n * Extensions to {@link TreeChangeEvents} which are not yet stable.\n *\n * @sealed @beta\n */\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - 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`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t *\n\t * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.\n\t */\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/**\n * Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @sealed @beta\n */\nexport interface TreeBeta {\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\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 TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/**\n\t * A less type-safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.\n\t * @remarks\n\t * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.\n\t * This does not support {@link ConciseTree|ConciseTrees} with customized handle encodings or using persisted keys.\n\t * Use \"compressed\" or \"verbose\" formats for more flexibility.\n\t *\n\t * When using this function,\n\t * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.\n\t * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,\n\t * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.\n\t *\n\t * Documented (and thus recoverable) error handling/reporting for this is not yet implemented,\n\t * but for now most invalid inputs will throw a recoverable error.\n\t */\n\timportConcise<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: ConciseTree | undefined,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\n\t/**\n\t * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.\n\t */\n\texportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;\n\n\t/**\n\t * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.\n\t */\n\texportConcise(\n\t\tnode: TreeNode | TreeLeafValue | undefined,\n\t\toptions?: TreeEncodingOptions,\n\t): ConciseTree | undefined;\n\n\t/**\n\t * Clones the persisted data associated with a node.\n\t *\n\t * @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t *\n\t * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t *\n\t * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t *\n\t * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t *\n\t * - If the node (or any node in its subtree) contains {@link ObjectSchemaOptions.allowUnknownOptionalFields|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t */\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /**\n\t//  * Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t//  * @remarks\n\t//  * This only clones the persisted data associated with a node.\n\t//  * Local state, such as properties added to customized schema classes, will not be cloned:\n\t//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t//  */\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/**\n\t// \t\t * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t */\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n\n\t/**\n\t * Construct tree content that is compatible with the field defined by the provided `schema`.\n\t * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.\n\t * @param data - The data used to construct the field content.\n\t * @remarks\n\t * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.\n\t * This function exists as a generalization that can be used in other cases as well,\n\t * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.\n\t */\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n}\n\n/**\n * Borrow a cursor from a node.\n * @remarks\n * The cursor must be put back to its original location before the node is used again.\n */\nexport function borrowCursorFromTreeNodeOrValue(\n\tnode: TreeNode | TreeLeafValue,\n): ITreeCursorSynchronous {\n\tif (isTreeValue(node)) {\n\t\treturn cursorFromVerbose(node, {});\n\t}\n\tconst kernel = getKernel(node);\n\tconst cursor = kernel.getInnerNode().borrowCursor();\n\treturn cursor;\n}\n\n/**\n * {@inheritDoc (TreeBeta:interface).importConcise}\n */\nexport function importConcise<TSchema extends ImplicitFieldSchema>(\n\tschema: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n/**\n * {@inheritDoc (TreeAlpha:interface).importConcise}\n */\nexport function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode | TreeLeafValue | undefined\n>;\nexport function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode | TreeLeafValue | undefined\n> {\n\t// Create the tree content from insertable data\n\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\tdata as InsertableField<UnsafeUnknownSchema>,\n\t\tschema,\n\t);\n\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\treturn result as Unhydrated<\n\t\tTSchema extends ImplicitFieldSchema\n\t\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t\t: TreeNode | TreeLeafValue | undefined\n\t>;\n}\n\n/**\n * {@inheritDoc (TreeBeta:interface).(exportConcise:1)}\n */\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue,\n\toptions?: TreeEncodingOptions,\n): ConciseTree;\n/**\n * {@inheritDoc (TreeBeta:interface).(exportConcise:2)}\n */\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue | undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree | undefined;\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue | undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree | undefined {\n\tif (!isTreeNode(node)) {\n\t\treturn node;\n\t}\n\tconst config: TreeEncodingOptions = { ...options };\n\n\tconst kernel = getKernel(node);\n\tconst cursor = borrowCursorFromTreeNodeOrValue(node);\n\treturn conciseFromCursor(cursor, kernel.context, config);\n}\n\n/**\n * Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\n\timportConcise,\n\texportConcise,\n\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\tconst fieldSchema: TreeFieldStoredSchema = {\n\t\t\tkind: FieldKinds.required.identifier,\n\t\t\ttypes: new Set([brand(kernel.schema.identifier)]),\n\t\t\tpersistedMetadata: undefined,\n\t\t};\n\t\treturn createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\t\tdata as InsertableContent | undefined,\n\t\t\tschema,\n\t\t);\n\t\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\t\treturn result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\t},\n};\n"]}
+{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.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\nimport type { ITreeCursorSynchronous, TreeFieldStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tFieldKinds,\n\tisTreeValue,\n} from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tgetOrCreateNodeFromInnerNode,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport {\n\tunhydratedFlexTreeFromInsertable,\n\ttype InsertableContent,\n} from \"../unhydratedFlexTreeFromInsertable.js\";\nimport type { InsertableField, UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport { conciseFromCursor, type ConciseTree } from \"./conciseTree.js\";\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeEncodingOptions } from \"./customTree.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\nimport { cursorFromVerbose } from \"./verboseTree.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/**\n * Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n */\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t *\n\t * Not present when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t *\n\t * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t */\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/**\n * Extensions to {@link TreeChangeEvents} which are not yet stable.\n *\n * @sealed @beta\n */\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - 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`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t *\n\t * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.\n\t */\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/**\n * Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @sealed @beta\n */\nexport interface TreeBeta {\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\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 TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/**\n\t * A less type-safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.\n\t * @remarks\n\t * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.\n\t * This does not support {@link ConciseTree|ConciseTrees} with customized handle encodings or using persisted keys.\n\t * Use \"compressed\" or \"verbose\" formats for more flexibility.\n\t *\n\t * When using this function,\n\t * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.\n\t * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,\n\t * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.\n\t *\n\t * Documented (and thus recoverable) error handling/reporting for this is not yet implemented,\n\t * but for now most invalid inputs will throw a recoverable error.\n\t */\n\timportConcise<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: ConciseTree | undefined,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\n\t/**\n\t * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.\n\t */\n\texportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;\n\n\t/**\n\t * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.\n\t */\n\texportConcise(\n\t\tnode: TreeNode | TreeLeafValue | undefined,\n\t\toptions?: TreeEncodingOptions,\n\t): ConciseTree | undefined;\n\n\t/**\n\t * Clones the persisted data associated with a node.\n\t *\n\t * @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t *\n\t * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t *\n\t * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t *\n\t * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t *\n\t * - If the node (or any node in its subtree) contains {@link ObjectSchemaOptions.allowUnknownOptionalFields|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t */\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /**\n\t//  * Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t//  * @remarks\n\t//  * This only clones the persisted data associated with a node.\n\t//  * Local state, such as properties added to customized schema classes, will not be cloned:\n\t//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t//  */\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/**\n\t// \t\t * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t */\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n\n\t/**\n\t * Construct tree content that is compatible with the field defined by the provided `schema`.\n\t * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.\n\t * @param data - The data used to construct the field content.\n\t * @remarks\n\t * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.\n\t * This function exists as a generalization that can be used in other cases as well,\n\t * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.\n\t */\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n}\n\n/**\n * Borrow a cursor from a node.\n * @remarks\n * The cursor must be put back to its original location before the node is used again.\n */\nexport function borrowCursorFromTreeNodeOrValue(\n\tnode: TreeNode | TreeLeafValue,\n): ITreeCursorSynchronous {\n\tif (isTreeValue(node)) {\n\t\treturn cursorFromVerbose(node, {});\n\t}\n\tconst kernel = getKernel(node);\n\tconst cursor = kernel.getInnerNode().borrowCursor();\n\treturn cursor;\n}\n\n/**\n * {@inheritDoc (TreeBeta:interface).importConcise}\n */\nexport function importConcise<TSchema extends ImplicitFieldSchema>(\n\tschema: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n/**\n * {@inheritDoc (TreeAlpha:interface).importConcise}\n */\nexport function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode | TreeLeafValue | undefined\n>;\nexport function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree | undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode | TreeLeafValue | undefined\n> {\n\t// Create the tree content from insertable data\n\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\tdata as InsertableField<UnsafeUnknownSchema>,\n\t\tschema,\n\t);\n\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\treturn result as Unhydrated<\n\t\tTSchema extends ImplicitFieldSchema\n\t\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t\t: TreeNode | TreeLeafValue | undefined\n\t>;\n}\n\n/**\n * {@inheritDoc (TreeBeta:interface).(exportConcise:1)}\n */\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue,\n\toptions?: TreeEncodingOptions,\n): ConciseTree;\n/**\n * {@inheritDoc (TreeBeta:interface).(exportConcise:2)}\n */\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue | undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree | undefined;\nexport function exportConcise(\n\tnode: TreeNode | TreeLeafValue | undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree | undefined {\n\tif (!isTreeNode(node)) {\n\t\treturn node;\n\t}\n\tconst config: TreeEncodingOptions = { ...options };\n\n\tconst kernel = getKernel(node);\n\tconst cursor = borrowCursorFromTreeNodeOrValue(node);\n\treturn conciseFromCursor(cursor, kernel.context, config);\n}\n\n/**\n * Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\n\timportConcise,\n\texportConcise,\n\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\tconst fieldSchema: TreeFieldStoredSchema = {\n\t\t\tkind: FieldKinds.required.identifier,\n\t\t\ttypes: new Set([brand(kernel.schema.identifier)]),\n\t\t\tpersistedMetadata: undefined,\n\t\t};\n\t\treturn createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\t\tdata as InsertableContent | undefined,\n\t\t\tschema,\n\t\t);\n\t\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\t\treturn result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\t},\n};\n"]}

package/dist/simple-tree/api/treeChangeEvents.d.ts

@@ -5,6 +5,9 @@
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
+ * @remarks
+ * Access these events via the {@link (Tree:variable)}'s {@link TreeNodeApi.on} method.
+ *
  * @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.

package/dist/simple-tree/api/treeChangeEvents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeChangeEvents.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeChangeEvents.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"treeChangeEvents.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeChangeEvents.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}

package/dist/simple-tree/api/treeChangeEvents.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeChangeEvents.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeChangeEvents.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - 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?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @sealed @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node if any changes affected the node.\n\t *\n\t * This event is emitted after all the changes in a batch have been applied to the whole tree.\n\t * This means that a handler for this event will be able to read the updated state of the tree.\n\t *\n\t * - 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`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @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.\n\t * 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.\n\t * This parameter exists to capture this fact in the type system.\n\t * 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.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t */\n\tnodeChanged(unstable?: unknown): void;\n\n\t/**\n\t * Emitted by a node if something changed anywhere in the subtree rooted at it.\n\t *\n\t * This event is emitted after all the changes in a batch have been applied to the whole tree.\n\t * This means that a handler for this event will be able to read the updated state of the tree.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}
+{"version":3,"file":"treeChangeEvents.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeChangeEvents.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @remarks\n * Access these events via the {@link (Tree:variable)}'s {@link TreeNodeApi.on} method.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - 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?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @sealed @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node if any changes affected the node.\n\t *\n\t * This event is emitted after all the changes in a batch have been applied to the whole tree.\n\t * This means that a handler for this event will be able to read the updated state of the tree.\n\t *\n\t * - 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`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @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.\n\t * 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.\n\t * This parameter exists to capture this fact in the type system.\n\t * 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.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t */\n\tnodeChanged(unstable?: unknown): void;\n\n\t/**\n\t * Emitted by a node if something changed anywhere in the subtree rooted at it.\n\t *\n\t * This event is emitted after all the changes in a batch have been applied to the whole tree.\n\t * This means that a handler for this event will be able to read the updated state of the tree.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}

package/dist/simple-tree/api/treeNodeApi.d.ts

@@ -5,6 +5,52 @@
 import { type TreeStatus } from "../../feature-libraries/index.js";
 import { type TreeNodeSchema, type TreeNode, type TreeLeafValue, type ImplicitAllowedTypes, type TreeNodeFromImplicitAllowedTypes } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
+/**
+ * A `"retain"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements that were not added or removed (though they may have nested changes).
+ * @sealed @alpha
+ */
+export interface ArrayNodeRetainOp {
+    readonly type: "retain";
+    readonly count: number;
+}
+/**
+ * An `"insert"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements added to the array.
+ * Read the new element values from the current tree at the positions described by this op.
+ * @sealed @alpha
+ */
+export interface ArrayNodeInsertOp {
+    readonly type: "insert";
+    readonly count: number;
+}
+/**
+ * A `"remove"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements removed from the array.
+ * @sealed @alpha
+ */
+export interface ArrayNodeRemoveOp {
+    readonly type: "remove";
+    readonly count: number;
+}
+/**
+ * A single operation in an array node change delta. Used to efficiently sync an external
+ * representation of an array (e.g. a text editor or virtual list) with tree changes without
+ * needing to snapshot the old state or diff the entire array. Each op describes a contiguous run
+ * of positions in the array before the change. For inserts, read the new element values from the
+ * current tree at those positions.
+ *
+ * @remarks
+ * There is no dedicated `"move"` op. Moves are represented as `"remove"` + `"insert"`.
+ * When an element is moved within the same array it appears
+ * as a `"remove"` at the source position followed by an `"insert"` at the destination position.
+ * When an element is moved across two different arrays, the source array's delta contains a
+ * `"remove"` and the destination array's delta contains an `"insert"` — they cannot be
+ * correlated without additional bookkeeping on the caller's side.
+ *
+ * @sealed @alpha
+ */
+export type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  *
@@ -64,6 +110,9 @@ export interface TreeNodeApi {
      * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
      * @returns A callback function which will deregister the event.
      * This callback should be called only once.
+     * @remarks
+     * The returned unsubscribe function should be called any time the need for the `listener` callback ends before the node is {@link TreeStatus.Deleted | deleted} (Not just {@link TreeStatus.Removed | removed}).
+     * Doing so removes the overhead of tracking and triggering the event, and also avoids leaking any memory retained by the callback.
      */
     on<K extends keyof TreeChangeEvents>(node: TreeNode, eventName: K, listener: TreeChangeEvents[K]): () => void;
     /**

package/dist/simple-tree/api/treeNodeApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeNodeApi.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeNodeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,kCAAkC,CAAC;AAE5F,OAAO,EAGN,KAAK,cAAc,EAEnB,KAAK,QAAQ,EAKb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EAErC,MAAM,kBAAkB,CAAC;AAY1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAC;IAEvD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,oBAAoB,EACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE7C;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAClC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,MAAM,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAEnC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WA4FzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,CA2BvE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,kBAAkB,GAC7B,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC/B,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,YAAY,GACvB,MAAM,GAAG,SAAS,CAAC;AACtB,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,cAAc,GACzB,MAAM,GAAG,SAAS,CAAC;AA8DtB;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAgB5D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,GAAG,MAAM,CAyBjB"}
+{"version":3,"file":"treeNodeApi.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeNodeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,kCAAkC,CAAC;AAE5F,OAAO,EAGN,KAAK,cAAc,EAEnB,KAAK,QAAQ,EAKb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EAErC,MAAM,kBAAkB,CAAC;AAY1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEzF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAC;IAEvD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,oBAAoB,EACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE7C;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;;;;OAUG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAClC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,MAAM,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAEnC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAqGzB,CAAC;AAgCF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,CA2BvE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,kBAAkB,GAC7B,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC/B,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,YAAY,GACvB,MAAM,GAAG,SAAS,CAAC;AACtB,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,cAAc,GACzB,MAAM,GAAG,SAAS,CAAC;AA8DtB;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAgB5D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAAG,MAAM,GACxB,MAAM,GAAG,MAAM,CAyBjB"}

package/dist/simple-tree/api/treeNodeApi.js

@@ -57,8 +57,17 @@ exports.treeNodeApi = {
                     });
                 }
                 else if ((0, index_js_5.isArrayNodeSchema)(nodeSchema)) {
-                    return kernel.events.on("childrenChangedAfterBatch", () => {
-                        listener({ changedProperties: undefined });
+                    return kernel.events.on("childrenChangedAfterBatch", ({ fieldMarks }) => {
+                        const marks = fieldMarks.get(index_js_1.EmptyKey);
+                        // `marks` is undefined when the field was modified across multiple batches
+                        // within a single flush (e.g. due to an interleaved schema change) and the
+                        // marks could not be composed. Emit `undefined` so callers know the delta is
+                        // unavailable rather than receiving stale marks from only the first batch.
+                        // TODO: Once the eventing stack is rewritten to walk the composed delta at
+                        // flush time, `marks` will always be defined. Remove the `undefined` fallback
+                        // and simplify to: `const delta = deltaMarksToArrayOps(marks);`
+                        const delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);
+                        listener({ delta });
                     });
                 }
                 else {
@@ -95,6 +104,36 @@ exports.treeNodeApi = {
         return getIdentifierFromNode(node, "preferCompressed");
     },
 };
+/**
+ * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
+ * array delta ops suitable for inclusion in {@link NodeChangedData.delta}.
+ *
+ * Each mark in the delta describes a contiguous run of positions in the original array:
+ * - A mark with only `count` (no attach/detach) → `"retain"` (elements unchanged at this level)
+ * - A mark with only `attach` → `"insert"` (new elements added)
+ * - A mark with only `detach` → `"remove"` (elements removed)
+ * - A mark with both `attach` and `detach` → `"remove"` + `"insert"`
+ *
+ * @privateRemarks
+ * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
+ * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
+ */
+function deltaMarksToArrayOps(marks) {
+    const ops = [];
+    for (const mark of marks) {
+        if (mark.detach !== undefined) {
+            ops.push({ type: "remove", count: mark.count });
+        }
+        if (mark.attach !== undefined) {
+            ops.push({ type: "insert", count: mark.count });
+        }
+        else if (mark.detach === undefined) {
+            // Neither attach nor detach: elements retained (may have nested changes in mark.fields).
+            ops.push({ type: "retain", count: mark.count });
+        }
+    }
+    return ops;
+}
 /**
  * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.
  * Returns undefined for other values.

package/dist/simple-tree/api/treeNodeApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeNodeApi.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\nimport type { Off } from \"@fluidframework/core-interfaces\";\nimport { assert, oob, fail, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { EmptyKey, rootFieldKey } from \"../../core/index.js\";\nimport { type TreeStatus, isTreeValue, FieldKinds } from \"../../feature-libraries/index.js\";\nimport { extractFromOpaque } from \"../../util/index.js\";\nimport {\n\tgetKernel,\n\tisTreeNode,\n\ttype TreeNodeSchema,\n\tNodeKind,\n\ttype TreeNode,\n\ttryGetTreeNodeSchema,\n\tgetOrCreateNodeFromInnerNode,\n\ttypeSchemaSymbol,\n\tgetInnerNode,\n\ttype TreeLeafValue,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNodeFromImplicitAllowedTypes,\n\tnormalizeAllowedTypes,\n} from \"../core/index.js\";\nimport { type ImplicitFieldSchema, FieldSchema } from \"../fieldSchema.js\";\nimport { tryGetTreeNodeForField } from \"../getTreeNodeForField.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport { isArrayNodeSchema, isObjectNodeSchema } from \"../node-kinds/index.js\";\n\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @remarks\n * With the exception of {@link TreeNodeApi.status}, these functions should not be called with nodes that have\n * been {@link TreeStatus.Deleted | deleted}.\n * To verify whether or not a node already has been deleted, use the {@link TreeNodeApi.status} function.\n *\n * This type should only be used via the public {@link (Tree:variable)} export.\n *\n * @privateRemarks\n * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.\n *\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 * @sealed @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema(node: TreeNode | TreeLeafValue): TreeNodeSchema;\n\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 ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\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\t * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.\n\t *\n\t * @see {@link (TreeAlpha:interface).child}\n\t * @see {@link (TreeAlpha:interface).children}\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t *\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t *\n\t * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\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 TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\tstatus(node: TreeNode): TreeStatus;\n\n\t/**\n\t * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node is {@link Unhydrated | hydrated}  and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.\n\t * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.\n\t * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.\n\t *\n\t * If the node's identifier is any other user-provided string, then this will return that string.\n\t *\n\t * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.\n\t *\n\t * If the node has more than one identifier, then this will throw an error.\n\t *\n\t * The returned integer should not be serialized or preserved outside of the current process.\n\t * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.\n\t * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * {@inheritDoc TreeNodeApi}\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent(node: TreeNode): TreeNode | undefined {\n\t\tconst editNode = getInnerNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeFromInnerNode(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey(node: TreeNode): string | number {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"property key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get property key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst propertyKey = getPropertyKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn propertyKey;\n\t},\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): Off {\n\t\tconst kernel = getKernel(node);\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\": {\n\t\t\t\tconst nodeSchema = kernel.schema;\n\t\t\t\tif (isObjectNodeSchema(nodeSchema)) {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", ({ changedFields }) => {\n\t\t\t\t\t\tconst changedProperties = new Set(\n\t\t\t\t\t\t\tArray.from(\n\t\t\t\t\t\t\t\tchangedFields,\n\t\t\t\t\t\t\t\t(field) =>\n\t\t\t\t\t\t\t\t\tnodeSchema.storedKeyToPropertyKey.get(field) ??\n\t\t\t\t\t\t\t\t\tfail(0xb36 /* Could not find stored key in schema. */),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tlistener({ changedProperties });\n\t\t\t\t\t});\n\t\t\t\t} else if (isArrayNodeSchema(nodeSchema)) {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", () => {\n\t\t\t\t\t\tlistener({ changedProperties: undefined });\n\t\t\t\t\t});\n\t\t\t\t} else {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", ({ changedFields }) => {\n\t\t\t\t\t\tlistener({ changedProperties: changedFields });\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\tcase \"treeChanged\": {\n\t\t\t\treturn kernel.events.on(\"subtreeChangedAfterBatch\", () => listener({}));\n\t\t\t}\n\t\t\tdefault: {\n\t\t\t\tthrow new UsageError(`No event named ${JSON.stringify(eventName)}.`);\n\t\t\t}\n\t\t}\n\t},\n\tstatus(node: TreeNode): TreeStatus {\n\t\treturn getKernel(node).getStatus();\n\t},\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> {\n\t\t// This \"is\" utility would return false if the provided schema is a base type of the actual schema.\n\t\t// This could be confusing, and that case can only be hit when violating the rule that there is a single most derived schema that gets used (See documentation on TreeNodeSchemaClass).\n\t\t// Therefore this uses markSchemaMostDerived to ensure an informative usage error is thrown in the case where a base type is used.\n\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\treturn normalizeAllowedTypes(schema).evaluateSet().has(actualSchema);\n\t},\n\tschema(node: TreeNode | TreeLeafValue): TreeNodeSchema {\n\t\treturn tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\treturn getIdentifierFromNode(node, \"preferCompressed\");\n\t},\n};\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema(value: unknown): undefined | TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"string\": {\n\t\t\treturn stringSchema;\n\t\t}\n\t\tcase \"number\": {\n\t\t\treturn numberSchema;\n\t\t}\n\t\tcase \"boolean\": {\n\t\t\treturn booleanSchema;\n\t\t}\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// TODO: This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetTreeNodeSchema(value);\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema;\n\t\t\t}\n\t\t}\n\t\tdefault: {\n\t\t\treturn undefined;\n\t\t}\n\t}\n}\n\n/**\n * Gets the identifier from a node.\n *\n * @param node - {@link TreeNode} where you want to extract the identifier from.\n * @param compression - string value to determine what type of identifier you want to retrieve.\n *\n * @remarks\n * If the node does not contain an identifier field, it returns undefined.\n *\n * If `compression` is set to `compressed`:\n *\n * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.\n *\n * - If the node contains an identifier, but is not compressible or unknown by the id compressor, `undefined` is returned.\n *\n * If `compression` is set to `preferCompressed`:\n *\n * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.\n *\n * - If the node contains an identifier, but is not compressible or unknown by the id compressor, the uncompressed identifier is returned.\n *\n * If `compression` is set to `uncompressed`:\n * - If the node contains an identifier field, the uncompressed identifier is returned.\n */\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"preferCompressed\",\n): number | string | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"compressed\",\n): number | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"uncompressed\",\n): string | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"preferCompressed\" | \"compressed\" | \"uncompressed\",\n): number | string | undefined {\n\tconst schema = node[typeSchemaSymbol];\n\tif (!isObjectNodeSchema(schema)) {\n\t\treturn undefined;\n\t}\n\n\tconst flexNode = getInnerNode(node);\n\tconst identifierFieldKeys = schema.identifierFieldKeys;\n\n\tswitch (identifierFieldKeys.length) {\n\t\tcase 0: {\n\t\t\treturn undefined;\n\t\t}\n\t\tcase 1: {\n\t\t\tconst key = identifierFieldKeys[0] ?? oob();\n\t\t\tconst identifierField = flexNode.tryGetField(key);\n\t\t\tassert(identifierField !== undefined, 0xbb5 /* missing identifier field */);\n\t\t\tconst identifierValue = tryGetTreeNodeForField(identifierField);\n\t\t\tassert(typeof identifierValue === \"string\", 0xbb6 /* identifier not a string */);\n\n\t\t\tconst context = flexNode.context;\n\t\t\tswitch (compression) {\n\t\t\t\tcase \"preferCompressed\": {\n\t\t\t\t\tif (context.isHydrated()) {\n\t\t\t\t\t\tconst localNodeKey =\n\t\t\t\t\t\t\tcontext.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);\n\t\t\t\t\t\treturn localNodeKey === undefined\n\t\t\t\t\t\t\t? identifierValue\n\t\t\t\t\t\t\t: extractFromOpaque(localNodeKey);\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn identifierValue;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcase \"compressed\": {\n\t\t\t\t\tif (context.isHydrated()) {\n\t\t\t\t\t\tconst localNodeKey =\n\t\t\t\t\t\t\tcontext.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);\n\t\t\t\t\t\treturn localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn undefined;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcase \"uncompressed\": {\n\t\t\t\t\treturn identifierValue;\n\t\t\t\t}\n\t\t\t\tdefault: {\n\t\t\t\t\tunreachableCase(compression);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tdefault: {\n\t\t\tthrow new UsageError(\n\t\t\t\t\"The node has more than one identifier. Retrieve identifiers individually via their fields instead.\",\n\t\t\t);\n\t\t}\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nexport function getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"property keys\".\n\tconst parentField = getInnerNode(node).parentField;\n\tif (parentField.parent.schema === FieldKinds.sequence.identifier) {\n\t\t// The parent of `node` is an array node\n\t\tassert(\n\t\t\tparentField.parent.key === EmptyKey,\n\t\t\t0xa28 /* When using index as key, field should use EmptyKey */,\n\t\t);\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined. If undefined, then `node` is a root/detached node.\n\tassert(parentField.index === 0, 0xa29 /* When using field key as key, index should be 0 */);\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the property key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nexport function getPropertyKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"property key\".\n\t// For any other kind of node, the stored key and the property key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all property keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from property keys) must be unique.\n\t// To find the property key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching property key.\n\tfor (const [propertyKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn propertyKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(0xb38 /* Existing stored key should always map to a property key */);\n\t}\n\n\treturn storedKey;\n}\n"]}
+{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeNodeApi.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\nimport type { Off } from \"@fluidframework/core-interfaces\";\nimport { assert, oob, fail, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { EmptyKey, rootFieldKey, type DeltaMark } from \"../../core/index.js\";\nimport { type TreeStatus, isTreeValue, FieldKinds } from \"../../feature-libraries/index.js\";\nimport { extractFromOpaque } from \"../../util/index.js\";\nimport {\n\tgetKernel,\n\tisTreeNode,\n\ttype TreeNodeSchema,\n\tNodeKind,\n\ttype TreeNode,\n\ttryGetTreeNodeSchema,\n\tgetOrCreateNodeFromInnerNode,\n\ttypeSchemaSymbol,\n\tgetInnerNode,\n\ttype TreeLeafValue,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNodeFromImplicitAllowedTypes,\n\tnormalizeAllowedTypes,\n} from \"../core/index.js\";\nimport { type ImplicitFieldSchema, FieldSchema } from \"../fieldSchema.js\";\nimport { tryGetTreeNodeForField } from \"../getTreeNodeForField.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport { isArrayNodeSchema, isObjectNodeSchema } from \"../node-kinds/index.js\";\n\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\n\n/**\n * A `\"retain\"` op in an {@link ArrayNodeDeltaOp} sequence.\n * Represents elements that were not added or removed (though they may have nested changes).\n * @sealed @alpha\n */\nexport interface ArrayNodeRetainOp {\n\treadonly type: \"retain\";\n\treadonly count: number;\n}\n\n/**\n * An `\"insert\"` op in an {@link ArrayNodeDeltaOp} sequence.\n * Represents elements added to the array.\n * Read the new element values from the current tree at the positions described by this op.\n * @sealed @alpha\n */\nexport interface ArrayNodeInsertOp {\n\treadonly type: \"insert\";\n\treadonly count: number;\n}\n\n/**\n * A `\"remove\"` op in an {@link ArrayNodeDeltaOp} sequence.\n * Represents elements removed from the array.\n * @sealed @alpha\n */\nexport interface ArrayNodeRemoveOp {\n\treadonly type: \"remove\";\n\treadonly count: number;\n}\n\n/**\n * A single operation in an array node change delta. Used to efficiently sync an external\n * representation of an array (e.g. a text editor or virtual list) with tree changes without\n * needing to snapshot the old state or diff the entire array. Each op describes a contiguous run\n * of positions in the array before the change. For inserts, read the new element values from the\n * current tree at those positions.\n *\n * @remarks\n * There is no dedicated `\"move\"` op. Moves are represented as `\"remove\"` + `\"insert\"`.\n * When an element is moved within the same array it appears\n * as a `\"remove\"` at the source position followed by an `\"insert\"` at the destination position.\n * When an element is moved across two different arrays, the source array's delta contains a\n * `\"remove\"` and the destination array's delta contains an `\"insert\"` — they cannot be\n * correlated without additional bookkeeping on the caller's side.\n *\n * @sealed @alpha\n */\nexport type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @remarks\n * With the exception of {@link TreeNodeApi.status}, these functions should not be called with nodes that have\n * been {@link TreeStatus.Deleted | deleted}.\n * To verify whether or not a node already has been deleted, use the {@link TreeNodeApi.status} function.\n *\n * This type should only be used via the public {@link (Tree:variable)} export.\n *\n * @privateRemarks\n * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.\n *\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 * @sealed @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema(node: TreeNode | TreeLeafValue): TreeNodeSchema;\n\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 ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\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\t * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.\n\t *\n\t * @see {@link (TreeAlpha:interface).child}\n\t * @see {@link (TreeAlpha:interface).children}\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t *\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t *\n\t * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t * @remarks\n\t * The returned unsubscribe function should be called any time the need for the `listener` callback ends before the node is {@link TreeStatus.Deleted | deleted} (Not just {@link TreeStatus.Removed | removed}).\n\t * Doing so removes the overhead of tracking and triggering the event, and also avoids leaking any memory retained by the callback.\n\t */\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\tstatus(node: TreeNode): TreeStatus;\n\n\t/**\n\t * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node is {@link Unhydrated | hydrated}  and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.\n\t * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.\n\t * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.\n\t *\n\t * If the node's identifier is any other user-provided string, then this will return that string.\n\t *\n\t * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.\n\t *\n\t * If the node has more than one identifier, then this will throw an error.\n\t *\n\t * The returned integer should not be serialized or preserved outside of the current process.\n\t * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.\n\t * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * {@inheritDoc TreeNodeApi}\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent(node: TreeNode): TreeNode | undefined {\n\t\tconst editNode = getInnerNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeFromInnerNode(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey(node: TreeNode): string | number {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"property key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get property key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst propertyKey = getPropertyKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn propertyKey;\n\t},\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): Off {\n\t\tconst kernel = getKernel(node);\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\": {\n\t\t\t\tconst nodeSchema = kernel.schema;\n\t\t\t\tif (isObjectNodeSchema(nodeSchema)) {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", ({ changedFields }) => {\n\t\t\t\t\t\tconst changedProperties = new Set(\n\t\t\t\t\t\t\tArray.from(\n\t\t\t\t\t\t\t\tchangedFields,\n\t\t\t\t\t\t\t\t(field) =>\n\t\t\t\t\t\t\t\t\tnodeSchema.storedKeyToPropertyKey.get(field) ??\n\t\t\t\t\t\t\t\t\tfail(0xb36 /* Could not find stored key in schema. */),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tlistener({ changedProperties });\n\t\t\t\t\t});\n\t\t\t\t} else if (isArrayNodeSchema(nodeSchema)) {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", ({ fieldMarks }) => {\n\t\t\t\t\t\tconst marks = fieldMarks.get(EmptyKey);\n\t\t\t\t\t\t// `marks` is undefined when the field was modified across multiple batches\n\t\t\t\t\t\t// within a single flush (e.g. due to an interleaved schema change) and the\n\t\t\t\t\t\t// marks could not be composed. Emit `undefined` so callers know the delta is\n\t\t\t\t\t\t// unavailable rather than receiving stale marks from only the first batch.\n\t\t\t\t\t\t// TODO: Once the eventing stack is rewritten to walk the composed delta at\n\t\t\t\t\t\t// flush time, `marks` will always be defined. Remove the `undefined` fallback\n\t\t\t\t\t\t// and simplify to: `const delta = deltaMarksToArrayOps(marks);`\n\t\t\t\t\t\tconst delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);\n\t\t\t\t\t\tlistener({ delta });\n\t\t\t\t\t});\n\t\t\t\t} else {\n\t\t\t\t\treturn kernel.events.on(\"childrenChangedAfterBatch\", ({ changedFields }) => {\n\t\t\t\t\t\tlistener({ changedProperties: changedFields });\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\tcase \"treeChanged\": {\n\t\t\t\treturn kernel.events.on(\"subtreeChangedAfterBatch\", () => listener({}));\n\t\t\t}\n\t\t\tdefault: {\n\t\t\t\tthrow new UsageError(`No event named ${JSON.stringify(eventName)}.`);\n\t\t\t}\n\t\t}\n\t},\n\tstatus(node: TreeNode): TreeStatus {\n\t\treturn getKernel(node).getStatus();\n\t},\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> {\n\t\t// This \"is\" utility would return false if the provided schema is a base type of the actual schema.\n\t\t// This could be confusing, and that case can only be hit when violating the rule that there is a single most derived schema that gets used (See documentation on TreeNodeSchemaClass).\n\t\t// Therefore this uses markSchemaMostDerived to ensure an informative usage error is thrown in the case where a base type is used.\n\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\treturn normalizeAllowedTypes(schema).evaluateSet().has(actualSchema);\n\t},\n\tschema(node: TreeNode | TreeLeafValue): TreeNodeSchema {\n\t\treturn tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\treturn getIdentifierFromNode(node, \"preferCompressed\");\n\t},\n};\n\n/**\n * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential\n * array delta ops suitable for inclusion in {@link NodeChangedData.delta}.\n *\n * Each mark in the delta describes a contiguous run of positions in the original array:\n * - A mark with only `count` (no attach/detach) → `\"retain\"` (elements unchanged at this level)\n * - A mark with only `attach` → `\"insert\"` (new elements added)\n * - A mark with only `detach` → `\"remove\"` (elements removed)\n * - A mark with both `attach` and `detach` → `\"remove\"` + `\"insert\"`\n *\n * @privateRemarks\n * The case where both `attach` and `detach` are set is unreachable today: the sequence-field\n * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.\n */\nfunction deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {\n\tconst ops: ArrayNodeDeltaOp[] = [];\n\tfor (const mark of marks) {\n\t\tif (mark.detach !== undefined) {\n\t\t\tops.push({ type: \"remove\", count: mark.count });\n\t\t}\n\t\tif (mark.attach !== undefined) {\n\t\t\tops.push({ type: \"insert\", count: mark.count });\n\t\t} else if (mark.detach === undefined) {\n\t\t\t// Neither attach nor detach: elements retained (may have nested changes in mark.fields).\n\t\t\tops.push({ type: \"retain\", count: mark.count });\n\t\t}\n\t}\n\treturn ops;\n}\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema(value: unknown): undefined | TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"string\": {\n\t\t\treturn stringSchema;\n\t\t}\n\t\tcase \"number\": {\n\t\t\treturn numberSchema;\n\t\t}\n\t\tcase \"boolean\": {\n\t\t\treturn booleanSchema;\n\t\t}\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// TODO: This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetTreeNodeSchema(value);\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema;\n\t\t\t}\n\t\t}\n\t\tdefault: {\n\t\t\treturn undefined;\n\t\t}\n\t}\n}\n\n/**\n * Gets the identifier from a node.\n *\n * @param node - {@link TreeNode} where you want to extract the identifier from.\n * @param compression - string value to determine what type of identifier you want to retrieve.\n *\n * @remarks\n * If the node does not contain an identifier field, it returns undefined.\n *\n * If `compression` is set to `compressed`:\n *\n * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.\n *\n * - If the node contains an identifier, but is not compressible or unknown by the id compressor, `undefined` is returned.\n *\n * If `compression` is set to `preferCompressed`:\n *\n * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.\n *\n * - If the node contains an identifier, but is not compressible or unknown by the id compressor, the uncompressed identifier is returned.\n *\n * If `compression` is set to `uncompressed`:\n * - If the node contains an identifier field, the uncompressed identifier is returned.\n */\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"preferCompressed\",\n): number | string | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"compressed\",\n): number | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"uncompressed\",\n): string | undefined;\nexport function getIdentifierFromNode(\n\tnode: TreeNode,\n\tcompression: \"preferCompressed\" | \"compressed\" | \"uncompressed\",\n): number | string | undefined {\n\tconst schema = node[typeSchemaSymbol];\n\tif (!isObjectNodeSchema(schema)) {\n\t\treturn undefined;\n\t}\n\n\tconst flexNode = getInnerNode(node);\n\tconst identifierFieldKeys = schema.identifierFieldKeys;\n\n\tswitch (identifierFieldKeys.length) {\n\t\tcase 0: {\n\t\t\treturn undefined;\n\t\t}\n\t\tcase 1: {\n\t\t\tconst key = identifierFieldKeys[0] ?? oob();\n\t\t\tconst identifierField = flexNode.tryGetField(key);\n\t\t\tassert(identifierField !== undefined, 0xbb5 /* missing identifier field */);\n\t\t\tconst identifierValue = tryGetTreeNodeForField(identifierField);\n\t\t\tassert(typeof identifierValue === \"string\", 0xbb6 /* identifier not a string */);\n\n\t\t\tconst context = flexNode.context;\n\t\t\tswitch (compression) {\n\t\t\t\tcase \"preferCompressed\": {\n\t\t\t\t\tif (context.isHydrated()) {\n\t\t\t\t\t\tconst localNodeKey =\n\t\t\t\t\t\t\tcontext.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);\n\t\t\t\t\t\treturn localNodeKey === undefined\n\t\t\t\t\t\t\t? identifierValue\n\t\t\t\t\t\t\t: extractFromOpaque(localNodeKey);\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn identifierValue;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcase \"compressed\": {\n\t\t\t\t\tif (context.isHydrated()) {\n\t\t\t\t\t\tconst localNodeKey =\n\t\t\t\t\t\t\tcontext.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);\n\t\t\t\t\t\treturn localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn undefined;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tcase \"uncompressed\": {\n\t\t\t\t\treturn identifierValue;\n\t\t\t\t}\n\t\t\t\tdefault: {\n\t\t\t\t\tunreachableCase(compression);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tdefault: {\n\t\t\tthrow new UsageError(\n\t\t\t\t\"The node has more than one identifier. Retrieve identifiers individually via their fields instead.\",\n\t\t\t);\n\t\t}\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nexport function getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"property keys\".\n\tconst parentField = getInnerNode(node).parentField;\n\tif (parentField.parent.schema === FieldKinds.sequence.identifier) {\n\t\t// The parent of `node` is an array node\n\t\tassert(\n\t\t\tparentField.parent.key === EmptyKey,\n\t\t\t0xa28 /* When using index as key, field should use EmptyKey */,\n\t\t);\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined. If undefined, then `node` is a root/detached node.\n\tassert(parentField.index === 0, 0xa29 /* When using field key as key, index should be 0 */);\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the property key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nexport function getPropertyKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"property key\".\n\t// For any other kind of node, the stored key and the property key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all property keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from property keys) must be unique.\n\t// To find the property key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching property key.\n\tfor (const [propertyKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn propertyKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(0xb38 /* Existing stored key should always map to a property key */);\n\t}\n\n\treturn storedKey;\n}\n"]}

package/dist/simple-tree/core/treeNodeKernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeNodeKernel.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"treeNodeKernel.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.ts"],"names":[],"mappings":"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"}

package/dist/simple-tree/core/treeNodeKernel.js

@@ -14,7 +14,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _TreeNodeKernel_hydrationState, _TreeNodeKernel_eventBuffer, _KernelEventBuffer_instances, _KernelEventBuffer_disposed, _KernelEventBuffer_disposeOnFlushListener, _KernelEventBuffer_events, _KernelEventBuffer_eventSource, _KernelEventBuffer_disposeSourceListeners, _KernelEventBuffer_childrenChangedBuffer, _KernelEventBuffer_subTreeChangedBuffer, _KernelEventBuffer_emit, _KernelEventBuffer_handleChildrenChangedAfterBatch, _KernelEventBuffer_handleSubtreeChangedAfterBatch, _KernelEventBuffer_assertNotDisposed;
+var _TreeNodeKernel_hydrationState, _TreeNodeKernel_eventBuffer, _KernelEventBuffer_instances, _KernelEventBuffer_disposed, _KernelEventBuffer_disposeOnFlushListener, _KernelEventBuffer_events, _KernelEventBuffer_eventSource, _KernelEventBuffer_disposeSourceListeners, _KernelEventBuffer_childrenChangedBuffer, _KernelEventBuffer_fieldMarksBuffer, _KernelEventBuffer_invalidatedFieldMarkKeys, _KernelEventBuffer_subTreeChangedBuffer, _KernelEventBuffer_emit, _KernelEventBuffer_handleChildrenChangedAfterBatch, _KernelEventBuffer_handleSubtreeChangedAfterBatch, _KernelEventBuffer_assertNotDisposed;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimpleContextSlot = exports.createTreeNodeFromInner = exports.treeNodeFromAnchor = exports.getInnerNode = exports.getSimpleContextFromInnerNode = exports.getSimpleNodeSchemaFromInnerNode = exports.tryDisposeTreeNode = exports.simpleTreeNodeSlot = exports.splitInnerNodeType = exports.withBufferedTreeEvents = exports.TreeNodeKernel = exports.tryGetTreeNodeSchema = exports.isTreeNode = exports.getKernel = void 0;
 const client_utils_1 = require("@fluid-internal/client-utils");
@@ -295,6 +295,18 @@ class KernelEventBuffer {
          * containing the accumulated set of changed fields.
          */
         _KernelEventBuffer_childrenChangedBuffer.set(this, new Set());
+        /**
+         * Buffer of field marks accumulated since events were paused.
+         * Emitted alongside the buffered changed-fields set when flushed.
+         */
+        _KernelEventBuffer_fieldMarksBuffer.set(this, new Map());
+        /**
+         * Fields whose marks have been permanently invalidated within the current buffer window due to
+         * two or more separate delta batches touching the same field.
+         * Once a key is in this set it must never be re-added to the marks buffer, even if
+         * a third (or later) batch arrives for that field.
+         */
+        _KernelEventBuffer_invalidatedFieldMarkKeys.set(this, new Set());
         /**
          * Whether or not the subtree has changed since events were paused.
          * When events are flushed, a single {@link AnchorEvents.subTreeChanged} event will be emitted if and only
@@ -318,7 +330,7 @@ class KernelEventBuffer {
         __classPrivateFieldGet(this, _KernelEventBuffer_disposeSourceListeners, "f").clear();
         __classPrivateFieldSet(this, _KernelEventBuffer_eventSource, newSource, "f");
         if (__classPrivateFieldGet(this, _KernelEventBuffer_events, "f").hasListeners("childrenChangedAfterBatch")) {
-            const off = __classPrivateFieldGet(this, _KernelEventBuffer_eventSource, "f").on("childrenChangedAfterBatch", ({ changedFields }) => __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_emit).call(this, "childrenChangedAfterBatch", { changedFields }));
+            const off = __classPrivateFieldGet(this, _KernelEventBuffer_eventSource, "f").on("childrenChangedAfterBatch", ({ changedFields, fieldMarks }) => __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_emit).call(this, "childrenChangedAfterBatch", { changedFields, fieldMarks }));
             __classPrivateFieldGet(this, _KernelEventBuffer_disposeSourceListeners, "f").set("childrenChangedAfterBatch", off);
         }
         if (__classPrivateFieldGet(this, _KernelEventBuffer_events, "f").hasListeners("subtreeChangedAfterBatch")) {
@@ -331,7 +343,9 @@ class KernelEventBuffer {
         // If we do not have any existing listeners for this event, then we need to bind to the source.
         if (!__classPrivateFieldGet(this, _KernelEventBuffer_events, "f").hasListeners(eventName)) {
             (0, internal_1.assert)(!__classPrivateFieldGet(this, _KernelEventBuffer_disposeSourceListeners, "f").has(eventName), 0xc4f /* Should not have a dispose function without listeners */);
-            const off = __classPrivateFieldGet(this, _KernelEventBuffer_eventSource, "f").on(eventName, (args) => __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_emit).call(this, eventName, args));
+            const off = eventName === "childrenChangedAfterBatch"
+                ? __classPrivateFieldGet(this, _KernelEventBuffer_eventSource, "f").on(eventName, (args) => __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_emit).call(this, eventName, args))
+                : __classPrivateFieldGet(this, _KernelEventBuffer_eventSource, "f").on(eventName, () => __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_emit).call(this, eventName));
             __classPrivateFieldGet(this, _KernelEventBuffer_disposeSourceListeners, "f").set(eventName, off);
         }
         __classPrivateFieldGet(this, _KernelEventBuffer_events, "f").on(eventName, listener);
@@ -354,8 +368,11 @@ class KernelEventBuffer {
         if (__classPrivateFieldGet(this, _KernelEventBuffer_childrenChangedBuffer, "f").size > 0) {
             __classPrivateFieldGet(this, _KernelEventBuffer_events, "f").emit("childrenChangedAfterBatch", {
                 changedFields: __classPrivateFieldGet(this, _KernelEventBuffer_childrenChangedBuffer, "f"),
+                fieldMarks: __classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f"),
             });
             __classPrivateFieldGet(this, _KernelEventBuffer_childrenChangedBuffer, "f").clear();
+            __classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f").clear();
+            __classPrivateFieldGet(this, _KernelEventBuffer_invalidatedFieldMarkKeys, "f").clear();
         }
         if (__classPrivateFieldGet(this, _KernelEventBuffer_subTreeChangedBuffer, "f")) {
             __classPrivateFieldGet(this, _KernelEventBuffer_events, "f").emit("subtreeChangedAfterBatch");
@@ -373,16 +390,18 @@ class KernelEventBuffer {
         }
         __classPrivateFieldGet(this, _KernelEventBuffer_disposeSourceListeners, "f").clear();
         __classPrivateFieldGet(this, _KernelEventBuffer_childrenChangedBuffer, "f").clear();
+        __classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f").clear();
+        __classPrivateFieldGet(this, _KernelEventBuffer_invalidatedFieldMarkKeys, "f").clear();
         __classPrivateFieldSet(this, _KernelEventBuffer_subTreeChangedBuffer, false, "f");
         __classPrivateFieldSet(this, _KernelEventBuffer_disposed, true, "f");
     }
 }
-_KernelEventBuffer_disposed = new WeakMap(), _KernelEventBuffer_disposeOnFlushListener = new WeakMap(), _KernelEventBuffer_events = new WeakMap(), _KernelEventBuffer_eventSource = new WeakMap(), _KernelEventBuffer_disposeSourceListeners = new WeakMap(), _KernelEventBuffer_childrenChangedBuffer = new WeakMap(), _KernelEventBuffer_subTreeChangedBuffer = new WeakMap(), _KernelEventBuffer_instances = new WeakSet(), _KernelEventBuffer_emit = function _KernelEventBuffer_emit(eventName, arg) {
+_KernelEventBuffer_disposed = new WeakMap(), _KernelEventBuffer_disposeOnFlushListener = new WeakMap(), _KernelEventBuffer_events = new WeakMap(), _KernelEventBuffer_eventSource = new WeakMap(), _KernelEventBuffer_disposeSourceListeners = new WeakMap(), _KernelEventBuffer_childrenChangedBuffer = new WeakMap(), _KernelEventBuffer_fieldMarksBuffer = new WeakMap(), _KernelEventBuffer_invalidatedFieldMarkKeys = new WeakMap(), _KernelEventBuffer_subTreeChangedBuffer = new WeakMap(), _KernelEventBuffer_instances = new WeakSet(), _KernelEventBuffer_emit = function _KernelEventBuffer_emit(eventName, arg) {
     __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_assertNotDisposed).call(this);
     switch (eventName) {
         case "childrenChangedAfterBatch": {
-            (0, internal_1.assert)(arg !== undefined, 0xc50 /* childrenChangedAfterBatch should have arg */);
-            return __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_handleChildrenChangedAfterBatch).call(this, arg.changedFields);
+            (0, internal_1.assert)(arg !== undefined, 0xcea /* childrenChangedAfterBatch requires arg */);
+            return __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_handleChildrenChangedAfterBatch).call(this, arg.changedFields, arg.fieldMarks);
         }
         case "subtreeChangedAfterBatch": {
             return __classPrivateFieldGet(this, _KernelEventBuffer_instances, "m", _KernelEventBuffer_handleSubtreeChangedAfterBatch).call(this);
@@ -391,14 +410,32 @@ _KernelEventBuffer_disposed = new WeakMap(), _KernelEventBuffer_disposeOnFlushLi
             (0, internal_1.unreachableCase)(eventName);
         }
     }
-}, _KernelEventBuffer_handleChildrenChangedAfterBatch = function _KernelEventBuffer_handleChildrenChangedAfterBatch(changedFields) {
+}, _KernelEventBuffer_handleChildrenChangedAfterBatch = function _KernelEventBuffer_handleChildrenChangedAfterBatch(changedFields, fieldMarks) {
     if (bufferTreeEvents) {
         for (const fieldKey of changedFields) {
             __classPrivateFieldGet(this, _KernelEventBuffer_childrenChangedBuffer, "f").add(fieldKey);
         }
+        for (const [key, marks] of fieldMarks) {
+            if (__classPrivateFieldGet(this, _KernelEventBuffer_invalidatedFieldMarkKeys, "f").has(key)) {
+                // Already permanently invalidated by an earlier collision; ignore this batch too.
+                // TODO: Once the eventing stack is rewritten to walk the composed delta at flush
+                // time, this collision path will be unreachable and can be removed entirely.
+                continue;
+            }
+            if (__classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f").has(key)) {
+                // A second batch of marks arrived for the same field before the buffer was flushed.
+                // We have no delta composition logic, so permanently invalidate this field so that
+                // any further batches are also discarded rather than incorrectly surfaced.
+                __classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f").delete(key);
+                __classPrivateFieldGet(this, _KernelEventBuffer_invalidatedFieldMarkKeys, "f").add(key);
+            }
+            else {
+                __classPrivateFieldGet(this, _KernelEventBuffer_fieldMarksBuffer, "f").set(key, marks);
+            }
+        }
     }
     else {
-        __classPrivateFieldGet(this, _KernelEventBuffer_events, "f").emit("childrenChangedAfterBatch", { changedFields });
+        __classPrivateFieldGet(this, _KernelEventBuffer_events, "f").emit("childrenChangedAfterBatch", { changedFields, fieldMarks });
     }
 }, _KernelEventBuffer_handleSubtreeChangedAfterBatch = function _KernelEventBuffer_handleSubtreeChangedAfterBatch() {
     if (bufferTreeEvents) {