@fluidframework/tree 2.1.0-281041 → 2.2.0

package/.mocharc.customBenchmarks.cjs

@@ -0,0 +1,33 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Mocha configuration file to run memory-profiling tests
+ */
+"use strict";
+
+const getFluidTestMochaConfig = require("@fluid-internal/mocha-test-setup/mocharc-common");
+
+const packageDir = __dirname;
+const baseConfig = getFluidTestMochaConfig(packageDir);
+
+const nodeOptions =
+	baseConfig["node-option"] !== undefined
+		? Array.isArray(baseConfig["node-option"])
+			? baseConfig["node-option"]
+			: [baseConfig["node-option"]] // If string, wrap as array to use spread operator
+		: []; // If undefined, use an empty array
+
+nodeOptions.push("expose-gc", "gc-global", "unhandled-rejections=strict");
+
+module.exports = {
+	...baseConfig,
+	"fgrep": ["@CustomBenchmark"],
+	"node-option": nodeOptions, // without leading "--"
+	"recursive": true,
+	"reporter": "@fluid-tools/benchmark/dist/MochaReporter.js",
+	"reporterOptions": ["reportDir=.customBenchmarksOutput/"],
+	"spec": ["lib/test/**/*.*js"],
+};

package/.vscode/Tree.code-workspace

@@ -18,6 +18,7 @@
 			"**/node_modules/**/@fluid*/*-previous",
 			"**/node_modules/**/@fluid*/*-previous/*"
 		],
-		"typescript.preferences.importModuleSpecifier": "project-relative"
+		"typescript.preferences.importModuleSpecifier": "project-relative",
+		"typescript.preferences.preferTypeOnlyAutoImports": true
 	}
 }

package/CHANGELOG.md

@@ -1,5 +1,340 @@
 # @fluidframework/tree
 
