@fluidframework/tree 2.117.0 → 3.0.0

package/src/text/textDomain.ts

@@ -14,15 +14,17 @@ import {
 import { typeFactory as tf } from "@fluidframework/type-factory/internal";
 
 import { EmptyKey, mapCursorField, type ITreeCursorSynchronous } from "../core/index.js";
-import { TreeAlpha } from "../shared-tree/index.js";
 import {
+	createArrayInsertionAnchor,
 	eraseSchemaDetails,
 	getInnerNode,
 	SchemaFactory,
 	SchemaFactoryAlpha,
 	TreeArrayNode,
 } from "../simple-tree/index.js";
+import { TreeBeta } from "../shared-tree/index.js";
 import type {
+	ArrayPlaceAnchor,
 	ArrayNodeDeltaOp,
 	ArrayNodeTreeChangedDeltaOp,
 	TreeNode,
@@ -176,11 +178,15 @@ class TextNode
 	public onCharactersChanged(
 		callback: (ops: readonly PlainText.TextOp[] | undefined) => void,
 	): () => void {
-		return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+		return TreeBeta.on(this.content, "nodeChanged", ({ delta }) =>
 			processCharactersChangedDelta(delta, (i) => this.content[i], callback),
 		);
 	}
 
+	public createInsertionAnchor(index: number): ArrayPlaceAnchor {
+		return createArrayInsertionAnchor(this.content, index);
+	}
+
 	public static fromString(value: string): TextNode {
 		// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its not necessary here,
 		// but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.
@@ -501,6 +507,13 @@ export namespace PlainText {
 		 * corresponds to two UTF-16 code units — convert before using the counts as string indices.
 		 */
 		onCharactersChanged(callback: (ops: readonly TextOp[] | undefined) => void): () => void;
+
+		/**
+		 * Creates an anchor that tracks an insertion point at `index` as the text is edited.
+		 * @param index - The character index of the insertion point to track.
+		 * @returns An anchor whose index updates as the text is edited. Call {@link ArrayPlaceAnchor.dispose} when it is no longer needed.
+		 */
+		createInsertionAnchor(index: number): ArrayPlaceAnchor;
 	}
 
 	/**

package/src/text/textDomainFormatted.ts

@@ -14,19 +14,20 @@ import {
 	type TreeValue,
 } from "../core/index.js";
 import { currentObserver, buildNodeComparator } from "../feature-libraries/index.js";
-import { TreeAlpha, Tree as TreeStatic } from "../shared-tree/index.js";
+import { TreeAlpha, Tree as TreeStatic, TreeBeta } from "../shared-tree/index.js";
 import {
+	createArrayInsertionAnchor,
 	getInnerNode,
 	SchemaFactory,
 	SchemaFactoryAlpha,
 	TreeArrayNode,
-	TreeBeta,
 	createCustomizedFluidFrameworkScopedFactory,
 	eraseSchemaDetails,
 	isObjectNodeSchema,
 	eraseSchemaDetailsSubclassable,
 } from "../simple-tree/index.js";
 import type {
+	ArrayPlaceAnchor,
 	TreeNodeSchema,
 	LazyItem,
 	ImplicitAllowedTypes,
@@ -390,7 +391,7 @@ export namespace FormattedText {
 			public onCharactersChanged(
 				callback: (ops: readonly PlainText.TextOp[] | undefined) => void,
 			): () => void {
-				return TreeAlpha.on(this.content, "nodeChanged", ({ delta }) =>
+				return TreeBeta.on(this.content, "nodeChanged", ({ delta }) =>
 					processCharactersChangedDelta(
 						delta,
 						(index) => this.getAtomCharacterAt(index),
@@ -399,10 +400,14 @@ export namespace FormattedText {
 				);
 			}
 
+			public createInsertionAnchor(index: number): ArrayPlaceAnchor {
+				return createArrayInsertionAnchor(this.content, index);
+			}
+
 			public onContentChanged(
 				callback: (ops: readonly PlainText.TextOp[] | undefined) => void,
 			): () => void {
-				return TreeAlpha.on(this.content, "treeChanged", ({ delta }) =>
+				return TreeBeta.on(this.content, "treeChanged", ({ delta }) =>
 					processCharactersChangedDelta(
 						delta,
 						(index) => this.getAtomCharacterAt(index),

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-	"extends": "../../../common/build/build-common/tsconfig.node16.json",
+	"extends": "../../../common/build/build-common/tsconfig.node20.json",
 	"include": ["src/**/*"],
 	"exclude": ["src/test/**/*"],
 	"compilerOptions": {

package/alpha.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/alpha.js";

package/beta.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/beta.js";

package/dist/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/dist/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/dist/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/dist/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/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/runtime-schema-upgrade.md

@@ -1,208 +0,0 @@
-# Runtime Schema Upgrade Mechanism
-
-> This document was generated by AI. It is intended for consumption by AI agents when working on this feature. Any change to the Runtime Schema Upgrade Mechanism should also update this document so future agents have current design context.
-
-## Summary
-
-Runtime schema upgrades let an application opt specific staged schema upgrades into stored schema when initializing a document or upgrading its stored schema.
-A staged schema upgrade is a schema upgrade that is declared in view schema but omitted from stored schema unless the application explicitly enables it.
-
-Enabled upgrades are provided at view construction time via `stagedUpgradePolicy` in alpha configuration passed to `viewWith`.
-The configured policy is fixed for that view instance and cannot be changed later through view APIs.
-
-This keeps the view schema and upgrade policy together in one place: the view configuration.
-Compatibility checking and schema generation both use that same construction-time upgrade set.
-
-## Problem
-
-### Testing Future Documents
-
-Problem: There is currently no easy way to create a test document that simulates a future version having completed a staged schema upgrade.
-Declaring a staged schema upgrade in the view schema is not enough to change the document: `initialize` and `upgradeSchema` only make that upgrade usable when they include it in the stored schema.
-As a result, an application cannot easily test whether the current version works correctly with documents created or upgraded by a future version.
-
-Solution: tests construct a view with an alpha configuration that includes selected staged schema upgrades which get applied to the stored schema when calling `initialize` or `upgradeSchema`.
-This makes it possible to create documents whose stored schema matches the state a future version would produce, while still running the test against the current application code.
-
-### Production Rollout Control
-
-Problem: In production, developers often need to deploy code that can read and write an upgraded schema before they are ready to enable that schema in documents.
-Without a runtime enablement mechanism, code rollout and feature rollout are coupled: once the staged schema upgrade stops being excluded from stored schema, all relevant documents may begin accepting the upgraded shape.
-This is risky for teams that need gradual rollout, monitoring, or fast rollback but do not have sophisticated slow-rollout tooling.
-
-Solution: applications derive `stagedUpgradePolicy` from feature flags and include it in view construction options.
-Code rollout can deploy support for the upgraded schema first, and feature rollout can later enable the staged schema upgrade by constructing views with the relevant `SchemaUpgrade` values.
-If the feature needs to be rolled back, applications stop constructing views with those values for documents that have not already been upgraded.
-
-The general production rollout process is:
-
-1. Deploy code that understands both the current schema and the upgraded schema.
-   Views are constructed with alpha configuration that includes `stagedUpgradePolicy`, but the flag initially leaves it as `undefined` (restrictive default).
-2. Enable the feature-rollout control.
-   New views are constructed with the relevant `SchemaUpgrade` values enabled.
-3. Existing documents are upgraded through `upgradeSchema`.
-   A schema op is sequenced for each upgraded document.
-   Once the op is in the document, all clients observe the upgraded stored schema, including clients whose local feature flag is off.
-4. New documents initialized while the control is enabled include the same staged schema upgrades from the start.
-5. If an issue is found, disable the feature-rollout control.
-   Callers stop constructing views with the relevant entries for documents that have not yet been upgraded and newly initialized documents do not include those staged schema members.
-   Note: this selective rollback plan is currently difficult in practice.
-   If a document has already enabled a staged upgrade, later calling `upgradeSchema` from a view configured without that token throws a `UsageError` because the request would narrow stored schema.
-   In most deployments it is hard to target only documents that have not already been upgraded, so this step is not generally feasible as written.
-
-Documents upgraded before the rollback continue to support the upgraded schema because their stored schema has already changed.
-Documents created after the rollback do not include that upgrade unless the flag is enabled again.
-
-## Goals
-
-- Allow callers to enable selected staged schema upgrades during `initialize`.
-- Allow callers to enable selected staged schema upgrades during `upgradeSchema`.
-- Make enabling an upgrade granular: only staged schema members associated with the supplied `SchemaUpgrade` values are included in the generated stored schema.
-- Support both production feature-flag rollouts and tests that simulate documents created or upgraded by a future application version.
-- Keep the default behavior unchanged when upgrades are omitted, `undefined`, or empty.
-- Keep view APIs immutable with respect to upgrade enablement after construction.
-- Support an easy integration-test mode that enables all staged upgrades.
-- Support composition/wrapping of generation options.
-
-## API Shape
-
-The alpha flow sets staged-upgrade policy in view construction:
-
-```typescript
-const view = tree.viewWith(
-	new TreeViewConfigurationAlpha({
-		schema: AppSchema,
-		stagedUpgradePolicy: featureFlags.enableFooUpgrade
-			? StagedSchemaUpgradePolicy.enabledStagedUpgrades(fooSchemaUpgrade)
-			: undefined,
-	}),
-);
-
-if (view.compatibility.canInitialize) {
-	view.initialize(initialContent);
-} else if (view.compatibility.canUpgrade) {
-	view.upgradeSchema();
-}
-```
-
-Key properties of this shape:
-
-- The upgrade set is fixed when the view is created.
-- `compatibility.canUpgrade`, `initialize`, and `upgradeSchema` all observe the same configured target.
-
-### Accepting `StagedSchemaUpgradePolicy`
-
-View construction accepts an optional `StagedSchemaUpgradePolicy` policy object via `TreeViewConfigurationAlpha.stagedUpgradePolicy`.
-This keeps policy selection at view construction time while allowing advanced callers to configure staged-type and staged-optional inclusion directly.
-
-The `StagedSchemaUpgradePolicy` namespace provides factory methods:
-
-- `.restrictive` — excludes all staged schema members (default when omitted).
-- `.permissive` — includes all staged schema upgrades (useful for testing).
-- `.enabledStagedUpgrades(...upgrades)` — includes only staged members guarded by the specified `SchemaUpgrade` values.
-
-```typescript
-const enabled = new Set<SchemaUpgrade>([fooSchemaUpgrade]);
-
-const view = tree.viewWith(
-	new TreeViewConfigurationAlpha({
-		schema: AppSchema,
-		stagedUpgradePolicy: {
-			includeStaged: (upgrade) => enabled.has(upgrade),
-			includeStagedOptional: (upgrade) => enabled.has(upgrade),
-		},
-	}),
-);
-```
-
-Custom policy objects conforming to `StagedSchemaUpgradePolicy` are also accepted for advanced use cases.
-
-Benefits:
-
-- Keeps schema-generation policy explicit and colocated with view construction.
-- Supports layered policy composition (base + local override) without adding mutable view APIs.
-- Preserves single-source-of-truth behavior: compatibility checks and schema generation consume the same resolved policy.
-- Enables broad integration-test scenarios (for example, all staged upgrades enabled) with `StagedSchemaUpgradePolicy.permissive`.
-
-Future consideration:
-
-- It may be useful to have the view expose the same type, `StagedSchemaUpgradePolicy`, for what is currently in the stored schema
-- That could let callers test whether a specific upgrade is already included.
-- That could clarify that the exposed policy is the default used when no custom options are declared.
-- Callers could build wrapper policies from that baseline instead of reconstructing it.
-
-## Why Construction-Time Upgrades?
-
-Construction-time configuration keeps staged-upgrade policy colocated with the view schema and avoids mutable runtime policy on the view instance.
-That has practical benefits:
-
-- Eliminates ordering concerns between view creation, compatibility reads, and upgrade declaration calls.
-- Prevents accidental policy drift on a long-lived view.
-- Ensures compatibility checks and schema writes always use the same immutable policy for a given view.
-- Makes testing deterministic because each view clearly represents one schema+upgrade configuration.
-
-## Initialization Versus Upgrade
-
-`initialize(...)` and `upgradeSchema()` both use the configured upgrades but affect different scenarios:
-
-- `upgradeSchema()` upgrades existing document stored schema.
-- `initialize(...)` writes initial stored schema and content for new documents.
-
-The insertion/validation path for initialization must use the same generated schema target as compatibility and upgrade paths.
-
-## Implementation Notes
-
-Stored schema generation remains based on `toUpgradeSchema(root, options?)` and `toInitialSchema(root, options?)`.
-The view is responsible for passing `stagedUpgradePolicy` from construction-time configuration to these helpers.
-
-`StagedSchemaUpgradePolicy.restrictive` and `StagedSchemaUpgradePolicy.permissive` provide built-in defaults for "none" and "all" staged-upgrade inclusion.
-`StagedSchemaUpgradePolicy.enabledStagedUpgrades(...upgrades)` converts a collection of `SchemaUpgrade` values into generation options.
-The `stagedUpgradePolicy` field on `ITreeViewConfigurationAlpha` is used directly as the source policy for compatibility and schema generation.
-
-Behavioral requirements:
-
-- No configured options (or `undefined`) means restrictive default behavior.
-- Configured options enable only staged members guarded by matching `SchemaUpgrade` values.
-- `upgradeSchema()` is a no-op when stored schema is already a superset of the configured target.
-- `upgradeSchema()` throws when the configured target is not a valid repo superset of current stored schema.
-
-## Testing Strategy
-
-Tests should cover both API entry points, the staged schema member kinds that are currently supported, and rollback-oriented production behavior.
-
-Generic runtime API tests should cover shared behavior such as creating a view with `stagedUpgradePolicy` and calling `initialize(content)` to accept enabled staged content, while rejecting that content when options are not configured.
-More specialized staged schema tests should exercise configured options with `upgradeSchema()` for each staged schema feature, such as staged allowed types and staged optional fields.
-
-When `StagedSchemaUpgradePolicy` is accepted at view construction, tests should also cover custom policy-object configuration paths in addition to the namespace factory methods.
-
-For `upgradeSchema`:
-
-- Create a document with the current schema.
-- Construct a view with configured upgrades.
-- Call `upgradeSchema()`.
-- Verify the stored schema includes the staged schema members guarded by the configured upgrade token.
-- Verify clients using a view configuration that omits that token observe expected compatibility/upgrade behavior.
-
-For `initialize`:
-
-- Construct a view with configured upgrades and initialize a new document with `initialize(content)`.
-- Use initial content that requires the upgraded schema.
-- Verify the content is accepted and the stored schema includes the enabled staged schema upgrade.
-- Verify constructing a view without upgrades rejects or excludes content that depends on that upgrade, matching existing restrictive behavior.
-
-For feature-flag rollback behavior:
-
-- Verify documents created or upgraded while the flag is enabled retain the upgraded stored schema.
-- Verify documents created after the flag is disabled omit the upgraded schema when callers construct views without the corresponding upgrade entry.
-
-Schema compatibility helper tests should remain schema-only.
-They can validate compatibility across staged rollout states by comparing stored schema snapshots, but they should not be used as substitutes for runtime tests that sequence schema edits through `initialize` or `upgradeSchema`.
-
-## Compatibility Notes
-
-Enabling a staged schema upgrade changes document stored schema through the existing schema update mechanism.
-Once the schema change is sequenced, the document state is authoritative.
-Clients should not need their local feature flag to be enabled in order to read a document whose stored schema already includes the upgrade, provided their code version understands that schema.
-
-The `upgrades` property names are not persisted.
-Compatibility depends on the schema and the `SchemaUpgrade` values, not on the application-specific flag names used at call sites.

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";