@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/lib/simple-tree/tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2DH;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAC7B;;;;;;OAMG;IACH,YACiB,MAAe,EACf,WAAgE;QADhE,WAAM,GAAN,MAAM,CAAS;QACf,gBAAW,GAAX,WAAW,CAAqD;IAC9E,CAAC;CACJ","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IChannel } from \"@fluidframework/datastore-definitions\";\nimport { ISubscribable } from \"../events/index.js\";\nimport { IDisposable } from \"../util/index.js\";\nimport {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"./schemaTypes.js\";\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @public\n */\nexport interface ITree extends IChannel {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the tree's stored schema is compatible, this will provide a schema-aware API for accessing the tree's content.\n\t * If the provided schema is incompatible with the stored data, the view will instead expose an error indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), the tree is initialized with the `initialTree` and\n\t * view `schema` in the provided `config`.\n\t *\n\t * The tree (now known to have been initialized) has its stored schema checked against the provided view schema.\n\t *\n\t * If the schemas are compatible, the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t *\n\t * If the schemas are not compatible, the view will indicate the error.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to enter or leave this error state: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t *\n\t * Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `schematize` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t *\n\t * Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t */\n\tschematize<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeConfiguration<TRoot>,\n\t): TreeView<TreeFieldFromImplicitField<TRoot>>;\n}\n\n/**\n * Configuration for how to {@link ITree.schematize|schematize} a tree.\n * @public\n */\nexport class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {\n\t/**\n\t * @param schema - The schema which the application wants to view the tree with.\n\t * @param initialTree - A function that returns the default tree content to initialize the tree with iff the tree is uninitialized\n\t * (meaning it does not even have any schema set at all).\n\t * If `initialTree` returns any actual node instances, they should be recreated each time `initialTree` runs.\n\t * This is because if the config is used a second time any nodes that were not recreated could error since nodes cannot be inserted into the tree multiple times.\n\t */\n\tpublic constructor(\n\t\tpublic readonly schema: TSchema,\n\t\tpublic readonly initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,\n\t) {}\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree.\n *\n * This view is always in one of two states:\n * 1. In schema: the stored schema is compatible with the provided view schema. There is no error, and root can be used.\n * 2. Out of schema: the stored schema is incompatible with the provided view schema. There is an error, and root cannot be used.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `schematize` anb/or `schematize` could return errors explicitly.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * If this does become a problem,\n * it could be mitigated by adding a `rootOrError` member and deprecating `root` to give users a warning if they might be missing the error checking.\n * @public\n */\nexport interface TreeView<in out TRoot> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If in the out of schema state, accessing this will throw.\n\t * To handle this case, check `error` before using.\n\t *\n\t * To get notified about changes to this field (including to it being in an `error` state),\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t */\n\treadonly root: TRoot;\n\n\t/**\n\t * Description of the error state, if any.\n\t * When this is undefined, the view schema and stored schema are compatible, and `root` can be used.\n\t */\n\treadonly error?: SchemaIncompatible;\n\n\t/**\n\t * When there is an `error` and {@link SchemaIncompatible.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will clear the error state, and allow access to `root`.\n\t * @remarks\n\t * It is an error to call this when {@link SchemaIncompatible.canUpgrade} is false, and a no-op when not in an `error` state.\n\t * When this changes the stored schema, any existing or future clients which were compatible with the old stored schema will get an `error` state when trying to schematize the document.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t */\n\tupgradeSchema(): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: ISubscribable<TreeViewEvents>;\n}\n\n/**\n * Information about how a view schema was incompatible.\n * @public\n */\nexport interface SchemaIncompatible {\n\t/**\n\t * True iff the view schema supports all possible documents permitted by the stored schema.\n\t *\n\t * @remarks\n\t * When true, this is still an error because the view schema supports more documents than the stored schema.\n\t * This means that writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read write access to the tree.\n\t *\n\t * Future version of SharedTree may provide readonly access to the document in this case because that would be safe:\n\t * but this is not currently supported.\n\t */\n\treadonly canUpgrade: boolean;\n}\n\n/**\n * Events for {@link TreeView}.\n * @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * A batch of changes has finished processing and the view has been updated.\n\t */\n\tafterBatch(): void;\n\n\t/**\n\t * {@link TreeView.root} has changed.\n\t * This includes going into or out of an `error` state where the root is unavailable due to stored schema changes.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t */\n\trootChanged(): void;\n}\n"]}
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+DH;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAC7B;;;;;;OAMG;IACH,YACiB,MAAe,EACf,WAAgE;QADhE,WAAM,GAAN,MAAM,CAAS;QACf,gBAAW,GAAX,WAAW,CAAqD;IAC9E,CAAC;CACJ","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IChannel } from \"@fluidframework/datastore-definitions\";\n\nimport { CommitMetadata } from \"../core/index.js\";\nimport { ISubscribable } from \"../events/index.js\";\nimport { RevertibleFactory } from \"../shared-tree/index.js\";\nimport { IDisposable } from \"../util/index.js\";\n\nimport {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"./schemaTypes.js\";\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @public\n */\nexport interface ITree extends IChannel {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the tree's stored schema is compatible, this will provide a schema-aware API for accessing the tree's content.\n\t * If the provided schema is incompatible with the stored data, the view will instead expose an error indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), the tree is initialized with the `initialTree` and\n\t * view `schema` in the provided `config`.\n\t *\n\t * The tree (now known to have been initialized) has its stored schema checked against the provided view schema.\n\t *\n\t * If the schemas are compatible, the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t *\n\t * If the schemas are not compatible, the view will indicate the error.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to enter or leave this error state: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t *\n\t * Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `schematize` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t *\n\t * Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t */\n\tschematize<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * Configuration for how to {@link ITree.schematize|schematize} a tree.\n * @public\n */\nexport class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {\n\t/**\n\t * @param schema - The schema which the application wants to view the tree with.\n\t * @param initialTree - A function that returns the default tree content to initialize the tree with iff the tree is uninitialized\n\t * (meaning it does not even have any schema set at all).\n\t * If `initialTree` returns any actual node instances, they should be recreated each time `initialTree` runs.\n\t * This is because if the config is used a second time any nodes that were not recreated could error since nodes cannot be inserted into the tree multiple times.\n\t */\n\tpublic constructor(\n\t\tpublic readonly schema: TSchema,\n\t\tpublic readonly initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>,\n\t) {}\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree.\n *\n * This view is always in one of two states:\n * 1. In schema: the stored schema is compatible with the provided view schema. There is no error, and root can be used.\n * 2. Out of schema: the stored schema is incompatible with the provided view schema. There is an error, and root cannot be used.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `schematize` anb/or `schematize` could return errors explicitly.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * If this does become a problem,\n * it could be mitigated by adding a `rootOrError` member and deprecating `root` to give users a warning if they might be missing the error checking.\n * @public\n */\nexport interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If in the out of schema state, accessing this will throw.\n\t * To handle this case, check `error` before using.\n\t *\n\t * To get notified about changes to this field (including to it being in an `error` state),\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t */\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/**\n\t * Description of the error state, if any.\n\t * When this is undefined, the view schema and stored schema are compatible, and `root` can be used.\n\t */\n\treadonly error?: SchemaIncompatible;\n\n\t/**\n\t * When there is an `error` and {@link SchemaIncompatible.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will clear the error state, and allow access to `root`.\n\t * @remarks\n\t * It is an error to call this when {@link SchemaIncompatible.canUpgrade} is false, and a no-op when not in an `error` state.\n\t * When this changes the stored schema, any existing or future clients which were compatible with the old stored schema will get an `error` state when trying to schematize the document.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t */\n\tupgradeSchema(): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: ISubscribable<TreeViewEvents>;\n}\n\n/**\n * Information about how a view schema was incompatible.\n * @public\n */\nexport interface SchemaIncompatible {\n\t/**\n\t * True iff the view schema supports all possible documents permitted by the stored schema.\n\t *\n\t * @remarks\n\t * When true, this is still an error because the view schema supports more documents than the stored schema.\n\t * This means that writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read write access to the tree.\n\t *\n\t * Future version of SharedTree may provide readonly access to the document in this case because that would be safe:\n\t * but this is not currently supported.\n\t */\n\treadonly canUpgrade: boolean;\n}\n\n/**\n * Events for {@link TreeView}.\n * @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * A batch of changes has finished processing and the view has been updated.\n\t */\n\tafterBatch(): void;\n\n\t/**\n\t * {@link TreeView.root} has changed.\n\t * This includes going into or out of an `error` state where the root is unavailable due to stored schema changes.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t */\n\trootChanged(): void;\n\n\t/**\n\t * Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t *\n\t * @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t */\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n"]}

