@fluidframework/tree 2.113.1 → 2.115.0

package/src/text/textDomainFormattedDefault.ts

@@ -3,23 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import {
-	enumFromStrings,
-	SchemaFactory,
-	SchemaFactoryAlpha,
-	SchemaFactoryBeta,
-} from "../simple-tree/index.js";
+import { enumFromStrings, SchemaFactory, SchemaFactoryBeta } from "../simple-tree/index.js";
 import type {
 	TreeNodeFromImplicitAllowedTypes,
 	InsertableTreeNodeFromImplicitAllowedTypes,
 } from "../simple-tree/index.js";
 
-import { FormattedTextAsTree } from "./textDomainFormatted.js";
+import { FormattedText } from "./textDomainFormatted.js";
 
 /**
  * Schema factory for default formatted text types which are not generic.
  */
-const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted.default");
+const sf = new SchemaFactoryBeta("com.fluidframework.text.formatted.default");
 
 const defaultFormat = {
 	bold: false,
@@ -30,28 +25,25 @@ const defaultFormat = {
 } as const;
 
 /**
- * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * A default parameterization of the generic {@link FormattedText} with hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
  * @remarks
- * This is a default parameterization of the generic {@link FormattedTextAsTree} with hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
- * It is unlikely this meets the needs of most users, but it can serve as an unstable example of how to use the generic {@link FormattedTextAsTree}.
+ * It is unlikely this meets the needs of most users, but it can serve as an unstable example of how to use the generic {@link FormattedText}.
  * @internal
  */
-export namespace FormattedTextAsTreeDefault {
+export namespace FormattedTextDefault {
 	/**
 	 * Portion of a string with formatting.
 	 * @sealed
 	 * @internal
 	 */
-	export type FormattedAtom = FormattedTextAsTree.FormattedAtom<
-		CharacterFormat,
-		StringAtomContent
-	>;
+	export type FormattedAtom = FormattedText.FormattedAtom<CharacterFormat, StringAtomContent>;
 
 	/**
 	 * Formatting options for characters.
+	 * @sealed
 	 * @internal
 	 */
-	export class CharacterFormat extends sf.objectAlpha("CharacterFormat", {
+	export class CharacterFormat extends sf.object("CharacterFormat", {
 		bold: SchemaFactory.boolean,
 		italic: SchemaFactory.boolean,
 		underline: SchemaFactory.boolean,
@@ -79,7 +71,8 @@ export namespace FormattedTextAsTreeDefault {
 		"codeBlock",
 	]);
 	/**
-	 * {@inheritdoc FormattedTextAsTreeDefault.(LineTag:variable)}
+	 * {@inheritdoc FormattedTextDefault.(LineTag:variable)}
+	 * @sealed
 	 * @internal
 	 */
 	export type LineTag = TreeNodeFromImplicitAllowedTypes<typeof LineTag.schema>;
@@ -93,6 +86,7 @@ export namespace FormattedTextAsTreeDefault {
 	 * The optional indent level mirrors Quill's indent attribute,
 	 * which is applies to the line before the line break.
 	 * Any tagged line can be indented independently.
+	 * @sealed
 	 * @internal
 	 */
 	export class StringLineAtom extends sf.object("StringLineAtom", {
@@ -104,45 +98,51 @@ export namespace FormattedTextAsTreeDefault {
 
 	/**
 	 * Types of "atoms" that make up the text.
+	 * @sealed
 	 * @internal
 	 */
-	export const StringAtomContent = [
-		FormattedTextAsTree.StringTextAtom,
-		StringLineAtom,
-	] as const;
+	export const StringAtomContent = [FormattedText.StringTextAtom, StringLineAtom] as const;
 	/**
-	 * {@inheritdoc FormattedTextAsTreeDefault.(StringAtomContent:variable)}
+	 * {@inheritdoc FormattedTextDefault.(StringAtomContent:variable)}
+	 * @sealed
 	 * @internal
 	 */
 	export type StringAtomContent = TreeNodeFromImplicitAllowedTypes<typeof StringAtomContent>;
 
 	/**
 	 * Statics for text nodes.
+	 * @sealed
 	 * @internal
 	 */
-	export type Statics<TTree = Tree> = FormattedTextAsTree.Statics<TTree>;
+	export type Statics<TTree = Tree> = FormattedText.Statics<TTree, typeof CharacterFormat>;
 
 	/**
-	 * Insertable shape for a formatted text atom used by {@link FormattedTextAsTree.Members.insertWithFormattingAt}.
+	 * Insertable shape for a formatted text atom used by {@link FormattedText.Members.insertWithFormattingAt}.
+	 * @sealed
 	 * @internal
 	 */
-	export type FormattedAtomInsertable = FormattedTextAsTree.FormattedAtom<
+	export type FormattedAtomInsertable = FormattedText.FormattedAtom<
 		InsertableTreeNodeFromImplicitAllowedTypes<typeof CharacterFormat>,
-		InsertableTreeNodeFromImplicitAllowedTypes<FormattedTextAtoms>
+		InsertableTreeNodeFromImplicitAllowedTypes<TextAtomSchemas>
 	>;
 
 	/**
 	 * Helper for expressing the full set of formatted text atoms for a given schema.
 	 * @privateRemarks
 	 * Eventually this should probably be given a better name and/or made a system type in a system namespace.
+	 * @sealed
 	 * @internal
 	 */
-	export type FormattedTextAtoms = FormattedTextAsTree.FormattedTextAtoms<
-		[typeof StringLineAtom]
-	>;
+	export type TextAtomSchemas = FormattedText.TextAtomSchemas<[typeof StringLineAtom]>;
 
-	export class Tree extends FormattedTextAsTree.createSchema(
-		new SchemaFactoryBeta("default"),
+	/**
+	 * The schema produced using {@link FormattedText.createSchema} with hard-coded assumptions
+	 * about what kind of embedded content and what kind of formatting is supported.
+	 * @sealed
+	 * @internal
+	 */
+	export class Tree extends FormattedText.createSchema(
+		sf,
 		CharacterFormat,
 		[StringLineAtom],
 		defaultFormat,

package/src/treeDataStore.ts

@@ -0,0 +1,125 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidLoadable } from "@fluidframework/core-interfaces";
+import type { DataStoreKind } from "@fluidframework/driver-definitions/internal";
+import type {
+	SharedObjectCreator,
+	SharedObjectKey,
+	SharedObjectRegistry,
+	SharedObjectKindAlpha,
+	DataStoreOptions,
+} from "@fluidframework/shared-object-base/internal";
+import {
+	sharedObjectRegistryFromIterable,
+	defineDataStore,
+} from "@fluidframework/shared-object-base/internal";
+
+import type {
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	ITree,
+	TreeView,
+	TreeViewConfiguration,
+} from "./simple-tree/index.js";
+import { SharedTreeAlpha } from "./treeFactory.js";
+
+/**
+ * Options for {@link defineTreeDataStore}.
+ * @input
+ * @alpha
+ */
+export interface TreeDataStoreOptions<TSchema extends ImplicitFieldSchema>
+	extends Pick<DataStoreOptions<never, never>, "type"> {
+	/**
+	 * Configuration for the tree view to be used in this data store.
+	 */
+	readonly config: TreeViewConfiguration<TSchema>;
+
+	/**
+	 * If provided, used to initialize the tree content when creating a new instance of the data store.
+	 */
+	readonly initializer?: (
+		creator: SharedObjectCreator,
+	) => InsertableTreeFieldFromImplicitField<TSchema>;
+
+	/**
+	 * If provided, must include at least a SharedTree kind in the registry.
+	 * @remarks
+	 * {@link configuredSharedTree} can be used to customize the SharedTree kind used in the registry.
+	 */
+	readonly registry?: Iterable<SharedObjectKindAlpha<IFluidLoadable>> | SharedObjectRegistry;
+
+	readonly key?: SharedObjectKey<ITree>;
+}
+
+/**
+ * Defines a {@link @fluidframework/driver-definitions#DataStoreKind} for a simple tree data store.
+ * @remarks
+ * This is a simple tree specific wrapper around {@link @fluidframework/shared-object-base#defineDataStore}.
+ * Use {@link @fluidframework/shared-object-base#defineDataStore} directly if more control is needed, even if still just using tree.
+ *
+ * This uses {@link instantiateTreeFirstTime} to create the tree, and optionally initialize it.
+ * @alpha
+ */
+export function defineTreeDataStore<const TSchema extends ImplicitFieldSchema>(
+	options: TreeDataStoreOptions<TSchema>,
+): DataStoreKind<TreeView<TSchema>> {
+	const registry: SharedObjectRegistry =
+		typeof options.registry === "function"
+			? options.registry
+			: sharedObjectRegistryFromIterable([...(options.registry ?? [SharedTreeAlpha])]);
+
+	const result = defineDataStore<TreeView<TSchema>, ITree>({
+		type: options.type,
+		registry,
+		async instantiateFirstTime(
+			rootCreator: SharedObjectCreator,
+			creator: SharedObjectCreator,
+		): Promise<ITree> {
+			return instantiateTreeFirstTime(
+				rootCreator,
+				creator,
+				options.key ?? SharedTreeAlpha,
+				options,
+			);
+		},
+		async view(tree): Promise<TreeView<TSchema>> {
+			const view = tree.viewWith(options.config);
+			return view;
+		},
+	});
+	return result;
+}
+
+/**
+ * Simple tree instantiation helper.
+ * @remarks
+ * This is used by {@link defineTreeDataStore}, but can also be used in custom data stores with {@link @fluidframework/shared-object-base#defineDataStore}.
+ * Typically used to implement {@link @fluidframework/shared-object-base#DataStoreOptions.instantiateFirstTime} to create the tree and optionally initialize it.
+ * @alpha
+ */
+export async function instantiateTreeFirstTime<TSchema extends ImplicitFieldSchema>(
+	rootCreator: SharedObjectCreator,
+	creator: SharedObjectCreator,
+	treeKind: SharedObjectKey<ITree>,
+	options: Pick<TreeDataStoreOptions<TSchema>, "config" | "initializer">,
+): Promise<ITree> {
+	const tree = await rootCreator.createSharedObject(treeKind);
+	initializeTreeFirstTime(tree, options, creator);
+	return tree;
+}
+
+function initializeTreeFirstTime<TSchema extends ImplicitFieldSchema>(
+	tree: ITree,
+	options: Pick<TreeDataStoreOptions<TSchema>, "config" | "initializer">,
+	creator: SharedObjectCreator,
+): void {
+	if (options.initializer !== undefined) {
+		const view = tree.viewWith(options.config);
+		view.initialize(options.initializer(creator));
+		view.dispose();
+	}
+}

package/src/treeFactory.ts

@@ -13,6 +13,7 @@ import {
 	type SharedKernelFactory,
 	type SharedObjectOptions,
 	type FactoryOut,
+	type SharedObjectKindAlpha,
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -111,7 +112,14 @@ function treeKernelFactory(
  * of objects, arrays, and other data types.
  * @legacy @beta
  */
-export const SharedTree = configuredSharedTree({});
+export const SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree> =
+	configuredSharedTree({});
+
+/**
+ * {@link SharedTree} but without legacy types, and with alpha types.
+ * @alpha
+ */
+export const SharedTreeAlpha: SharedObjectKindAlpha<ITree> = configuredSharedTree({});
 
 /**
  * {@link SharedTree} but allowing a non-default configuration.
@@ -189,14 +197,14 @@ export function configuredSharedTreeAlpha(
  */
 export function configuredSharedTree(
 	options: SharedTreeOptions,
-): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {
 	const internalOptions = resolveOptions(options);
 	return configuredSharedTreeInternal(internalOptions);
 }
 
 export function configuredSharedTreeInternal(
 	options: SharedTreeOptionsInternal,
-): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+): ISharedObjectKind<ITree> & SharedObjectKindAlpha<ITree> {
 	const sharedObjectOptions: SharedObjectOptions<ITree> = {
 		type: SharedTreeFactoryType,
 		attributes: SharedTreeAttributes,

package/src/util/compressedIds.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { LogLevel, type ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import type {
 	IIdCompressor,
@@ -166,6 +167,12 @@ export interface IdentifierHealingConfig {
 	 * same session offsets.
 	 */
 	readonly sharedObjectId: string;
+
+	/**
+	 * Optional logger used by {@link forceDecodeEncodedIdWithoutSession} to record telemetry
+	 * when the heal-on-decode recovery path is taken (a non-final identifier is healed).
+	 */
+	readonly logger?: ITelemetryBaseLogger;
 }
 
 /**
@@ -177,6 +184,16 @@ export interface IdentifierHealingConfig {
  * deterministic v5 UUID string — *not* a `StableId`, since that brand requires
  * v4, but still a valid identifier value; the `string` arm of the return type
  * covers this case.
+ *
+ * The recovery (heal) path only occurs because of a prior bug where non-finalized identifiers were
+ * written into summaries. When {@link IdentifierHealingConfig.logger} is supplied, a telemetry event
+ * is recorded on that path so heals can be observed in the wild. The error/throw path is intentionally
+ * not instrumented here: the thrown exception is expected to surface via the application's own error
+ * telemetry, and should never be silently swallowed.
+ *
+ * @param id - The op-space compressed ID to decode.
+ * @param idCompressor - The ID compressor used to normalize the ID.
+ * @param healing - Heal-on-decode configuration. Presence enables healing of non-final IDs.
  */
 export function forceDecodeEncodedIdWithoutSession(
 	id: OpSpaceCompressedId,
@@ -189,7 +206,19 @@ export function forceDecodeEncodedIdWithoutSession(
 	}
 	// `id` is a non-final op-space compressed id.
 	if (healing !== undefined) {
-		return uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
+		const healed = uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
+		healing.logger?.send(
+			{
+				category: "generic",
+				eventName: "HealUnresolvableIdentifierOnDecode",
+			},
+			// This telemetry should be very low-volume (and possibly never happen at all),
+			// as should only occur when loading documents that were corrupted by a now fixed bug and have not been re-summarized since healing was added.
+			// It is useful for monitoring and diagnosing for this to be reported in the same cases in which the error case would be reported,
+			// which is the essential level.
+			LogLevel.essential,
+		);
+		return healed;
 	}
 	throw new Error(
 		"Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.",
@@ -261,9 +290,13 @@ export interface IdDecoderOptionsWithOriginator {
  */
 export class IdDecodingContext {
 	/**
-	 * Used internally to prevent the use of this decoder in incremental chunks if it has a session id (which would be wrong in those chunks).
+	 * Whether this context resolves identifiers using an originator session ID.
+	 * @remarks
+	 * Consulted by {@link FieldBatchDecodingContext} to prevent using an originator-based
+	 * decoder in incremental chunks (which may come from other sessions, making such a
+	 * decoder wrong there).
 	 */
-	protected readonly hasOriginatorSessionId: boolean;
+	public readonly hasOriginatorSessionId: boolean;
 
 	/**
 	 * Compressor which can decompress session-space identifiers from {@link resolveEncodedId} as needed.