feat(tree): Promote importConcise and exportConcise to beta

.changeset/tangy-poodles-ramble.md

@@ -0,0 +1,11 @@
+---
+"@fluidframework/tree": minor
+"fluid-framework": minor
+"__section": tree
+---
+Promote importConcise and exportConcise to beta
+
+`importConcise` and `exportConcise` were previously available via [TreeAlpha](https://fluidframework.com/docs/api/tree/treealpha-interface).
+They may now also be accessed via [TreeBeta](https://fluidframework.com/docs/api/tree/treebeta-interface).
+
+Note that the beta form of `importConcise` does not support [UnsafeUnknownSchema](https://fluidframework.com/docs/api/fluid-framework/unsafeunknownschema-typealias).

examples/apps/tree-cli-app/src/utils.ts

@@ -31,6 +31,7 @@ import {
 	TreeAlpha,
 	KeyEncodingOptions,
 } from "@fluidframework/tree/alpha";
+import { TreeBeta } from "@fluidframework/tree/beta";
 import { type Static, Type } from "@sinclair/typebox";
 
 import type { Item } from "./schema.js";
@@ -61,7 +62,7 @@ export function loadDocument(source: string | undefined): List {
 
 	switch (parts.at(-2)) {
 		case "concise": {
-			return TreeAlpha.importConcise(List, fileData as ConciseTree);
+			return TreeBeta.importConcise(List, fileData as ConciseTree);
 		}
 		case "verbose": {
 			return TreeAlpha.importVerbose(List, fileData as VerboseTree);
@@ -140,13 +141,13 @@ export function exportContent(destination: string, tree: List): JsonCompatible {
 
 	switch (parts.at(-2)) {
 		case "concise": {
-			return TreeAlpha.exportConcise(tree) as JsonCompatible;
+			return TreeBeta.exportConcise(tree) as JsonCompatible;
 		}
 		case "verbose": {
 			return TreeAlpha.exportVerbose(tree) as JsonCompatible;
 		}
 		case "concise-stored": {
-			return TreeAlpha.exportConcise(tree, {
+			return TreeBeta.exportConcise(tree, {
 				keys: KeyEncodingOptions.knownStoredKeys,
 			}) as JsonCompatible;
 		}

packages/dds/tree/api-report/tree.alpha.api.md

@@ -119,7 +119,7 @@ export interface CommitMetadata {
 // @alpha
 export function comparePersistedSchema(persisted: JsonCompatible, view: ImplicitFieldSchema, options: ICodecOptions): Omit<SchemaCompatibilityStatus, "canInitialize">;
 
-// @alpha
+// @beta
 export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle | ConciseTree<THandle>[] | {
     [key: string]: ConciseTree<THandle>;
 };
@@ -577,7 +577,7 @@ export type JsonTreeSchema = JsonFieldSchema & {
     readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
 };
 
-// @alpha @input
+// @beta @input
 export enum KeyEncodingOptions {
     allStoredKeys = "allStoredKeys",
     knownStoredKeys = "knownStoredKeys",
@@ -1362,6 +1362,9 @@ export const TreeArrayNode: {
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+    exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
+    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
+    importConcise<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: ConciseTree | undefined): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
     on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>): () => void;
 }
 
@@ -1408,7 +1411,7 @@ export enum TreeCompressionStrategy {
     Uncompressed = 1
 }
 
-// @alpha @input
+// @beta @input
 export interface TreeEncodingOptions<TKeyOptions = KeyEncodingOptions> {
     readonly keys?: TKeyOptions;
 }

packages/dds/tree/api-report/tree.beta.api.md

@@ -43,6 +43,11 @@ export interface CommitMetadata {
     readonly kind: CommitKind;
 }
 
+// @beta
+export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle | ConciseTree<THandle>[] | {
+    [key: string]: ConciseTree<THandle>;
+};
+
 // @beta
 export function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): SharedObjectKind<ITree>;
 
@@ -219,6 +224,13 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @beta @input
+export enum KeyEncodingOptions {
+    allStoredKeys = "allStoredKeys",
+    knownStoredKeys = "knownStoredKeys",
+    usePropertyKeys = "usePropertyKeys"
+}
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -555,6 +567,9 @@ export const TreeArrayNode: {
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+    exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
+    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
+    importConcise<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: ConciseTree | undefined): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
     on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>): () => void;
 }
 
@@ -572,6 +587,11 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode> extends
     nodeChanged: (data: NodeChangedData<TNode> & (TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record> ? Required<Pick<NodeChangedData<TNode>, "changedProperties">> : unknown)) => void;
 }
 
+// @beta @input
+export interface TreeEncodingOptions<TKeyOptions = KeyEncodingOptions> {
+    readonly keys?: TKeyOptions;
+}
+
 // @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;
 

packages/dds/tree/api-report/tree.legacy.beta.api.md

@@ -43,6 +43,11 @@ export interface CommitMetadata {
     readonly kind: CommitKind;
 }
 
+// @beta
+export type ConciseTree<THandle = IFluidHandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle | ConciseTree<THandle>[] | {
+    [key: string]: ConciseTree<THandle>;
+};
+
 // @beta
 export function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): SharedObjectKind<ITree>;
 
@@ -222,6 +227,13 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @beta @input
+export enum KeyEncodingOptions {
+    allStoredKeys = "allStoredKeys",
+    knownStoredKeys = "knownStoredKeys",
+    usePropertyKeys = "usePropertyKeys"
+}
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -567,6 +579,9 @@ export const TreeArrayNode: {
 export interface TreeBeta {
     clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;
     create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+    exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
+    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
+    importConcise<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: ConciseTree | undefined): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
     on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>): () => void;
 }
 
@@ -584,6 +599,11 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode> extends
     nodeChanged: (data: NodeChangedData<TNode> & (TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record> ? Required<Pick<NodeChangedData<TNode>, "changedProperties">> : unknown)) => void;
 }
 
+// @beta @input
+export interface TreeEncodingOptions<TKeyOptions = KeyEncodingOptions> {
+    readonly keys?: TKeyOptions;
+}
+
 // @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;
 

packages/dds/tree/src/jsonDomainSchema.ts

@@ -37,7 +37,7 @@ const sf = new SchemaFactoryAlpha("com.fluidframework.json");
  *
  * 2. The order of fields on an object is not preserved. The resulting order is arbitrary.
  *
- * JSON data can be imported from JSON into this format using `JSON.parse` then {@link (TreeAlpha:interface).importConcise} with the {@link JsonAsTree.(Tree:variable)} schema.
+ * JSON data can be imported from JSON into this format using `JSON.parse` then {@link (TreeBeta:interface).importConcise} with the {@link JsonAsTree.(Tree:variable)} schema.
  *
  * @alpha
  */
@@ -63,7 +63,7 @@ export namespace JsonAsTree {
 	 * {@link AllowedTypes} for any content allowed in the {@link JsonAsTree} domain.
 	 * @example
 	 * ```typescript
-	 * const tree = TreeAlpha.importConcise(JsonAsTree.Union, { example: { nested: true }, value: 5 });
+	 * const tree = TreeBeta.importConcise(JsonAsTree.Union, { example: { nested: true }, value: 5 });
 	 * ```
 	 * @privateRemarks
 	 * The order here should not matter for any functionality related reasons.
@@ -95,7 +95,7 @@ export namespace JsonAsTree {
 	 * // Due to TypeScript restrictions on recursive types, the constructor and be somewhat limiting.
 	 * const fromArray = new JsonAsTreeObject([["a", 0]]);
 	 * // Using `importConcise` can work better for JSON data:
-	 * const imported = TreeAlpha.importConcise(JsonAsTree.Object, { a: 0 });
+	 * const imported = TreeBeta.importConcise(JsonAsTree.Object, { a: 0 });
 	 * // Node API is like a Map:
 	 * const value = imported.get("a");
 	 * ```
@@ -128,13 +128,13 @@ export namespace JsonAsTree {
 	/**
 	 * Arbitrary JSON array as a {@link TreeNode}.
 	 * @remarks
-	 * This can be imported using {@link (TreeAlpha:interface).importConcise}.
+	 * This can be imported using {@link (TreeBeta:interface).importConcise}.
 	 * @example
 	 * ```typescript
 	 * // Due to TypeScript restrictions on recursive types, the constructor can be somewhat limiting.
 	 * const usingConstructor = new JsonAsTree.Array(["a", 0, new JsonAsTree.Array([1])]);
 	 * // Using `importConcise` can work better for JSON data:
-	 * const imported = TreeAlpha.importConcise(JsonAsTree.Array, ["a", 0, [1]]);
+	 * const imported = TreeBeta.importConcise(JsonAsTree.Array, ["a", 0, [1]]);
 	 * // Node API is like an Array:
 	 * const inner: JsonAsTree.Tree = imported[2];
 	 * assert(Tree.is(inner, JsonAsTree.Array));

packages/dds/tree/src/serializableDomainSchema.ts

@@ -23,14 +23,14 @@ const sf = new SchemaFactoryAlpha("com.fluidframework.serializable");
  * @remarks
  * Schema which replicate the Fluid Serializable data model with {@link TreeNode}s.
  *
- * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link (TreeAlpha:interface).importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
+ * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link (TreeBeta:interface).importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
  * @alpha
  */
 export namespace FluidSerializableAsTree {
 	/**
 	 * Data which can be serialized by Fluid.
 	 * @remarks
-	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link (TreeAlpha:interface).importConcise}.
+	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link (TreeBeta:interface).importConcise}.
 	 * @alpha
 	 */
 	export type Data = JsonCompatible<IFluidHandle>;
@@ -39,7 +39,7 @@ export namespace FluidSerializableAsTree {
 	 * {@link AllowedTypes} for any content allowed in the {@link FluidSerializableAsTree} domain.
 	 * @example
 	 * ```typescript
-	 * const tree = TreeAlpha.importConcise(FluidSerializableAsTree.Tree, { example: { nested: true }, value: 5 });
+	 * const tree = TreeBeta.importConcise(FluidSerializableAsTree.Tree, { example: { nested: true }, value: 5 });
 	 * ```
 	 * @alpha
 	 */
@@ -69,7 +69,7 @@ export namespace FluidSerializableAsTree {
 	 * // Due to TypeScript restrictions on recursive types, the constructor and be somewhat limiting.
 	 * const fromArray = new JsonAsTreeObject([["a", 0]]);
 	 * // Using `importConcise` can work better for Fluid Serializable data:
-	 * const imported = TreeAlpha.importConcise(FluidSerializableAsTree.Object, { a: 0 });
+	 * const imported = TreeBeta.importConcise(FluidSerializableAsTree.Object, { a: 0 });
 	 * // Node API is like a Map:
 	 * const value = imported.get("a");
 	 * ```
@@ -102,13 +102,13 @@ export namespace FluidSerializableAsTree {
 	/**
 	 * Arbitrary Fluid Serializable array as a {@link TreeNode}.
 	 * @remarks
-	 * This can be imported using {@link (TreeAlpha:interface).importConcise}.
+	 * This can be imported using {@link (TreeBeta:interface).importConcise}.
 	 * @example
 	 * ```typescript
 	 * // Due to TypeScript restrictions on recursive types, the constructor can be somewhat limiting.
 	 * const usingConstructor = new FluidSerializableAsTree.Array(["a", 0, new FluidSerializableAsTree.Array([1])]);
 	 * // Using `importConcise` can work better for Fluid Serializable data:
-	 * const imported = TreeAlpha.importConcise(FluidSerializableAsTree.Array, ["a", 0, [1]]);
+	 * const imported = TreeBeta.importConcise(FluidSerializableAsTree.Array, ["a", 0, [1]]);
 	 * // Node API is like an Array:
 	 * const inner: FluidSerializableAsTree.Tree = imported[2];
 	 * assert(Tree.is(inner, FluidSerializableAsTree.Array));