@fluidframework/tree 2.71.0 → 2.72.0

package/src/simple-tree/core/treeNode.ts

@@ -8,7 +8,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
-// eslint-disable-next-line import/no-deprecated
+// eslint-disable-next-line import-x/no-deprecated
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
 import { markEager } from "./flexList.js";
 
@@ -80,7 +80,7 @@ export abstract class TreeNode implements WithType {
 	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
 	 * @deprecated Use {@link typeSchemaSymbol} instead.
 	 */
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	public abstract get [typeNameSymbol](): string;
 
 	/**

package/src/simple-tree/index.ts

@@ -74,6 +74,7 @@ export {
 	type ITreeConfigurationOptions,
 	SchemaFactory,
 	SchemaFactoryBeta,
+	type SchemaStaticsBeta,
 	SchemaFactoryAlpha,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
@@ -180,7 +181,6 @@ export {
 	type TreeChangeEvents,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
-	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
 	incrementalSummaryHint,
@@ -280,3 +280,7 @@ export {
 	nullSchema,
 } from "./leafNodeSchema.js";
 export type { LeafSchema } from "./leafNodeSchema.js";
+export {
+	encodeSimpleSchema,
+	decodeSimpleSchema,
+} from "./api/index.js";

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -16,7 +16,7 @@ import { FieldKinds, isTreeValue } from "../../../feature-libraries/index.js";
 import {
 	CompatibilityLevel,
 	type WithType,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	NodeKind,
 	type TreeNode,
@@ -1266,7 +1266,7 @@ export function arraySchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -22,7 +22,7 @@ import {
 	type InnerNode,
 	NodeKind,
 	type TreeNodeSchema,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	type TreeNode,
 	typeSchemaSymbol,
@@ -334,7 +334,7 @@ export function mapSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -32,7 +32,7 @@ import {
 	type TreeNodeSchema,
 	NodeKind,
 	type WithType,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type InternalTreeNode,
@@ -275,7 +275,7 @@ function createProxyHandler(
 			if (propertyKey === typeSchemaSymbol) {
 				return schema;
 			}
-			// eslint-disable-next-line import/no-deprecated
+			// eslint-disable-next-line import-x/no-deprecated
 			if (propertyKey === typeNameSymbol) {
 				return schema.identifier;
 			}
@@ -573,7 +573,7 @@ export function objectSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			nodeOptions.persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -11,7 +11,7 @@ import { type JsonCompatibleReadOnlyObject, brand } from "../../../util/index.js
 import {
 	type TreeNodeSchema,
 	NodeKind,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type UnhydratedFlexTreeNode,
@@ -80,7 +80,7 @@ function createRecordNodeProxy(
 					case typeSchemaSymbol: {
 						return schema;
 					}
-					// eslint-disable-next-line import/no-deprecated
+					// eslint-disable-next-line import-x/no-deprecated
 					case typeNameSymbol: {
 						return schema.identifier;
 					}
@@ -370,7 +370,7 @@ export function recordSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/simpleSchema.ts

@@ -58,6 +58,15 @@ export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown>
 	 * especially if/when TreeNodeSchema for objects provide more maps.
 	 */
 	readonly fields: ReadonlyMap<string, SimpleObjectFieldSchema>;
+
+	/**
+	 * Whether the object node allows unknown optional fields.
+	 *
+	 * @see {@link ObjectSchemaOptions.allowUnknownOptionalFields} for the API where this field is set as part of authoring a schema.
+	 *
+	 * @remarks Only populated for view schemas, undefined otherwise. Relevant for compatibility checking scenarios.
+	 */
+	readonly allowUnknownOptionalFields: boolean | undefined;
 }
 
 /**
@@ -163,14 +172,14 @@ export type SimpleNodeSchema =
 	| SimpleRecordNodeSchema;
 
 /**
- * Information about allowed types.
+ * Information about allowed types under a field.
  *
  * @alpha
  * @sealed
  */
 export interface SimpleAllowedTypeAttributes {
 	/**
-	 * True if this schema is included as a {@link SchemaStaticsAlpha.staged | staged} schema upgrade,
+	 * True if this schema is included as a {@link SchemaStaticsBeta.staged | staged} schema upgrade,
 	 * allowing the view schema be compatible with stored schema with (post upgrade) or without it (pre-upgrade).
 	 * New documents and schema upgrades will omit any staged schema.
 	 *
@@ -238,7 +247,7 @@ export interface SimpleTreeSchema {
 	 * @remarks
 	 * The keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
 	 *
-	 * Information about if a schema is {@link SchemaStaticsAlpha.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
+	 * Information about if a schema is {@link SchemaStaticsBeta.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
 	 * Options for filtering out staged schemas from view schema are available in {@link extractPersistedSchema}.
 	 */
 	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;

package/src/simple-tree/simpleSchemaFormatV1.ts

@@ -0,0 +1,179 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Type, type ObjectOptions, type Static } from "@sinclair/typebox";
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+/**
+ * The format version for the schema.
+ */
+export const SimpleSchemaFormatVersion = {
+	v1: 1,
+} as const;
+
+/**
+ * The allowed types and their attributes in the simple schema format.
+ * @see {@link SimpleAllowedTypes}.
+ */
+export const SimpleAllowedTypeAttributesFormat = Type.Object(
+	{
+		isStaged: Type.Optional(Type.Boolean()),
+	},
+	noAdditionalProps,
+);
+
+export type SimpleAllowedTypeAttributesFormat = Static<
+	typeof SimpleAllowedTypeAttributesFormat
+>;
+
+/**
+ * A set of allowed types in the simple schema format.
+ * The keys are the type identifiers, and the values are their attributes.
+ */
+export const SimpleAllowedTypesFormat = Type.Record(
+	Type.String(),
+	SimpleAllowedTypeAttributesFormat,
+);
+export type SimpleAllowedTypesFormat = Static<typeof SimpleAllowedTypesFormat>;
+
+/**
+ * Persisted format for a field schema in the simple schema format.
+ * @see {@link SimpleFieldSchema}.
+ */
+export const SimpleFieldSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		simpleAllowedTypes: SimpleAllowedTypesFormat,
+	},
+	noAdditionalProps,
+);
+export type SimpleFieldSchemaFormat = Static<typeof SimpleFieldSchemaFormat>;
+
+/**
+ * Persisted format for an object field schema in the simple schema format.
+ * @see {@link SimpleObjectFieldSchema}.
+ */
+export const SimpleObjectFieldSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		simpleAllowedTypes: SimpleAllowedTypesFormat,
+		storedKey: Type.String(),
+	},
+	noAdditionalProps,
+);
+export type SimpleObjectFieldSchemaFormat = Static<typeof SimpleObjectFieldSchemaFormat>;
+
+/**
+ * Persisted format for an array node schema in the simple schema format.
+ * @see {@link SimpleArrayNodeSchema}.
+ */
+export const SimpleArrayNodeSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		simpleAllowedTypes: SimpleAllowedTypesFormat,
+	},
+	noAdditionalProps,
+);
+export type SimpleArrayNodeSchemaFormat = Static<typeof SimpleArrayNodeSchemaFormat>;
+
+/**
+ * Persisted format for a map node schema in the simple schema format.
+ * @see {@link SimpleMapNodeSchema}.
+ */
+export const SimpleMapNodeSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		simpleAllowedTypes: SimpleAllowedTypesFormat,
+	},
+	noAdditionalProps,
+);
+export type SimpleMapNodeSchemaFormat = Static<typeof SimpleMapNodeSchemaFormat>;
+
+/**
+ * Persisted format for a record node schema in the simple schema format.
+ * @see {@link SimpleRecordNodeSchema}.
+ */
+export const SimpleRecordNodeSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		simpleAllowedTypes: SimpleAllowedTypesFormat,
+	},
+	noAdditionalProps,
+);
+export type SimpleRecordNodeSchemaFormat = Static<typeof SimpleRecordNodeSchemaFormat>;
+
+/**
+ * Persisted format for a leaf node schema in the simple schema format.
+ * @see {@link SimpleLeafNodeSchema}.
+ */
+export const SimpleLeafNodeSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		leafKind: Type.Integer(),
+	},
+	noAdditionalProps,
+);
+export type SimpleLeafNodeSchemaFormat = Static<typeof SimpleLeafNodeSchemaFormat>;
+
+/**
+ * Persisted format for the field schemas of an object node in the simple schema format.
+ */
+export const SimpleObjectFieldSchemasFormat = Type.Record(
+	Type.String(),
+	SimpleObjectFieldSchemaFormat,
+);
+export type SimpleObjectFieldSchemasFormat = Static<typeof SimpleObjectFieldSchemasFormat>;
+
+/**
+ * Persisted format for an object node schema in the simple schema format.
+ * @see {@link SimpleObjectNodeSchema}.
+ */
+export const SimpleObjectNodeSchemaFormat = Type.Object(
+	{
+		kind: Type.Integer(),
+		fields: SimpleObjectFieldSchemasFormat,
+		allowUnknownOptionalFields: Type.Optional(Type.Boolean()),
+	},
+	noAdditionalProps,
+);
+export type SimpleObjectNodeSchemaFormat = Static<typeof SimpleObjectNodeSchemaFormat>;
+
+/**
+ * Discriminated union of all possible node schemas.
+ *
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+export const SimpleNodeSchemaUnionFormat = Type.Object({
+	array: Type.Optional(SimpleArrayNodeSchemaFormat),
+	map: Type.Optional(SimpleMapNodeSchemaFormat),
+	record: Type.Optional(SimpleRecordNodeSchemaFormat),
+	leaf: Type.Optional(SimpleLeafNodeSchemaFormat),
+	object: Type.Optional(SimpleObjectNodeSchemaFormat),
+});
+export type SimpleNodeSchemaUnionFormat = Static<typeof SimpleNodeSchemaUnionFormat>;
+
+/**
+ * Helper type for the schema definitions map in the persisted format.
+ */
+export const SimpleSchemaDefinitionsFormat = Type.Record(
+	Type.String(),
+	SimpleNodeSchemaUnionFormat,
+);
+export type SimpleSchemaDefinitionsFormat = Static<typeof SimpleSchemaDefinitionsFormat>;
+
+/**
+ * Persisted format for the entire tree schema in the simple schema format.
+ * @see {@link SimpleTreeSchema}.
+ */
+export const SimpleTreeSchemaFormat = Type.Object(
+	{
+		version: Type.Literal(SimpleSchemaFormatVersion.v1),
+		root: SimpleFieldSchemaFormat,
+		definitions: SimpleSchemaDefinitionsFormat,
+	},
+	noAdditionalProps,
+);
+export type SimpleTreeSchemaFormat = Static<typeof SimpleTreeSchemaFormat>;

