@fluidframework/tree 2.118.0 → 3.0.0

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

@@ -1,83 +0,0 @@
-"use strict";
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TreeBeta = exports.exportConcise = exports.importConcise = exports.borrowCursorFromTreeNodeOrValue = void 0;
-const index_js_1 = require("../../feature-libraries/index.js");
-const index_js_2 = require("../../util/index.js");
-const index_js_3 = require("../core/index.js");
-const createContext_js_1 = require("../createContext.js");
-const unhydratedFlexTreeFromInsertable_js_1 = require("../unhydratedFlexTreeFromInsertable.js");
-const conciseTree_js_1 = require("./conciseTree.js");
-const create_js_1 = require("./create.js");
-const treeNodeApi_js_1 = require("./treeNodeApi.js");
-const verboseTree_js_1 = require("./verboseTree.js");
-/**
- * Borrow a cursor from a node.
- * @remarks
- * The cursor must be put back to its original location before the node is used again.
- */
-function borrowCursorFromTreeNodeOrValue(node) {
-    if ((0, index_js_1.isTreeValue)(node)) {
-        return (0, verboseTree_js_1.cursorFromVerbose)(node, {});
-    }
-    const kernel = (0, index_js_3.getKernel)(node);
-    const cursor = kernel.getInnerNode().borrowCursor();
-    return cursor;
-}
-exports.borrowCursorFromTreeNodeOrValue = borrowCursorFromTreeNodeOrValue;
-function importConcise(schema, data) {
-    // Create the tree content from insertable data
-    const mapTree = (0, unhydratedFlexTreeFromInsertable_js_1.unhydratedFlexTreeFromInsertable)(data, schema);
-    const result = mapTree === undefined ? undefined : (0, index_js_3.getOrCreateNodeFromInnerNode)(mapTree);
-    return result;
-}
-exports.importConcise = importConcise;
-function exportConcise(node, options) {
-    if (!(0, index_js_3.isTreeNode)(node)) {
-        return node;
-    }
-    const config = { ...options };
-    const kernel = (0, index_js_3.getKernel)(node);
-    const cursor = borrowCursorFromTreeNodeOrValue(node);
-    return (0, conciseTree_js_1.conciseFromCursor)(cursor, kernel.context, config);
-}
-exports.exportConcise = exportConcise;
-/**
- * Extensions to {@link (Tree:variable)} which are not yet stable.
- * @see {@link (TreeBeta:interface)}.
- * @beta
- */
-exports.TreeBeta = {
-    on(node, eventName, listener) {
-        return treeNodeApi_js_1.treeNodeApi.on(node, eventName, listener);
-    },
-    importConcise,
-    exportConcise,
-    clone(node) {
-        // The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.
-        if (!(0, index_js_3.isTreeNode)(node)) {
-            return node;
-        }
-        const kernel = (0, index_js_3.getKernel)(node);
-        const cursor = kernel.getInnerNode().borrowCursor();
-        // To handle when the node transitively contains unknown optional fields,
-        // derive the context from the source node's stored schema which has stored schema for any such fields and their contents.
-        const flexContext = new index_js_3.UnhydratedContext(index_js_1.defaultSchemaPolicy, kernel.context.flexContext.schema);
-        const context = new index_js_3.Context(flexContext, (0, createContext_js_1.getUnhydratedContext)(kernel.schema).schema);
-        const fieldSchema = {
-            kind: index_js_1.FieldKinds.required.identifier,
-            types: new Set([(0, index_js_2.brand)(kernel.schema.identifier)]),
-            persistedMetadata: undefined,
-        };
-        return (0, create_js_1.createFromCursor)(kernel.schema, cursor, fieldSchema, context);
-    },
-    create(schema, data) {
-        const mapTree = (0, unhydratedFlexTreeFromInsertable_js_1.unhydratedFlexTreeFromInsertable)(data, schema);
-        const result = mapTree === undefined ? undefined : (0, index_js_3.getOrCreateNodeFromInnerNode)(mapTree);
-        return result;
-    },
-};
-//# sourceMappingURL=treeBeta.js.map

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

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

package/docs/main/glossary.md