package/lib/simple-tree/treeApi.d.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 import { TreeStatus } from "../feature-libraries/index.js";
+import { NodeFromSchema, NodeKind, type TreeLeafValue, TreeNodeSchema } from "./schemaTypes.js";
 import { TreeNode } from "./types.js";
-import { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from "./schemaTypes.js";
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  *
@@ -42,14 +42,22 @@ export interface TreeNodeApi {
     key(node: TreeNode): string | number;
     /**
      * Register an event listener on the given node.
+     * @param node - The node whose events should be subscribed to.
+     * @param eventName - Which event to subscribe to.
+     * @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.
      */
-    on<K extends keyof TreeNodeEvents>(node: TreeNode, eventName: K, listener: TreeNodeEvents[K]): () => void;
+    on<K extends keyof TreeChangeEvents>(node: TreeNode, eventName: K, listener: TreeChangeEvents[K]): () => void;
     /**
      * Returns the {@link TreeStatus} of the given node.
      */
     readonly status: (node: TreeNode) => TreeStatus;
+    /**
+     * If the given node has an identifier specified by a field of kind "identifier" then this returns the compressed form of that identifier.
+     * Otherwise returns undefined.
+     */
+    shortId(node: TreeNode): number | undefined;
 }
 /**
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
@@ -57,12 +65,81 @@ export interface TreeNodeApi {
 export declare const treeNodeApi: TreeNodeApi;
 /**
  * A collection of events that can be raised by a {@link TreeNode}.
+ *
+ * @privateRemarks
+ * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
+ * Probably have object node and map node specific APIs for this.
+ *
+ * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
+ *
+ * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
+ * Some ideas:
+ *
+ * - treeChanged, but with some subtrees/fields/paths excluded
+ * - helper to batch several nodeChanged calls to a treeChanged scope
+ * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
+ * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
+ * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
+ * to allow efficiently searching for new content (and initial content) of a given type.
+ *
  * @public
  */
-export interface TreeNodeEvents {
+export interface TreeChangeEvents {
+    /**
+     * Emitted by a node when a batch of changes is applied to it, where a change is:
+     *
+     * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
+     * to something else, including `undefined`).
+     *
+     * - For an array node, when an element is added, removed, or moved.
+     *
+     * - For a map node, when an entry is added, updated, or removed.
+     *
+     * @remarks
+     * This event is not raised when:
+     *
+     * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+     * elements/entries) will raise this event on the array/map node itself, but not on the node that contains the
+     * array/map node as one of its properties.
+     *
+     * - The node is moved to a different location in the tree or removed from the tree.
+     * In this case the event is raised on the _parent_ node, not the node itself.
+     *
+     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+     * the client that made the original edit.
+     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+     * how many times this event will be raised during any intermediate states.
+     * When it is raised, the tree is guaranteed to be in-schema.
+     *
+     * @privateRemarks
+     * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+     * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+     * node, or when the node has to be updated due to resolution of a merge conflict
+     * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+     */
+    nodeChanged(): void;
     /**
-     * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.
+     * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.
+     *
+     * @remarks
+     * This event is guaranteed to be emitted whenever the subtree _has_ changed.
+     * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.
+     *
+     * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario
+     * where the event fires with no visible changes as well.
+     *
+     * This event is not raised when the node itself is moved to a different location in the tree or removed from the tree.
+     * In that case it is raised on the _parent_ node, not the node itself.
+     *
+     * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
+     * of the node itself.
+     *
+     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+     * the client that made the original edit.
+     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+     * how many times this event will be raised during any intermediate states.
+     * When it is raised, the tree is guaranteed to be in-schema.
      */
-    afterChange(): void;
+    treeChanged(): void;
 }
 //# sourceMappingURL=treeApi.d.ts.map

package/lib/simple-tree/treeApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeApi.d.ts","sourceRoot":"","sources":["../../src/simple-tree/treeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAIN,UAAU,EAGV,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAG3F;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,aAAa,EACxC,IAAI,EAAE,CAAC,GACL,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,cAAc,EAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACpC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC7C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACrC;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAChC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,MAAM,IAAI,CAAC;IACd;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC;CAChD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAyDzB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"treeApi.d.ts","sourceRoot":"","sources":["../../src/simple-tree/treeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAIN,UAAU,EAGV,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EACN,cAAc,EACd,QAAQ,EACR,KAAK,aAAa,EAClB,cAAc,EAGd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,aAAa,EACxC,IAAI,EAAE,CAAC,GACL,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,cAAc,EAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IAEpC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE7C;;;;;OAKG;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,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC;IAEhD;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAkGzB,CAAC;AAmDF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}

package/lib/simple-tree/treeApi.js

@@ -2,11 +2,15 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert } from "@fluidframework/core-utils";
-import { LeafNodeSchema, Multiplicity, isTreeValue, valueSchemaAllows, } from "../feature-libraries/index.js";
-import { getFlexNode, tryGetFlexNode } from "./flexNode.js";
-import { getClassSchema, getOrCreateNodeProxy } from "./proxies.js";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { Multiplicity, rootFieldKey } from "../core/index.js";
+import { FieldKinds, LeafNodeSchema, isTreeValue, valueSchemaAllows, } from "../feature-libraries/index.js";
+import { fail, extractFromOpaque } from "../util/index.js";
+import { getOrCreateNodeProxy } from "./proxies.js";
+import { getFlexNode, tryGetFlexNode } from "./proxyBinding.js";
+import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import { schemaFromValue } from "./schemaFactory.js";
+import { NodeKind, FieldSchema, } from "./schemaTypes.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 /**
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
@@ -22,16 +26,41 @@ export const treeNodeApi = {
         return output;
     },
     key: (node) => {
-        const parentField = getFlexNode(node).parentField;
-        if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
-            // The parent of `node` is an array node
-            return parentField.index;
+        // If the parent is undefined, then this node is under the root field,
+        // so we know its key is the special root one.
+        const parent = treeNodeApi.parent(node);
+        if (parent === undefined) {
+            return rootFieldKey;
         }
-        // The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
-        return parentField.parent.key;
+        // The flex-domain strictly operates in terms of "stored keys".
+        // To find the associated developer-facing "view key", we need to look up the field associated with
+        // the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.
+        const storedKey = getStoredKey(node);
+        const parentSchema = treeNodeApi.schema(parent);
+        const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
+        return viewKey;
     },
     on: (node, eventName, listener) => {
-        return getFlexNode(node).on(eventName, listener);
+        const flex = getFlexNode(node);
+        const anchor = flex.anchorNode;
+        switch (eventName) {
+            case "nodeChanged": {
+                let unsubscribeFromTreeChanged;
+                return anchor.on("childrenChanged", () => {
+                    if (unsubscribeFromTreeChanged === undefined) {
+                        unsubscribeFromTreeChanged = anchor.on("subtreeChanged", () => {
+                            listener();
+                            unsubscribeFromTreeChanged?.();
+                            unsubscribeFromTreeChanged = undefined;
+                        });
+                    }
+                });
+            }
+            case "treeChanged":
+                return anchor.on("subtreeChanged", () => listener());
+            default:
+                return unreachableCase(eventName);
+        }
     },
     status: (node) => {
         return getFlexNode(node, true).treeStatus();
@@ -47,7 +76,56 @@ export const treeNodeApi = {
         if (isTreeValue(node)) {
             return schemaFromValue(node);
         }
-        return getClassSchema(getFlexNode(node).schema);
+        return tryGetSimpleNodeSchema(getFlexNode(node).schema);
+    },
+    shortId(node) {
+        const flexNode = getFlexNode(node);
+        for (const field of flexNode.boxedIterator()) {
+            if (field.schema.kind === FieldKinds.identifier) {
+                const identifier = field.boxedAt(0);
+                assert(identifier !== undefined, 0x927 /* The identifier must exist */);
+                return extractFromOpaque(identifier.context.nodeKeys.localize(identifier.value));
+            }
+        }
     },
 };
+/**
+ * Gets the stored key with which the provided node is associated in the parent.
+ */
+function getStoredKey(node) {
+    // Note: the flex domain strictly works with "stored keys", and knows nothing about the developer-facing
+    // "view keys".
+    const parentField = getFlexNode(node).parentField;
+    if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
+        // The parent of `node` is an array node
+        return parentField.index;
+    }
+    // The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
+    return parentField.parent.key;
+}
+/**
+ * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.
+ */
+function getViewKeyFromStoredKey(schema, storedKey) {
+    // Only object nodes have the concept of a "stored key", differentiated from the developer-facing "view key".
+    // For any other kind of node, the stored key and the view key are the same.
+    if (schema.kind !== NodeKind.Object) {
+        return storedKey;
+    }
+    const fields = schema.info;
+    // Invariants:
+    // - The set of all view keys under an object must be unique.
+    // - The set of all stored keys (including those implicitly created from view keys) must be unique.
+    // To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).
+    // If we don't find any, then search for a matching view key.
+    for (const [viewKey, fieldSchema] of Object.entries(fields)) {
+        if (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {
+            return viewKey;
+        }
+    }
+    if (fields[storedKey] === undefined) {
+        fail("Existing stored key should always map to a view key");
+    }
+    return storedKey;
+}
 //# sourceMappingURL=treeApi.js.map

package/lib/simple-tree/treeApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,OAAO,EAEN,cAAc,EACd,YAAY,EAEZ,WAAW,EACX,iBAAiB,GACjB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA0DlD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAgB;IACvC,MAAM,EAAE,CAAC,IAAc,EAAwB,EAAE;QAChD,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC7D,IAAI,QAAQ,KAAK,SAAS,EAAE;YAC3B,OAAO,SAAS,CAAC;SACjB;QAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,CACL,CAAC,WAAW,CAAC,MAAM,CAAC,EACpB,KAAK,CAAC,gEAAgE,CACtE,CAAC;QACF,OAAO,MAAM,CAAC;IACf,CAAC;IACD,GAAG,EAAE,CAAC,IAAc,EAAE,EAAE;QACvB,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC;QAClD,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,KAAK,YAAY,CAAC,QAAQ,EAAE;YAC1E,wCAAwC;YACxC,OAAO,WAAW,CAAC,KAAK,CAAC;SACzB;QAED,yGAAyG;QACzG,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC;IAC/B,CAAC;IACD,EAAE,EAAE,CACH,IAAc,EACd,SAAY,EACZ,QAA+B,EAC9B,EAAE;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE;QAC1B,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;IAC7C,CAAC;IACD,EAAE,EAAE,CACH,KAAc,EACd,MAAe,EACoB,EAAE;QACrC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE;YACvB,OAAO,CACN,UAAU,YAAY,cAAc,IAAI,iBAAiB,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CACjF,CAAC;SACF;QACD,OAAO,cAAc,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;IACvD,CAAC;IACD,MAAM,CAAiC,IAAO;QAC7C,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE;YACtB,OAAO,eAAe,CAAC,IAAI,CAAiD,CAAC;SAC7E;QACD,OAAO,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CAK7C,CAAC;IACH,CAAC;CACD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils\";\nimport { TreeValue } from \"../core/index.js\";\nimport {\n\tEditableTreeEvents,\n\tLeafNodeSchema,\n\tMultiplicity,\n\tTreeStatus,\n\tisTreeValue,\n\tvalueSchemaAllows,\n} from \"../feature-libraries/index.js\";\nimport { TreeNode } from \"./types.js\";\nimport { getFlexNode, tryGetFlexNode } from \"./flexNode.js\";\nimport { getClassSchema, getOrCreateNodeProxy } from \"./proxies.js\";\nimport { schemaFromValue } from \"./schemaFactory.js\";\nimport { NodeFromSchema, NodeKind, TreeNodeSchema, TreeLeafValue } from \"./schemaTypes.js\";\nimport { getFlexSchema } from \"./toFlexSchema.js\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @privateRemarks\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema>;\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\t/**\n\t * Register an event listener on the given node.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeNodeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeNodeEvents[K],\n\t): () => void;\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\treadonly status: (node: TreeNode) => TreeStatus;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent: (node: TreeNode): TreeNode | undefined => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(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) => {\n\t\tconst parentField = getFlexNode(node).parentField;\n\t\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t\t// The parent of `node` is an array node\n\t\t\treturn parentField.index;\n\t\t}\n\n\t\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\t\treturn parentField.parent.key;\n\t},\n\ton: <K extends keyof EditableTreeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: EditableTreeEvents[K],\n\t) => {\n\t\treturn getFlexNode(node).on(eventName, listener);\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node, true).treeStatus();\n\t},\n\tis: <TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema> => {\n\t\tconst flexSchema = getFlexSchema(schema);\n\t\tif (isTreeValue(value)) {\n\t\t\treturn (\n\t\t\t\tflexSchema instanceof LeafNodeSchema && valueSchemaAllows(flexSchema.info, value)\n\t\t\t);\n\t\t}\n\t\treturn tryGetFlexNode(value)?.is(flexSchema) ?? false;\n\t},\n\tschema<T extends TreeNode | TreeValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\tif (isTreeValue(node)) {\n\t\t\treturn schemaFromValue(node) as TreeNodeSchema<string, NodeKind, unknown, T>;\n\t\t}\n\t\treturn getClassSchema(getFlexNode(node).schema) as TreeNodeSchema<\n\t\t\tstring,\n\t\t\tNodeKind,\n\t\t\tunknown,\n\t\t\tT\n\t\t>;\n\t},\n};\n\n/**\n * A collection of events that can be raised by a {@link TreeNode}.\n * @public\n */\nexport interface TreeNodeEvents {\n\t/**\n\t * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.\n\t */\n\tafterChange(): void;\n}\n"]}
+{"version":3,"file":"treeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeApi.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 { assert, unreachableCase } from \"@fluidframework/core-utils/internal\";\n\nimport { Multiplicity, rootFieldKey } from \"../core/index.js\";\nimport {\n\tFieldKinds,\n\tLeafNodeSchema,\n\tStableNodeKey,\n\tTreeStatus,\n\tisTreeValue,\n\tvalueSchemaAllows,\n} from \"../feature-libraries/index.js\";\nimport { fail, extractFromOpaque } from \"../util/index.js\";\n\nimport { getOrCreateNodeProxy } from \"./proxies.js\";\nimport { getFlexNode, tryGetFlexNode } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport { schemaFromValue } from \"./schemaFactory.js\";\nimport {\n\tNodeFromSchema,\n\tNodeKind,\n\ttype TreeLeafValue,\n\tTreeNodeSchema,\n\ttype ImplicitFieldSchema,\n\tFieldSchema,\n} from \"./schemaTypes.js\";\nimport { getFlexSchema } from \"./toFlexSchema.js\";\nimport { TreeNode } from \"./types.js\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @privateRemarks\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema>;\n\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\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\treadonly status: (node: TreeNode) => TreeStatus;\n\n\t/**\n\t * If the given node has an identifier specified by a field of kind \"identifier\" then this returns the compressed form of that identifier.\n\t * Otherwise returns undefined.\n\t */\n\tshortId(node: TreeNode): number | undefined;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent: (node: TreeNode): TreeNode | undefined => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(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) => {\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 \"view key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn viewKey;\n\t},\n\ton: <K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t) => {\n\t\tconst flex = getFlexNode(node);\n\t\tconst anchor = flex.anchorNode;\n\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\": {\n\t\t\t\tlet unsubscribeFromTreeChanged: (() => void) | undefined;\n\t\t\t\treturn anchor.on(\"childrenChanged\", () => {\n\t\t\t\t\tif (unsubscribeFromTreeChanged === undefined) {\n\t\t\t\t\t\tunsubscribeFromTreeChanged = anchor.on(\"subtreeChanged\", () => {\n\t\t\t\t\t\t\tlistener();\n\t\t\t\t\t\t\tunsubscribeFromTreeChanged?.();\n\t\t\t\t\t\t\tunsubscribeFromTreeChanged = undefined;\n\t\t\t\t\t\t});\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 anchor.on(\"subtreeChanged\", () => listener());\n\t\t\tdefault:\n\t\t\t\treturn unreachableCase(eventName);\n\t\t}\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node, true).treeStatus();\n\t},\n\tis: <TSchema extends TreeNodeSchema>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is NodeFromSchema<TSchema> => {\n\t\tconst flexSchema = getFlexSchema(schema);\n\t\tif (isTreeValue(value)) {\n\t\t\treturn (\n\t\t\t\tflexSchema instanceof LeafNodeSchema && valueSchemaAllows(flexSchema.info, value)\n\t\t\t);\n\t\t}\n\t\treturn tryGetFlexNode(value)?.is(flexSchema) ?? false;\n\t},\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\tif (isTreeValue(node)) {\n\t\t\treturn schemaFromValue(node) as TreeNodeSchema<string, NodeKind, unknown, T>;\n\t\t}\n\t\treturn tryGetSimpleNodeSchema(getFlexNode(node).schema) as TreeNodeSchema<\n\t\t\tstring,\n\t\t\tNodeKind,\n\t\t\tunknown,\n\t\t\tT\n\t\t>;\n\t},\n\tshortId(node: TreeNode): number | undefined {\n\t\tconst flexNode = getFlexNode(node);\n\t\tfor (const field of flexNode.boxedIterator()) {\n\t\t\tif (field.schema.kind === FieldKinds.identifier) {\n\t\t\t\tconst identifier = field.boxedAt(0);\n\t\t\t\tassert(identifier !== undefined, 0x927 /* The identifier must exist */);\n\n\t\t\t\treturn extractFromOpaque(\n\t\t\t\t\tidentifier.context.nodeKeys.localize(identifier.value as StableNodeKey),\n\t\t\t\t);\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 */\nfunction 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// \"view keys\".\n\tconst parentField = getFlexNode(node).parentField;\n\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t// The parent of `node` is an array node\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nfunction getViewKeyFromStoredKey(\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 \"view key\".\n\t// For any other kind of node, the stored key and the view 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 view keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from view keys) must be unique.\n\t// To find the view 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 view key.\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn viewKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(\"Existing stored key should always map to a view key\");\n\t}\n\n\treturn storedKey;\n}\n\n/**\n * A collection of events that can be raised 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 * @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node when a batch of changes is applied to it, where a change is:\n\t *\n\t * - For an object node, when the value of one of its properties changes (i.e., the property's value is set\n\t * to something else, including `undefined`).\n\t *\n\t * - For an array node, when an element is added, removed, or moved.\n\t *\n\t * - For a map node, when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not raised 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 raise 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 raised 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 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about\n\t * how many times this event will be raised during any intermediate states.\n\t * When it is raised, 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\tnodeChanged(): void;\n\n\t/**\n\t * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is guaranteed to be emitted whenever the subtree _has_ changed.\n\t * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.\n\t *\n\t * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario\n\t * where the event fires with no visible changes as well.\n\t *\n\t * This event is not raised 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 raised 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 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about\n\t * how many times this event will be raised during any intermediate states.\n\t * When it is raised, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}

package/lib/simple-tree/types.d.ts

@@ -2,9 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { FlexFieldNodeSchema, FlexMapNodeSchema, FlexObjectNodeSchema } from "../feature-libraries/index.js";
-import { type, WithType } from "./schemaTypes.js";
-import { IterableTreeArrayContent } from "./treeArrayNode.js";
+import { WithType, type } from "./schemaTypes.js";
 /**
  * Type alias to document which values are un-hydrated.
  *
@@ -65,143 +63,4 @@ export declare abstract class TreeNode implements WithType {
      */
     abstract get [type](): string;
 }