package/src/tableSchema.ts

@@ -216,7 +216,10 @@ export namespace System_TableSchema {
 					throw new UsageError(`Column with ID "${this.id}" is not contained in a table.`);
 				}
 
-				const result = [];
+				const result: {
+					rowId: string;
+					cell: CellValueType;
+				}[] = [];
 				for (const row of tableNode.rows) {
 					const cell = row.getCell(this.id);
 					if (cell !== undefined) {
@@ -226,7 +229,7 @@ export namespace System_TableSchema {
 							);
 						}
 
-						result.push({ rowId: row.id, cell: cell as CellValueType });
+						result.push({ rowId: row.id, cell });
 					}
 				}
 				return result;

package/src/treeFactory.ts

@@ -26,8 +26,12 @@ import {
 } from "./shared-tree/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
 import type { ITree } from "./simple-tree/index.js";
-import { Breakable } from "./util/index.js";
+import { Breakable, copyProperty } from "./util/index.js";
 import { FluidClientVersion } from "./codec/index.js";
+import {
+	editManagerFormatVersionSelectorForSharedBranches,
+	messageFormatVersionSelectorForSharedBranches,
+} from "./shared-tree-core/index.js";
 
 /**
  * {@link ITreePrivate} extended with ISharedObject.
@@ -169,6 +173,13 @@ export function configuredSharedTreeBetaLegacy(
  */
 export function configuredSharedTree(
 	options: SharedTreeOptions,
+): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
+	const internalOptions = resolveOptions(options);
+	return configuredSharedTreeInternal(internalOptions);
+}
+
+export function configuredSharedTreeInternal(
+	options: SharedTreeOptionsInternal,
 ): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {
 	const sharedObjectOptions: SharedObjectOptions<ITree> = {
 		type: SharedTreeFactoryType,
@@ -179,3 +190,24 @@ export function configuredSharedTree(
 
 	return makeSharedObjectKind<ITree>(sharedObjectOptions);
 }
+
+export function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {
+	const internal: SharedTreeOptionsInternal = {
+		...resolveSharedBranchesOptions(options.enableSharedBranches),
+	};
+	copyProperty(options, "forest", internal);
+	copyProperty(options, "jsonValidator", internal);
+	copyProperty(options, "minVersionForCollab", internal);
+	copyProperty(options, "treeEncodeType", internal);
+	return internal;
+}
+
+function resolveSharedBranchesOptions(
+	enableSharedBranches: boolean | undefined,
+): SharedTreeOptionsInternal {
+	return enableSharedBranches === true ? sharedBranchesOptions : {};
+}
+const sharedBranchesOptions: SharedTreeOptionsInternal = {
+	messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
+	editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
+};

package/src/util/brand.ts

@@ -9,7 +9,7 @@ import type { Covariant } from "./typeCheck.js";
 
 /**
  * Constructs a "Branded" type, adding a type-checking only field to `ValueType`.
- *
+ * @remarks
  * Two usages of `Brand` should never use the same `Name`.
  * If they do, the resulting types will be assignable which defeats the point of this type.
  *
@@ -18,11 +18,17 @@ import type { Covariant } from "./typeCheck.js";
  * `Type 'Name1' is not assignable to type 'Name2'.`
  *
  * These branded types are not opaque: A `Brand<A, B>` can still be used as a `A`.
+ *
+ * @example Simple usage:
+ * ```typescript
+ * export type StrongId = Brand<string, "tree.StrongId">;
+ * const x: StrongId = brand("myId");
+ * ```
  */
 export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;
 
 /**
- * Helper for {@link Brand}.
+ * Implementation detail for {@link Brand}.
  *
  * See `MakeNominal` for some more details.
  *
@@ -98,6 +104,11 @@ export type NameFromBranded<T extends BrandedType<unknown, unknown>> = T extends
  * Adds a type {@link Brand} to a value.
  *
  * Only do this when specifically allowed by the requirements of the type being converted to.
+ * @remarks
+ * This infers the branded type from context so it can very easily be used to a semantically invalid conversion.
+ * Treat this like "as" casts: they are an indicator that the user/reader must ensure the conversion is valid.
+ *
+ * If branding a constant, and wanting to preserve the exact typing of the constant, use {@link brandConst} instead.
  * @privateRemarks
  * Leaving `T` unconstrained here allows for better type inference when branding unions.
  * For example when assigning `brand(number)` a number to an optional branded number field,
@@ -111,3 +122,30 @@ export function brand<T>(
 ): T {
 	return value as T;
 }
+
+/**
+ * Adds a type {@link Brand} to a value, while preserving the exact type of the value being branded.
+ * @remarks
+ * This takes in the type to brand to as a required type parameter, unlike {@link brand} which infers it from context.
+ * This also preserves the exact type of the value being branded.
+ * TypeScript has no way to take an explicit type parameter and infer another in a single generic context.
+ * To work around this, two generic contexts are used, first a function to infer the parameter type,
+ * and a second function (returned) to take the explicit type parameter.
+ *
+ * This is intended for use when branding constants.
+ * @example
+ * ```typescript
+ * const requiredIdentifier = brandConst("Value")<FieldKindIdentifier>();
+ * ```
+ * @privateRemarks
+ * The dummy parameter is used to produce a compile error in the event where the value being branded is incompatible with the branded type.
+ */
+export function brandConst<const T>(
+	value: T,
+): <T2 extends BrandedType<unknown, unknown>>(
+	...dummy: T extends (T2 extends BrandedType<infer ValueType, unknown> ? ValueType : never)
+		? []
+		: [never]
+) => T2 & T {
+	return <T2>() => value as T2 & T;
+}

package/src/util/brandedMap.ts

@@ -11,10 +11,12 @@ import { getOrCreate } from "./utils.js";
 /**
  * Key in a {@link BrandedMapSubset}.
  * @remarks
+ * `TContent` is used as part of the brand to strongly associate the key type with the type of the values it looks up.
+ *
  * Due to the `TContent` type parameter being invariant (which it has to be since keys are used to both read and write data),
  * generic collections end up needing to constrain their key's `TContent` to `any`.
  */
-export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;
+export type BrandedKey<TKey, TContent> = Brand<TKey, ["BrandedKey", Invariant<TContent>]>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<

package/src/util/index.ts

@@ -9,6 +9,7 @@ export {
 	BrandedType,
 	type NameFromBranded,
 	type ValueFromBranded,
+	brandConst,
 } from "./brand.js";
 export { brandedNumberType, brandedStringType } from "./typeboxBrand.js";
 export {