fluid-framework 2.23.0 → 2.30.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # fluid-framework
 
+## 2.30.0
+
+### Minor Changes
+
+-   New SchemaFactoryAlpha.scopedFactory method ([#23987](https://github.com/microsoft/FluidFramework/pull/23987)) [cddd5139c3](https://github.com/microsoft/FluidFramework/commit/cddd5139c3e070ef26db55331528435a99c0a1b1)
+
+    The [`SchemaFactoryAlpha.scopedFactory`](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class)
+    method has been added, providing an easy way to create a new `SchemaFactory` with a nested scope string.
+
+-   TreeBranchEvents now exposes the rootChanged event ([#24014](https://github.com/microsoft/FluidFramework/pull/24014)) [702a08af83](https://github.com/microsoft/FluidFramework/commit/702a08af83206c21e1016ca47051052fa8554aa5)
+
+    `TreeBranchEvents` now includes the `rootChanged` event from `TreeViewEvents`.
+
+-   Alpha APIs for replacing handles in export formats have been redesigned ([#24061](https://github.com/microsoft/FluidFramework/pull/24061)) [34b319cae7](https://github.com/microsoft/FluidFramework/commit/34b319cae7a78db5530dc898689e2eb846f1419f)
+
+    The various import and export [`VerboseTree`](https://fluidframework.com/docs/api/fluid-framework/verbosetree-typealias) and [`ConciseTree`](https://fluidframework.com/docs/api/fluid-framework/concisetree-typealias) APIs no longer include `valueConverter` options.
+    Instead the resulting tree can be further processed to do any desired replacements.
+    The following `@alpha` APIs have been added to assist with this:
+
+    1. `cloneWithReplacements`
+    2. `replaceHandles`
+    3. `replaceConciseTreeHandles`
+    4. `replaceVerboseTreeHandles`
+
+-   Rules regarding how and when lazy schema references are resolved have been clarified ([#24030](https://github.com/microsoft/FluidFramework/pull/24030)) [23f32794db](https://github.com/microsoft/FluidFramework/commit/23f32794dbd3672dcc18e2a9ba2f16f4bf1241f0)
+
+    A lazy schema reference is a [LazyItem](https://fluidframework.com/docs/api/fluid-framework/lazyitem-typealias) referencing a [TreeNodeSchema](https://fluidframework.com/docs/api/fluid-framework/treenodeschema-typealias).
+    They typically look like `() => MySchema` and are used when a [forward reference](https://en.wikipedia.org/wiki/Forward_declaration#Forward_reference) from one schema to another is required (including but not limited to recursive and co-recursive schema).
+
+    [TreeViewConfiguration](https://fluidframework.com/docs/api/fluid-framework/treeviewconfiguration-class#_constructor_-constructor) now documents its significance with respect to lazy schema references.
+    Additionally some implicit assumptions like no modifications of [AllowedTypes](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias)
+    after resolving of lazy schema references have been enforced (such modifications would previously cause undefined behavior in the future, and now an error is thrown when trying to modify them).
+
+    `evaluateLazySchema` has been added as an `@alpha` API that is now consistently used by all internal code when evaluating lazy schema references.
+    This ensures consistent behavior and error reporting, but also adds caching.
+    Therefore it is now supported for applications to have lazy schema references which compute the schema when invoked,
+    without having to implement their own caching as long as those applications use `evaluateLazySchema` anytime they need to evaluate a lazy schema reference.
+
 ## 2.23.0
 
 ### Minor Changes

package/api-report/fluid-framework.alpha.api.md

@@ -51,6 +51,12 @@ export interface BranchableTree extends ViewableTree {
     rebase(branch: TreeBranchFork): void;
 }
 
+// @alpha
+export function cloneWithReplacements(root: unknown, rootKey: string, replacer: (key: string, value: unknown) => {
+    clone: boolean;
+    value: unknown;
+}): unknown;
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -123,9 +129,8 @@ interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider
 }
 
 // @alpha
-export interface EncodeOptions<TCustom> {
+export interface EncodeOptions {
     readonly useStoredKeys?: boolean;
-    valueConverter(data: IFluidHandle): TCustom;
 }
 
 // @alpha
@@ -145,6 +150,9 @@ export abstract class ErasedType<out Name = unknown> {
     protected abstract brand(dummy: never): Name;
 }
 
+// @alpha
+export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>): T;
+
 // @public
 type ExtractItemType<Item extends LazyItem> = Item extends () => infer Result ? Result : Item;
 
@@ -260,6 +268,9 @@ export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(v
 // @alpha
 export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;
 
+// @alpha
+export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
+
 // @alpha
 export interface ICodecOptions {
     readonly jsonValidator: JsonValidator;
@@ -898,9 +909,8 @@ type ObjectFromSchemaRecordUnsafe<T extends Unenforced<RestrictiveStringRecord<I
 export type Off = () => void;
 
 // @alpha
-export interface ParseOptions<TCustom> {
+export interface ParseOptions {
     readonly useStoredKeys?: boolean;
-    valueConverter(data: VerboseTree<TCustom>): TreeLeafValue | VerboseTreeNode<TCustom>;
 }
 
 // @alpha
@@ -934,11 +944,20 @@ export type ReadSchema<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema
 TSchema
 ] extends [ImplicitFieldSchema] ? TSchema : ImplicitFieldSchema;
 
+// @alpha
+export function replaceConciseTreeHandles<T>(tree: ConciseTree, replacer: HandleConverter<T>): ConciseTree<T>;
+
+// @alpha
+export function replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>): unknown;
+
 // @public
 export type ReplaceIEventThisPlaceHolder<L extends any[], TThis> = L extends any[] ? {
     [K in keyof L]: L[K] extends IEventThisPlaceHolder ? TThis : L[K];
 } : L;
 
+// @alpha
+export function replaceVerboseTreeHandles<T>(tree: VerboseTree, replacer: HandleConverter<T>): VerboseTree<T>;
+
 // @public @deprecated
 export type RestrictiveReadonlyRecord<K extends symbol | string, T> = {
     readonly [P in symbol | string]: P extends K ? T : never;
@@ -1071,6 +1090,7 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
     }, false, T, undefined, TCustomMetadata>;
     object<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNode<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T, never, TCustomMetadata>;
     objectRecursive<const Name extends TName, const T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>, const TCustomMetadata = unknown>(name: Name, t: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecordUnsafe<T>, false, T, never, TCustomMetadata>;
+    scopedFactory<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner>;
 }
 
 // @alpha
@@ -1189,12 +1209,9 @@ export const TreeAlpha: {
     branch(node: TreeNode): TreeBranch | undefined;
     create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
     importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
-    importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<ParseOptions<IFluidHandle>>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
-    importVerbose<const TSchema extends ImplicitFieldSchema, THandle>(schema: TSchema, data: VerboseTree<THandle> | undefined, options: ParseOptions<THandle>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
-    exportConcise(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): ConciseTree;
-    exportConcise<THandle>(node: TreeNode | TreeLeafValue, options: EncodeOptions<THandle>): ConciseTree<THandle>;
-    exportVerbose(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): VerboseTree;
-    exportVerbose<T>(node: TreeNode | TreeLeafValue, options: EncodeOptions<T>): VerboseTree<T>;
+    importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<ParseOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+    exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
+    exportVerbose(node: TreeNode | TreeLeafValue, options?: EncodeOptions): VerboseTree;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
         oldestCompatibleClient: FluidClientVersion;
         idCompressor?: IIdCompressor;
@@ -1258,10 +1275,9 @@ export interface TreeBranch extends IDisposable {
 }
 
 // @alpha @sealed
-export interface TreeBranchEvents {
+export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied"> {
     changed(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
     commitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;
-    schemaChanged(): void;
 }
 
 // @alpha @sealed

package/dist/alpha.d.ts

@@ -153,6 +153,7 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	HandleConverter, 
 	ICodecOptions, 
 	IdentifierIndex, 
 	Insertable, 
@@ -212,17 +213,22 @@ export {
 	VoidTransactionCallbackStatus, 
 	adaptEnum, 
 	asTreeViewAlpha, 
+	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
 	createIdentifierIndex, 
 	createSimpleTreeIndex, 
 	enumFromStrings, 
+	evaluateLazySchema, 
 	extractPersistedSchema, 
 	getBranch, 
 	getJsonSchema, 
 	independentInitializedView, 
 	independentView, 
 	noopValidator, 
+	replaceConciseTreeHandles, 
+	replaceHandles, 
+	replaceVerboseTreeHandles, 
 	singletonSchema, 
 	typeboxValidator
 } from "./index.js";

package/lib/alpha.d.ts

@@ -153,6 +153,7 @@ export {
 	ForestTypeExpensiveDebug, 
 	ForestTypeOptimized, 
 	ForestTypeReference, 
+	HandleConverter, 
 	ICodecOptions, 
 	IdentifierIndex, 
 	Insertable, 
@@ -212,17 +213,22 @@ export {
 	VoidTransactionCallbackStatus, 
 	adaptEnum, 
 	asTreeViewAlpha, 
+	cloneWithReplacements, 
 	comparePersistedSchema, 
 	configuredSharedTree, 
 	createIdentifierIndex, 
 	createSimpleTreeIndex, 
 	enumFromStrings, 
+	evaluateLazySchema, 
 	extractPersistedSchema, 
 	getBranch, 
 	getJsonSchema, 
 	independentInitializedView, 
 	independentView, 
 	noopValidator, 
+	replaceConciseTreeHandles, 
+	replaceHandles, 
+	replaceVerboseTreeHandles, 
 	singletonSchema, 
 	typeboxValidator
 } from "./index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.23.0",
+  "version": "2.30.0",
   "description": "The main entry point into Fluid Framework public packages",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -57,16 +57,16 @@
   "main": "lib/index.js",
   "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluidframework/container-definitions": "~2.23.0",
-    "@fluidframework/container-loader": "~2.23.0",
-    "@fluidframework/core-interfaces": "~2.23.0",
-    "@fluidframework/driver-definitions": "~2.23.0",
-    "@fluidframework/fluid-static": "~2.23.0",
-    "@fluidframework/map": "~2.23.0",
-    "@fluidframework/runtime-utils": "~2.23.0",
-    "@fluidframework/sequence": "~2.23.0",
-    "@fluidframework/shared-object-base": "~2.23.0",
-    "@fluidframework/tree": "~2.23.0"
+    "@fluidframework/container-definitions": "~2.30.0",
+    "@fluidframework/container-loader": "~2.30.0",
+    "@fluidframework/core-interfaces": "~2.30.0",
+    "@fluidframework/driver-definitions": "~2.30.0",
+    "@fluidframework/fluid-static": "~2.30.0",
+    "@fluidframework/map": "~2.30.0",
+    "@fluidframework/runtime-utils": "~2.30.0",
+    "@fluidframework/sequence": "~2.30.0",
+    "@fluidframework/shared-object-base": "~2.30.0",
+    "@fluidframework/tree": "~2.30.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",