@fluidframework/tree 2.22.1 → 2.23.0-325054

package/src/jsonDomainSchema.ts

@@ -0,0 +1,129 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	SchemaFactory,
+	type AllowedTypes,
+	type FixRecursiveArraySchema,
+	type TreeNodeFromImplicitAllowedTypes,
+	type ValidateRecursiveSchema,
+} from "./simple-tree/index.js";
+
+const sf = new SchemaFactory("com.fluidframework.json");
+
+/**
+ * Utilities for storing JSON data in {@link TreeNode}s.
+ * @remarks
+ * Schema which replicate the JSON data model with {@link TreeNode}s.
+ *
+ * This allows JSON to be losslessly round-tripped through a tree with the following limitations:
+ *
+ * 1. Only information that would be preserved by JSON.parse is preserved. This means (among other things) that numbers are limited to JavasScript's numeric precision.
+ *
+ * 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.importConcise} with the {@link JsonAsTree.(Tree:variable)} schema.
+ *
+ * @alpha
+ */
+export namespace JsonAsTree {
+	/**
+	 * {@link AllowedTypes} for primitives types allowed in JSON.
+	 * @alpha
+	 */
+	export const Primitive = [
+		sf.null,
+		sf.boolean,
+		sf.number,
+		sf.string,
+	] as const satisfies AllowedTypes;
+
+	/**
+	 * @alpha
+	 */
+	export type Primitive = TreeNodeFromImplicitAllowedTypes<typeof Primitive>;
+
+	/**
+	 * {@link AllowedTypes} for any content allowed in the {@link JsonAsTree} domain.
+	 * @example
+	 * ```typescript
+	 * const tree = TreeAlpha.importConcise(JsonAsTree.Union, { example: { nested: true }, value: 5 });
+	 * ```
+	 * @alpha
+	 */
+	export const Tree = [() => JsonObject, () => Array, ...Primitive] as const;
+
+	/**
+	 * @alpha
+	 */
+	export type Tree = TreeNodeFromImplicitAllowedTypes<typeof Tree>;
+
+	/**
+	 * Do not use. Exists only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.
+	 * @system @alpha
+	 */
+	export const _APIExtractorWorkaroundObjectBase = sf.mapRecursive("object", Tree);
+
+	/**
+	 * Arbitrary JSON object as a {@link TreeNode}.
+	 * @remarks
+	 * API of the tree node is more aligned with an es6 map than a JS object using its properties like a map.
+	 * @example
+	 * ```typescript
+	 * // 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 });
+	 * // Node API is like a Map:
+	 * const value = imported.get("a");
+	 * ```
+	 * @privateRemarks
+	 * Due to https://github.com/microsoft/TypeScript/issues/61270 this can't be named `Object`.
+	 * @sealed @alpha
+	 */
+	export class JsonObject extends _APIExtractorWorkaroundObjectBase {}
+	{
+		type _check = ValidateRecursiveSchema<typeof JsonObject>;
+	}
+
+	/**
+	 * D.ts bug workaround, see {@link FixRecursiveArraySchema}.
+	 * @privateRemarks
+	 * In the past this this had to reference the base type (_APIExtractorWorkaroundArrayBase).
+	 * Testing for this in examples/utils/import-testing now shows it has to reference JsonAsTree.Array instead.
+	 * @system @alpha
+	 */
+	export declare type _RecursiveArrayWorkaroundJsonArray = FixRecursiveArraySchema<
+		typeof Array
+	>;
+
+	/**
+	 * Do not use. Exists only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.
+	 * @system @alpha
+	 */
+	export const _APIExtractorWorkaroundArrayBase = sf.arrayRecursive("array", Tree);
+
+	/**
+	 * Arbitrary JSON array as a {@link TreeNode}.
+	 * @remarks
+	 * This can be imported using {@link TreeAlpha.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]]);
+	 * // Node API is like an Array:
+	 * const inner: JsonAsTree.Tree = imported[2];
+	 * assert(Tree.is(inner, JsonAsTree.Array));
+	 * const leaf = inner[0];
+	 * ```
+	 * @sealed @alpha
+	 */
+	export class Array extends _APIExtractorWorkaroundArrayBase {}
+	{
+		type _check = ValidateRecursiveSchema<typeof Array>;
+	}
+}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.22.1";
+export const pkgVersion = "2.23.0-325054";

package/src/serializableDomainSchema.ts