-/**
- * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
- *
- * @privateRemarks
- * Inlining this into TreeArrayNode causes recursive array use to stop compiling.
- *
- * @public
- */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom> extends ReadonlyArray<T>, TreeNode {
-    /**
-     * Inserts new item(s) at a specified location.
-     * @param index - The index at which to insert `value`.
-     * @param value - The content to insert.
-     * @throws Throws if `index` is not in the range [0, `array.length`).
-     */
-    insertAt(index: number, ...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-    /**
-     * Inserts new item(s) at the start of the array.
-     * @param value - The content to insert.
-     */
-    insertAtStart(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-    /**
-     * Inserts new item(s) at the end of the array.
-     * @param value - The content to insert.
-     */
-    insertAtEnd(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;
-    /**
-     * Removes the item at the specified location.
-     * @param index - The index at which to remove the item.
-     * @throws Throws if `index` is not in the range [0, `array.length`).
-     */
-    removeAt(index: number): void;
-    /**
-     * Removes all items between the specified indices.
-     * @param start - The starting index of the range to remove (inclusive). Defaults to the start of the array.
-     * @param end - The ending index of the range to remove (exclusive).
-     * @throws Throws if `start` is not in the range [0, `array.length`).
-     * @throws Throws if `end` is less than `start`.
-     * If `end` is not supplied or is greater than the length of the array, all items after `start` are removed.
-     */
-    removeRange(start?: number, end?: number): void;
-    /**
-     * Moves the specified item to the start of the array.
-     * @param sourceIndex - The index of the item to move.
-     * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-     */
-    moveToStart(sourceIndex: number): void;
-    /**
-     * Moves the specified item to the start of the array.
-     * @param sourceIndex - The index of the item to move.
-     * @param source - The source array to move the item out of.
-     * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-     */
-    moveToStart(sourceIndex: number, source: TMoveFrom): void;
-    /**
-     * Moves the specified item to the end of the array.
-     * @param sourceIndex - The index of the item to move.
-     * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-     */
-    moveToEnd(sourceIndex: number): void;
-    /**
-     * Moves the specified item to the end of the array.
-     * @param sourceIndex - The index of the item to move.
-     * @param source - The source array to move the item out of.
-     * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).
-     */
-    moveToEnd(sourceIndex: number, source: TMoveFrom): void;
-    /**
-     * Moves the specified item to the desired location in the array.
-     * @param index - The index to move the item to.
-     * This is based on the state of the array before moving the source item.
-     * @param sourceIndex - The index of the item to move.
-     * @throws Throws if any of the input indices are not in the range [0, `array.length`).
-     */
-    moveToIndex(index: number, sourceIndex: number): void;
-    /**
-     * Moves the specified item to the desired location in the array.
-     * @param index - The index to move the item to.
-     * @param sourceIndex - The index of the item to move.
-     * @param source - The source array to move the item out of.
-     * @throws Throws if any of the input indices are not in the range [0, `array.length`).
-     */
-    moveToIndex(index: number, sourceIndex: number, source: TMoveFrom): void;
-    /**
-     * Moves the specified items to the start of the array.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToStart(sourceStart: number, sourceEnd: number): void;
-    /**
-     * Moves the specified items to the start of the array.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @param source - The source array to move items out of.
-     * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-     * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToStart(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
-    /**
-     * Moves the specified items to the end of the array.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToEnd(sourceStart: number, sourceEnd: number): void;
-    /**
-     * Moves the specified items to the end of the array.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @param source - The source array to move items out of.
-     * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-     * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToEnd(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
-    /**
-     * Moves the specified items to the desired location within the array.
-     * @param index - The index to move the items to.
-     * This is based on the state of the array before moving the source items.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @throws Throws if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToIndex(index: number, sourceStart: number, sourceEnd: number): void;
-    /**
-     * Moves the specified items to the desired location within the array.
-     * @param index - The index to move the items to.
-     * @param sourceStart - The starting index of the range to move (inclusive).
-     * @param sourceEnd - The ending index of the range to move (exclusive)
-     * @param source - The source array to move items out of.
-     * @throws Throws if the types of any of the items being moved are not allowed in the destination array,
-     * if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.
-     */
-    moveRangeToIndex(index: number, sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
-}
-/**
- * Given a node's schema, return the corresponding object in the proxy-based API.
- */
-export type TypedNode<TSchema extends FlexObjectNodeSchema | FlexFieldNodeSchema | FlexMapNodeSchema> = TreeNode & WithType<TSchema["name"]>;
 //# sourceMappingURL=types.d.ts.map

package/lib/simple-tree/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;IACjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IAGH;;;;OAIG;IACH,aAAoB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;CACrC"}

package/lib/simple-tree/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAAE,IAAI,EAAY,MAAM,kBAAkB,CAAC;AAclD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,QAAQ;CAgC7B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n\tFlexFieldNodeSchema,\n\tFlexMapNodeSchema,\n\tFlexObjectNodeSchema,\n} from \"../feature-libraries/index.js\";\nimport { type, WithType } from \"./schemaTypes.js\";\nimport { IterableTreeArrayContent } from \"./treeArrayNode.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * A non-leaf SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or subclassed), is not supported:\n * it may be replaced with an interface or union in the future.\n * @privateRemarks\n * Future changes may replace this with a branded interface if the runtime oddities related to this are not cleaned up.\n *\n * Currently not all node implications include this in their prototype chain (some hide it with a proxy), and thus cause `instanceof` to fail.\n * This results in the runtime and compile time behavior of `instanceof` differing.\n * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.\n * The runtime behavior can be changed by implementing `Symbol.hasInstance`.\n * One of those approaches could be used to resolve this inconsistency if TreeNode is kept as a class.\n * @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since sin ce the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * TODO: This is disabled due to compilation of this project not targeting es2022,\n\t * which causes this to polyfill to use of a weak map which has some undesired runtime overhead.\n\t * Consider enabling this for stronger typing after targeting es2022.\n\t * The [type] symbol here provides a lot of the value this private brand would, but is not all of it:\n\t * someone could manually make an object literal with it and pass it off as a node: this private brand would prevent that.\n\t * Another option would be to add a protected or private symbol, which would also get the stronger typing.\n\t */\n\t// readonly #brand!: unknown;\n\n\t/**\n\t * {@inheritdoc \"type\"}\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [type](): string;\n}\n\n/**\n * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.\n *\n * @privateRemarks\n * Inlining this into TreeArrayNode causes recursive array use to stop compiling.\n *\n * @public\n */\nexport interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom>\n\textends ReadonlyArray<T>,\n\t\tTreeNode {\n\t/**\n\t * Inserts new item(s) at a specified location.\n\t * @param index - The index at which to insert `value`.\n\t * @param value - The content to insert.\n\t * @throws Throws if `index` is not in the range [0, `array.length`).\n\t */\n\tinsertAt(index: number, ...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;\n\n\t/**\n\t * Inserts new item(s) at the start of the array.\n\t * @param value - The content to insert.\n\t */\n\tinsertAtStart(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;\n\n\t/**\n\t * Inserts new item(s) at the end of the array.\n\t * @param value - The content to insert.\n\t */\n\tinsertAtEnd(...value: (TNew | IterableTreeArrayContent<TNew>)[]): void;\n\n\t/**\n\t * Removes the item at the specified location.\n\t * @param index - The index at which to remove the item.\n\t * @throws Throws if `index` is not in the range [0, `array.length`).\n\t */\n\tremoveAt(index: number): void;\n\n\t/**\n\t * Removes all items between the specified indices.\n\t * @param start - The starting index of the range to remove (inclusive). Defaults to the start of the array.\n\t * @param end - The ending index of the range to remove (exclusive).\n\t * @throws Throws if `start` is not in the range [0, `array.length`).\n\t * @throws Throws if `end` is less than `start`.\n\t * If `end` is not supplied or is greater than the length of the array, all items after `start` are removed.\n\t */\n\tremoveRange(start?: number, end?: number): void;\n\n\t/**\n\t * Moves the specified item to the start of the array.\n\t * @param sourceIndex - The index of the item to move.\n\t * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).\n\t */\n\tmoveToStart(sourceIndex: number): void;\n\n\t/**\n\t * Moves the specified item to the start of the array.\n\t * @param sourceIndex - The index of the item to move.\n\t * @param source - The source array to move the item out of.\n\t * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).\n\t */\n\tmoveToStart(sourceIndex: number, source: TMoveFrom): void;\n\n\t/**\n\t * Moves the specified item to the end of the array.\n\t * @param sourceIndex - The index of the item to move.\n\t * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).\n\t */\n\tmoveToEnd(sourceIndex: number): void;\n\n\t/**\n\t * Moves the specified item to the end of the array.\n\t * @param sourceIndex - The index of the item to move.\n\t * @param source - The source array to move the item out of.\n\t * @throws Throws if `sourceIndex` is not in the range [0, `array.length`).\n\t */\n\tmoveToEnd(sourceIndex: number, source: TMoveFrom): void;\n\n\t/**\n\t * Moves the specified item to the desired location in the array.\n\t * @param index - The index to move the item to.\n\t * This is based on the state of the array before moving the source item.\n\t * @param sourceIndex - The index of the item to move.\n\t * @throws Throws if any of the input indices are not in the range [0, `array.length`).\n\t */\n\tmoveToIndex(index: number, sourceIndex: number): void;\n\n\t/**\n\t * Moves the specified item to the desired location in the array.\n\t * @param index - The index to move the item to.\n\t * @param sourceIndex - The index of the item to move.\n\t * @param source - The source array to move the item out of.\n\t * @throws Throws if any of the input indices are not in the range [0, `array.length`).\n\t */\n\tmoveToIndex(index: number, sourceIndex: number, source: TMoveFrom): void;\n\n\t/**\n\t * Moves the specified items to the start of the array.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToStart(sourceStart: number, sourceEnd: number): void;\n\n\t/**\n\t * Moves the specified items to the start of the array.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @param source - The source array to move items out of.\n\t * @throws Throws if the types of any of the items being moved are not allowed in the destination array,\n\t * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToStart(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;\n\n\t/**\n\t * Moves the specified items to the end of the array.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @throws Throws if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToEnd(sourceStart: number, sourceEnd: number): void;\n\n\t/**\n\t * Moves the specified items to the end of the array.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @param source - The source array to move items out of.\n\t * @throws Throws if the types of any of the items being moved are not allowed in the destination array,\n\t * if either of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToEnd(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;\n\n\t/**\n\t * Moves the specified items to the desired location within the array.\n\t * @param index - The index to move the items to.\n\t * This is based on the state of the array before moving the source items.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @throws Throws if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToIndex(index: number, sourceStart: number, sourceEnd: number): void;\n\n\t/**\n\t * Moves the specified items to the desired location within the array.\n\t * @param index - The index to move the items to.\n\t * @param sourceStart - The starting index of the range to move (inclusive).\n\t * @param sourceEnd - The ending index of the range to move (exclusive)\n\t * @param source - The source array to move items out of.\n\t * @throws Throws if the types of any of the items being moved are not allowed in the destination array,\n\t * if any of the input indices are not in the range [0, `array.length`) or if `sourceStart` is greater than `sourceEnd`.\n\t */\n\tmoveRangeToIndex(\n\t\tindex: number,\n\t\tsourceStart: number,\n\t\tsourceEnd: number,\n\t\tsource: TMoveFrom,\n\t): void;\n}\n\n/**\n * Given a node's schema, return the corresponding object in the proxy-based API.\n */\nexport type TypedNode<\n\tTSchema extends FlexObjectNodeSchema | FlexFieldNodeSchema | FlexMapNodeSchema,\n> = TreeNode & WithType<TSchema[\"name\"]>;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAalD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,QAAQ;CAgC7B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { WithType, type } from \"./schemaTypes.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * A non-leaf SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or subclassed), is not supported:\n * it may be replaced with an interface or union in the future.\n * @privateRemarks\n * Future changes may replace this with a branded interface if the runtime oddities related to this are not cleaned up.\n *\n * Currently not all node implications include this in their prototype chain (some hide it with a proxy), and thus cause `instanceof` to fail.\n * This results in the runtime and compile time behavior of `instanceof` differing.\n * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.\n * The runtime behavior can be changed by implementing `Symbol.hasInstance`.\n * One of those approaches could be used to resolve this inconsistency if TreeNode is kept as a class.\n * @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since sin ce the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * TODO: This is disabled due to compilation of this project not targeting es2022,\n\t * which causes this to polyfill to use of a weak map which has some undesired runtime overhead.\n\t * Consider enabling this for stronger typing after targeting es2022.\n\t * The [type] symbol here provides a lot of the value this private brand would, but is not all of it:\n\t * someone could manually make an object literal with it and pass it off as a node: this private brand would prevent that.\n\t * Another option would be to add a protected or private symbol, which would also get the stronger typing.\n\t */\n\t// readonly #brand!: unknown;\n\n\t/**\n\t * {@inheritdoc \"type\"}\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [type](): string;\n}\n"]}