@fluidframework/tree 2.70.0 → 2.72.0

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/simple-tree/toStoredSchema.ts

@@ -139,7 +139,10 @@ export function convertField(
 	if (schema instanceof FieldSchemaAlpha) {
 		types = convertAllowedTypes(schema.allowedTypes, options);
 	} else {
-		types = schema.allowedTypesIdentifiers as TreeTypeSet;
+		const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+			schema.simpleAllowedTypes.keys(),
+		);
+		types = allowedTypesIdentifiers as TreeTypeSet;
 	}
 	return { kind, types, persistedMetadata: schema.persistedMetadata };
 }
@@ -175,7 +178,10 @@ export function getStoredSchema(
 		}
 		case NodeKind.Map:
 		case NodeKind.Record: {
-			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
+			const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+				schema.simpleAllowedTypes.keys(),
+			);
+			const types = allowedTypesIdentifiers as TreeTypeSet;
 			return new MapNodeStoredSchema(
 				{
 					kind: FieldKinds.optional.identifier,
@@ -187,7 +193,10 @@ export function getStoredSchema(
 			);
 		}
 		case NodeKind.Array: {
-			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
+			const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+				schema.simpleAllowedTypes.keys(),
+			);
+			const types = allowedTypesIdentifiers as TreeTypeSet;
 			return arrayNodeStoredSchema(types, schema.persistedMetadata);
 		}
 		case NodeKind.Object: {

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 {

package/src/util/referenceCounting.ts

@@ -39,6 +39,7 @@ export interface ReferenceCounted {
  * Base class to assist with implementing ReferenceCounted.
  */
 export abstract class ReferenceCountedBase implements ReferenceCounted {
+	// eslint-disable-next-line @typescript-eslint/prefer-readonly -- false positive; modified in multiple places
 	protected constructor(private refCount: number = 1) {}
 
 	public referenceAdded(count = 1): void {