@@ -0,0 +1,121 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import {
+	SchemaFactory,
+	type FixRecursiveArraySchema,
+	type TreeNodeFromImplicitAllowedTypes,
+	type ValidateRecursiveSchema,
+} from "./simple-tree/index.js";
+import type { JsonCompatible } from "./util/index.js";
+
+const sf = new SchemaFactory("com.fluidframework.serializable");
+
+/**
+ * Utilities for storing {@link FluidSerializableAsTree.Data|Fluid Serializable data} in {@link TreeNode}s.
+ *
+ * Same as {@link JsonAsTree} except allows {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}s.
+ * @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.importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
+ * @internal
+ */
+export namespace FluidSerializableAsTree {
+	/**
+	 * Data which can be serialized by Fluid.
+	 * @remarks
+	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link TreeAlpha.importConcise}.
+	 * @internal
+	 */
+	export type Data = JsonCompatible<IFluidHandle>;
+
+	/**
+	 * {@link AllowedTypes} for any content allowed in the {@link FluidSerializableAsTree} domain.
+	 * @example
+	 * ```typescript
+	 * const tree = TreeAlpha.importConcise(FluidSerializableAsTree.Tree, { example: { nested: true }, value: 5 });
+	 * ```
+	 * @internal
+	 */
+	export const Tree = [
+		() => FluidSerializableObject,
+		() => Array,
+		...SchemaFactory.leaves,
+	] as const;
+
+	/**
+	 * @internal
+	 */
+	export type Tree = TreeNodeFromImplicitAllowedTypes<typeof Tree>;
+
+	/**
+	 * Do not use. Exists only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.
+	 * @system @internal
+	 */
+	export const _APIExtractorWorkaroundObjectBase = sf.mapRecursive("object", Tree);
+
+	/**
+	 * Arbitrary Fluid Serializable object as a {@link TreeNode}.
+	 * @remarks
+	 * API of the tree node is more aligned with an es6 map than a JS object using its properties like a map.
+	 * @example
+	 * ```typescript
+	 * // 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 });
+	 * // Node API is like a Map:
+	 * const value = imported.get("a");
+	 * ```
+	 * @privateRemarks
+	 * Due to https://github.com/microsoft/TypeScript/issues/61270 this can't be named `Object`.
+	 * @sealed @internal
+	 */
+	export class FluidSerializableObject extends _APIExtractorWorkaroundObjectBase {}
+	{
+		type _check = ValidateRecursiveSchema<typeof FluidSerializableObject>;
+	}
+
+	/**
+	 * D.ts bug workaround, see {@link FixRecursiveArraySchema}.
+	 * @privateRemarks
+	 * In the past this this had to reference the base type (_APIExtractorWorkaroundArrayBase).
+	 * Testing for this in examples/utils/import-testing now shows it has to reference FluidSerializableAsTree.Array instead.
+	 * @system @internal
+	 */
+	export declare type _RecursiveArrayWorkaroundJsonArray = FixRecursiveArraySchema<
+		typeof Array
+	>;
+
+	/**
+	 * Do not use. Exists only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.
+	 * @system @internal
+	 */
+	export const _APIExtractorWorkaroundArrayBase = sf.arrayRecursive("array", Tree);
+
+	/**
+	 * Arbitrary Fluid Serializable array as a {@link TreeNode}.
+	 * @remarks
+	 * This can be imported using {@link TreeAlpha.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]]);
+	 * // Node API is like an Array:
+	 * const inner: FluidSerializableAsTree.Tree = imported[2];
+	 * assert(Tree.is(inner, FluidSerializableAsTree.Array));
+	 * const leaf = inner[0];
+	 * ```
+	 * @sealed @internal
+	 */
+	export class Array extends _APIExtractorWorkaroundArrayBase {}
+	{
+		type _check = ValidateRecursiveSchema<typeof Array>;
+	}
+}

package/src/shared-tree/index.ts

@@ -21,7 +21,6 @@ export {
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
 	ForestTypeReference,
-	type IChannelView,
 } from "./sharedTree.js";
 
 export {

package/src/shared-tree/schematizeTree.ts

@@ -198,7 +198,7 @@ export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredConte
 					break;
 				}
 				default: {
-					fail("unexpected root field kind during initialize");
+					fail(0xac7 /* unexpected root field kind during initialize */);
 				}
 			}
 		});

package/src/shared-tree/sharedTree.ts

