@fluidframework/tree 2.11.0 → 2.12.0

package/src/simple-tree/leafNodeSchema.ts

@@ -68,27 +68,8 @@ function makeLeaf<Name extends string, const T extends ValueSchema>(
 }
 
 // Leaf schema shared between all SchemaFactory instances.
-/**
- * @internal
- */
 export const stringSchema = makeLeaf("string", ValueSchema.String);
-
-/**
- * @internal
- */
 export const numberSchema = makeLeaf("number", ValueSchema.Number);
-
-/**
- * @internal
- */
 export const booleanSchema = makeLeaf("boolean", ValueSchema.Boolean);
-
-/**
- * @internal
- */
 export const nullSchema = makeLeaf("null", ValueSchema.Null);
-
-/**
- * @internal
- */
 export const handleSchema = makeLeaf("handle", ValueSchema.FluidHandle);

package/src/simple-tree/objectNode.ts

@@ -6,7 +6,7 @@
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { FieldKey } from "../core/index.js";
+import type { FieldKey, SchemaPolicy } from "../core/index.js";
 import {
 	FieldKinds,
 	type FlexTreeField,
@@ -42,7 +42,11 @@ import {
 } from "./core/index.js";
 import { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
 import { type RestrictiveStringRecord, fail, type FlattenKeys } from "../util/index.js";
-import type { ObjectNodeSchema, ObjectNodeSchemaInternalData } from "./objectNodeTypes.js";
+import {
+	isObjectNodeSchema,
+	type ObjectNodeSchema,
+	type ObjectNodeSchemaInternalData,
+} from "./objectNodeTypes.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
 
@@ -330,6 +334,7 @@ export function objectSchema<
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
+	allowUnknownOptionalFields: boolean,
 ): ObjectNodeSchema<TName, T, ImplicitlyConstructable> & ObjectNodeSchemaInternalData {
 	// Ensure no collisions between final set of property keys, and final set of stored keys (including those
 	// implicitly derived from property keys)
@@ -368,6 +373,7 @@ export function objectSchema<
 			]),
 		);
 		public static readonly identifierFieldKeys: readonly FieldKey[] = identifierFieldKeys;
+		public static readonly allowUnknownOptionalFields: boolean = allowUnknownOptionalFields;
 
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
@@ -509,3 +515,21 @@ function assertUniqueKeys<
 		derivedStoredKeys.add(storedKey);
 	}
 }
+
+/**
+ * Creates a policy for allowing unknown optional fields on an object node which delegates to the policy defined
+ * on the object node's internal schema data.
+ */
+export function createUnknownOptionalFieldPolicy(
+	schema: ImplicitFieldSchema,
+): SchemaPolicy["allowUnknownOptionalFields"] {
+	const context = getUnhydratedContext(schema);
+	return (identifier) => {
+		const storedSchema = context.schema.get(identifier);
+		return (
+			storedSchema !== undefined &&
+			isObjectNodeSchema(storedSchema) &&
+			storedSchema.allowUnknownOptionalFields
+		);
+	};
+}

package/src/simple-tree/objectNodeTypes.ts

