@fluidframework/tree 2.63.0-358419 → 2.63.0-359461

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

@@ -1 +1 @@
-{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAshBH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAuB;IAEvB,OAAO,IAA8B,CAAC;AACvC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\n\nimport type {\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\nimport type {\n\t// This is referenced by doc comments.\n\t// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports\n\tTreeAlpha,\n} from \"../../shared-tree/index.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableField,\n\tInsertableTreeFieldFromImplicitField,\n\tReadableField,\n\tReadSchema,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport type { UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\nimport type { SimpleTreeSchema } from \"../simpleSchema.js\";\n\nimport type { TreeViewConfiguration } from \"./configuration.js\";\nimport type {\n\tRunTransactionParams,\n\tTransactionCallbackStatus,\n\tTransactionResult,\n\tTransactionResultExt,\n\tVoidTransactionCallbackStatus,\n} from \"./transactionTypes.js\";\nimport type { VerboseTree } from \"./verboseTree.js\";\n\n/**\n * A tree from which a {@link TreeView} can be created.\n *\n * @privateRemarks\n * TODO:\n * Add stored key versions of {@link (TreeAlpha:interface).(exportVerbose:2)}, {@link (TreeAlpha:interface).(exportConcise:2)} and {@link (TreeAlpha:interface).exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * @system @sealed @public\n */\nexport interface ViewableTree {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to change its compatibility status: 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 `viewWith` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Support adapters for handling out-of-schema data.\n\t */\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n */\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/**\n * {@link ITree} extended with some alpha APIs.\n * @sealed @alpha\n */\nexport interface ITreeAlpha extends ITree {\n\t/**\n\t * Exports root in the same format as {@link (TreeAlpha:interface).(exportVerbose:1)} using stored keys.\n\t * @remarks\n\t * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).\n\t */\n\texportVerbose(): VerboseTree | undefined;\n\n\t/**\n\t * Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.\n\t * @remarks\n\t * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.\n\t */\n\texportSimpleSchema(): SimpleTreeSchema;\n\n\t/**\n\t * Creates a fork of the current state of the main branch.\n\t * This new branch will be shared with and editable by all clients.\n\t */\n\tcreateSharedBranch(): string;\n\n\t/**\n\t * Returns a list of all shared branches that currently exist on this tree.\n\t * Any one of them can be checked out using {@link ITreeAlpha.viewSharedBranchWith}.\n\t */\n\tgetSharedBranchIds(): string[];\n\n\t/**\n\t * Returns a view of the tree on the specified shared branch, using the provided schema.\n\t * See {@link ViewableTree.viewWith}.\n\t */\n\tviewSharedBranchWith<TRoot extends ImplicitFieldSchema>(\n\t\tbranchId: string,\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.\n *\n * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n *\n * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranch.hasRootSchema | hasRootSchema()}.\n *\n * The branch associated directly with the {@link ITree | SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @alpha\n */\nexport interface TreeBranch extends IDisposable {\n\t/**\n\t * Events for the branch\n\t */\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/**\n\t * Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.\n\t *\n\t * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t *   // ...\n\t * }\n\t * ```\n\t */\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t/**\n\t * Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge | merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose | explicitly} or {@link TreeBranch.merge | implicitly when merging} into another branch.\n\t */\n\tfork(): TreeBranch;\n\n\t/**\n\t * Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t */\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/**\n\t * Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork | branch} - attempting to rebase the main branch will throw.\n\t *\n\t * Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t *\n\t * The {@link TreeBranch | main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t */\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/**\n\t * Run a transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:\n\t *\n\t * - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t *\n\t * @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t *\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t *\n\t * Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t *\n\t * Nested transactions:\n\t * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:\n\t *\n\t * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t */\n\trunTransaction<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResultExt<TSuccessValue, TFailureValue>;\n\t/**\n\t * Run a transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It may return the following:\n\t *\n\t * - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t *\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not.\n\t *\n\t * @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t *\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t *\n\t * Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t *\n\t * Nested transactions:\n\t * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:\n\t *\n\t * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t */\n\trunTransaction(\n\t\ttransaction: () => VoidTransactionCallbackStatus | void,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResult;\n\n\t/**\n\t * Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.\n\t *\n\t * Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.\n\t *\n\t * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.\n\t */\n\tdispose(error?: Error): void;\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree based on some schema.\n *\n * @remarks\n * This schema (known as the view schema) may or may not align with the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility | compatibility}.\n *\n * Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md | schema-evolution.md}\n * and choose a schema compatibility policy that aligns with their application's needs.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\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 *\n * @see {@link TreeViewAlpha}\n * @see {@link asTreeViewAlpha}\n *\n * @sealed @public\n */\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility | compatibility}'s {@link SchemaCompatibilityStatus.canView | canView} before using.\n\t *\n\t * To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t *\n\t * To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t */\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/**\n\t * Description of the current compatibility status between the view schema and stored schema.\n\t *\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t */\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/**\n\t * When the schemas are not an exact match and {@link SchemaCompatibilityStatus.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 update the compatibility state, and allow access to `root`.\n\t * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!\n\t * @remarks\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.\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 * Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t *\n\t * Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t *\n\t * Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t */\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/**\n\t * The view schema used by this TreeView.\n\t */\n\treadonly schema: TSchema;\n}\n\n/**\n * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n */\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,\n> extends Omit<TreeView<ReadSchema<TSchema>>, \"root\" | \"initialize\">,\n\t\tTreeBranch {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/**\n * Information about a view schema's compatibility with the document's stored schema.\n *\n * See SharedTree's README for more information about choosing a compatibility policy.\n * @sealed @public\n */\nexport interface SchemaCompatibilityStatus {\n\t/**\n\t * Whether the view schema allows exactly the same set of documents as the stored schema.\n\t *\n\t * @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t *\n\t * Examples which are expressible where this may occur include:\n\t *\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t *\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)\n\t *\n\t * These cases are typically not interesting to applications.\n\t */\n\treadonly isEquivalent: boolean;\n\n\t/**\n\t * Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t *\n\t * Currently, this field is true iff `isEquivalent` is true.\n\t * Do not rely on this:\n\t * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.\n\t * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,\n\t * likely through out-of-schema content adapters that the application can provide alongside their view schema.\n\t *\n\t * Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!\n\t * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that\n\t * aligns with their application's needs.\n\t *\n\t * @remarks\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * this is false because 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 * See {@link SchemaCompatibilityStatus.canUpgrade}.\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\t * @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t */\n\treadonly canView: boolean;\n\n\t/**\n\t * True iff the view schema supports all possible documents permitted by the stored schema.\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t */\n\treadonly canUpgrade: boolean;\n\n\t/**\n\t * True iff the document is uninitialized (i.e. it has no schema and no content).\n\t *\n\t * To initialize the document, call {@link TreeView.initialize}.\n\t *\n\t * @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t */\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/**\n * Events for {@link TreeBranch}.\n * @sealed @alpha\n */\nexport interface TreeBranchEvents extends Omit<TreeViewEvents, \"commitApplied\"> {\n\t/**\n\t * Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t *\n\t * @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t */\n\tchanged(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/**\n\t * Fired when:\n\t *\n\t * - a local commit is applied outside of a transaction\n\t *\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t *\n\t * - a local commit is applied within a transaction\n\t *\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?: RevertibleAlphaFactory): void;\n}\n\n/**\n * Events for {@link TreeView}.\n * @sealed @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * Raised whenever {@link TreeView.root} is invalidated.\n\t *\n\t * This includes changes to the document schema.\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 * The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t *\n\t * @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t */\n\tschemaChanged(): void;\n\n\t/**\n\t * Fired when:\n\t *\n\t * - a local commit is applied outside of a transaction\n\t *\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t *\n\t * - a local commit is applied within a transaction\n\t *\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\n/**\n * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.\n * @alpha\n * @deprecated Use {@link asAlpha} instead.\n * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyiBH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAuB;IAEvB,OAAO,IAA8B,CAAC;AACvC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\n\nimport type {\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\nimport type {\n\t// This is referenced by doc comments.\n\t// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports\n\tTreeAlpha,\n} from \"../../shared-tree/index.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableField,\n\tInsertableTreeFieldFromImplicitField,\n\tReadableField,\n\tReadSchema,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport type { UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\nimport type { SimpleTreeSchema } from \"../simpleSchema.js\";\n\nimport type { TreeViewConfiguration } from \"./configuration.js\";\nimport type {\n\tRunTransactionParams,\n\tTransactionCallbackStatus,\n\tTransactionResult,\n\tTransactionResultExt,\n\tVoidTransactionCallbackStatus,\n} from \"./transactionTypes.js\";\nimport type { VerboseTree } from \"./verboseTree.js\";\n\n/**\n * A tree from which a {@link TreeView} can be created.\n *\n * @privateRemarks\n * TODO:\n * Add stored key versions of {@link (TreeAlpha:interface).(exportVerbose:2)}, {@link (TreeAlpha:interface).(exportConcise:2)} and {@link (TreeAlpha:interface).exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * @system @sealed @public\n */\nexport interface ViewableTree {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to change its compatibility status: 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 `viewWith` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Support adapters for handling out-of-schema data.\n\t */\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n */\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/**\n * {@link ITree} extended with some alpha APIs.\n * @sealed @alpha\n */\nexport interface ITreeAlpha extends ITree {\n\t/**\n\t * Exports root in the same format as {@link (TreeAlpha:interface).(exportVerbose:1)} using stored keys.\n\t * @remarks\n\t * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).\n\t */\n\texportVerbose(): VerboseTree | undefined;\n\n\t/**\n\t * Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.\n\t * @remarks\n\t * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.\n\t */\n\texportSimpleSchema(): SimpleTreeSchema;\n\n\t/**\n\t * Creates a fork of the current state of the main branch.\n\t * This new branch will be shared with and editable by all clients.\n\t */\n\tcreateSharedBranch(): string;\n\n\t/**\n\t * Returns a list of all shared branches that currently exist on this tree.\n\t * Any one of them can be checked out using {@link ITreeAlpha.viewSharedBranchWith}.\n\t */\n\tgetSharedBranchIds(): string[];\n\n\t/**\n\t * Returns a view of the tree on the specified shared branch, using the provided schema.\n\t * See {@link ViewableTree.viewWith}.\n\t */\n\tviewSharedBranchWith<TRoot extends ImplicitFieldSchema>(\n\t\tbranchId: string,\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.\n *\n * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n *\n * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranch.hasRootSchema | hasRootSchema()}.\n *\n * The branch associated directly with the {@link ITree | SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @alpha\n */\nexport interface TreeBranch extends IDisposable {\n\t/**\n\t * Events for the branch\n\t */\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/**\n\t * Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.\n\t *\n\t * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t *   // ...\n\t * }\n\t * ```\n\t */\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t/**\n\t * Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge | merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose | explicitly} or {@link TreeBranch.merge | implicitly when merging} into another branch.\n\t */\n\tfork(): TreeBranch;\n\n\t/**\n\t * Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t */\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/**\n\t * Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork | branch} - attempting to rebase the main branch will throw.\n\t *\n\t * Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t *\n\t * The {@link TreeBranch | main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t */\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/**\n\t * Run a transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:\n\t *\n\t * - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t *\n\t * @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t *\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t *\n\t * Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t *\n\t * Nested transactions:\n\t * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:\n\t *\n\t * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t */\n\trunTransaction<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResultExt<TSuccessValue, TFailureValue>;\n\t/**\n\t * Run a transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It may return the following:\n\t *\n\t * - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t *\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not.\n\t *\n\t * @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t *\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t *\n\t * Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t *\n\t * Nested transactions:\n\t * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:\n\t *\n\t * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t */\n\trunTransaction(\n\t\ttransaction: () => VoidTransactionCallbackStatus | void,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResult;\n\n\t/**\n\t * Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.\n\t *\n\t * Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.\n\t *\n\t * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.\n\t */\n\tdispose(error?: Error): void;\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree based on some schema.\n *\n * @remarks\n * This schema (known as the view schema) may or may not align with the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility | compatibility}.\n *\n * Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md | schema-evolution.md}\n * and choose a schema compatibility policy that aligns with their application's needs.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\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 *\n * @see {@link TreeViewAlpha}\n * @see {@link asTreeViewAlpha}\n *\n * @sealed @public\n */\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility | compatibility}'s {@link SchemaCompatibilityStatus.canView | canView} before using.\n\t *\n\t * To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t *\n\t * To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t */\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/**\n\t * Description of the current compatibility status between the view schema and stored schema.\n\t *\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t */\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/**\n\t * When {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * @remarks\n\t * This will update the {@link TreeView.compatibility}, allowing access to `root`.\n\t * Beware that this may impact other clients' ability to view the document: see {@link SchemaCompatibilityStatus.canView} for more information.\n\t *\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false.\n\t * {@link SchemaCompatibilityStatus.canUpgrade} being true does not mean that an upgrade is required, nor that an upgrade will have any effect.\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 * - update only a specific change (add an optional field, or apply a staged upgrade)\n\t * - update persistedMetadata or not\n\t *\n\t * As persisted metadata becomes more supported, how it interacts with isEquivalent and upgradeSchema should be clarified:\n\t * for now the docs are being left somewhat vague to allow flexibility in this area.\n\t */\n\tupgradeSchema(): void;\n\n\t/**\n\t * Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t *\n\t * Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t *\n\t * Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t */\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/**\n\t * The view schema used by this TreeView.\n\t */\n\treadonly schema: TSchema;\n}\n\n/**\n * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n */\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,\n> extends Omit<TreeView<ReadSchema<TSchema>>, \"root\" | \"initialize\">,\n\t\tTreeBranch {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/**\n * Information about a view schema's compatibility with the document's stored schema.\n *\n * See SharedTree's README for more information about choosing a compatibility policy.\n * @privateRemarks\n * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.\n * @sealed @public\n */\nexport interface SchemaCompatibilityStatus {\n\t/**\n\t * Whether the view schema allows exactly the same set of documents as the stored schema.\n\t *\n\t * @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t *\n\t * Examples which are expressible where this may occur include:\n\t *\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t *\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (for example: an object node type containing a required field with no allowed types)\n\t *\n\t * These cases are typically not interesting to applications.\n\t *\n\t * Note that other content in the stored schema that does not impact document compatibility, like {@link NodeSchemaOptionsAlpha.persistedMetadata}, does not affect this field.\n\t *\n\t * For the computation of this equivalence, {@link SchemaStaticsAlpha.staged | staged} schemas are not included.\n\t * If there are any unknown optional fields, even if allowed by {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.\n\t */\n\treadonly isEquivalent: boolean;\n\n\t/**\n\t * Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t * @remarks\n\t * If the view schema does not opt into supporting any additional cases, then `canView` is only true when `isEquivalent` is also true.\n\t * The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:\n\t *\n\t * - An object node with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.\n\t *\n\t * - An additional type allowed at a location in the stored schema where it is {@link SchemaStaticsAlpha.staged | staged} in the view schema.\n\t *\n\t * In these cases `canUpgrade` and `isEquivalent` will be false.\n\t *\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * `canView` is false because 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 * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t *\n\t * Future versions 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\t * @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs only tolerate very specific cases beyond their schema (unknown optional fields).\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t */\n\treadonly canView: boolean;\n\n\t/**\n\t * True when {@link TreeView.upgradeSchema} can add support for all content required to be supported by the view schema.\n\t * @remarks\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t *\n\t * When adding optional fields to schema which previously were marked with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}\n\t * the schema upgrade (assuming no other changes are included) will allow the previous version to view.\n\t * Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades.\n\t * Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used,\n\t * to ensure that documents containing it can still be upgraded.\n\t */\n\treadonly canUpgrade: boolean;\n\n\t/**\n\t * True iff the document is uninitialized (i.e. it has no schema and no content).\n\t *\n\t * To initialize the document, call {@link TreeView.initialize}.\n\t *\n\t * @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t */\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/**\n * Events for {@link TreeBranch}.\n * @sealed @alpha\n */\nexport interface TreeBranchEvents extends Omit<TreeViewEvents, \"commitApplied\"> {\n\t/**\n\t * Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t *\n\t * @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t */\n\tchanged(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/**\n\t * Fired when:\n\t *\n\t * - a local commit is applied outside of a transaction\n\t *\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t *\n\t * - a local commit is applied within a transaction\n\t *\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?: RevertibleAlphaFactory): void;\n}\n\n/**\n * Events for {@link TreeView}.\n * @sealed @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * Raised whenever {@link TreeView.root} is invalidated.\n\t *\n\t * This includes changes to the document schema.\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 * The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t *\n\t * @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t */\n\tschemaChanged(): void;\n\n\t/**\n\t * Fired when:\n\t *\n\t * - a local commit is applied outside of a transaction\n\t *\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t *\n\t * - a local commit is applied within a transaction\n\t *\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\n/**\n * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.\n * @alpha\n * @deprecated Use {@link asAlpha} instead.\n * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}

package/lib/simple-tree/api/treeBeta.d.ts

@@ -2,8 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { type NodeKind, type TreeNode, type WithType } from "../core/index.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
+import { type NodeKind, type TreeNode, type Unhydrated, type WithType } from "../core/index.js";
+import type { ImplicitFieldSchema, InsertableTreeFieldFromImplicitField, TreeFieldFromImplicitField } from "../fieldSchema.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 /**
  * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
@@ -98,6 +98,16 @@ export interface TreeBeta {
      * those fields will be cloned just like the known fields.
      */
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
+    /**
+     * Construct tree content that is compatible with the field defined by the provided `schema`.
+     * @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.
+     * @param data - The data used to construct the field content.
+     * @remarks
+     * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
+     * This function exists as a generalization that can be used in other cases as well,
+     * 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.
+     */
+    create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }
 /**
  * Extensions to {@link (Tree:variable)} which are not yet stable.

package/lib/simple-tree/api/treeBeta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeBeta.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAKN,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEb,KAAK,QAAQ,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAGzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjE;;;;;;;;OAQG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAEvC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACtE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,WAAW,EAAE,CACZ,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAE3B,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,GAC3D,OAAO,CAAC,KACR,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,QAAQ,EACrE,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/C,MAAM,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,mBAAmB,EAC9C,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACvC,0BAA0B,CAAC,OAAO,CAAC,CAAC;CAoBvC;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAoCtB,CAAC"}
+{"version":3,"file":"treeBeta.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACX,mBAAmB,EACnB,oCAAoC,EACpC,0BAA0B,EAC1B,MAAM,mBAAmB,CAAC;AAO3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjE;;;;;;;;OAQG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAEvC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACtE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,WAAW,EAAE,CACZ,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAE3B,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,GAC3D,OAAO,CAAC,KACR,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,QAAQ,EACrE,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/C,MAAM,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,mBAAmB,EAC9C,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACvC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAqBvC;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,mBAAmB,EAC/C,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,oCAAoC,CAAC,OAAO,CAAC,GACjD,UAAU,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC;CACnD;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAgDtB,CAAC"}

package/lib/simple-tree/api/treeBeta.js

@@ -4,8 +4,9 @@
  */
 import { defaultSchemaPolicy, FieldKinds } from "../../feature-libraries/index.js";
 import { brand } from "../../util/index.js";
-import { Context, getKernel, isTreeNode, UnhydratedContext, } from "../core/index.js";
+import { Context, getKernel, getOrCreateNodeFromInnerNode, isTreeNode, UnhydratedContext, } from "../core/index.js";
 import { getUnhydratedContext } from "../createContext.js";
+import { unhydratedFlexTreeFromInsertable, } from "../unhydratedFlexTreeFromInsertable.js";
 import { createFromCursor } from "./create.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 /**
@@ -35,5 +36,10 @@ export const TreeBeta = {
         };
         return createFromCursor(kernel.schema, cursor, fieldSchema, context);
     },
+    create(schema, data) {
+        const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
+        const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
+        return result;
+    },
 };
 //# sourceMappingURL=treeBeta.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EACN,OAAO,EACP,SAAS,EACT,UAAU,EACV,iBAAiB,GAKjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA4I/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IACjC,EAAE,CACD,IAAW,EACX,SAAY,EACZ,QAAiD;QAEjD,OAAO,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,CACJ,IAAyC;QAEzC,mIAAmI;QACnI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC,YAAY,EAAE,CAAC;QAE5D,yEAAyE;QACzE,0HAA0H;QAC1H,MAAM,WAAW,GAAG,IAAI,iBAAiB,CACxC,mBAAmB,EACnB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CACjC,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,WAAW,EAAE,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;QAErF,MAAM,WAAW,GAA0B;YAC1C,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU;YACpC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACjD,iBAAiB,EAAE,SAAS;SAC5B,CAAC;QACF,OAAO,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAElE,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 type { TreeFieldStoredSchema } from \"../../core/index.js\";\nimport { defaultSchemaPolicy, FieldKinds } from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type { ImplicitFieldSchema, TreeFieldFromImplicitField } from \"../fieldSchema.js\";\n\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.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 * @system @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 * 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 SchemaFactoryObjectOptions.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\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\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.getOrCreateInnerNode().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"]}
+{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EACN,OAAO,EACP,SAAS,EACT,4BAA4B,EAC5B,UAAU,EACV,iBAAiB,GAKjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAM3D,OAAO,EACN,gCAAgC,GAEhC,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0J/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IACjC,EAAE,CACD,IAAW,EACX,SAAY,EACZ,QAAiD;QAEjD,OAAO,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,CACJ,IAAyC;QAEzC,mIAAmI;QACnI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC,YAAY,EAAE,CAAC;QAE5D,yEAAyE;QACzE,0HAA0H;QAC1H,MAAM,WAAW,GAAG,IAAI,iBAAiB,CACxC,mBAAmB,EACnB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CACjC,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,WAAW,EAAE,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;QAErF,MAAM,WAAW,GAA0B;YAC1C,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU;YACpC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACjD,iBAAiB,EAAE,SAAS;SAC5B,CAAC;QACF,OAAO,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAElE,CAAC;IACH,CAAC;IAED,MAAM,CACL,MAAe,EACf,IAAmD;QAEnD,MAAM,OAAO,GAAG,gCAAgC,CAC/C,IAAqC,EACrC,MAAM,CACN,CAAC;QACF,MAAM,MAAM,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,4BAA4B,CAAC,OAAO,CAAC,CAAC;QACzF,OAAO,MAAyD,CAAC;IAClE,CAAC;CACD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeFieldStoredSchema } from \"../../core/index.js\";\nimport { defaultSchemaPolicy, FieldKinds } 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 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\";\n\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.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 * @system @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 * 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 SchemaFactoryObjectOptions.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 * 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\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.getOrCreateInnerNode().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/lib/simple-tree/api/typesUnsafe.d.ts

@@ -311,7 +311,7 @@ export interface MapNodeCustomizableSchemaUnsafe<out TName extends string, in ou
  * {@link Unenforced} version of {@link TreeRecordNode}.
  * @remarks
  * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
- * @system @sealed @alpha
+ * @system @sealed @beta
  */
 export interface TreeRecordNodeUnsafe<TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe> extends Record<string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>>, TreeNode {
     [Symbol.iterator](): IterableIterator<[

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

@@ -1 +1 @@
-{"version":3,"file":"typesUnsafe.js","sourceRoot":"","sources":["../../../src/simple-tree/api/typesUnsafe.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tIsUnion,\n\tRestrictiveStringRecord,\n\tUnionToIntersection,\n} from \"../../util/index.js\";\n\nimport type {\n\tApplyKind,\n\tApplyKindInput,\n\tFieldKind,\n\tFieldSchema,\n\tFieldSchemaAlpha,\n} from \"../fieldSchema.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNode,\n\tUnhydrated,\n\tInternalTreeNode,\n\tTreeNodeSchema,\n\tTreeNodeSchemaCore,\n\tTreeNodeSchemaClass,\n\tImplicitAllowedTypes,\n\tTreeLeafValue,\n\tFlexListToUnion,\n\tLazyItem,\n} from \"../core/index.js\";\nimport type { TreeArrayNode } from \"../node-kinds/index.js\";\nimport type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from \"../simpleSchema.js\";\n\n/*\n * TODO:\n * Below are a bunch of \"unsafe\" versions of types from \"schemaTypes.ts\".\n * These types duplicate the ones in \"schemaTypes.ts\", except with some of the extends clauses unenforced.\n * This is not great for type safety or maintainability.\n * Eventually it would be great to do at least one of the following:\n * 1. Find a way to avoid needing these entirely, possibly by improving TSC's recursive type support.\n * 2. Deduplicate the safe and unsafe types (possibly by having the safe one call the unsafe ones, or some other trick).\n * 3. Add type tests that check that the two copies of these types produce identical results.\n */\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/**\n * A placeholder to use in {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints | extends constraints} when using the real type breaks compilation of some recursive types due to {@link https://github.com/microsoft/TypeScript/issues/55758 | a design limitation of TypeScript}.\n *\n * These extends constraints only serve as documentation:\n * to avoid breaking compilation, this type has to not actually enforce anything, and thus is just `unknown`.\n * Therefore the type safety is the responsibility of the user of the API.\n * @public\n */\nexport type Unenforced<_DesiredExtendsConstraint> = unknown;\n\n/**\n * A collection of {@link Unenforced} types that are used in the implementation of recursive schema.\n * These are all `@system` types, and thus should not be used directly.\n * @privateRemarks\n * Due to limitations of API-Extractor, all types in this namespace are treated as `@public`:\n * therefore, non-public types should not be included in this namespace.\n * @system @public\n */\nexport namespace System_Unsafe {\n\t/**\n\t * {@link Unenforced} version of `ObjectFromSchemaRecord`.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This does not bother special casing `{}` since no one should make empty objects using the *Recursive APIs.\n\t * @system @public\n\t */\n\texport type ObjectFromSchemaRecordUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t> = {\n\t\t-readonly [Property in keyof T]: Property extends string\n\t\t\t? TreeFieldFromImplicitFieldUnsafe<T[Property]>\n\t\t\t: unknown;\n\t};\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchema}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeNodeSchemaUnsafe<\n\t\tName extends string = string,\n\t\tKind extends NodeKind = NodeKind,\n\t\tTNode extends Unenforced<TreeNode | TreeLeafValue> = unknown,\n\t\tTBuild = never,\n\t\tImplicitlyConstructable extends boolean = boolean,\n\t\tInfo = unknown,\n\t> =\n\t\t| TreeNodeSchemaClassUnsafe<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>\n\t\t| TreeNodeSchemaNonClassUnsafe<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchemaClass}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport interface TreeNodeSchemaClassUnsafe<\n\t\tout Name extends string,\n\t\tout Kind extends NodeKind,\n\t\tout TNode extends Unenforced<TreeNode>,\n\t\tin TInsertable,\n\t\tout ImplicitlyConstructable extends boolean,\n\t\tout Info,\n\t\tout TCustomMetadata = unknown,\n\t> extends TreeNodeSchemaCore<\n\t\t\tName,\n\t\t\tKind,\n\t\t\tImplicitlyConstructable,\n\t\t\tInfo,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> {\n\t\t/**\n\t\t * Constructs an {@link Unhydrated} node with this schema.\n\t\t * @remarks\n\t\t * This constructor is also used internally to construct hydrated nodes with a different parameter type.\n\t\t * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.\n\t\t * @sealed\n\t\t */\n\t\tnew (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchemaNonClass}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport interface TreeNodeSchemaNonClassUnsafe<\n\t\tout Name extends string,\n\t\tout Kind extends NodeKind,\n\t\tout TNode extends Unenforced<TreeNode | TreeLeafValue>,\n\t\tin TInsertable,\n\t\tout ImplicitlyConstructable extends boolean,\n\t\tout Info = unknown,\n\t> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\t\tcreate(data: TInsertable): TNode;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeObjectNode}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeObjectNodeUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t\tTypeName extends string = string,\n\t> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object, T>;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeFieldFromImplicitFieldUnsafe<TSchema extends ImplicitFieldSchemaUnsafe> =\n\t\tTSchema extends FieldSchemaUnsafe<infer Kind, infer Types>\n\t\t\t? ApplyKind<TreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind>\n\t\t\t: TSchema extends ImplicitAllowedTypesUnsafe\n\t\t\t\t? TreeNodeFromImplicitAllowedTypesUnsafe<TSchema>\n\t\t\t\t: unknown;\n\n\t/**\n\t * {@link Unenforced} version of {@link AllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];\n\n\t/**\n\t * {@link Unenforced} version of {@link ImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is similar to `Unenforced<ImplicitAllowedTypes>` in that it avoids constraining the schema\n\t * (which is necessary to avoid breaking recursive types),\n\t * but is superior from a safety perspective because it constrains the structure containing the schema.\n\t * @system @public\n\t */\n\texport type ImplicitAllowedTypesUnsafe =\n\t\t| TreeNodeSchemaUnsafe\n\t\t// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments\n\t\t| readonly LazyItem<Unenforced<TreeNodeSchema>>[];\n\n\t/**\n\t * {@link Unenforced} version of {@link ImplicitFieldSchema}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is similar to `Unenforced<ImplicitFieldSchema>` in that it avoids constraining the schema\n\t * (which is necessary to avoid breaking recursive types),\n\t * but is superior from a safety perspective because it constrains the structure containing the schema.\n\t * @system @public\n\t */\n\texport type ImplicitFieldSchemaUnsafe =\n\t\t| FieldSchemaUnsafe<FieldKind, ImplicitAllowedTypesUnsafe>\n\t\t| ImplicitAllowedTypesUnsafe;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeNodeFromImplicitAllowedTypesUnsafe<\n\t\tTSchema extends ImplicitAllowedTypesUnsafe,\n\t> = TSchema extends TreeNodeSchemaUnsafe\n\t\t? NodeFromSchemaUnsafe<TSchema>\n\t\t: TSchema extends AllowedTypesUnsafe\n\t\t\t? NodeFromSchemaUnsafe<FlexListToUnion<TSchema>>\n\t\t\t: unknown;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<\n\t\tTSchema extends ImplicitAllowedTypesUnsafe,\n\t> = [TSchema] extends [TreeNodeSchemaUnsafe]\n\t\t? InsertableTypedNodeUnsafe<TSchema>\n\t\t: [TSchema] extends [AllowedTypesUnsafe]\n\t\t\t? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema>\n\t\t\t: never;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromAllowedTypes}.\n\t * @see {@link Input}\n\t * @privateRemarks\n\t * TODO: AB#36348: it seems like the order of the union this produces is what is non-deterministic in incremental builds\n\t * of the JsonAsTree schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> =\n\t\tIsUnion<TList> extends true\n\t\t\t? never\n\t\t\t: {\n\t\t\t\t\treadonly [Property in keyof TList]: TList[Property] extends LazyItem<\n\t\t\t\t\t\tinfer TSchema extends TreeNodeSchemaUnsafe\n\t\t\t\t\t>\n\t\t\t\t\t\t? InsertableTypedNodeUnsafe<TSchema>\n\t\t\t\t\t\t: never;\n\t\t\t\t}[number];\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTypedNode}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * TODO:\n\t * This is less strict than InsertableTypedNode when given non-exact schema to avoid compilation issues.\n\t * This should probably be fixed or documented somehow.\n\t * @system @public\n\t */\n\texport type InsertableTypedNodeUnsafe<\n\t\tTSchema extends TreeNodeSchemaUnsafe,\n\t\tT = UnionToIntersection<TSchema>,\n\t> =\n\t\t| (T extends TreeNodeSchemaUnsafe<string, NodeKind, TreeNode | TreeLeafValue, never, true>\n\t\t\t\t? NodeBuilderDataUnsafe<T>\n\t\t\t\t: never)\n\t\t| (T extends TreeNodeSchemaUnsafe ? NodeFromSchemaUnsafe<T> : never);\n\n\t/**\n\t * {@link Unenforced} version of {@link NodeFromSchema}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =\n\t\tT extends TreeNodeSchemaUnsafe<string, NodeKind, infer TNode> ? TNode : never;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =\n\t\tT extends TreeNodeSchemaUnsafe<string, NodeKind, unknown, infer TBuild> ? TBuild : never;\n\n\t/**\n\t * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface TreeArrayNodeUnsafe<TAllowedTypes extends ImplicitAllowedTypesUnsafe>\n\t\textends TreeArrayNode<\n\t\t\tTAllowedTypes,\n\t\t\tTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,\n\t\t\tInsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>\n\t\t> {}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeMapNode}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface TreeMapNodeUnsafe<T extends ImplicitAllowedTypesUnsafe>\n\t\textends ReadonlyMapInlined<string, T>,\n\t\t\tTreeNode {\n\t\t/**\n\t\t * {@inheritdoc TreeMapNode.set}\n\t\t */\n\t\tset(\n\t\t\tkey: string,\n\t\t\tvalue: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T> | undefined,\n\t\t): void;\n\n\t\t/**\n\t\t * {@inheritdoc TreeMapNode.delete}\n\t\t */\n\t\tdelete(key: string): void;\n\t}\n\n\t/**\n\t * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.\n\t * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),\n\t * except that it avoids the above mentioned compile error.\n\t * Authored by manually inlining ReadonlyMap from from the TypeScript lib which can be found by navigating to the definition of `ReadonlyMap`.\n\t * @system @sealed @public\n\t */\n\texport interface ReadonlyMapInlined<K, T extends ImplicitAllowedTypesUnsafe> {\n\t\t/** Returns an iterable of entries in the map. */\n\t\t[Symbol.iterator](): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;\n\n\t\t/**\n\t\t * Returns an iterable of key, value pairs for every entry in the map.\n\t\t */\n\t\tentries(): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;\n\n\t\t/**\n\t\t * Returns an iterable of keys in the map\n\t\t */\n\t\tkeys(): IterableIterator<K>;\n\n\t\t/**\n\t\t * Returns an iterable of values in the map\n\t\t */\n\t\tvalues(): IterableIterator<TreeNodeFromImplicitAllowedTypesUnsafe<T>>;\n\n\t\tforEach(\n\t\t\tcallbackfn: (\n\t\t\t\tvalue: TreeNodeFromImplicitAllowedTypesUnsafe<T>,\n\t\t\t\tkey: K,\n\t\t\t\tmap: ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t) => void,\n\t\t\tthisArg?: any,\n\t\t): void;\n\t\tget(key: K): TreeNodeFromImplicitAllowedTypesUnsafe<T> | undefined;\n\t\thas(key: K): boolean;\n\t\treadonly size: number;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of `FieldHasDefault`.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport type FieldHasDefaultUnsafe<T extends ImplicitFieldSchemaUnsafe> =\n\t\tT extends FieldSchemaUnsafe<\n\t\t\tFieldKind.Optional | FieldKind.Identifier,\n\t\t\tImplicitAllowedTypesUnsafe\n\t\t>\n\t\t\t? true\n\t\t\t: false;\n\n\t/**\n\t * {@link Unenforced} version of `InsertableObjectFromSchemaRecord`.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableObjectFromSchemaRecordUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t> = {\n\t\t// Field might not have a default, so make it required:\n\t\treadonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends false\n\t\t\t? Property\n\t\t\t: never]: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;\n\t} & {\n\t\t// Field might have a default, so allow optional.\n\t\t// Note that if the field could be either, this returns boolean, causing both fields to exist, resulting in required.\n\t\treadonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends true\n\t\t\t? Property\n\t\t\t: never]?: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;\n\t};\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeFieldFromImplicitFieldUnsafe<\n\t\tTSchemaInput extends ImplicitFieldSchemaUnsafe,\n\t\tTSchema = UnionToIntersection<TSchemaInput>,\n\t> = [TSchema] extends [FieldSchemaUnsafe<infer Kind, infer Types>]\n\t\t? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind, true>\n\t\t: [TSchema] extends [ImplicitAllowedTypes]\n\t\t\t? InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema>\n\t\t\t: never;\n\n\t/**\n\t * {@link Unenforced} version of {@link FieldSchema}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface FieldSchemaUnsafe<\n\t\tout Kind extends FieldKind,\n\t\tout Types extends ImplicitAllowedTypesUnsafe,\n\t\tout TCustomMetadata = unknown,\n\t> extends FieldSchema<Kind, any, TCustomMetadata> {\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.kind}\n\t\t */\n\t\treadonly kind: Kind;\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.allowedTypes}\n\t\t */\n\t\treadonly allowedTypes: Types;\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.allowedTypeSet}\n\t\t */\n\t\treadonly allowedTypeSet: ReadonlySet<TreeNodeSchema>;\n\t}\n}\n\n/**\n * {@link Unenforced} version of {@link FieldSchemaAlpha}.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @system @sealed @alpha\n */\nexport interface FieldSchemaAlphaUnsafe<\n\tout Kind extends FieldKind,\n\tout Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata = unknown,\n> extends FieldSchemaAlpha<Kind, any, TCustomMetadata>,\n\t\tSystem_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata> {\n\t/**\n\t * {@inheritDoc FieldSchema.allowedTypes}\n\t */\n\treadonly allowedTypes: Types;\n}\n\n/* eslint-enable @typescript-eslint/no-explicit-any */\n\n/**\n * {@link Unenforced} version of {@link ArrayNodeCustomizableSchema}s.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @sealed\n * @alpha\n * @system\n */\nexport interface ArrayNodeCustomizableSchemaUnsafe<\n\tout TName extends string,\n\tin out T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata,\n> extends TreeNodeSchemaClass<\n\t\t\tTName,\n\t\t\tNodeKind.Array,\n\t\t\tSystem_Unsafe.TreeArrayNodeUnsafe<T> & WithType<TName, NodeKind.Array, T>,\n\t\t\t{\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\tSystem_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>\n\t\t\t\t>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t>,\n\t\tSimpleArrayNodeSchema<TCustomMetadata> {}\n\n/**\n * {@link Unenforced} version of {@link MapNodeCustomizableSchema}s.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @sealed\n * @alpha\n * @system\n */\nexport interface MapNodeCustomizableSchemaUnsafe<\n\tout TName extends string,\n\tin out T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata,\n> extends TreeNodeSchemaClass<\n\t\t\tTName,\n\t\t\tNodeKind.Map,\n\t\t\tSystem_Unsafe.TreeMapNodeUnsafe<T> & WithType<TName, NodeKind.Map, T>,\n\t\t\t| {\n\t\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t\t[string, System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t\t>;\n\t\t\t  }\n\t\t\t| {\n\t\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t  },\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t>,\n\t\tSimpleMapNodeSchema<TCustomMetadata> {}\n\n/**\n * {@link Unenforced} version of {@link TreeRecordNode}.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @system @sealed @alpha\n */\nexport interface TreeRecordNodeUnsafe<\n\tTAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n> extends Record<string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>>,\n\t\tTreeNode {\n\t[Symbol.iterator](): IterableIterator<\n\t\t[string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>]\n\t>;\n}\n"]}
+{"version":3,"file":"typesUnsafe.js","sourceRoot":"","sources":["../../../src/simple-tree/api/typesUnsafe.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tIsUnion,\n\tRestrictiveStringRecord,\n\tUnionToIntersection,\n} from \"../../util/index.js\";\n\nimport type {\n\tApplyKind,\n\tApplyKindInput,\n\tFieldKind,\n\tFieldSchema,\n\tFieldSchemaAlpha,\n} from \"../fieldSchema.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNode,\n\tUnhydrated,\n\tInternalTreeNode,\n\tTreeNodeSchema,\n\tTreeNodeSchemaCore,\n\tTreeNodeSchemaClass,\n\tImplicitAllowedTypes,\n\tTreeLeafValue,\n\tFlexListToUnion,\n\tLazyItem,\n} from \"../core/index.js\";\nimport type { TreeArrayNode } from \"../node-kinds/index.js\";\nimport type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from \"../simpleSchema.js\";\n\n/*\n * TODO:\n * Below are a bunch of \"unsafe\" versions of types from \"schemaTypes.ts\".\n * These types duplicate the ones in \"schemaTypes.ts\", except with some of the extends clauses unenforced.\n * This is not great for type safety or maintainability.\n * Eventually it would be great to do at least one of the following:\n * 1. Find a way to avoid needing these entirely, possibly by improving TSC's recursive type support.\n * 2. Deduplicate the safe and unsafe types (possibly by having the safe one call the unsafe ones, or some other trick).\n * 3. Add type tests that check that the two copies of these types produce identical results.\n */\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/**\n * A placeholder to use in {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-constraints | extends constraints} when using the real type breaks compilation of some recursive types due to {@link https://github.com/microsoft/TypeScript/issues/55758 | a design limitation of TypeScript}.\n *\n * These extends constraints only serve as documentation:\n * to avoid breaking compilation, this type has to not actually enforce anything, and thus is just `unknown`.\n * Therefore the type safety is the responsibility of the user of the API.\n * @public\n */\nexport type Unenforced<_DesiredExtendsConstraint> = unknown;\n\n/**\n * A collection of {@link Unenforced} types that are used in the implementation of recursive schema.\n * These are all `@system` types, and thus should not be used directly.\n * @privateRemarks\n * Due to limitations of API-Extractor, all types in this namespace are treated as `@public`:\n * therefore, non-public types should not be included in this namespace.\n * @system @public\n */\nexport namespace System_Unsafe {\n\t/**\n\t * {@link Unenforced} version of `ObjectFromSchemaRecord`.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This does not bother special casing `{}` since no one should make empty objects using the *Recursive APIs.\n\t * @system @public\n\t */\n\texport type ObjectFromSchemaRecordUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t> = {\n\t\t-readonly [Property in keyof T]: Property extends string\n\t\t\t? TreeFieldFromImplicitFieldUnsafe<T[Property]>\n\t\t\t: unknown;\n\t};\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchema}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeNodeSchemaUnsafe<\n\t\tName extends string = string,\n\t\tKind extends NodeKind = NodeKind,\n\t\tTNode extends Unenforced<TreeNode | TreeLeafValue> = unknown,\n\t\tTBuild = never,\n\t\tImplicitlyConstructable extends boolean = boolean,\n\t\tInfo = unknown,\n\t> =\n\t\t| TreeNodeSchemaClassUnsafe<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>\n\t\t| TreeNodeSchemaNonClassUnsafe<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchemaClass}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport interface TreeNodeSchemaClassUnsafe<\n\t\tout Name extends string,\n\t\tout Kind extends NodeKind,\n\t\tout TNode extends Unenforced<TreeNode>,\n\t\tin TInsertable,\n\t\tout ImplicitlyConstructable extends boolean,\n\t\tout Info,\n\t\tout TCustomMetadata = unknown,\n\t> extends TreeNodeSchemaCore<\n\t\t\tName,\n\t\t\tKind,\n\t\t\tImplicitlyConstructable,\n\t\t\tInfo,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> {\n\t\t/**\n\t\t * Constructs an {@link Unhydrated} node with this schema.\n\t\t * @remarks\n\t\t * This constructor is also used internally to construct hydrated nodes with a different parameter type.\n\t\t * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.\n\t\t * @sealed\n\t\t */\n\t\tnew (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeSchemaNonClass}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport interface TreeNodeSchemaNonClassUnsafe<\n\t\tout Name extends string,\n\t\tout Kind extends NodeKind,\n\t\tout TNode extends Unenforced<TreeNode | TreeLeafValue>,\n\t\tin TInsertable,\n\t\tout ImplicitlyConstructable extends boolean,\n\t\tout Info = unknown,\n\t> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\t\tcreate(data: TInsertable): TNode;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeObjectNode}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeObjectNodeUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t\tTypeName extends string = string,\n\t> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object, T>;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeFieldFromImplicitFieldUnsafe<TSchema extends ImplicitFieldSchemaUnsafe> =\n\t\tTSchema extends FieldSchemaUnsafe<infer Kind, infer Types>\n\t\t\t? ApplyKind<TreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind>\n\t\t\t: TSchema extends ImplicitAllowedTypesUnsafe\n\t\t\t\t? TreeNodeFromImplicitAllowedTypesUnsafe<TSchema>\n\t\t\t\t: unknown;\n\n\t/**\n\t * {@link Unenforced} version of {@link AllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type AllowedTypesUnsafe = readonly LazyItem<TreeNodeSchemaUnsafe>[];\n\n\t/**\n\t * {@link Unenforced} version of {@link ImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is similar to `Unenforced<ImplicitAllowedTypes>` in that it avoids constraining the schema\n\t * (which is necessary to avoid breaking recursive types),\n\t * but is superior from a safety perspective because it constrains the structure containing the schema.\n\t * @system @public\n\t */\n\texport type ImplicitAllowedTypesUnsafe =\n\t\t| TreeNodeSchemaUnsafe\n\t\t// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments\n\t\t| readonly LazyItem<Unenforced<TreeNodeSchema>>[];\n\n\t/**\n\t * {@link Unenforced} version of {@link ImplicitFieldSchema}.\n\t * @remarks\n\t * Do not use this type directly: it is only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is similar to `Unenforced<ImplicitFieldSchema>` in that it avoids constraining the schema\n\t * (which is necessary to avoid breaking recursive types),\n\t * but is superior from a safety perspective because it constrains the structure containing the schema.\n\t * @system @public\n\t */\n\texport type ImplicitFieldSchemaUnsafe =\n\t\t| FieldSchemaUnsafe<FieldKind, ImplicitAllowedTypesUnsafe>\n\t\t| ImplicitAllowedTypesUnsafe;\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeNodeFromImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type TreeNodeFromImplicitAllowedTypesUnsafe<\n\t\tTSchema extends ImplicitAllowedTypesUnsafe,\n\t> = TSchema extends TreeNodeSchemaUnsafe\n\t\t? NodeFromSchemaUnsafe<TSchema>\n\t\t: TSchema extends AllowedTypesUnsafe\n\t\t\t? NodeFromSchemaUnsafe<FlexListToUnion<TSchema>>\n\t\t\t: unknown;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeNodeFromImplicitAllowedTypesUnsafe<\n\t\tTSchema extends ImplicitAllowedTypesUnsafe,\n\t> = [TSchema] extends [TreeNodeSchemaUnsafe]\n\t\t? InsertableTypedNodeUnsafe<TSchema>\n\t\t: [TSchema] extends [AllowedTypesUnsafe]\n\t\t\t? InsertableTreeNodeFromAllowedTypesUnsafe<TSchema>\n\t\t\t: never;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromAllowedTypes}.\n\t * @see {@link Input}\n\t * @privateRemarks\n\t * TODO: AB#36348: it seems like the order of the union this produces is what is non-deterministic in incremental builds\n\t * of the JsonAsTree schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeNodeFromAllowedTypesUnsafe<TList extends AllowedTypesUnsafe> =\n\t\tIsUnion<TList> extends true\n\t\t\t? never\n\t\t\t: {\n\t\t\t\t\treadonly [Property in keyof TList]: TList[Property] extends LazyItem<\n\t\t\t\t\t\tinfer TSchema extends TreeNodeSchemaUnsafe\n\t\t\t\t\t>\n\t\t\t\t\t\t? InsertableTypedNodeUnsafe<TSchema>\n\t\t\t\t\t\t: never;\n\t\t\t\t}[number];\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTypedNode}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * TODO:\n\t * This is less strict than InsertableTypedNode when given non-exact schema to avoid compilation issues.\n\t * This should probably be fixed or documented somehow.\n\t * @system @public\n\t */\n\texport type InsertableTypedNodeUnsafe<\n\t\tTSchema extends TreeNodeSchemaUnsafe,\n\t\tT = UnionToIntersection<TSchema>,\n\t> =\n\t\t| (T extends TreeNodeSchemaUnsafe<string, NodeKind, TreeNode | TreeLeafValue, never, true>\n\t\t\t\t? NodeBuilderDataUnsafe<T>\n\t\t\t\t: never)\n\t\t| (T extends TreeNodeSchemaUnsafe ? NodeFromSchemaUnsafe<T> : never);\n\n\t/**\n\t * {@link Unenforced} version of {@link NodeFromSchema}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type NodeFromSchemaUnsafe<T extends Unenforced<TreeNodeSchema>> =\n\t\tT extends TreeNodeSchemaUnsafe<string, NodeKind, infer TNode> ? TNode : never;\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeNodeFromImplicitAllowedTypes}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =\n\t\tT extends TreeNodeSchemaUnsafe<string, NodeKind, unknown, infer TBuild> ? TBuild : never;\n\n\t/**\n\t * {@link Unenforced} version of {@link (TreeArrayNode:interface)}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface TreeArrayNodeUnsafe<TAllowedTypes extends ImplicitAllowedTypesUnsafe>\n\t\textends TreeArrayNode<\n\t\t\tTAllowedTypes,\n\t\t\tTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,\n\t\t\tInsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>\n\t\t> {}\n\n\t/**\n\t * {@link Unenforced} version of {@link TreeMapNode}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface TreeMapNodeUnsafe<T extends ImplicitAllowedTypesUnsafe>\n\t\textends ReadonlyMapInlined<string, T>,\n\t\t\tTreeNode {\n\t\t/**\n\t\t * {@inheritdoc TreeMapNode.set}\n\t\t */\n\t\tset(\n\t\t\tkey: string,\n\t\t\tvalue: InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T> | undefined,\n\t\t): void;\n\n\t\t/**\n\t\t * {@inheritdoc TreeMapNode.delete}\n\t\t */\n\t\tdelete(key: string): void;\n\t}\n\n\t/**\n\t * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.\n\t * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @privateRemarks\n\t * This is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),\n\t * except that it avoids the above mentioned compile error.\n\t * Authored by manually inlining ReadonlyMap from from the TypeScript lib which can be found by navigating to the definition of `ReadonlyMap`.\n\t * @system @sealed @public\n\t */\n\texport interface ReadonlyMapInlined<K, T extends ImplicitAllowedTypesUnsafe> {\n\t\t/** Returns an iterable of entries in the map. */\n\t\t[Symbol.iterator](): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;\n\n\t\t/**\n\t\t * Returns an iterable of key, value pairs for every entry in the map.\n\t\t */\n\t\tentries(): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;\n\n\t\t/**\n\t\t * Returns an iterable of keys in the map\n\t\t */\n\t\tkeys(): IterableIterator<K>;\n\n\t\t/**\n\t\t * Returns an iterable of values in the map\n\t\t */\n\t\tvalues(): IterableIterator<TreeNodeFromImplicitAllowedTypesUnsafe<T>>;\n\n\t\tforEach(\n\t\t\tcallbackfn: (\n\t\t\t\tvalue: TreeNodeFromImplicitAllowedTypesUnsafe<T>,\n\t\t\t\tkey: K,\n\t\t\t\tmap: ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t) => void,\n\t\t\tthisArg?: any,\n\t\t): void;\n\t\tget(key: K): TreeNodeFromImplicitAllowedTypesUnsafe<T> | undefined;\n\t\thas(key: K): boolean;\n\t\treadonly size: number;\n\t}\n\n\t/**\n\t * {@link Unenforced} version of `FieldHasDefault`.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport type FieldHasDefaultUnsafe<T extends ImplicitFieldSchemaUnsafe> =\n\t\tT extends FieldSchemaUnsafe<\n\t\t\tFieldKind.Optional | FieldKind.Identifier,\n\t\t\tImplicitAllowedTypesUnsafe\n\t\t>\n\t\t\t? true\n\t\t\t: false;\n\n\t/**\n\t * {@link Unenforced} version of `InsertableObjectFromSchemaRecord`.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableObjectFromSchemaRecordUnsafe<\n\t\tT extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>,\n\t> = {\n\t\t// Field might not have a default, so make it required:\n\t\treadonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends false\n\t\t\t? Property\n\t\t\t: never]: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;\n\t} & {\n\t\t// Field might have a default, so allow optional.\n\t\t// Note that if the field could be either, this returns boolean, causing both fields to exist, resulting in required.\n\t\treadonly [Property in keyof T as FieldHasDefaultUnsafe<T[Property & string]> extends true\n\t\t\t? Property\n\t\t\t: never]?: InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;\n\t};\n\n\t/**\n\t * {@link Unenforced} version of {@link InsertableTreeFieldFromImplicitField}.\n\t * @see {@link Input}\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @public\n\t */\n\texport type InsertableTreeFieldFromImplicitFieldUnsafe<\n\t\tTSchemaInput extends ImplicitFieldSchemaUnsafe,\n\t\tTSchema = UnionToIntersection<TSchemaInput>,\n\t> = [TSchema] extends [FieldSchemaUnsafe<infer Kind, infer Types>]\n\t\t? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<Types>, Kind, true>\n\t\t: [TSchema] extends [ImplicitAllowedTypes]\n\t\t\t? InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TSchema>\n\t\t\t: never;\n\n\t/**\n\t * {@link Unenforced} version of {@link FieldSchema}.\n\t * @remarks\n\t * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n\t * @system @sealed @public\n\t */\n\texport interface FieldSchemaUnsafe<\n\t\tout Kind extends FieldKind,\n\t\tout Types extends ImplicitAllowedTypesUnsafe,\n\t\tout TCustomMetadata = unknown,\n\t> extends FieldSchema<Kind, any, TCustomMetadata> {\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.kind}\n\t\t */\n\t\treadonly kind: Kind;\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.allowedTypes}\n\t\t */\n\t\treadonly allowedTypes: Types;\n\t\t/**\n\t\t * {@inheritDoc FieldSchema.allowedTypeSet}\n\t\t */\n\t\treadonly allowedTypeSet: ReadonlySet<TreeNodeSchema>;\n\t}\n}\n\n/**\n * {@link Unenforced} version of {@link FieldSchemaAlpha}.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @system @sealed @alpha\n */\nexport interface FieldSchemaAlphaUnsafe<\n\tout Kind extends FieldKind,\n\tout Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata = unknown,\n> extends FieldSchemaAlpha<Kind, any, TCustomMetadata>,\n\t\tSystem_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata> {\n\t/**\n\t * {@inheritDoc FieldSchema.allowedTypes}\n\t */\n\treadonly allowedTypes: Types;\n}\n\n/* eslint-enable @typescript-eslint/no-explicit-any */\n\n/**\n * {@link Unenforced} version of {@link ArrayNodeCustomizableSchema}s.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @sealed\n * @alpha\n * @system\n */\nexport interface ArrayNodeCustomizableSchemaUnsafe<\n\tout TName extends string,\n\tin out T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata,\n> extends TreeNodeSchemaClass<\n\t\t\tTName,\n\t\t\tNodeKind.Array,\n\t\t\tSystem_Unsafe.TreeArrayNodeUnsafe<T> & WithType<TName, NodeKind.Array, T>,\n\t\t\t{\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\tSystem_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>\n\t\t\t\t>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t>,\n\t\tSimpleArrayNodeSchema<TCustomMetadata> {}\n\n/**\n * {@link Unenforced} version of {@link MapNodeCustomizableSchema}s.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @sealed\n * @alpha\n * @system\n */\nexport interface MapNodeCustomizableSchemaUnsafe<\n\tout TName extends string,\n\tin out T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tout TCustomMetadata,\n> extends TreeNodeSchemaClass<\n\t\t\tTName,\n\t\t\tNodeKind.Map,\n\t\t\tSystem_Unsafe.TreeMapNodeUnsafe<T> & WithType<TName, NodeKind.Map, T>,\n\t\t\t| {\n\t\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t\t[string, System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t\t>;\n\t\t\t  }\n\t\t\t| {\n\t\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t  },\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t>,\n\t\tSimpleMapNodeSchema<TCustomMetadata> {}\n\n/**\n * {@link Unenforced} version of {@link TreeRecordNode}.\n * @remarks\n * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.\n * @system @sealed @beta\n */\nexport interface TreeRecordNodeUnsafe<\n\tTAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n> extends Record<string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>>,\n\t\tTreeNode {\n\t[Symbol.iterator](): IterableIterator<\n\t\t[string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>]\n\t>;\n}\n"]}

package/lib/simple-tree/core/treeNode.d.ts

@@ -20,13 +20,14 @@ import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType
  *
  * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
  * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
+ * There are also higher level APIs which wrap these, including {@link (TreeBeta:interface).create}, {@link (TreeBeta:interface).clone},
+ * and import APIs like {@link (TreeAlpha:interface).importConcise}, {@link (TreeAlpha:interface).importVerbose}, and {@link (TreeAlpha:interface).importCompressed}.
  *
  * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
- * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
+ * These APIs internally call the constructor with the provided value (typically behaving like {@link (TreeAlpha:interface).create}), so it's really just a special case of the above option.
  * Note that when constructing nodes, sometimes implicit construction is not allowed
  * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
  * in such cases, explicit construction must be used.
- *
  * @privateRemarks
  * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
  * and some runtime enforcement of schema class policy (see the the validation in the constructor).

package/lib/simple-tree/core/treeNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeNode.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAY,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;;OAKG;IAEH,aAAoB,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC;IAE/C;;;;OAIG;IACH,aAAoB,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC;IAE9D;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CACjC,OAAO,SAAS,QAAQ,MACvB,GAAG,IAAI,EAAE,GAAG,EAAE,KACV,QAAQ,EACZ,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAahE;;;;;;;OAOG;IACH,SAAS,aAAa,KAAK,EAAE,OAAO;CAKpC;AAID;;GAEG;AACH,eAAO,MAAM,YAAY,IAAK,CAAC;AAE/B;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E"}
+{"version":3,"file":"treeNode.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAY,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;;OAKG;IAEH,aAAoB,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC;IAE/C;;;;OAIG;IACH,aAAoB,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC;IAE9D;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CACjC,OAAO,SAAS,QAAQ,MACvB,GAAG,IAAI,EAAE,GAAG,EAAE,KACV,QAAQ,EACZ,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAahE;;;;;;;OAOG;IACH,SAAS,aAAa,KAAK,EAAE,OAAO;CAKpC;AAID;;GAEG;AACH,eAAO,MAAM,YAAY,IAAK,CAAC;AAE/B;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E"}

package/lib/simple-tree/core/treeNode.js

@@ -26,13 +26,14 @@ import { markEager } from "./flexList.js";
  *
  * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
  * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
+ * There are also higher level APIs which wrap these, including {@link (TreeBeta:interface).create}, {@link (TreeBeta:interface).clone},
+ * and import APIs like {@link (TreeAlpha:interface).importConcise}, {@link (TreeAlpha:interface).importVerbose}, and {@link (TreeAlpha:interface).importCompressed}.
  *
  * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
- * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
+ * These APIs internally call the constructor with the provided value (typically behaving like {@link (TreeAlpha:interface).create}), so it's really just a special case of the above option.
  * Note that when constructing nodes, sometimes implicit construction is not allowed
  * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
  * in such cases, explicit construction must be used.
- *
  * @privateRemarks
  * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
  * and some runtime enforcement of schema class policy (see the the validation in the constructor).

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

@@ -1 +1 @@
-{"version":3,"file":"treeNode.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAA4B,MAAM,qBAAqB,CAAC;AACzE,gDAAgD;AAChD,OAAO,EAAiB,cAAc,EAAyB,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAgB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AACD,gJAAgJ;AAChJ,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEpB;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,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/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { markEager } from \"./flexList.js\";\n\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes extend.\n *\n * This type 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 extending it), is not currently supported.\n *\n * There are three ways to get instances of TreeNode:\n *\n * 1. From a {@link TreeView} loading nodes from an existing document, or creating local copies of nodes inserted by a remote collaborator.\n * This case provides an {@link InternalTreeNode} to the constructor: subclasses must not modify how the constructor handles this case.\n *\n * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.\n * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.\n *\n * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.\n * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.\n * Note that when constructing nodes, sometimes implicit construction is not allowed\n * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):\n * in such cases, explicit construction must be used.\n *\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * @sealed @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 * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\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 since 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 * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\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 [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\nmarkEager(TreeNode);\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n"]}
+{"version":3,"file":"treeNode.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAA4B,MAAM,qBAAqB,CAAC;AACzE,gDAAgD;AAChD,OAAO,EAAiB,cAAc,EAAyB,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAgB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AACD,gJAAgJ;AAChJ,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEpB;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,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/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { markEager } from \"./flexList.js\";\n\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes extend.\n *\n * This type 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 extending it), is not currently supported.\n *\n * There are three ways to get instances of TreeNode:\n *\n * 1. From a {@link TreeView} loading nodes from an existing document, or creating local copies of nodes inserted by a remote collaborator.\n * This case provides an {@link InternalTreeNode} to the constructor: subclasses must not modify how the constructor handles this case.\n *\n * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.\n * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.\n * There are also higher level APIs which wrap these, including {@link (TreeBeta:interface).create}, {@link (TreeBeta:interface).clone},\n * and import APIs like {@link (TreeAlpha:interface).importConcise}, {@link (TreeAlpha:interface).importVerbose}, and {@link (TreeAlpha:interface).importCompressed}.\n *\n * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.\n * These APIs internally call the constructor with the provided value (typically behaving like {@link (TreeAlpha:interface).create}), so it's really just a special case of the above option.\n * Note that when constructing nodes, sometimes implicit construction is not allowed\n * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):\n * in such cases, explicit construction must be used.\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * @sealed @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 * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\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 since 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 * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\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 [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\nmarkEager(TreeNode);\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n"]}