@@ -13,10 +13,10 @@ import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
 	IChannelStorageService,
-	IChannel,
 } from "@fluidframework/datastore-definitions/internal";
 import {
 	SharedObject,
+	type IChannelView,
 	type IFluidSerializer,
 	type ISharedObject,
 } from "@fluidframework/shared-object-base/internal";
@@ -29,6 +29,7 @@ import type {
 	ITelemetryContext,
 	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
+	IRuntimeMessageCollection,
 } from "@fluidframework/runtime-definitions/internal";
 import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 
@@ -100,13 +101,7 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
-import {
-	Breakable,
-	breakingClass,
-	fail,
-	throwIfBroken,
-	type WithBreakable,
-} from "../util/index.js";
+import { Breakable, breakingClass, fail, throwIfBroken } from "../util/index.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -132,14 +127,6 @@ export interface SharedTreeContentSnapshot {
 	readonly removed: [string | number | undefined, number, JsonableTree][];
 }
 
-/**
- * Information about a Fluid channel.
- * @privateRemarks
- * This is distinct from {@link IChannel} as it omits the APIs used by the runtime to manage the channel and instead only has things which are useful (and safe) to expose to users of the channel.
- * @internal
- */
-export type IChannelView = Pick<IChannel, "id" | "attributes" | "isAttached">;
-
 /**
  * {@link ITree} extended with some non-public APIs.
  * @internal
@@ -161,6 +148,11 @@ export interface ITreePrivate extends ITreeInternal {
 	 * This does not include everything that is included in a tree summary, since information about how to merge future edits is omitted.
 	 */
 	contentSnapshot(): SharedTreeContentSnapshot;
+
+	/**
+	 * Access to internals for testing.
+	 */
+	readonly kernel: SharedTreeKernel;
 }
 
 /**
@@ -215,17 +207,10 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 /**
  * Shared object wrapping {@link SharedTreeKernel}.
  */
-export class SharedTree extends SharedObject implements ISharedTree, WithBreakable {
-	public readonly breaker: Breakable = new Breakable("Shared Tree");
+export class SharedTree extends SharedObject implements ISharedTree {
+	private readonly breaker: Breakable = new Breakable("Shared Tree");
 
-	public get checkout(): TreeCheckout {
-		return this.kernel.checkout;
-	}
-	public get storedSchema(): TreeStoredSchemaRepository {
-		return this.checkout.storedSchema;
-	}
-
-	private readonly kernel: SharedTreeKernel;
+	public readonly kernel: SharedTreeKernel;
 
 	public constructor(
 		id: string,
@@ -250,10 +235,6 @@ export class SharedTree extends SharedObject implements ISharedTree, WithBreakab
 		);
 	}
 
-	public get editor(): SharedTreeEditBuilder {
-		return this.kernel.getEditor();
-	}
-
 	public summarizeCore(
 		serializer: IFluidSerializer,
 		telemetryContext?: ITelemetryContext,
@@ -270,7 +251,13 @@ export class SharedTree extends SharedObject implements ISharedTree, WithBreakab
 		this.kernel.processCore(message, local, localOpMetadata);
 	}
 
-	protected onDisconnect(): void {}
+	protected override processMessagesCore(messagesCollection: IRuntimeMessageCollection): void {
+		this.kernel.processMessagesCore(messagesCollection);
+	}
+
+	protected onDisconnect(): void {
+		this.kernel.onDisconnect();
+	}
 
 	public exportVerbose(): VerboseTree | undefined {
 		return this.kernel.exportVerbose();
@@ -483,7 +470,7 @@ class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeC
 				cursor.enterNode(0);
 				return verboseFromCursor(cursor, this.storedSchema.nodeSchema);
 			} else {
-				fail("Invalid document root length");
+				fail(0xac8 /* Invalid document root length */);
 			}
 		} finally {
 			cursor.free();
@@ -581,6 +568,8 @@ class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeC
 			super.submitCommit(commit, schemaAndPolicy, isResubmit),
 		);
 	}
