New SharedTree configuration option:`ITreeConfigurationOptions.preventAmbiguity`
The new `ITreeConfigurationOptions.preventAmbiguity` flag can be set to true to enable checking of some additional rules when constructing the `TreeViewConfiguration`.
A recursive map schema like the above (which follows all our recommended best practices for maximum chances of working) would work when used from within its compilation unit, but would generate d.ts that fails to compile when exporting it:
This schema would work when used from within its compilation unit, but would generate d.ts that fails to compile when exporting it:
This results in the compile error in TypeScript 5.4.5:
> error TS2310: Type 'RecursiveMap' recursively references itself as a base type.
This is in TypeScript 5.4.5.
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.
This schema converter had several known issues and has been removed. Read the [schema converter section](https://github.com/microsoft/FluidFramework/blob/main/experimental/PropertyDDS/packages/property-shared-tree-interop/README.md#schema-converter-runtime) of the package readme for more details.
These properties `gcThrowOnTombstoneUsage` and `gcTombstoneEnforcementAllowed` have been deprecated in `IFluidParentContext` and `ContainerRuntime`. These were included in certain garbage collection telemetry to identify whether the corresponding features have been enabled. These features are now enabled by default and this information is added to the "GarbageCollectorLoaded" telemetry.
gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed are deprecated
Also, the following Garbage collection runtime options and configs have been removed. They were added during GC feature development to roll out and control functionalities. The functionalities corresponding are on by default and can no longer be controlled:
These properties `gcThrowOnTombstoneUsage` and `gcTombstoneEnforcementAllowed` have been deprecated in
`IFluidParentContext` and `ContainerRuntime`. These were included in certain garbage collection (GC) telemetry to
identify whether the corresponding features have been enabled. These features are now enabled by default and this
information is added to the "GarbageCollectorLoaded" telemetry.
Also, the following Garbage collection runtime options and configs have been removed. They were added during GC feature
development to roll out and control functionalities. The corresponding features are on by default and can no longer be
@ -13,7 +13,7 @@ Support generation of JSON Schema from Shared Tree view schema (alpha)
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`.
Fix document-corrupting bug when rebasing over move compositions.
Fix document-corrupting bug when rebasing over move compositions
Before this fix, if multiple users concurrently performed moves (possibly by reverting prior moves), there was a chance that the document would become corrupted.
<!-- THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. -->
# Fluid Framework v2.2.0
## Contents
- [✨ New Features](#-new-features)
- [New `isFluidHandle` type guard to check if an object is an `IFluidHandle` (#22029)](#new-isfluidhandle-type-guard-to-check-if-an-object-is-an-ifluidhandle-22029)
- [✨ New! When unambiguous, ArrayNodes can now be constructed from Maps and MapNodes from arrays (#22036)](#-new-when-unambiguous-arraynodes-can-now-be-constructed-from-maps-and-mapnodes-from-arrays-22036)
- [✨ New! `Record`-typed objects can now be used to construct MapNodes (#22042)](#-new-record-typed-objects-can-now-be-used-to-construct-mapnodes-22042)
- [Implicit TreeNode construction improvements (#21995)](#implicit-treenode-construction-improvements-21995)
- [Fix document-corrupting bug when rebasing over move compositions (#21993)](#fix-document-corrupting-bug-when-rebasing-over-move-compositions-21993)
- [Enforce use of TreeViewConfiguration's constructor (#22055)](#enforce-use-of-treeviewconfigurations-constructor-22055)
- [Add `@alpha` API `FixRecursiveArraySchema` as a workaround around an issue with recursive ArrayNode schema (#22122)](#add-alpha-api-fixrecursivearrayschema-as-a-workaround-around-an-issue-with-recursive-arraynode-schema-22122)
- [Support generation of JSON Schema from Shared Tree view schema (alpha) (#21984)](#support-generation-of-json-schema-from-shared-tree-view-schema-alpha-21984)
- [`Tree.schema` now returns `TreeNodeSchema` (#22185)](#treeschema-now-returns-treenodeschema-22185)
- [Compile-time type narrowing based on a TreeNode's NodeKind (#22222)](#compile-time-type-narrowing-based-on-a-treenodes-nodekind-22222)
- [🐛 Bug Fixes](#-bug-fixes)
- [Recursive SharedTree schemas using MapNodes no longer produce invalid d.ts files (#22106)](#recursive-sharedtree-schemas-using-mapnodes-no-longer-produce-invalid-dts-files-22106)
- [⚠️ Deprecations](#️-deprecations)
- [container-loader: summarizeProtocolTree and its corresponding duplicate ILoaderOptions definition is deprecated (#21999)](#container-loader-summarizeprotocoltree-and-its-corresponding-duplicate-iloaderoptions-definition-is-deprecated-21999)
- [gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed are deprecated (#21992)](#gcthrowontombstoneusage-and-gctombstoneenforcementallowed-are-deprecated-21992)
- [InactiveResponseHeaderKey header is deprecated (#22107)](#inactiveresponseheaderkey-header-is-deprecated-22107)
- [The PropertyManager class and related functions and properties are deprecated (#22183)](#the-propertymanager-class-and-related-functions-and-properties-are-deprecated-22183)
- [Deprecate segmentGroups and ack on ISegment (#22183)](#deprecate-segmentgroups-and-ack-on-isegment-22183)
### New `isFluidHandle` type guard to check if an object is an `IFluidHandle` ([#22029](https://github.com/microsoft/FluidFramework/issues/22029))
The `isFluidHandle` type guard function is now exported and can be used to detect which objects are `IFluidHandle`s. Since `IFluidHandle` often needs special handling (for example when serializing since it's not JSON compatible), having a dedicated detection function for it is useful. Doing this detection was possible previously using the `tree` package's schema system via `Tree.is(value, new SchemaFactory("").handle)`, but can now be done with just `isFluidHandle(value)`.
### ✨ New! When unambiguous, ArrayNodes can now be constructed from Maps and MapNodes from arrays ([#22036](https://github.com/microsoft/FluidFramework/issues/22036))
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.
### ✨ New! `Record`-typed objects can now be used to construct MapNodes ([#22042](https://github.com/microsoft/FluidFramework/issues/22042))
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.
### Implicit TreeNode construction improvements ([#21995](https://github.com/microsoft/FluidFramework/issues/21995))
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.
### Fix document-corrupting bug when rebasing over move compositions ([#21993](https://github.com/microsoft/FluidFramework/issues/21993))
Before this fix, if multiple users concurrently performed moves (possibly by reverting prior moves), there was a chance that the document would become corrupted.
### Enforce use of TreeViewConfiguration's constructor ([#22055](https://github.com/microsoft/FluidFramework/issues/22055))
`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:
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.
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.
### New SharedTree configuration option: `ITreeConfigurationOptions.preventAmbiguity` ([#22048](https://github.com/microsoft/FluidFramework/issues/22048))
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.
### Add `@alpha` API `FixRecursiveArraySchema` as a workaround around an issue with recursive ArrayNode schema ([#22122](https://github.com/microsoft/FluidFramework/issues/22122))
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.
### Support generation of JSON Schema from Shared Tree view schema (alpha) ([#21984](https://github.com/microsoft/FluidFramework/issues/21984))
> 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),
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/issues/22106))
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<typeofRecursiveMap>;
}
```
This schema would work when used from within its compilation unit, but would generate d.ts that fails to compile when exporting it:
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.
### container-loader: summarizeProtocolTree and its corresponding duplicate ILoaderOptions definition is deprecated ([#21999](https://github.com/microsoft/FluidFramework/issues/21999))
The `summarizeProtocolTree` property in ILoaderOptions was added to test single-commit summaries during the initial implementation phase. The flag is no longer required and should no longer be used, and is now marked deprecated. If a driver needs to enable or disable single-commit summaries, it can do so via `IDocumentServicePolicies`.
### gcThrowOnTombstoneUsage and gcTombstoneEnforcementAllowed are deprecated ([#21992](https://github.com/microsoft/FluidFramework/issues/21992))
These properties `gcThrowOnTombstoneUsage` and `gcTombstoneEnforcementAllowed` have been deprecated in `IFluidParentContext` and `ContainerRuntime`. These were included in certain garbage collection (GC) telemetry to identify whether the corresponding features have been enabled. These features are now enabled by default and this information is added to the "GarbageCollectorLoaded" telemetry.
Also, the following Garbage collection runtime options and configs have been removed. They were added during GC feature development to roll out and control functionalities. The corresponding features are on by default and can no longer be disabled or controlled:
### InactiveResponseHeaderKey header is deprecated ([#22107](https://github.com/microsoft/FluidFramework/issues/22107))
The header `InactiveResponseHeaderKey` is deprecated and will be removed in the future. It was part of an experimental feature where loading an inactive data store would result in returning a 404 with this header set to true. This feature is no longer supported.
### The PropertyManager class and related functions and properties are deprecated ([#22183](https://github.com/microsoft/FluidFramework/issues/22183))
The `PropertyManager` class, along with the `propertyManager` properties and `addProperties` functions on segments and intervals, are not intended for external use. These elements will be removed in a future release for the following reasons:
- There are no scenarios where they need to be used directly.
- Using them directly will cause eventual consistency problems.
- Upcoming features will require modifications to these mechanisms.
### Deprecate segmentGroups and ack on ISegment ([#22183](https://github.com/microsoft/FluidFramework/issues/22183))
The `SegmentGroupCollection` class, along with the `segmentGroups` property and `ack` function on segments, are not intended for external use. These elements will be removed in a future release for the following reasons:
- There are no scenarios where they need to be used directly.
- Using them directly will cause eventual consistency problems.
- Upcoming features will require modifications to these mechanisms.
This schema converter had several known issues and has been removed. Read the [schema converter section](https://github.com/microsoft/FluidFramework/blob/main/experimental/PropertyDDS/packages/property-shared-tree-interop/README.md#schema-converter-runtime) of the package readme for more details.
Please continue to engage with us on GitHub [Discussion](https://github.com/microsoft/FluidFramework/discussions) and [Issue](https://github.com/microsoft/FluidFramework/issues) pages as you adopt Fluid Framework!
Tyler Butler
GitHub