@@ -55,6 +55,11 @@ export interface ObjectNodeSchemaInternalData {
 	 * Stored keys which hold identifiers.
 	 */
 	readonly identifierFieldKeys: readonly FieldKey[];
+
+	/**
+	 * Whether to tolerate (and preserve) additional unknown optional fields in instances of this object node.
+	 */
+	readonly allowUnknownOptionalFields: boolean;
 }
 
 export const ObjectNodeSchema = {

package/src/simple-tree/schemaTypes.ts

@@ -24,6 +24,7 @@ import type {
 	TreeNodeSchemaClass,
 	TreeNode,
 	TreeNodeSchemaCore,
+	TreeNodeSchemaNonClass,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
@@ -759,15 +760,19 @@ export type InsertableTreeNodeFromAllowedTypes<TList extends AllowedTypes> =
 
 /**
  * Takes in `TreeNodeSchema[]` and returns a TypedNode union.
+ * @privateRemarks
+ * If a schema is both TreeNodeSchemaClass and TreeNodeSchemaNonClass, prefer TreeNodeSchemaClass since that includes subclasses properly.
  * @public
  */
-export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<
+export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchemaClass<
 	string,
 	NodeKind,
 	infer TNode
 >
 	? TNode
-	: never;
+	: T extends TreeNodeSchemaNonClass<string, NodeKind, infer TNode>
+		? TNode
+		: never;
 
 /**
  * Data which can be used as a node to be inserted.

package/src/simple-tree/toStoredSchema.ts

@@ -20,7 +20,7 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-import { brand, fail, isReadonlyArray } from "../util/index.js";
+import { brand, fail, getOrCreate, isReadonlyArray } from "../util/index.js";
 import { NodeKind, type TreeNodeSchema } from "./core/index.js";
 import {
 	FieldKind,
@@ -33,29 +33,35 @@ import { LeafNodeSchema } from "./leafNodeSchema.js";
 import { isObjectNodeSchema } from "./objectNodeTypes.js";
 import { normalizeFlexListEager } from "./flexList.js";
 
+const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
+
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
  */
 export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
-	walkFieldSchema(root, {
-		node(schema) {
-			if (nodeSchema.has(brand(schema.identifier))) {
-				// Use JSON.stringify to quote and escape identifier string.
-				throw new UsageError(
-					`Multiple schema encountered with the identifier ${JSON.stringify(
-						schema.identifier,
-					)}. Remove or rename them to avoid the collision.`,
-				);
-			}
-			nodeSchema.set(brand(schema.identifier), getStoredSchema(schema));
-		},
-	});
+	return getOrCreate(viewToStoredCache, root, () => {
+		const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
+		walkFieldSchema(root, {
+			node(schema) {
+				if (nodeSchema.has(brand(schema.identifier))) {
+					// Use JSON.stringify to quote and escape identifier string.
+					throw new UsageError(
+						`Multiple schema encountered with the identifier ${JSON.stringify(
+							schema.identifier,
+						)}. Remove or rename them to avoid the collision.`,
+					);
+				}
+				nodeSchema.set(brand(schema.identifier), getStoredSchema(schema));
+			},
+		});
 
-	return {
-		nodeSchema,
-		rootFieldSchema: convertField(root),
-	};
+		const result: TreeStoredSchema = {
+			nodeSchema,
+			rootFieldSchema: convertField(root),
+		};
+		viewToStoredCache.set(root, result);
+		return result;
+	});
 }
 
 /**

package/src/util/brand.ts

@@ -18,7 +18,6 @@ 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 `B`.
- * @internal
  */
 export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;
 
@@ -42,7 +41,6 @@ export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;
  * - get nominal typing (so types produced without using this class can never be assignable to it).
  *
  * @sealed
- * @internal
  */
 export abstract class BrandedType<out ValueType, Name> {
 	protected _typeCheck?: Covariant<ValueType>;

package/src/util/index.ts

@@ -93,6 +93,7 @@ export {
 	getLast,
 	hasSome,
 	hasSingle,
+	defineLazyCachedProperty,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 

package/src/util/typeCheck.ts

@@ -107,8 +107,6 @@ export interface Contravariant<in T> {
  * ```typescript
  * protected _typeCheck?: Covariant<T>;
  * ```
- *
- * @internal
  */
 export interface Covariant<out T> {
 	_removeContravariance?: T;

package/src/util/utils.ts

@@ -537,3 +537,29 @@ export function capitalize<S extends string>(s: S): Capitalize<S> {
 export function compareStrings<T extends string>(a: T, b: T): number {
 	return a > b ? 1 : a === b ? 0 : -1;
 }
+
+/**
+ * Defines a property on an object that is lazily initialized and cached.
+ * @remarks This is useful for properties that are expensive to compute and it is not guaranteed that they will be accessed.
+ * This function initially defines a getter on the object, but after first read it replaces the getter with a value property.
+ * @param obj - The object on which to define the property.
+ * @param key - The key of the property to define.
+ * @param get - The function (called either once or not at all) to compute the value of the property.
+ * @returns `obj`, typed such that it has the new property.
+ * This allows for the new property to be read off of `obj` in a type-safe manner after calling this function.
+ */
+export function defineLazyCachedProperty<
+	T extends object,
+	K extends string | number | symbol,
+	V,
+>(obj: T, key: K, get: () => V): typeof obj & { [P in K]: V } {
+	Reflect.defineProperty(obj, key, {
+		get() {
+			const value = get();
+			Reflect.defineProperty(obj, key, { value });
+			return value;
+		},
+		configurable: true,
+	});
+	return obj as typeof obj & { [P in K]: V };
+}

package/dist/feature-libraries/chunked-forest/chunk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAE3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IAClD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,QAAuB,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,MAA8B,CAAC;AAEhE;;GAEG;AACH,UAAU,SAAS;IAClB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAMtE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,sBAAsB,EAAE,SAAS;IACvE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,aAAa,CAAC;CACtB"}

package/dist/feature-libraries/chunked-forest/chunk.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,kDAM6B;AA8B7B;;;;GAIG;AACU,QAAA,SAAS,GAAa,uBAAY,CAAC;AAEhD;;GAEG;AACU,QAAA,WAAW,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AA2BhE;;GAEG;AACH,SAAgB,WAAW,CAAC,MAAmB;IAC9C,IAAA,iBAAM,EACL,MAAM,CAAC,IAAI,qCAA6B,EACxC,KAAK,CAAC,+CAA+C,CACrD,CAAC;IACF,OAAQ,MAAoB,CAAC,mBAAW,CAAC,CAAC;AAC3C,CAAC;AAND,kCAMC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tCursorLocationType,\n\ttype FieldKey,\n\ttype ITreeCursor,\n\ttype ITreeCursorSynchronous,\n\trootFieldKey,\n} from \"../../core/index.js\";\nimport type { ReferenceCounted } from \"../../util/index.js\";\n\n/**\n * Contiguous part of the tree which get stored together in some data format.\n * Copy-on-write, but optimized to be mutated in place when a chunk only has a single user (detected using reference counting).\n * This allows for efficient cloning without major performance overheads for non-cloning scenarios.\n */\nexport interface TreeChunk extends ReferenceCounted {\n\t/**\n\t * The number of nodes at the top level of this chunk.\n\t *\n\t * If this chunk is included in a field, this is the amount this chunk contributes to the length of the field.\n\t */\n\treadonly topLevelLength: number;\n\n\t/**\n\t * Creates a cursor for navigating the content of this chunk.\n\t *\n\t * Starts in \"fields\" mode in a `dummyRoot` field containing the top level nodes.\n\t *\n\t * This cursor does not own a reference to the data:\n\t * it is up to the caller of this function to ensure the cursor is not used after they release their owning ref to this chunk.\n\t *\n\t * TODO: consider starting this in \"fields\" mode above the top level\n\t * which would compose better with utilities for processing sequences of nodes.\n\t */\n\tcursor(): ChunkedCursor;\n}\n\n/**\n * The key used for the field that contains the root of chunks when not parented anywhere.\n *\n * For now this is using the document root key to ease testing/compatibility, but this may change.\n */\nexport const dummyRoot: FieldKey = rootFieldKey;\n\n/**\n * A symbol for extracting a TreeChunk from {@link ITreeCursor}.\n */\nexport const cursorChunk: unique symbol = Symbol(\"cursorChunk\");\n\n/**\n * Cursors can optionally implement this interface, allowing querying them for the chunk they are traversing.\n */\ninterface WithChunk {\n\t/**\n\t * When in nodes mode, if a value is returned, it is a TreeChunk who's top level nodes are the\n\t * chunkLength nodes starting from chunkStart.\n\t *\n\t *\n\t * @remarks\n\t * Note that there may be other tree representations with different chunk APIs and thus different ways to query them.\n\t * The chunkStart and chunkLength values thus to not uniquely apply to the chunks accessed through this field.\n\t *\n\t * TODO:\n\t * This API (including the chunk start and end on ITreeCUrsor) have some issues:\n\t * 1. There are cases where multiple possible chunks could be considered.\n\t * For example, when in a SequenceChunk, it could be returned, or the chunk within it could be.\n\t * 2. When in a location other than the root of a chunk,\n\t * it can't provide information about the containing chunk other than by allocating a new chunk that just represents that field.\n\t *\n\t * As more optimizations get implemented, this API may need to change to better address these issues.\n\t */\n\treadonly [cursorChunk]?: TreeChunk | undefined;\n}\n\n/**\n * See {@link WithChunk}.\n */\nexport function tryGetChunk(cursor: ITreeCursor): undefined | TreeChunk {\n\tassert(\n\t\tcursor.mode === CursorLocationType.Nodes,\n\t\t0x57b /* cursorChunk only accessible in nodes mode */,\n\t);\n\treturn (cursor as WithChunk)[cursorChunk];\n}\n\n/**\n * Cursor for a chunk which can be wrapped by another cursor.\n *\n * @remarks See `BasicChunkCursor` which uses this.\n */\nexport interface ChunkedCursor extends ITreeCursorSynchronous, WithChunk {\n\t/**\n\t * Checks if the cursor is in the top level nodes of the chunk.\n\t *\n\t * @returns true iff cursor is within the root field, including at a node within that field.\n\t */\n\tatChunkRoot(): boolean;\n\n\t/**\n\t * Clones the cursor to produce a new independent cursor.\n\t * Does not add any counted references to any chunks.\n\t */\n\tfork(): ChunkedCursor;\n}\n"]}

package/lib/feature-libraries/chunked-forest/chunk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAE3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IAClD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,QAAuB,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,MAA8B,CAAC;AAEhE;;GAEG;AACH,UAAU,SAAS;IAClB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAMtE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,sBAAsB,EAAE,SAAS;IACvE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,aAAa,CAAC;CACtB"}

package/lib/feature-libraries/chunked-forest/chunk.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,OAAO,EAKN,YAAY,GACZ,MAAM,qBAAqB,CAAC;AA8B7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa,YAAY,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AA2BhE;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC9C,MAAM,CACL,MAAM,CAAC,IAAI,qCAA6B,EACxC,KAAK,CAAC,+CAA+C,CACrD,CAAC;IACF,OAAQ,MAAoB,CAAC,WAAW,CAAC,CAAC;AAC3C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tCursorLocationType,\n\ttype FieldKey,\n\ttype ITreeCursor,\n\ttype ITreeCursorSynchronous,\n\trootFieldKey,\n} from \"../../core/index.js\";\nimport type { ReferenceCounted } from \"../../util/index.js\";\n\n/**\n * Contiguous part of the tree which get stored together in some data format.\n * Copy-on-write, but optimized to be mutated in place when a chunk only has a single user (detected using reference counting).\n * This allows for efficient cloning without major performance overheads for non-cloning scenarios.\n */\nexport interface TreeChunk extends ReferenceCounted {\n\t/**\n\t * The number of nodes at the top level of this chunk.\n\t *\n\t * If this chunk is included in a field, this is the amount this chunk contributes to the length of the field.\n\t */\n\treadonly topLevelLength: number;\n\n\t/**\n\t * Creates a cursor for navigating the content of this chunk.\n\t *\n\t * Starts in \"fields\" mode in a `dummyRoot` field containing the top level nodes.\n\t *\n\t * This cursor does not own a reference to the data:\n\t * it is up to the caller of this function to ensure the cursor is not used after they release their owning ref to this chunk.\n\t *\n\t * TODO: consider starting this in \"fields\" mode above the top level\n\t * which would compose better with utilities for processing sequences of nodes.\n\t */\n\tcursor(): ChunkedCursor;\n}\n\n/**\n * The key used for the field that contains the root of chunks when not parented anywhere.\n *\n * For now this is using the document root key to ease testing/compatibility, but this may change.\n */\nexport const dummyRoot: FieldKey = rootFieldKey;\n\n/**\n * A symbol for extracting a TreeChunk from {@link ITreeCursor}.\n */\nexport const cursorChunk: unique symbol = Symbol(\"cursorChunk\");\n\n/**\n * Cursors can optionally implement this interface, allowing querying them for the chunk they are traversing.\n */\ninterface WithChunk {\n\t/**\n\t * When in nodes mode, if a value is returned, it is a TreeChunk who's top level nodes are the\n\t * chunkLength nodes starting from chunkStart.\n\t *\n\t *\n\t * @remarks\n\t * Note that there may be other tree representations with different chunk APIs and thus different ways to query them.\n\t * The chunkStart and chunkLength values thus to not uniquely apply to the chunks accessed through this field.\n\t *\n\t * TODO:\n\t * This API (including the chunk start and end on ITreeCUrsor) have some issues:\n\t * 1. There are cases where multiple possible chunks could be considered.\n\t * For example, when in a SequenceChunk, it could be returned, or the chunk within it could be.\n\t * 2. When in a location other than the root of a chunk,\n\t * it can't provide information about the containing chunk other than by allocating a new chunk that just represents that field.\n\t *\n\t * As more optimizations get implemented, this API may need to change to better address these issues.\n\t */\n\treadonly [cursorChunk]?: TreeChunk | undefined;\n}\n\n/**\n * See {@link WithChunk}.\n */\nexport function tryGetChunk(cursor: ITreeCursor): undefined | TreeChunk {\n\tassert(\n\t\tcursor.mode === CursorLocationType.Nodes,\n\t\t0x57b /* cursorChunk only accessible in nodes mode */,\n\t);\n\treturn (cursor as WithChunk)[cursorChunk];\n}\n\n/**\n * Cursor for a chunk which can be wrapped by another cursor.\n *\n * @remarks See `BasicChunkCursor` which uses this.\n */\nexport interface ChunkedCursor extends ITreeCursorSynchronous, WithChunk {\n\t/**\n\t * Checks if the cursor is in the top level nodes of the chunk.\n\t *\n\t * @returns true iff cursor is within the root field, including at a node within that field.\n\t */\n\tatChunkRoot(): boolean;\n\n\t/**\n\t * Clones the cursor to produce a new independent cursor.\n\t * Does not add any counted references to any chunks.\n\t */\n\tfork(): ChunkedCursor;\n}\n"]}