@fluidframework/tree 2.4.0-299707 → 2.5.0-302463

package/src/simple-tree/schemaTypes.ts

@@ -8,12 +8,18 @@ import { Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { NodeKeyManager } from "../feature-libraries/index.js";
-import { type MakeNominal, brand, isReadonlyArray } from "../util/index.js";
+import {
+	type MakeNominal,
+	brand,
+	isReadonlyArray,
+	type UnionToIntersection,
+} from "../util/index.js";
 import type {
 	Unhydrated,
 	NodeKind,
 	TreeNodeSchema,
 	TreeNodeSchemaClass,
+	TreeNode,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
@@ -25,7 +31,7 @@ import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 export function isTreeNodeSchemaClass<
 	Name extends string,
 	Kind extends NodeKind,
-	TNode,
+	TNode extends TreeNode | TreeLeafValue,
 	TBuild,
 	ImplicitlyConstructable extends boolean,
 	Info,
@@ -39,8 +45,16 @@ export function isTreeNodeSchemaClass<
  * Types for use in fields.
  * @remarks
  * Type constraint used in schema declaration APIs.
+ *
+ * The order of types in the array is not significant.
+ * Additionally, it is legal for users of this type to have the runtime and compile time order of items within this array not match.
+ * Therefor to ensure type safety, these arrays should not be indexed, and instead just be iterated.
+ *
+ * Ideally this restriction would be modeled in the type itself, but it is not ergonomic to do so as there is no easy (when compared to arrays)
+ * way to declare and manipulate unordered sets of types in TypeScript.
+ *
  * Not intended for direct use outside of package.
- * @public
+ * @system @public
  */
 export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 
@@ -381,39 +395,122 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 
 /**
- * Converts ImplicitFieldSchema to the corresponding tree node's field type.
+ * Converts an `ImplicitFieldSchema` to a property type suitable for reading a field with this that schema.
+ *
+ * @typeparam TSchema - When non-exact schema are provided this errors on the side of returning too general of a type (a conservative union of all possibilities).
+ * This is ideal for "output APIs" - i.e. it converts the schema type to the runtime type that a user will _read_ from the tree.
+ * Examples of such "non-exact" schema include `ImplicitFieldSchema`, `ImplicitAllowedTypes`, and  TypeScript unions of schema types.
  * @public
  */
 export type TreeFieldFromImplicitField<TSchema extends ImplicitFieldSchema = FieldSchema> =
 	TSchema extends FieldSchema<infer Kind, infer Types>
-		? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind, false>
+		? ApplyKind<TreeNodeFromImplicitAllowedTypes<Types>, Kind>
 		: TSchema extends ImplicitAllowedTypes
 			? TreeNodeFromImplicitAllowedTypes<TSchema>
-			: unknown;
+			: TreeNode | TreeLeafValue | undefined;
 
 /**
  * Type of content that can be inserted into the tree for a field of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam TSchema - Do not specify: default value used as implementation detail.
  * @public
  */
 export type InsertableTreeFieldFromImplicitField<
-	TSchema extends ImplicitFieldSchema = FieldSchema,
-> = TSchema extends FieldSchema<infer Kind, infer Types>
-	? ApplyKind<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
-	: TSchema extends ImplicitAllowedTypes
+	TSchemaInput extends ImplicitFieldSchema,
+	TSchema = UnionToIntersection<TSchemaInput>,
+> = [TSchema] extends [FieldSchema<infer Kind, infer Types>]
+	? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true>
+	: [TSchema] extends [ImplicitAllowedTypes]
 		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
-		: unknown;
+		: never;
+
+/**
+ * {@inheritdoc (UnsafeUnknownSchema:type)}
+ * @alpha
+ */
+export const UnsafeUnknownSchema: unique symbol = Symbol("UnsafeUnknownSchema");
+
+/**
+ * A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.
+ * @remarks
+ * When used, this means the TypeScript typing should err on the side of completeness (allow all inputs that could be valid).
+ * This introduces the risk that out-of-schema data could be allowed at compile time, and only error at runtime.
+ *
+ * @privateRemarks
+ * This only applies to APIs which input data which is expected to be in schema, since APIs outputting have easy mechanisms to do so in a type safe way even when the schema is unknown.
+ * In most cases that amounts to returning `TreeNode | TreeLeafValue`.
+ *
+ * This can be contrasted with the default behavior of TypeScript, which is to require the intersection of the possible types for input APIs,
+ * which for unknown schema defining input trees results in the `never` type.
+ *
+ * Any APIs which use this must produce UsageErrors when out of schema data is encountered, and never produce unrecoverable errors,
+ * or silently accept invalid data.
+ * This is currently only type exported from the package: the symbol is just used as a way to get a named type.
+ * @alpha
+ */
+export type UnsafeUnknownSchema = typeof UnsafeUnknownSchema;
+
+/**
+ * Content which could be inserted into a tree.
+ *
+ * @see {@link Input}
+ * @remarks
+ * Extended version of {@link InsertableTreeNodeFromImplicitAllowedTypes} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type Insertable<TSchema extends ImplicitAllowedTypes | UnsafeUnknownSchema> =
+	TSchema extends ImplicitAllowedTypes
+		? InsertableTreeNodeFromImplicitAllowedTypes<TSchema>
+		: InsertableContent;
+
+/**
+ * Content which could be inserted into a field within a tree.
+ *
+ * @see {@link Input}
+ * @remarks
+ * Extended version of {@link InsertableTreeFieldFromImplicitField} that also allows {@link (UnsafeUnknownSchema:type)}.
+ * @alpha
+ */
+export type InsertableField<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> = [
+	TSchema,
+] extends [ImplicitFieldSchema]
+	? InsertableTreeFieldFromImplicitField<TSchema>
+	: [TSchema] extends [UnsafeUnknownSchema]
+		? InsertableContent | undefined
+		: never;
 
 /**
  * Suitable for output.
  * For input must error on side of excluding undefined instead.
  * @system @public
  */
-export type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> = {
+export type ApplyKind<T, Kind extends FieldKind> = {
 	[FieldKind.Required]: T;
 	[FieldKind.Optional]: T | undefined;
-	[FieldKind.Identifier]: DefaultsAreOptional extends true ? T | undefined : T;
+	[FieldKind.Identifier]: T;
 }[Kind];
 
+/**
+ * Suitable for input.
+ *
+ * @see {@link Input}
+ * @system @public
+ */
+export type ApplyKindInput<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> = [
+	Kind,
+] extends [FieldKind.Required]
+	? T
+	: [Kind] extends [FieldKind.Optional]
+		? T | undefined
+		: [Kind] extends [FieldKind.Identifier]
+			? DefaultsAreOptional extends true
+				? T | undefined
+				: T
+			: never;
+
 /**
  * Type of tree node for a field of the given schema.
  * @public
@@ -426,16 +523,91 @@ export type TreeNodeFromImplicitAllowedTypes<
 		? NodeFromSchema<FlexListToUnion<TSchema>>
 		: unknown;
 
+/**
+ * This type exists only to be linked from documentation to provide a single linkable place to document some details of
+ * "Input" types and how they handle schema.
+ *
+ * When a schema is used to describe data which is an input into an API, the API is [contravariant](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)) over the schema.
+ * (See also, [TypeScript Variance Annotations](https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations)).
+ *
+ * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.
+ *
+ * Consider a field with schema type of `A | B` (where A and B are types of schema).
+ *
+ * - Reading the field behaves covariantly so {@link NodeFromSchema} of `<A | B>` is the same as `NodeFromSchema<A> | NodeFromSchema<B>`, indicating that either type of node can be read from the field.
+ * - Writing to the field behaves contravariantly. Since it is unknown if the node actually has a schema `A` or a schema `B`, the only legal values (known to be in schema regardless of which schema the underlying node has) are values which are legal for both `A & B`.
+ *
+ * Note that this is distinct from the case where the schema is `[A, B]`.
+ * In this case it is known that the field allows both A and B (the field can be set to an A or a B value).
+ * When `A | B` is used, the field might allow
+ * A but not B (so assigning a B value would be out of schema),
+ * B but not A (so assigning an A value would be out of schema)
+ * or both A and B.
+ *
+ * This gets more extreme when given completely unspecified schema.
+ * For example if a field is just provided {@link ImplicitFieldSchema}, nothing is known about the content of the field.
+ * This means that reading the field (via {@link TreeFieldFromImplicitField}) can give any valid tree field content,
+ * but there are no safe values which could be written to the field (since it is unknown what values would be out of schema) so {@link InsertableTreeFieldFromImplicitField} gives `never`.
+ *
+ * To implement this variance correctly, the computation of types for input and output have to use separate utilities
+ * which take very different approaches when encountering non-exact schema like unions or `ImplicitFieldSchema`.
+ * The utilities which behave contravariantly (as required to handle input correctly) link this documentation to indicate that this is how they behave.
+ *
+ * In addition to behaving contravariantly, these input type computation utilities often have further limitations.
+ * This is due to TypeScript making it difficult to implement this contravariance exactly.
+ * When faced with these implementation limitations these contravariant type computation utilities error on the side of producing overly strict requirements.
+ * For example in the above case of `A | B`, the utilities might compute an allowed insertable type as `never` even if there happens to be a common value accepted by both `A` and `B`.
+ * Future versions of the API can relax these requirements as the type computations are made more accurate.
+ *
+ * For a more concrete example: if {@link InsertableTreeFieldFromImplicitField} produced `never` for a schema `A | OptionalField<A>`,
+ * a future version could instead return a more flexible but still safe type, like `A`.
+ *
+ * More generally: try to avoid providing non-exact schema, especially for the fields of other schema.
+ * While these APIs attempt to handle such cases correctly, there are limitations and known bugs in this handling.
+ * Code using non-exact schema is much more likely to have its compilation break due to updates of this package or even TypeScript,
+ * and thus compilation breaks due to edge cases of non-exact schema handling, especially with recursive schema, are not considered breaking changes.
+ * This may change as the API become more stable.
+ *
+ * @privateRemarks
+ * There likely is a better way to share this documentation, but none was found at the time of writing.
+ *
+ * TODO: Once {@link InsertableField} is public, consider using it in the examples above.
+ * @system @public
+ */
+export type Input<T extends never> = T;
+
 /**
  * Type of content that can be inserted into the tree for a node of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchema - Schema to process.
+ *
+ * @privateRemarks
+ * This is a bit overly conservative, since cases like `A | [A]` give never and could give `A`.
  * @public
  */
-export type InsertableTreeNodeFromImplicitAllowedTypes<
-	TSchema extends ImplicitAllowedTypes = TreeNodeSchema,
-> = TSchema extends TreeNodeSchema
-	? InsertableTypedNode<TSchema>
-	: TSchema extends AllowedTypes
-		? InsertableTypedNode<FlexListToUnion<TSchema>>
+export type InsertableTreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes> =
+	[TSchema] extends [TreeNodeSchema]
+		? InsertableTypedNode<TSchema>
+		: [TSchema] extends [AllowedTypes]
+			? InsertableTreeNodeFromAllowedTypes<TSchema>
+			: never;
+
+/**
+ * Type of content that can be inserted into the tree for a node of the given schema.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TList - AllowedTypes to process
+ * @system @public
+ */
+export type InsertableTreeNodeFromAllowedTypes<TList extends AllowedTypes> =
+	TList extends readonly [
+		LazyItem<infer TSchema extends TreeNodeSchema>,
+		...infer Rest extends AllowedTypes,
+	]
+		? InsertableTypedNode<TSchema> | InsertableTreeNodeFromAllowedTypes<Rest>
 		: never;
 
 /**
@@ -453,11 +625,31 @@ export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 /**
  * Data which can be used as a node to be inserted.
  * Either an unhydrated node, or content to build a new node.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam T - Do not specify: default value used as implementation detail.
+ * @privateRemarks
+ * This can't really be fully correct, since TreeNodeSchema's TNode is generally use covariantly but this code uses it contravariantly.
+ * That makes this TreeNodeSchema actually invariant with respect to TNode, but doing that would break all `extends TreeNodeSchema` clauses.
+ * As is, this works correctly in most realistic use-cases.
+ *
+ * One special case this makes is if the result of NodeFromSchema contains TreeNode, this must be an under constrained schema, so the result is set to never.
+ * Note that applying UnionToIntersection on the result of NodeFromSchema<T> does not work since it breaks booleans.
+ *
  * @public
  */
-export type InsertableTypedNode<T extends TreeNodeSchema> =
-	| (T extends { implicitlyConstructable: true } ? NodeBuilderData<T> : never)
-	| Unhydrated<NodeFromSchema<T>>;
+export type InsertableTypedNode<
+	TSchema extends TreeNodeSchema,
+	T = UnionToIntersection<TSchema>,
+> =
+	| (T extends TreeNodeSchema<string, NodeKind, TreeNode | TreeLeafValue, never, true>
+			? NodeBuilderData<T>
+			: never)
+	| (T extends TreeNodeSchema
+			? Unhydrated<TreeNode extends NodeFromSchema<T> ? never : NodeFromSchema<T>>
+			: never);
 
 /**
  * Given a node's schema, return the corresponding object from which the node could be built.
@@ -471,7 +663,7 @@ export type InsertableTypedNode<T extends TreeNodeSchema> =
 export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 	string,
 	NodeKind,
-	unknown,
+	TreeNode | TreeLeafValue,
 	infer TBuild
 >
 	? TBuild

package/src/simple-tree/toFlexSchema.ts

@@ -98,7 +98,7 @@ export function getStoredSchema(schema: TreeNodeSchema): TreeNodeStoredSchema {
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf: {
-			assert(schema instanceof LeafNodeSchema, "invalid kind");
+			assert(schema instanceof LeafNodeSchema, 0xa4a /* invalid kind */);
 			return new LeafNodeStoredSchema(schema.info);
 		}
 		case NodeKind.Map: {
@@ -116,7 +116,7 @@ export function getStoredSchema(schema: TreeNodeSchema): TreeNodeStoredSchema {
 			return new ObjectNodeStoredSchema(fields);
 		}
 		case NodeKind.Object: {
-			assert(isObjectNodeSchema(schema), "invalid kind");
+			assert(isObjectNodeSchema(schema), 0xa4b /* invalid kind */);
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 			for (const field of schema.flexKeyMap.values()) {
 				fields.set(field.storedKey, convertField(field.schema));

package/src/simple-tree/toMapTree.ts

@@ -726,6 +726,7 @@ function tryGetInnerNode(target: unknown): InnerNode | undefined {
  * Content which can be used to build a node.
  * @remarks
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
+ * @system @alpha
  */
 export type FactoryContent =
 	| IFluidHandle
@@ -744,12 +745,14 @@ export type FactoryContent =
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
  *
  * Supports object and map nodes.
+ * @system @alpha
  */
-type FactoryContentObject = {
+export type FactoryContentObject = {
 	readonly [P in string]?: InsertableContent;
 };
 
 /**
  * Content which can be inserted into a tree.
+ * @system @alpha
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;

package/src/util/index.ts

@@ -99,8 +99,14 @@ export type {
 	RestrictiveStringRecord,
 	_InlineTrick,
 	FlattenKeys,
+	IsUnion,
+	UnionToIntersection,
+	UnionToTuple,
+	PopUnion,
 } from "./typeUtils.js";
 
+export { unsafeArrayToTuple } from "./typeUtils.js";
+
 export {
 	type BrandedKey,
 	type BrandedKeyContent,

package/src/util/typeUtils.ts

@@ -137,3 +137,90 @@ export type RestrictiveStringRecord<T> = {
 } & {
 	readonly [P in symbol]?: never;
 };
+
+/**
+ * Returns `true` if T is a union and false if it is not.
+ * @typeparam T - Type to test if it is a union.
+ * @typeparam T2 - Do not specify: default value used as implementation detail.
+ * @system @alpha
+ */
+export type IsUnion<T, T2 = T> = T extends unknown
+	? [T2] extends [T]
+		? false
+		: true
+	: "error";
+
+/**
+ * Convert a union of types to an intersection of those types. Useful for `TransformEvents`.
+ * @privateRemarks
+ * First an always true extends clause is used (T extends T) to distribute T into to a union of types contravariant over each member of the T union.
+ * Then the constraint on the type parameter in this new context is inferred, giving the intersection.
+ * @system @public
+ */
+export type UnionToIntersection<T> = (T extends T ? (k: T) => unknown : never) extends (
+	k: infer U,
+) => unknown
+	? U
+	: never;
+
+/**
+ * Gets the first item of a union type.
+ *
+ * @typeparam Union - The union to convert.
+ * @typeparam AsOverloadedFunction - Implementation detail: do not specify.
+ * @system @alpha
+ */
+export type PopUnion<
+	Union,
+	AsOverloadedFunction = UnionToIntersection<
+		Union extends unknown ? (f: Union) => void : never
+	>,
+> = AsOverloadedFunction extends (a: infer First) => void ? First : never;
+
+/**
+ * Converts a union type to a tuple type.
+ *
+ * @typeparam T - The union to convert.
+ * @typeparam A - Implementation detail: do not specify.
+ * @typeparam First - Implementation detail: do not specify.
+ *
+ * @privateRemarks
+ * `A` is a tuple to prepend members of the union to.
+ *
+ * https://www.hacklewayne.com/typescript-convert-union-to-tuple-array-yes-but-how and https://catchts.com/union-array both explain the general approach this uses pretty well.
+ * This implementation is inspired to those, but slightly different in implementation.
+ * @alpha
+ */
+export type UnionToTuple<
+	Union,
+	A extends unknown[] = [],
+	First = PopUnion<Union>,
+> = IsUnion<Union> extends true
+	? UnionToTuple<Exclude<Union, First>, [First, ...A]>
+	: [Union, ...A];
+
+/**
+ * This is unsafe, meaning that the returned value might not match its type.
+ *
+ * For the result to match its type, T must be a union of the types of each item in `items` in the order that they occur.
+ * For this to be possible, there must be no duplicate or overlapping types.
+ * This is fragile and must be used with care.
+ *
+ * @remarks
+ * The main use-case for this is recovering lost information from {@link AllowedTypes} which is necessary to preserve when using them with {@link Input} APIs.
+ * Since {@link AllowedTypes} is actually order independent, it is somewhat safer when used to produce `AllowedTypes`.
+ *
+ * @example
+ * ```typescript
+ * // Gives imprecise type (typeof A | typeof B)[]
+ * const schemaBad = [A, B];
+ * // Fixes the type to be [typeof A, typeof B]
+ * const schema = unsafeArrayToTuple(schemaBad);
+ *
+ * const config = new TreeViewConfiguration({ schema });
+ * ```
+ * @alpha
+ */
+export function unsafeArrayToTuple<T>(items: T[]): UnionToTuple<T> {
+	return items as UnionToTuple<T>;
+}