@@ -1,163 +0,0 @@
-# SharedTree Glossary
-
-This glossary defines core concepts used throughout SharedTree's design and implementation, ordered
-roughly from the simplest/most foundational concepts to the more complex ones that build on them.
-It is intended as a reference for developers working on SharedTree internals (rather than the public
-consumer-facing API).
-
-## Node
-
-An addressable piece of tree data. Every SharedTree document is made of nodes; there is always an
-implicit root node. A node may have an optional [value](#value) and a set of [fields](#field).
-See [data-model.md](./data-model.md#node).
-
-## Value
-
-The optional scalar payload (e.g. a number, string, or boolean) stored on a node. Values are opaque,
-immutable byte sequences from the data model's perspective. See [data-model.md](./data-model.md#value).
-
-## Field
-
-A named relationship between a parent node and an ordered sequence of child nodes. Fields are
-distinguished by a field *key*. See [data-model.md](./data-model.md#field).
-
-## Cell
-
-A conceptual unit of storage within a field's sequence that never moves and never disappears; it may be
-*empty* or *full*. Higher level concepts like insertion, removal, and moving of content are built on top
-of allocating, filling, clearing, and forwarding cells. See
-[cell-model-of-collaborative-editing.md](./cell-model-of-collaborative-editing.md).
-
-## Anchor
-
-A stable reference to a location in the tree (e.g. a node or a position in a field) that remains valid
-across edits, even as the tree changes shape around it. Anchors are how application code and internal
-logic keep track of "the same place" over time without holding onto stale node identities.
-
-## Forest
-
-The in-memory data structure that stores the current state of the tree's content, indexed for efficient
-navigation and editing (analogous to a forest of trees in the graph-theory sense). A `ForestIndex` is one
-example of an [index](#index) that provides this functionality.
-See [indexes-and-branches.md](./indexes-and-branches.md#indexes).
-
-## Index
-
-A piece of state, derived from and kept up to date by the document's edit history, that answers queries
-about the tree (analogous to a database index). Indexes own all persisted document data; the forest and
-schema are both implemented as indexes. See [indexes-and-branches.md](./indexes-and-branches.md#indexes).
-
-## Changeset
-
-The data describing the edit(s) made by a single [commit](#commit) — i.e., the concrete representation of
-"what changed." Changesets are produced, composed, inverted, and rebased against one another by a
-`ChangeFamily`/`Rebaser` implementation. See
-[modular-change-family.md](./modular-change-family.md).
-
-## Delta
-
-A derived, lower-level description of the concrete effects of a changeset on the tree's content (e.g.
-"insert this content here," "remove this content there"), used to actually update the [forest](#forest)
-and notify listeners, as opposed to the changeset's richer, rebasable representation.
-
-## Revision / Revision tag
-
-A unique identifier (`RevisionTag`) assigned to a [commit](#commit). Commits that are rebased but remain
-semantically the same operation retain the same revision tag across rebases.
-
-## Commit
-
-A node in a graph of changes: it pairs a [changeset](#changeset) with a [revision tag](#revision--revision-tag)
-and a reference to its parent commit (the commit its change is based on). A sequence of commits linked by
-parentage forms a [branch](#branch).
-
-## Op
-
-The Fluid Framework's unit of an operation sent over the wire to the ordering service and other clients.
-Roughly speaking, a local [commit](#commit) becomes an op when it is submitted, and an op becomes a
-sequenced commit on the [trunk](#trunk) once it is acknowledged/ordered by the service.
-
-## Sequence number
-
-The order assigned to an op by the Fluid ordering (sequencing) service once it has been totally ordered
-relative to all other ops. This is what makes the [trunk](#trunk) a single, canonical timeline.
-
-## Rebase
-
-The operation of taking a commit (or a chain of commits) whose change was computed against one base state
-and re-expressing it as an equivalent change against a different (usually newer) base state. Rebasing is
-central to how SharedTree reconciles concurrent edits from different clients/branches.
-
-## Branch
-
-A timeline of a document's state as viewed from a particular perspective — the same concept as a branch in
-version control. A branch is represented internally as a chain of [commits](#commit) sharing a common
-ancestry. See [indexes-and-branches.md](./indexes-and-branches.md#branches).
-
-## Trunk
-
-The branch consisting of every commit that has been sequenced by the Fluid ordering service, in the
-canonical order chosen by that service. The trunk is append-only (commits on it are never rebased or
-reset). It is analogous to a `main` branch in `git` that is only updated by merging in already-agreed-upon
-history. See [indexes-and-branches.md](./indexes-and-branches.md#branches).
-
-## Trunk base
-
-A special, non-sequenced commit that serves as the root/tail of the trunk, allowing the trunk to be
-modeled uniformly with any other branch (as something that "branches off of" a base commit). As trunk
-commits are evicted/trimmed (once every client has seen them), the most recently evicted commit becomes
-the new trunk base.
-
-## Main branch
-
-Commonly used to refer to the primary shared document branch, i.e. the [trunk](#trunk) plus the current
-client's [local branch](#local-branch) of not-yet-sequenced edits. In `git` terms, this is the combination
-of the shared upstream history and the local commits not yet merged into it.
-
-## Local branch
-
-The [trunk](#trunk), plus any edits made locally that have not yet been sequenced (acknowledged by the
-service). This is analogous to a local feature branch in `git` that gets rebased onto `main` every time
-`main` advances. See [indexes-and-branches.md](./indexes-and-branches.md#branches).
-
-## Peer branch / remote branch
-
-A branch that replicates the local branch state a *remote* client had at the time it sent an op, used so
-that the receiving client can correctly rebase that peer's edit relative to the trunk and other peers'
-edits. Every connected client's outstanding edits are tracked this way.
-
-## Working copy
-
-The [local branch](#local-branch) plus the state of any in-progress (not yet committed) transaction. This
-is analogous to the uncommitted changes in a `git` working copy on top of a checked-out branch.
-
-## Transaction
-
-A group of edits applied together as a single logical unit and represented as a single [commit](#commit).
-Transactions may be nested, in which case their `customMetadata` is combined into a tree reflecting that
-nesting.
-
-## Session
-
-A single connected client's identity/context (`SessionId`) for the purposes of generating and attributing
-[commits](#commit). Every commit records (directly or via its revision tag) the session that authored it.
-
-## Summary / Summarization
-
-The Fluid mechanism by which a client serializes the current document state (including all
-[indexes](#index), such as the forest and schema) so that new or reconnecting clients can load the
-document without replaying the entire edit history. See
-[indexes-and-branches.md](./indexes-and-branches.md#indexes).
-
-## Reference (durable reference)
-
-A lightweight, stable way to point at a particular node via its special *id* field, independent of the
-node's current position in the tree — the basis for features like "share link" URLs and graph-like
-relationships within the tree. See [data-model.md](./data-model.md#id).
-
-## Long-lived branch
-
-A branch explicitly created by a user/application that can persist independently of the [main
-branch](#main-branch) for extended periods (e.g. feature branches, release branches, or offline work).
-Not currently implemented/supported by SharedTree, but considered in forward-looking designs. See
-[indexes-and-branches.md](./indexes-and-branches.md#branches).

package/internal.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate node10Entrypoints" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/entrypoints/internal.js";

package/legacy.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate node10Entrypoints" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/entrypoints/legacy.js";

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

@@ -1,126 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { NodeKind, TreeNode, WithType } from "../core/index.js";
-import type { TreeChangeEventsBeta } from "./treeBeta.js";
-import type { TreeChangeEvents } from "./treeChangeEvents.js";
-import type { ArrayNodeDeltaOp, ArrayNodeTreeChangedDeltaOp } from "./treeNodeApi.js";
-export type { ArrayNodeDeltaOp, ArrayNodeInsertOp, ArrayNodeRemoveOp, ArrayNodeRetainOp, ArrayNodeTreeChangedDeltaOp, ArrayNodeTreeChangedRetainOp, } from "./treeNodeApi.js";
-/**
- * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
- * @sealed @alpha
- */
-export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {
-    /**
-     * Lists all the properties which changed on the node.
-     * @remarks
-     * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
-     *
-     * 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.
-     */
-    readonly changedProperties: ReadonlySet<TNode extends WithType<string, NodeKind.Object, infer TInfo> ? string & keyof TInfo : string>;
-}
-/**
- * Data carried by the {@link TreeChangeEventsAlpha.nodeChanged} event for array nodes.
- * @sealed @alpha
- */
-export interface NodeChangedDataDelta {
-    /**
-     * The sequential operations describing what changed in the array node.
-     * @remarks
-     * The value may be `undefined` when the document was updated in a way that required multiple
-     * internal change passes in a single operation (for example, a data change combined with a
-     * schema upgrade).
-     *
-     * See {@link ArrayNodeDeltaOp} for op semantics.
-     */
-    readonly delta: readonly ArrayNodeDeltaOp[] | undefined;
-}
-/**
- * Data carried by the {@link TreeChangeEventsAlpha.treeChanged} event for array nodes.
- * @remarks
- * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a
- * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant
- * of the retained element changed.
- * @sealed @alpha
- */
-export interface NodeChangedDataTreeDelta {
-    /**
-     * The sequential operations describing what changed in the array node,
-     * including subtree-change information on retain ops.
-     * @remarks
-     * The value may be `undefined` when the document was updated in a way that required multiple
-     * internal change passes in a single operation (for example, a data change combined with a
-     * schema upgrade).
-     *
-     * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.
-     */
-    readonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;
-}
-/**
- * The data passed to {@link TreeChangeEventsAlpha.nodeChanged} and, for array nodes,
- * to {@link TreeChangeEventsAlpha.treeChanged}.
- * @remarks
- * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).
- * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).
- * - For a generic/unknown node type: the union of both.
- * @alpha
- */
-export type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> = TNode extends WithType<string, NodeKind.Array> ? NodeChangedDataDelta : TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record> ? NodeChangedDataProperties<TNode> : NodeChangedDataProperties<TNode> | NodeChangedDataDelta;
-/**
- * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event and a
- * delta-carrying `treeChanged` event for array nodes.
- * @remarks
- * Provides a `nodeChanged` event that includes a delta payload for array nodes and
- * requires `changedProperties` for object, map, and record nodes.
- * Also provides a `treeChanged` event that, for array nodes, carries a {@link NodeChangedDataDelta}
- * payload describing both shallow and deep changes.
- * For non-array nodes, the `treeChanged` signature is the same as the base event.
- *
- * Use via `TreeAlpha.on`.
- * @sealed @alpha
- */
-export interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode> extends TreeChangeEvents {
-    /**
-     * Emitted when a shallow change occurs on this node, i.e., when the node's direct children change.
-     *
-     * @remarks
-     * For array nodes: the event data includes a {@link NodeChangedDataDelta.delta | delta} payload
-     * as a sequence of {@link ArrayNodeDeltaOp} values. Does not fire for deep changes (e.g. a
-     * property of an array element changed without any shallow array change). Subscribe to
-     * {@link TreeChangeEventsAlpha.treeChanged} on the array to receive a delta for those cases as well.
-     *
-     * For object, map, and record nodes: the event data includes
-     * {@link NodeChangedDataProperties.changedProperties | changedProperties}.
-     * @privateRemarks
-     * 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.
-     */
-    nodeChanged: (data: NodeChangedDataAlpha<TNode>) => void;
-    /**
-     * Emitted when something in the subtree rooted at this node changes.
-     *
-     * @remarks
-     * For array nodes: emitted when any change occurred within the array, including both
-     * shallow changes (insert, remove, move) and deep changes (e.g. a property of an element
-     * changed). The event data carries a {@link NodeChangedDataTreeDelta.delta | delta} payload
-     * describing what changed. The delta uses {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
-     * to flag elements that have deep changes, without describing the details of those deep changes.
-     * To inspect deep changes, subscribe to `nodeChanged` or `treeChanged` on the individual
-     * element nodes.
-     *
-     * When this array is nested inside another array, the outer array's `treeChanged` still
-     * fires with a delta, but that delta only shows `subtreeChanged: true` for the element
-     * position containing this inner array — it does not include the inner array's detailed
-     * insert/remove/retain ops. To receive those detailed ops, subscribe to `treeChanged`
-     * directly on the inner array.
-     * Ancestor non-array nodes still receive the base (no-payload) `treeChanged` via normal
-     * subtree propagation.
-     *
-     * For non-array nodes: same as the base {@link TreeChangeEvents.treeChanged}.
-     * @privateRemarks
-     * 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.
-     */
-    treeChanged: TNode extends WithType<string, NodeKind.Array> ? (data: NodeChangedDataTreeDelta) => void : TreeChangeEventsBeta<TNode>["treeChanged"];
-}
-//# sourceMappingURL=treeAlpha.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"treeAlpha.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeAlpha.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACtF,YAAY,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,MAAM,WAAW,yBAAyB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAC3E;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAEtC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,IACjE,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GAC3C,oBAAoB,GACpB,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC/E,yBAAyB,CAAC,KAAK,CAAC,GAChC,yBAAyB,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACvE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,WAAW,EAAE,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxD,CAAC,IAAI,EAAE,wBAAwB,KAAK,IAAI,GACxC,oBAAoB,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC;CAC9C"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"treeAlpha.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeAlpha.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 { NodeKind, TreeNode, WithType } from \"../core/index.js\";\n\nimport type { TreeChangeEventsBeta } from \"./treeBeta.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport type { ArrayNodeDeltaOp, ArrayNodeTreeChangedDeltaOp } from \"./treeNodeApi.js\";\nexport type {\n\tArrayNodeDeltaOp,\n\tArrayNodeInsertOp,\n\tArrayNodeRemoveOp,\n\tArrayNodeRetainOp,\n\tArrayNodeTreeChangedDeltaOp,\n\tArrayNodeTreeChangedRetainOp,\n} from \"./treeNodeApi.js\";\n\n/**\n * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.\n * @sealed @alpha\n */\nexport interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {\n\t/**\n\t * Lists all the properties which changed on the node.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t *\n\t * 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, strongly type 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 * Data carried by the {@link TreeChangeEventsAlpha.nodeChanged} event for array nodes.\n * @sealed @alpha\n */\nexport interface NodeChangedDataDelta {\n\t/**\n\t * The sequential operations describing what changed in the array node.\n\t * @remarks\n\t * The value may be `undefined` when the document was updated in a way that required multiple\n\t * internal change passes in a single operation (for example, a data change combined with a\n\t * schema upgrade).\n\t *\n\t * See {@link ArrayNodeDeltaOp} for op semantics.\n\t */\n\treadonly delta: readonly ArrayNodeDeltaOp[] | undefined;\n}\n\n/**\n * Data carried by the {@link TreeChangeEventsAlpha.treeChanged} event for array nodes.\n * @remarks\n * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a\n * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant\n * of the retained element changed.\n * @sealed @alpha\n */\nexport interface NodeChangedDataTreeDelta {\n\t/**\n\t * The sequential operations describing what changed in the array node,\n\t * including subtree-change information on retain ops.\n\t * @remarks\n\t * The value may be `undefined` when the document was updated in a way that required multiple\n\t * internal change passes in a single operation (for example, a data change combined with a\n\t * schema upgrade).\n\t *\n\t * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.\n\t */\n\treadonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;\n}\n\n/**\n * The data passed to {@link TreeChangeEventsAlpha.nodeChanged} and, for array nodes,\n * to {@link TreeChangeEventsAlpha.treeChanged}.\n * @remarks\n * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).\n * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).\n * - For a generic/unknown node type: the union of both.\n * @alpha\n */\nexport type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> =\n\tTNode extends WithType<string, NodeKind.Array>\n\t\t? NodeChangedDataDelta\n\t\t: TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>\n\t\t\t? NodeChangedDataProperties<TNode>\n\t\t\t: NodeChangedDataProperties<TNode> | NodeChangedDataDelta;\n\n/**\n * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event and a\n * delta-carrying `treeChanged` event for array nodes.\n * @remarks\n * Provides a `nodeChanged` event that includes a delta payload for array nodes and\n * requires `changedProperties` for object, map, and record nodes.\n * Also provides a `treeChanged` event that, for array nodes, carries a {@link NodeChangedDataDelta}\n * payload describing both shallow and deep changes.\n * For non-array nodes, the `treeChanged` signature is the same as the base event.\n *\n * Use via `TreeAlpha.on`.\n * @sealed @alpha\n */\nexport interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/**\n\t * Emitted when a shallow change occurs on this node, i.e., when the node's direct children change.\n\t *\n\t * @remarks\n\t * For array nodes: the event data includes a {@link NodeChangedDataDelta.delta | delta} payload\n\t * as a sequence of {@link ArrayNodeDeltaOp} values. Does not fire for deep changes (e.g. a\n\t * property of an array element changed without any shallow array change). Subscribe to\n\t * {@link TreeChangeEventsAlpha.treeChanged} on the array to receive a delta for those cases as well.\n\t *\n\t * For object, map, and record nodes: the event data includes\n\t * {@link NodeChangedDataProperties.changedProperties | changedProperties}.\n\t * @privateRemarks\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: (data: NodeChangedDataAlpha<TNode>) => void;\n\n\t/**\n\t * Emitted when something in the subtree rooted at this node changes.\n\t *\n\t * @remarks\n\t * For array nodes: emitted when any change occurred within the array, including both\n\t * shallow changes (insert, remove, move) and deep changes (e.g. a property of an element\n\t * changed). The event data carries a {@link NodeChangedDataTreeDelta.delta | delta} payload\n\t * describing what changed. The delta uses {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}\n\t * to flag elements that have deep changes, without describing the details of those deep changes.\n\t * To inspect deep changes, subscribe to `nodeChanged` or `treeChanged` on the individual\n\t * element nodes.\n\t *\n\t * When this array is nested inside another array, the outer array's `treeChanged` still\n\t * fires with a delta, but that delta only shows `subtreeChanged: true` for the element\n\t * position containing this inner array — it does not include the inner array's detailed\n\t * insert/remove/retain ops. To receive those detailed ops, subscribe to `treeChanged`\n\t * directly on the inner array.\n\t * Ancestor non-array nodes still receive the base (no-payload) `treeChanged` via normal\n\t * subtree propagation.\n\t *\n\t * For non-array nodes: same as the base {@link TreeChangeEvents.treeChanged}.\n\t * @privateRemarks\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\ttreeChanged: TNode extends WithType<string, NodeKind.Array>\n\t\t? (data: NodeChangedDataTreeDelta) => void\n\t\t: TreeChangeEventsBeta<TNode>[\"treeChanged\"];\n}\n"]}

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

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

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

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