fluid-framework 2.31.1 → 2.32.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # fluid-framework
 
+## 2.32.0
+
+### Minor Changes
+
+- Cleanup of several tree and schema alpha APIs for content import and export ([#24350](https://github.com/microsoft/FluidFramework/pull/24350)) [fe924a173b](https://github.com/microsoft/FluidFramework/commit/fe924a173b71abd96ba76da787eec3b4c077d32b)
+
+  A new `TreeSchema` type has been introduced which extends `SimpleTreeSchema` but contains `TreeNodeSchema` instead of `SimpleNodeSchema`.
+
+  `TreeViewConfigurationAlpha` is added which is just `TreeViewConfiguration` but implementing `TreeSchema`.
+
+  `SimpleTreeSchema` was modified to have a `root` property instead of implementing `SimpleFieldSchema` directly:
+  this makes it possible for `TreeViewConfigurationAlpha` to implement `TreeSchema` which extends `SimpleTreeSchema`.
+
+  `generateSchemaFromSimpleSchema` now returns the new `TreeSchema` type.
+
+  `EncodeOptions` and `ParseOptions` have been unified as `TreeEncodingOptions` which covers both the encoding and parsing cases.
+
+  `getJsonSchema` now takes in `ImplicitAllowedTypes` instead of `ImplicitFieldSchema` since it can't handle optional roots.
+  `getJsonSchema` also takes in the new `TreeSchemaEncodingOptions` to provide options for how to handle stored keys vs property keys, and fields with defaults.
+
+  Now that `getJsonSchema` takes in configuration options, its results are no longer cached.
+
+- Provide alpha APIs for accessing tree content and stored schema without requiring a compatible view schema ([#24350](https://github.com/microsoft/FluidFramework/pull/24350)) [fe924a173b](https://github.com/microsoft/FluidFramework/commit/fe924a173b71abd96ba76da787eec3b4c077d32b)
+
+  Adds an `ITreeAlpha` interface (which `ITree` can be down-casted to) that provides access to both the tree content and the schema.
+  This allows inspecting the content saved in a SharedTree in a generic way that can work on any SharedTree.
+
+  This can be combined with the existing `generateSchemaFromSimpleSchema` to generate a schema that can be used with [`IIree.viewWith`](https://fluidframework.com/docs/api/fluid-framework/viewabletree-interface#viewwith-methodsignature) to allow constructing a [`TreeView`](https://fluidframework.com/docs/api/fluid-framework/treeview-interface) for any SharedTree, regardless of its schema.
+
+  Note that the resulting TypeScript typing for such a view will not be friendly: the `TreeView` APIs are designed for statically known schema. Using them is possible with care and a lot of type casts but not recommended if it can be avoided: see disclaimer on `generateSchemaFromSimpleSchema`.
+  Example using `ITreeAlpha` and `generateSchemaFromSimpleSchema`:
+
+  ```typescript
+  const viewAlpha = tree as ITreeAlpha;
+  const treeSchema = generateSchemaFromSimpleSchema(
+    viewAlpha.exportSimpleSchema(),
+  );
+  const config = new TreeViewConfiguration({ schema: treeSchema.root });
+  const view = viewAlpha.viewWith(config);
+  ```
+
+  `getSimpleSchema` is also added as an `@alpha` API to provide a way to clone schema into the simple schema formats.
+  Note that when using (or copying) a view schema as a simple schema, more metadata will be preserved than when deriving one from the stored schema using `ITreeAlpha`.
+
 ## 2.31.0
 
 ### Minor Changes

package/api-extractor/api-extractor.current.json

@@ -2,5 +2,9 @@
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
 	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts",
-	"bundledPackages": ["@fluidframework/*"]
+	"bundledPackages": ["@fluidframework/*"],
+	"apiReport": {
+		// The base config omits alpha. Explicitly opt into alpha reports (in addition to public/beta) for this package.
+		"reportVariants": ["public", "beta", "alpha"]
+	}
 }

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

@@ -150,11 +150,6 @@ export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema,
 interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider"> {
 }
 
-// @alpha
-export interface EncodeOptions {
-    readonly useStoredKeys?: boolean;
-}
-
 // @alpha
 export function enumFromStrings<TScope extends string, const Members extends readonly string[]>(factory: SchemaFactory<TScope>, members: Members): (<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & {
     readonly value: TValue;
@@ -298,7 +293,7 @@ export const ForestTypeOptimized: ForestType;
 export const ForestTypeReference: ForestType;
 
 // @alpha
-export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchemaAlpha;
+export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema;
 
 // @alpha @deprecated
 export function getBranch(tree: ITree): BranchableTree;
@@ -307,7 +302,10 @@ export function getBranch(tree: ITree): BranchableTree;
 export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(view: TreeViewAlpha<T>): BranchableTree;
 
 // @alpha
-export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;
+export function getJsonSchema(schema: ImplicitAllowedTypes, options: Required<TreeSchemaEncodingOptions>): JsonTreeSchema;
+
+// @alpha
+export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema;
 
 // @alpha
 export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
@@ -750,6 +748,12 @@ export class IterableTreeArrayContent<T> implements Iterable<T> {
 export interface ITree extends ViewableTree, IFluidLoadable {
 }
 
+// @alpha @sealed
+export interface ITreeAlpha extends ITree {
+    exportSimpleSchema(): SimpleTreeSchema;
+    exportVerbose(): VerboseTree | undefined;
+}
+
 // @public
 export interface ITreeConfigurationOptions {
     enableSchemaValidation?: boolean;
@@ -995,11 +999,6 @@ export type Off = () => void;
 // @alpha
 export function onAssertionFailure(handler: (error: Error) => void): () => void;
 
-// @alpha
-export interface ParseOptions {
-    readonly useStoredKeys?: boolean;
-}
-
 // @alpha
 export type PopUnion<Union, AsOverloadedFunction = UnionToIntersection<Union extends unknown ? (f: Union) => void : never>> = AsOverloadedFunction extends (a: infer First) => void ? First : never;
 
@@ -1165,9 +1164,12 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
     arrayAlpha<const Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     arrayRecursive<const Name extends TName, const T extends ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): ArrayNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
     static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha_2<FieldKind_2.Identifier, LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, TCustomMetadata>;
+    static readonly leaves: readonly [LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, LeafSchema_2<"number", number> & SimpleLeafNodeSchema_2, LeafSchema_2<"boolean", boolean> & SimpleLeafNodeSchema_2, LeafSchema_2<"null", null> & SimpleLeafNodeSchema_2, LeafSchema_2<"handle", IFluidHandle_2<unknown>> & SimpleLeafNodeSchema_2];
     mapAlpha<Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     mapRecursive<Name extends TName, const T extends ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): MapNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
-    object<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
+    object<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: SchemaFactoryObjectOptions<TCustomMetadata>): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
+        readonly createFromInsertable: unknown;
+    };
     objectRecursive<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>, 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> & SimpleObjectNodeSchema<TCustomMetadata> & Pick<ObjectNodeSchema, "fields">;
     static readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha_2<FieldKind_2.Optional, T, TCustomMetadata>;
     static readonly optionalRecursive: <const T extends ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe_2<FieldKind_2.Optional, T, TCustomMetadata>;
@@ -1280,10 +1282,9 @@ export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown> extends S
 export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
 
 // @alpha @sealed
-export interface SimpleTreeSchema extends SimpleFieldSchema {
-    readonly allowedTypesIdentifiers: ReadonlySet<string>;
+export interface SimpleTreeSchema {
     readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
-    readonly kind: FieldKind;
+    readonly root: SimpleFieldSchema;
 }
 
 // @alpha
@@ -1345,10 +1346,10 @@ 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>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
-    exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
-    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: EncodeOptions): ConciseTree | undefined;
-    exportVerbose(node: TreeNode | TreeLeafValue, options?: EncodeOptions): VerboseTree;
+    importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<TreeEncodingOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+    exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
+    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
+    exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
         oldestCompatibleClient: FluidClientVersion;
         idCompressor?: IIdCompressor;
@@ -1439,6 +1440,11 @@ export enum TreeCompressionStrategy {
     Uncompressed = 1
 }
 
+// @alpha
+export interface TreeEncodingOptions {
+    readonly useStoredKeys?: boolean;
+}
+
 // @public
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> = TSchema extends FieldSchema<infer Kind, infer Types> ? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind> : TSchema extends ImplicitAllowedTypes ? TreeNodeFromImplicitAllowedTypes<TSchema> : TreeNode | TreeLeafValue | undefined;
 
@@ -1550,6 +1556,17 @@ export type TreeObjectNode<T extends RestrictiveStringRecord<ImplicitFieldSchema
 // @public
 export type TreeObjectNodeUnsafe<T extends RestrictiveStringRecord<ImplicitFieldSchemaUnsafe>, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object, T>;
 
+// @alpha @sealed (undocumented)
+export interface TreeSchema extends SimpleTreeSchema {
+    readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+    readonly root: FieldSchemaAlpha;
+}
+
+// @alpha
+export interface TreeSchemaEncodingOptions extends TreeEncodingOptions {
+    readonly requireFieldsWithDefaults?: boolean;
+}
+
 // @public
 export enum TreeStatus {
     Deleted = 2,
@@ -1594,6 +1611,13 @@ export class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = I
     protected _typeCheck: MakeNominal;
 }
 
+// @alpha @sealed
+export class TreeViewConfigurationAlpha<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends TreeViewConfiguration<TSchema> implements TreeSchema {
+    constructor(props: ITreeViewConfiguration<TSchema>);
+    readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+    readonly root: FieldSchemaAlpha;
+}
+
 // @public @sealed
 export interface TreeViewEvents {
     commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;

package/dist/alpha.d.ts

@@ -151,7 +151,6 @@ export {
 	ArrayNodeSchema, 
 	BranchableTree, 
 	ConciseTree, 
-	EncodeOptions, 
 	FactoryContent, 
 	FactoryContentObject, 
 	FieldSchemaAlpha, 
@@ -165,6 +164,7 @@ export {
 	ForestTypeReference, 
 	HandleConverter, 
 	ICodecOptions, 
+	ITreeAlpha, 
 	IdentifierIndex, 
 	Insertable, 
 	InsertableContent, 
@@ -192,7 +192,6 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	ObjectNodeSchema, 
-	ParseOptions, 
 	PopUnion, 
 	ReadSchema, 
 	ReadableField, 
@@ -224,10 +223,14 @@ export {
 	TreeBranchEvents, 
 	TreeBranchFork, 
 	TreeCompressionStrategy, 
+	TreeEncodingOptions, 
 	TreeIndex, 
 	TreeIndexKey, 
 	TreeIndexNodes, 
+	TreeSchema, 
+	TreeSchemaEncodingOptions, 
 	TreeViewAlpha, 
+	TreeViewConfigurationAlpha, 
 	UnionToTuple, 
 	UnsafeUnknownSchema, 
 	ValueSchema, 
@@ -248,6 +251,7 @@ export {
 	generateSchemaFromSimpleSchema, 
 	getBranch, 
 	getJsonSchema, 
+	getSimpleSchema, 
 	independentInitializedView, 
 	independentView, 
 	noopValidator, 

package/lib/alpha.d.ts

@@ -151,7 +151,6 @@ export {
 	ArrayNodeSchema, 
 	BranchableTree, 
 	ConciseTree, 
-	EncodeOptions, 
 	FactoryContent, 
 	FactoryContentObject, 
 	FieldSchemaAlpha, 
@@ -165,6 +164,7 @@ export {
 	ForestTypeReference, 
 	HandleConverter, 
 	ICodecOptions, 
+	ITreeAlpha, 
 	IdentifierIndex, 
 	Insertable, 
 	InsertableContent, 
@@ -192,7 +192,6 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	ObjectNodeSchema, 
-	ParseOptions, 
 	PopUnion, 
 	ReadSchema, 
 	ReadableField, 
@@ -224,10 +223,14 @@ export {
 	TreeBranchEvents, 
 	TreeBranchFork, 
 	TreeCompressionStrategy, 
+	TreeEncodingOptions, 
 	TreeIndex, 
 	TreeIndexKey, 
 	TreeIndexNodes, 
+	TreeSchema, 
+	TreeSchemaEncodingOptions, 
 	TreeViewAlpha, 
+	TreeViewConfigurationAlpha, 
 	UnionToTuple, 
 	UnsafeUnknownSchema, 
 	ValueSchema, 
@@ -248,6 +251,7 @@ export {
 	generateSchemaFromSimpleSchema, 
 	getBranch, 
 	getJsonSchema, 
+	getSimpleSchema, 
 	independentInitializedView, 
 	independentView, 
 	noopValidator, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.31.1",
+  "version": "2.32.0",
   "description": "The main entry point into Fluid Framework public packages",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -57,24 +57,24 @@
   "main": "lib/index.js",
   "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluidframework/container-definitions": "~2.31.1",
-    "@fluidframework/container-loader": "~2.31.1",
-    "@fluidframework/core-interfaces": "~2.31.1",
-    "@fluidframework/core-utils": "~2.31.1",
-    "@fluidframework/driver-definitions": "~2.31.1",
-    "@fluidframework/fluid-static": "~2.31.1",
-    "@fluidframework/map": "~2.31.1",
-    "@fluidframework/runtime-utils": "~2.31.1",
-    "@fluidframework/sequence": "~2.31.1",
-    "@fluidframework/shared-object-base": "~2.31.1",
-    "@fluidframework/tree": "~2.31.1"
+    "@fluidframework/container-definitions": "~2.32.0",
+    "@fluidframework/container-loader": "~2.32.0",
+    "@fluidframework/core-interfaces": "~2.32.0",
+    "@fluidframework/core-utils": "~2.32.0",
+    "@fluidframework/driver-definitions": "~2.32.0",
+    "@fluidframework/fluid-static": "~2.32.0",
+    "@fluidframework/map": "~2.32.0",
+    "@fluidframework/runtime-utils": "~2.32.0",
+    "@fluidframework/sequence": "~2.32.0",
+    "@fluidframework/shared-object-base": "~2.32.0",
+    "@fluidframework/tree": "~2.32.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-tools/build-cli": "^0.54.0",
+    "@fluid-tools/build-cli": "^0.55.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.54.0",
+    "@fluidframework/build-tools": "^0.55.0",
     "@fluidframework/eslint-config-fluid": "^5.7.3",
     "@microsoft/api-extractor": "7.50.1",
     "@types/node": "^18.19.0",