+
+	public onDisconnect(): void {}
 }
 
 /**
@@ -607,13 +596,13 @@ export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 export function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(
 	treeOrView: ITree | TreeViewAlpha<T>,
 ): BranchableTree {
-	assert(
-		treeOrView instanceof SharedTree || treeOrView instanceof SchematizingSimpleTreeView,
-		0xa48 /* Unsupported implementation */,
-	);
-	const checkout: TreeCheckout = treeOrView.checkout;
+	if (treeOrView instanceof SchematizingSimpleTreeView) {
+		return treeOrView.checkout as unknown as BranchableTree;
+	}
+	const kernel = (treeOrView as ITree as ITreePrivate).kernel;
+	assert(kernel instanceof SharedTreeKernel, 0xb56 /* Invalid ITree */);
 	// This cast is safe so long as TreeCheckout supports all the operations on the branch interface.
-	return checkout as unknown as BranchableTree;
+	return kernel.checkout as unknown as BranchableTree;
 }
 
 /**
@@ -778,7 +767,8 @@ function verboseFromCursor(
 	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
 ): VerboseTree {
 	const fields = customFromCursorStored(reader, schema, verboseFromCursor);
-	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
+	const nodeSchema =
+		schema.get(reader.type) ?? fail(0xac9 /* missing schema for type in cursor */);
 	if (nodeSchema instanceof LeafNodeStoredSchema) {
 		return fields as CustomTreeValue<IFluidHandle>;
 	}
@@ -806,7 +796,7 @@ function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFie
 			assert(schema.types.size === 0, 0xa94 /* invalid forbidden field */);
 			break;
 		default:
-			fail("invalid field kind");
+			fail(0xaca /* invalid field kind */);
 	}
 	return { kind, allowedTypes: schema.types };
 }
@@ -833,5 +823,5 @@ function exportSimpleNodeSchemaStored(schema: TreeNodeStoredSchema): SimpleNodeS
 	if (schema instanceof LeafNodeStoredSchema) {
 		return { kind: NodeKind.Leaf, leafKind: schema.leafValue };
 	}
-	fail("invalid schema kind");
+	fail(0xacb /* invalid schema kind */);
 }

package/src/shared-tree/sharedTreeChangeFamily.ts

@@ -151,7 +151,7 @@ export class SharedTreeChangeFamily
 					};
 				}
 				default:
-					fail("Unknown SharedTree change type.");
+					fail(0xacc /* Unknown SharedTree change type. */);
 			}
 		};
 		return {

package/src/shared-tree/treeApiAlpha.ts

@@ -310,7 +310,11 @@ export const TreeAlpha: {
 		};
 
 		const cursor = borrowCursorFromTreeNodeOrValue(node);
-		return conciseFromCursor(cursor, tryGetSchema(node) ?? fail("invalid input"), config);
+		return conciseFromCursor(
+			cursor,
+			tryGetSchema(node) ?? fail(0xacd /* invalid input */),
+			config,
+		);
 	},
 
 	exportVerbose<T>(
@@ -325,7 +329,11 @@ export const TreeAlpha: {
 		};
 
 		const cursor = borrowCursorFromTreeNodeOrValue(node);
-		return verboseFromCursor(cursor, tryGetSchema(node) ?? fail("invalid input"), config);
+		return verboseFromCursor(
+			cursor,
+			tryGetSchema(node) ?? fail(0xace /* invalid input */),
+			config,
+		);
 	},
 
 	exportCompressed(
@@ -335,7 +343,7 @@ export const TreeAlpha: {
 			idCompressor?: IIdCompressor;
 		},
 	): JsonCompatible<IFluidHandle> {
-		const schema = tryGetSchema(node) ?? fail("invalid input");
+		const schema = tryGetSchema(node) ?? fail(0xacf /* invalid input */);
 		const format = versionToFormat[options.oldestCompatibleClient];
 		const codec = makeFieldBatchCodec({ jsonValidator: noopValidator }, format);
 		const cursor = borrowFieldCursorFromTreeNodeOrValue(node);
@@ -375,7 +383,7 @@ function borrowCursorFromTreeNodeOrValue(
 ): ITreeCursorSynchronous {
 	if (isTreeValue(node)) {
 		return cursorFromInsertable<UnsafeUnknownSchema>(
-			tryGetSchema(node) ?? fail("missing schema"),
+			tryGetSchema(node) ?? fail(0xad0 /* missing schema */),
 			node,
 		);
 	}

package/src/shared-tree/treeCheckout.ts

@@ -524,7 +524,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 					// original (reinstated) schema.
 					this.storedSchema.apply(change.innerChange.schema.new);
 				} else {
-					fail("Unknown Shared Tree change type.");
+					fail(0xad1 /* Unknown Shared Tree change type. */);
 				}
 			}
 		}