@fluidframework/tree 2.23.0 → 2.31.0

package/src/simple-tree/api/customTree.ts

@@ -5,7 +5,7 @@
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	EmptyKey,
@@ -14,11 +14,12 @@ import {
 	LeafNodeStoredSchema,
 	mapCursorField,
 	ObjectNodeStoredSchema,
+	type FieldKey,
 	type ITreeCursor,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 } from "../../core/index.js";
-import { fail } from "../../util/index.js";
+import { cloneWithReplacements } from "../../util/index.js";
 import type { TreeLeafValue } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import {
@@ -35,13 +36,7 @@ import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js"
  * Options for how to encode a tree.
  * @alpha
  */
-export interface EncodeOptions<TCustom> {
-	/**
-	 * How to encode any {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the tree.
-	 * @remarks
-	 * See note on {@link ParseOptions.valueConverter}.
-	 */
-	valueConverter(data: IFluidHandle): TCustom;
+export interface EncodeOptions {
 	/**
 	 * If true, interpret the input keys of object nodes as stored keys.
 	 * If false, interpret them as property keys.
@@ -50,15 +45,36 @@ export interface EncodeOptions<TCustom> {
 	readonly useStoredKeys?: boolean;
 }
 
+/**
+ * Options for how to transcode handles.
+ * @remarks
+ * Can be applied using {@link replaceHandles}.
+ * @alpha
+ */
+export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
+
+/**
+ * Options for how to interpret a `ConciseTree<TCustom>` without relying on schema.
+ */
+export interface SchemalessParseOptions {
+	/**
+	 * Converts stored keys into whatever key the tree is using in its encoding.
+	 */
+	keyConverter?: {
+		parse(type: string, inputKey: string): FieldKey;
+		encode(type: string, key: FieldKey): string;
+	};
+}
+
 /**
  * Tree representation with fields as properties and customized handle and child representations.
  */
-export type CustomTree<TChild, THandle> = CustomTreeNode<TChild> | CustomTreeValue<THandle>;
+export type CustomTree<TChild> = CustomTreeNode<TChild> | CustomTreeValue;
 
 /**
  * TreeLeafValue except the handle type is customized.
  */
-export type CustomTreeValue<THandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle;
+export type CustomTreeValue = TreeLeafValue;
 
 /**
  * Tree node representation with fields as properties and customized child representation.
@@ -68,16 +84,16 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
  */
-export function customFromCursor<TChild, THandle>(
+export function customFromCursor<TChild>(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions<THandle>>,
+	options: Required<EncodeOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 	childHandler: (
 		reader: ITreeCursor,
-		options: Required<EncodeOptions<THandle>>,
+		options: Required<EncodeOptions>,
 		schema: ReadonlyMap<string, TreeNodeSchema>,
 	) => TChild,
-): CustomTree<TChild, THandle> {
+): CustomTree<TChild> {
 	const type = reader.type;
 	const nodeSchema = schema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
 
@@ -92,7 +108,7 @@ export function customFromCursor<TChild, THandle>(
 		case handleSchema.identifier:
 			assert(reader.value !== undefined, 0xa52 /* out of schema: missing value */);
 			assert(isFluidHandle(reader.value), 0xa53 /* out of schema: expected FluidHandle */);
-			return options.valueConverter(reader.value);
+			return reader.value;
 		default: {
 			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
 			if (nodeSchema.kind === NodeKind.Array) {
@@ -136,7 +152,7 @@ export function customFromCursorStored<TChild>(
 		reader: ITreeCursor,
 		schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,
 	) => TChild,
-): CustomTree<TChild, IFluidHandle> {
+): CustomTree<TChild> {
 	const type = reader.type;
 	const nodeSchema = schema.get(type) ?? fail(0xb30 /* missing schema for type in cursor */);
 
@@ -186,3 +202,30 @@ export function tryStoredSchemaAsArray(
 		}
 	}
 }
+
+/**
+ * Clones tree, replacing any handles.
+ * @remarks
+ * This can be useful converting data containing handles to JSON compatible formats,
+ * or just asserting that data does not contain handles.
+ *
+ * Reversing this replacement depends on how the replacer encodes handles, and can often be impossible if the replacer
+ * does not have all the necessary context to restore the handles
+ * (e.g. if the handles are something insufficiently descriptive,
+ * if data referenced by the handle got garbage collected,
+ * if the encoded form of the handle can't be differentiated from other data,
+ * or the replacer doesn't have access to the correct Fluid container to to restore them from).
+ *
+ * Code attempting to reverse this replacement may want to use {@link cloneWithReplacements}.
+ * @alpha
+ */
+export function replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>): unknown {
+	return cloneWithReplacements(tree, "", (key, value) => {
+		// eslint-disable-next-line unicorn/prefer-ternary
+		if (isFluidHandle(value)) {
+			return { clone: false, value: replacer(value) };
+		} else {
+			return { clone: true, value };
+		}
+	});
+}

package/src/simple-tree/api/getJsonSchema.ts

@@ -60,6 +60,16 @@ const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
  * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
  * For now, while still an experimental API, it is surfaced as a free function.
  *
+ * TODO:
+ * This API should allow generating JSON schema for the whole matrix of combinations:
+ *
+ * 1. VerboseTree and ConciseTree
+ * 2. With and without requiring values with defaults (for insertion vs reading)
+ * 3. Using stored keys and property keys
+ *
+ * This current API seems to give ConciseTree with property keys and ignoring default values.
+ *
+ *
  * @alpha
  */
 export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema {

package/src/simple-tree/api/getSimpleSchema.ts

@@ -6,7 +6,7 @@
 import { getOrCreate } from "../../util/index.js";
 import type { TreeNodeSchema } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../schemaTypes.js";
-import type { SimpleTreeSchema } from "./simpleSchema.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**
@@ -15,57 +15,27 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 const simpleSchemaCache = new WeakMap<TreeNodeSchema, SimpleTreeSchema>();
 
 /**
- * Creates a simplified representation of the provided {@link TreeNodeSchema}.
+ * Creates a {@link SimpleTreeSchema} from the provided {@link ImplicitFieldSchema}.
  *
- * @remarks Caches the result on the input schema for future calls.
+ * @remarks
+ * This provides easy access by identifier to any schema transitively referenced by the input schema via {@link SimpleTreeSchema.definitions}.
  *
- * @example
+ * Caches the result on the input schema for future calls.
  *
- * A Shared Tree schema like the following:
- *
- * ```typescript
- * class MyObject extends schemaFactory.object("MyObject", {
- * 	foo: schemaFactory.number,
- * 	bar: schemaFactory.optional(schemaFactory.string),
- * });
- * ```
+ * @privateRemarks
+ * In the future, we may wish to move this to a more discoverable API location.
+ * For now, while still an experimental API, it is surfaced as a free function.
  *
- * Will yield JSON Schema like the following:
+ * If the main use for this is the "definitions" map, we should provide a better way to access it (that doesn't type erase the TreeNodeSchema down to SimpleNodeSchema).
+ * TODO: Having TreeViewConfiguration implement SimpleTreeSchema directly but with more specific types would be a good way to do this.
  *
- * ```typescript
- * {
- * 	definitions: [
- * 		["com.fluidframework.leaf.number", {
- * 			kind: "leaf",
- * 			type: "number",
- * 		}],
- * 		["com.fluidframework.leaf.string", {
- * 			kind: "leaf",
- * 			type: "string",
- * 		}],
- * 		["com.myapp.MyObject", {
- * 			kind: "object",
- * 			fields: {
- * 				foo: {
- * 					kind: "required",
- * 					allowedTypes: ["com.fluidframework.leaf.number"]
- * 				},
- * 				bar: {
- * 					kind: "optional",
- * 					allowedTypes: ["com.fluidframework.leaf.string"]
- * 				},
- * 			},
- * 		}],
- * 	],
- * 	allowedTypes: ["com.myapp.MyObject"],
- * }
- * ```
+ * Note that all TreeNodeSchema get a {@link Context} cached on them as part of one time initialization which contains a map from identifier to all transitively referenced schema.
+ * Perhaps exposing access to that would cover this use-case as well.
  *
- * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
- * For now, while still an experimental API, it is surfaced as a free function.
+ * TODO: does having this caching layer add value? Maybe this wrapper around toSimpleTreeSchema should be removed.
  *
  * @internal
  */
 export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
-	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema));
+	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema, false));
 }

package/src/simple-tree/api/index.ts

@@ -22,7 +22,7 @@ export {
 	SchemaFactory,
 	type ScopedSchemaName,
 	type SchemaFactoryObjectOptions,
-	type schemaStatics,
+	type SchemaStatics,
 } from "./schemaFactory.js";
 export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {
@@ -36,16 +36,6 @@ export {
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
-export type {
-	SimpleTreeSchema,
-	SimpleNodeSchema,
-	SimpleFieldSchema,
-	SimpleLeafNodeSchema,
-	SimpleMapNodeSchema,
-	SimpleArrayNodeSchema,
-	SimpleObjectNodeSchema,
-	SimpleNodeSchemaBase,
-} from "./simpleSchema.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,
@@ -84,8 +74,13 @@ export type {
 	TreeNodeSchemaClassUnsafe,
 	TreeNodeSchemaUnsafe,
 	AllowedTypesUnsafe,
+	ImplicitAllowedTypesUnsafe,
+	ImplicitFieldSchemaUnsafe,
 	TreeNodeSchemaNonClassUnsafe,
 	InsertableTreeNodeFromAllowedTypesUnsafe,
+	FieldSchemaAlphaUnsafe,
+	ArrayNodeCustomizableSchemaUnsafe,
+	MapNodeCustomizableSchemaUnsafe,
 } from "./typesUnsafe.js";
 
 export {
@@ -95,6 +90,7 @@ export {
 	applySchemaToParserOptions,
 	cursorFromVerbose,
 	verboseFromCursor,
+	replaceVerboseTreeHandles,
 } from "./verboseTree.js";
 
 export {
@@ -103,9 +99,15 @@ export {
 	type CustomTreeNode,
 	type CustomTreeValue,
 	tryStoredSchemaAsArray,
+	replaceHandles,
+	type HandleConverter,
 } from "./customTree.js";
 
-export { type ConciseTree, conciseFromCursor } from "./conciseTree.js";
+export {
+	type ConciseTree,
+	conciseFromCursor,
+	replaceConciseTreeHandles,
+} from "./conciseTree.js";
 
 export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";
 export { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
@@ -133,6 +135,9 @@ export {
 	rollback,
 } from "./transactionTypes.js";
 
+export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
+export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
+
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639
 export {

package/src/simple-tree/api/schemaCreationUtilities.ts

@@ -4,8 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-
-import { fail } from "../../util/index.js";
+import { fail } from "@fluidframework/core-utils/internal";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
 import type { NodeFromSchema } from "../schemaTypes.js";