+## 2.2.0
+
+### Minor Changes
+
+-   Compile-time type narrowing based on a TreeNode's NodeKind ([#22222](https://github.com/microsoft/FluidFramework/pull/22222)) [4d3bc876ae](https://github.com/microsoft/FluidFramework/commit/4d3bc876ae32fa3f2568299e29246f6970e48ee0)
+
+    `TreeNode`'s schema-aware APIs implement `WithType`, which now has a `NodeKind` parameter that can be used to narrow `TreeNode`s based on `NodeKind`.
+
+    Example:
+
+    ```typescript
+    function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];
+    function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];
+    function getKeys(node: TreeNode): string[] | number[];
+    function getKeys(node: TreeNode): string[] | number[] {
+    	const schema = Tree.schema(node);
+    	switch (schema.kind) {
+    		case NodeKind.Array: {
+    			const arrayNode = node as TreeArrayNode;
+    			const keys: number[] = [];
+    			for (let index = 0; index < arrayNode.length; index++) {
+    				keys.push(index);
+    			}
+    			return keys;
+    		}
+    		case NodeKind.Map:
+    			return [...(node as TreeMapNode).keys()];
+    		case NodeKind.Object:
+    			return Object.keys(node);
+    		default:
+    			throw new Error("Unsupported Kind");
+    	}
+    }
+    ```
+
+-   ✨ New! `Record`-typed objects can now be used to construct MapNodes ([#22042](https://github.com/microsoft/FluidFramework/pull/22042)) [25deff344b](https://github.com/microsoft/FluidFramework/commit/25deff344b447380486c1efb64ed69177c32ddc5)
+
+    You can now construct MapNodes from `Record` typed objects, similar to how maps are expressed in JSON.
+
+    Before this change, an `Iterable<string, Child>` was required, but now an object like `{key1: Child1, key2: Child2}` is allowed.
+
+    Full example using this new API:
+
+    ```typescript
+    class Schema extends schemaFactory.map("ExampleMap", schemaFactory.number) {}
+    const fromRecord = new Schema({ x: 5 });
+    ```
+
+    This new feature makes it possible for schemas to construct a tree entirely from JSON-compatible objects using their constructors,
+    as long as they do not require unhydrated nodes to differentiate ambiguous unions,
+    or IFluidHandles (which themselves are not JSON compatible).
+
+    Due to limitations of TypeScript and recursive types,
+    recursive maps do not advertise support for this feature in their typing,
+    but it works at runtime.
+
+-   New SharedTree configuration option: `ITreeConfigurationOptions.preventAmbiguity` ([#22048](https://github.com/microsoft/FluidFramework/pull/22048)) [966906a034](https://github.com/microsoft/FluidFramework/commit/966906a03490daa5a914030b37342abb8267c12d)
+
+    The new `ITreeConfigurationOptions.preventAmbiguity` flag can be set to true to enable checking of some additional rules when constructing the `TreeViewConfiguration`.
+
+    This example shows an ambiguous schema:
+
+    ```typescript
+    const schemaFactory = new SchemaFactory("com.example");
+    class Feet extends schemaFactory.object("Feet", { length: schemaFactory.number }) {}
+    class Meters extends schemaFactory.object("Meters", { length: schemaFactory.number }) {}
+    const config = new TreeViewConfiguration({
+    	// This combination of schema can lead to ambiguous cases, and will error since preventAmbiguity is true.
+    	schema: [Feet, Meters],
+    	preventAmbiguity: true,
+    });
+    const view = tree.viewWith(config);
+    // This is invalid since it is ambiguous which type of node is being constructed.
+    // The error thrown above when constructing the TreeViewConfiguration is because of this ambiguous case:
+    view.initialize({ length: 5 });
+    ```
+
+    See the documentation on `ITreeConfigurationOptions.preventAmbiguity` for a more complete example and more details.
+
+-   `Tree.schema` now returns `TreeNodeSchema` ([#22185](https://github.com/microsoft/FluidFramework/pull/22185)) [bfe8310a94](https://github.com/microsoft/FluidFramework/commit/bfe8310a9406a8658c2fac8827c7114844c32234)
+
+    The typing of `Tree.schema` has changed from:
+
+    ```typescript
+    schema<T extends TreeNode | TreeLeafValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T>;
+    ```
+
+    to:
+
+    ```typescript
+    schema(node: TreeNode | TreeLeafValue): TreeNodeSchema;
+    ```
+
+    The runtime behavior is unaffected: any code which worked and still compiles is fine and does not need changes.
+
+    `Tree.schema` was changed to mitigate two different issues:
+
+    1. It tried to give a more specific type based on the type of the passed in value.
+       When the type of the input is not known precisely (for example it is a union of node types like `Foo | Bar`, or `TreeNode` or even `TreeNode | TreeLeafValue`), this was fine since schema are covariant over their node type.
+       However when the input was more specific that the schema type, for example the type is simply `0`, this would result in unsound typing, since the create function could actually return values that did not conform with that schema (for example `schema.create(1)` for the number schema typed with `0` would return `1` with type `0`).
+    2. The node type was provided to the incorrect type parameter of TreeNodeSchema.
+       The `TNode` parameter is the third one, not the fourth.
+       The fourth is `TBuild` which sets the input accepted to its create function or constructor.
+       Thus this code accidentally left `TNode` unset (which is good due to the above issue), but invalidly set `TBuild`.
+       `TBuild` is contravariant, so it has the opposite issue that setting `TNode` would have: if your input is simply typed as something general like `TreeNode`, then the returned schema would claim to be able to construct an instance given any `TreeNode`.
+       This is incorrect, and this typing has been removed.
+
+    Fortunately it should be rare for code to be impacted by this issue.
+    Any code which manually specified a generic type parameter to `Tree.schema()` will break, as well as code which assigned its result to an overly specifically typed variable.
+    Code which used `typeof` on the returned schema could also break, though there are few use-cases for this so such code is not expected to exist.
+    Currently it's very difficult to invoke the create function or constructor associated with a `TreeNodeSchema` as doing so already requires narrowing to `TreeNodeSchemaClass` or `TreeNodeSchemaNonClass`.
+    It is possible some such code exists which will need to have an explicit cast added because it happened to work with the more specific (but incorrect) constructor input type.
+
+-   Recursive SharedTree schemas using MapNodes no longer produce invalid d.ts files ([#22106](https://github.com/microsoft/FluidFramework/pull/22106)) [554fc5a94e](https://github.com/microsoft/FluidFramework/commit/554fc5a94e57e2d109ea9008b7c64517c58a6b73)
+
+    Consider a recursive SharedTree schema like the following, which follows all our recommended best practices:
+
+    ```typescript
+    export class RecursiveMap extends schema.mapRecursive("RM", [() => RecursiveMap]) {}
+    {
+    	type _check = ValidateRecursiveSchema<typeof RecursiveMap>;
+    }
+    ```
+
+    This schema would work when used from within its compilation unit, but would generate d.ts that fails to compile when exporting it:
+
+    ```typescript
+    declare const RecursiveMap_base: import("@fluidframework/tree").TreeNodeSchemaClass<
+    	"com.example.RM",
+    	import("@fluidframework/tree").NodeKind.Map,
+    	import("@fluidframework/tree").TreeMapNodeUnsafe<readonly [() => typeof RecursiveMap]> &
+    		import("@fluidframework/tree").WithType<"com.example.RM">,
+    	{
+    		[Symbol.iterator](): Iterator<[string, RecursiveMap], any, undefined>;
+    	},
+    	false,
+    	readonly [() => typeof RecursiveMap]
+    >;
+    export declare class RecursiveMap extends RecursiveMap_base {}
+    ```
+
+    This results in the compile error in TypeScript 5.4.5:
+
+    > error TS2310: Type 'RecursiveMap' recursively references itself as a base type.
+
+    With this change, that error is fixed by modifying the `TreeMapNodeUnsafe` type it references to inline the definition of `ReadonlyMap` instead of using the one from the TypeScript standard library.
+
+-   ✨ New! When unambiguous, ArrayNodes can now be constructed from Maps and MapNodes from arrays ([#22036](https://github.com/microsoft/FluidFramework/pull/22036)) [25e74f9f3b](https://github.com/microsoft/FluidFramework/commit/25e74f9f3bed6e6ff041c088813c4cc1ea276b9c)
+
+    Since the types for ArrayNodes and MapNodes indicate they can be constructed from iterables,
+    it should work, even if those iterables are themselves arrays or maps.
+    To avoid this being a breaking change, a priority system was introduced.
+    ArrayNodes will only be implicitly constructable from JavaScript Map objects in contexts where no MapNodes are allowed.
+    Similarly MapNodes will only be implicitly constructable from JavaScript Array objects in contexts where no ArrayNodes are allowed.
+
+    In practice, the main case in which this is likely to matter is when implicitly constructing a map node. If you provide an array of key value pairs, this now works instead of erroring, as long as no ArrayNode is valid at that location in the tree.
+
+    ```typescript
+    class MyMapNode extends schemaFactory.map("x", schemaFactory.number) {}
+    class Root extends schemaFactory.object("root", { data: MyMapNode }) {}
+    // This now works (before it compiled, but error at runtime):
+    const fromArray = new Root({ data: [["x", 5]] });
+    ```
+
+    Prior versions used to have to do:
+
+    ```typescript
+    new Root({ data: new MyMapNode([["x", 5]]) });
+    ```
+
+    or:
+
+    ```typescript
+    new Root({ data: new Map([["x", 5]]) });
+    ```
+
+    Both of these options still work: strictly more cases are allowed with this change.
+
+-   Implicit TreeNode construction improvements ([#21995](https://github.com/microsoft/FluidFramework/pull/21995)) [977f96c1a0](https://github.com/microsoft/FluidFramework/commit/977f96c1a0dd1d5eb0dbcd087d07cb7510d533ea)
+
+    ArrayNodes and MapNodes could always be explicitly constructed (using `new`) from iterables.
+    The types also allowed using of iterables to implicitly construct array nodes and map nodes,
+    but this did not work at runtime.
+    This has been fixed for all cases except implicitly constructing an ArrayNode form an `Iterable` that is actually a `Map`,
+    and implicitly constructing a MapNode from an `Iterable` that is actually an `Array`.
+    These cases may be fixed in the future, but require additional work to ensure unions of array nodes and map nodes work correctly.
+
+    Additionally MapNodes can now be constructed from `Iterator<readonly [string, content]>` where previously the inner arrays had to be mutable.
+
+-   Support generation of JSON Schema from Shared Tree view schema (alpha) ([#21984](https://github.com/microsoft/FluidFramework/pull/21984)) [9097bf8a44](https://github.com/microsoft/FluidFramework/commit/9097bf8a44310d0dcf1a4d2efc3a6f75997c58b3)
+
+    > [!WARNING]
+    > This API is [alpha quality](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels) and may change at any time.
+
+    Adds alpha-quality support for canonical [JSON Schema](https://json-schema.org/docs) representation of Shared Tree schema and adds a `getJsonSchema` function for getting that representation for a given `TreeNodeSchema`.
+    This JSON Schema representation can be used to describe schema requirements to external systems, and can be used with validation tools like [ajv](https://ajv.js.org/) to validate data before inserting it into a `SharedTree`.
+
+    #### Example
+
+    Given a `SharedTree` schema like the following:
+
+    ```typescript
+    class MyObject extends schemaFactory.object("MyObject", {
+    	foo: schemaFactory.number,
+    	bar: schemaFactory.optional(schemaFactory.string),
+    });
+    ```
+
+    JSON Schema like the following would be produced:
+
+    ```json
+    {
+    	"$defs": {
+    		"com.fluidframework.leaf.string": {
+    			"type": "string"
+    		},
+    		"com.fluidframework.leaf.number": {
+    			"type": "number"
+    		},
+    		"com.myapp.MyObject": {
+    			"type": "object",
+    			"properties": {
+    				"foo": { "$ref": "com.fluidframework.leaf.number" },
+    				"bar": { "$ref": "com.fluidframework.leaf.string" }
+    			},
+    			"required": ["foo"]
+    		}
+    	},
+    	"anyOf": [{ "$ref": "#/$defs/com.myapp.MyObject" }]
+    }
+    ```
+
+-   Enforce use of TreeViewConfiguration's constructor ([#22055](https://github.com/microsoft/FluidFramework/pull/22055)) [e8955579f6](https://github.com/microsoft/FluidFramework/commit/e8955579f6d52a6c7e300642088c60d6ed12d7db)
+
+    `TreeViewConfiguration` is `@sealed`, meaning creating custom implementations of it such as assigning object literals to a `TreeViewConfiguration` or sub-classing it are not supported.
+    This reserved the ability for the Fluid Framework to add members to this class over time, informing users that they must use it in such a way where such changes are non-breaking.
+    However, there was no compiler-based enforcement of this expectation.
+    It was only indicated via documentation and an implicit assumption that when an API takes in a typed defined as a class, that an instance of that class must be used rather than an arbitrary object of a similar shape.
+
+    With this change, the TypeScript compiler will now inform users when they invalidly provide an object literal as a `TreeViewConfiguration`.
+
+    More specifically this causes code like this to produce a compile error:
+
+    ```typescript
+    // Don't do this!
+    const view = tree.viewWith({ schema: TestNode, enableSchemaValidation: false });
+    ```
+
+    The above was never intended to work, and is not a supported use of the `viewWith` since it requires a `TreeViewConfiguration` which is sealed.
+    Any code using the above pattern will break in Fluid Framework 2.2 and above. Such code will need to be updated to the pattern shown below.
+    Any code broken by this change is technically unsupported and only worked due to a gap in the type checking. This is not considered a breaking change.
+    The correct way to get a `TreeViewConfiguration` is by using its constructor:
+
+    ```typescript
+    // This pattern correctly initializes default values and validates input.
+    const view = tree.viewWith(new TreeViewConfiguration({ schema: TestNode }));
+    ```
+
+    Skipping the constructor causes the following problems:
+
+    1. `TreeViewConfiguration` does validation in its constructor, so skipping it also skips the validation which leads to much less friendly error messages for invalid schema.
+    2. Skipping the constructor also discards any default values for options like `enableSchemaValidation`.
+       This means that code written in that style would break if more options were added. Since such changes are planned,
+       it is not practical to support this pattern.
+
+-   Add a function `isRepoSuperset` to determine if changes to a document schema are backward-compatible ([#22045](https://github.com/microsoft/FluidFramework/pull/22045)) [f6fdc95bb3](https://github.com/microsoft/FluidFramework/commit/f6fdc95bb36a892710bc315aae85fd2c75aec975)
+
+    Note: These changes are not customer-facing and make progress toward future plans in Tree's schema evolution space.
+
+-   Add `@alpha` API `FixRecursiveArraySchema` as a workaround around an issue with recursive ArrayNode schema ([#22122](https://github.com/microsoft/FluidFramework/pull/22122)) [9ceacf9b54](https://github.com/microsoft/FluidFramework/commit/9ceacf9b5468ac8280a1dc48ada9d8b46b499f14)
+
+    Importing a recursive ArrayNode schema via a d.ts file can produce an error like
+    `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.`
+    if using a tsconfig with `"skipLibCheck": false`.
+
+    This error occurs due to the TypeScript compiler splitting the class definition into two separate declarations in the d.ts file (one for the base, and one for the actual class).
+    For unknown reasons, splitting the class declaration in this way breaks the recursive type handling, leading to the mentioned error.
+
+    Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error.
+    For the case of ArrayNodes, this can be done via usage that looks like this:
+
+    ```typescript
+    /**
+     * Workaround to avoid
+     * `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.` in the d.ts file.
+     */
+    export declare const _RecursiveArrayWorkaround: FixRecursiveArraySchema<typeof RecursiveArray>;
+    export class RecursiveArray extends schema.arrayRecursive("RA", [() => RecursiveArray]) {}
+    {
+    	type _check = ValidateRecursiveSchema<typeof RecursiveArray>;
+    }
+    ```
+
+-   Fix document-corrupting bug when rebasing over move compositions ([#21993](https://github.com/microsoft/FluidFramework/pull/21993)) [f3af9d1cd3](https://github.com/microsoft/FluidFramework/commit/f3af9d1cd3f7ee1ea3660ae934ddca8473fbdb9b)
+
+    Before this fix, if multiple users concurrently performed moves (possibly by reverting prior moves), there was a chance that the document would become corrupted.
+
+## 2.1.0
+
+### Minor Changes
+
+-   Detect arrayNode iterator invalidation ([#21760](https://github.com/microsoft/FluidFramework/pull/21760)) [6fd320c385](https://github.com/microsoft/FluidFramework/commit/6fd320c38561e272a1acaf4248f47fc386c650e4)
+
+    When `arrayNode`s are edited concurrently during iteration, an error will be thrown.
+
+-   tree: Improved performance for accessing identifiers in shortId API ([#21944](https://github.com/microsoft/FluidFramework/pull/21944)) [6b4cf26d9c](https://github.com/microsoft/FluidFramework/commit/6b4cf26d9cc14c1a36cf07fd7408f1d1227e373a)
+
+    Users should see improved performance when calling the `Tree.shortId` API. Identifier field keys are now cached in the schema for faster access.
+
+-   ✨ New! Debug visualizers for TreeNodes in NodeJS and browsers ([#21895](https://github.com/microsoft/FluidFramework/pull/21895)) [0d197fefec](https://github.com/microsoft/FluidFramework/commit/0d197fefec852df2911151217ac1b71cde528a70)
+
+    TreeNodes now have custom debug visualizers to improve the debug experience in NodeJS and in browsers. Note that custom formatters must be enabled in the browser developer tools for that visualizer to be used.
+
+-   Using "delete" on tree fields now throws an error instead of not working correctly ([#21609](https://github.com/microsoft/FluidFramework/pull/21609)) [416849b1fd](https://github.com/microsoft/FluidFramework/commit/416849b1fda029870ee1c1742100de4f8dde45b7)
+
+    TypeScript allows `delete` on object node optional fields if the `exactOptionalPropertyTypes` tsconfig setting is not
+    enabled. This does not work correctly at runtime and now produces an informative error.
+
+-   SharedTree content that is removed is now deleted ([#21372](https://github.com/microsoft/FluidFramework/pull/21372)) [a6e412159a](https://github.com/microsoft/FluidFramework/commit/a6e412159a4df6aceb84aac35288b108a5351905)
+
+    SharedTree now supports garbage collection so that removed content is not retained forever.
+    This is an internal change and users of SharedTree won't need to adapt any existing code.
+
+    This change could cause errors with cross-version collaboration where an older client does not send data that a newer
+    version may need. In this case, a "refresher data not found" error will be thrown.
+
+-   Improved error reporting ([#21940](https://github.com/microsoft/FluidFramework/pull/21940)) [3b8a366dd1](https://github.com/microsoft/FluidFramework/commit/3b8a366dd15660f9c916832040faf772534c0755)
+
+    Several cases of invalid usage patterns for tree APIs have gained improved error reporting, as well as improved documentation on the APIs detailing what usage is supported.
+    These improvements include:
+
+    -   Unsupported usages of schema classes: using more than one schema class derived from a single SchemaFactory generated base class. This used to hit internal asserts, but now has a descriptive user-facing UsageError. Most of this work was done in [9fb3dcf](https://github.com/microsoft/FluidFramework/commit/9fb3dcf491a7f0d66f4abbdc64ab97ccabef4707).
+    -   Improved detection of when prior exception may have left SharedTree in an invalid state.
+        These cases now report a UsageError including a reference to the prior exception. This was mainly done in [9fb3dcf](https://github.com/microsoft/FluidFramework/commit/9fb3dcf491a7f0d66f4abbdc64ab97ccabef4707) and [b77d530](https://github.com/microsoft/FluidFramework/commit/b77d530b9252201c40a90d1a2a6315f76f1a4a4b).
+
 ## 2.0.0-rc.5.0.0
 
 ### Minor Changes

package/README.md

@@ -7,7 +7,7 @@ The contents of this package are also reported as part of the [`fluid-framework`
 [SharedTree Philosophy](./docs/SharedTree%20Philosophy.md) covers the goals of the SharedTree project,
 and some of the implications of those goals for developers working on this package.
 
-<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_PACKAGE_README_HEADER) -->
+<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_README_HEADER) -->
 
 <!-- prettier-ignore-start -->
 <!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
@@ -37,6 +37,10 @@ To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidf
 
 To access the `beta` APIs, import via `@fluidframework/tree/beta`.
 
+## API Documentation
+
+API documentation for **@fluidframework/tree** is available at <https://fluidframework.com/docs/apis/tree>.
+
 <!-- prettier-ignore-end -->
 
 <!-- AUTO-GENERATED-CONTENT:END -->
@@ -46,8 +50,8 @@ To access the `beta` APIs, import via `@fluidframework/tree/beta`.
 Notable consideration that early adopters should be wary of:
 
 -   The persisted format is stable such that documents created with released versions 2.0.0 or greater of this package are fully supported long term.
--   SharedTree currently has unbounded memory growth:
-    -   Removed content is retained in memory and persisted in the document at rest ([fix](https://github.com/microsoft/FluidFramework/pull/21372)).
+-   In versions prior to 2.1.0, SharedTree had unbounded memory growth:
+    -   Removed content was retained in memory and persisted in the document at rest ([fix](https://github.com/microsoft/FluidFramework/pull/21372)). This was fixed in version 2.1.0.
 -   All range changes are atomized.
     This means that, when inserting/removing/moving multiple contiguous nodes the edit is split up into separate single node edits.
     This can impact the merge behavior of these edits, as well as the performance of large array edits.
@@ -125,6 +129,36 @@ This package can be developed using any of the [regular workflows for working on
     both of these are provided by the mocha testing extension thats recommended by the workspace.
     Note that this does not build the tests, so always be sure to build first.
 
+## Frequently asked questions
+
+### Why can't I assign insertable content to a field?
+
+``` typescript
+import { SchemaFactory } from "@fluidframework/tree";
+
+const factory = new SchemaFactory("com.fluidframework.faq");
+class Empty extends factory.object("Empty", {}) {}
+class Test extends factory.object("Test", { data: Empty }) {}
+function set(node: Test) {
+	node.data = {}; // Why does this not compile?
+}
+```
+
+This is due to [a limitation of the TypeScript language](https://github.com/microsoft/TypeScript/issues/43826) which makes it impossible for tree to allow that to type-check while keeping the strong typing on the getters for reading data.
+
+To workaround this, create an unhydrated node:
+
+``` typescript
+node.data = new Empty({}); // The unhydrated node's type matches the type returned by the getter, and thus is compatible with the setter
+```
+
+Insertable content can still be used in other places, like when nested in other insertable content, in ArrayNode editing methods, and when initializing views.
+
+``` typescript
+// The empty node can be implicitly constructed from `{}` here, since this context allows insertable content, not just nodes.
+const node = new Test({ data: {} });
+```
+
 ## Architecture
 
 This section covers the internal structure of the Tree DDS.
@@ -406,26 +440,22 @@ flowchart
     package-->runtime["Fluid runtime"]
 ```
 
-# Open Design Questions
+## Open Design Questions
 
 The design issues here all impact the architectural role of top-level modules in this package in a way that when fixed will likely require changes to the architectural details covered above.
 Smaller scoped issues which will not impact the overall architecture should be documented in more localized locations.
 
-## How should specialized sub-tree handling compose?
+### How should specialized sub-tree handling compose?
 
 Applications should have a domain model that can mix tree nodes with custom implementations as needed.
 Custom implementations should probably be able to be projections of flex trees, the forest content (via cursors), and updated via either regeneration from the input, or updated by a delta.
 This is important for performance/scalability and might be how we do virtualization (maybe subtrees that aren't downloaded are just one custom representation?).
 
-<!-- AUTO-GENERATED-CONTENT:START (LIBRARY_PACKAGE_README_FOOTER) -->
+<!-- AUTO-GENERATED-CONTENT:START (README_FOOTER) -->
 
 <!-- prettier-ignore-start -->
 <!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
 
-## API Documentation
-
-API documentation for **@fluidframework/tree** is available at <https://fluidframework.com/docs/apis/tree>.
-
 ## Minimum Client Requirements
 
 These are the platform requirements for the current version of Fluid Framework Client Packages.

package/api-extractor.json

@@ -11,4 +11,21 @@
 			}
 		}
 	}
+	// In some cases (like diagnosing ae-forgotten-export errors for internal APIs)
+	// It can be very useful to enable the below options so "_api-extractor-temp/tree.api.md"
+	// can be searched for the references to the type that is causing the erroring type to need exporting.
+	// "apiReport": {
+	// 	"enabled": true,
+	// 	"reportVariants": ["public", "beta", "alpha", "complete"]
+	// },
+	// "messages": {
+	// 	"extractorMessageReporting": {
+	// 		"ae-forgotten-export": {
+	// 			"logLevel": "warning"
+	// 		},
+	// 		"ae-unresolved-link": {
+	// 			"logLevel": "warning"
+	// 		}
+	// 	}
+	// }
 }