@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/feature-libraries/chunked-forest/chunk.ts

@@ -75,7 +75,7 @@ interface WithChunk {
 	 *
 	 * As more optimizations get implemented, this API may need to change to better address these issues.
 	 */
-	readonly [cursorChunk]?: TreeChunk;
+	readonly [cursorChunk]?: TreeChunk | undefined;
 }
 
 /**

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -158,7 +158,7 @@ export class Chunker implements IChunker {
  * @param cursor - cursor in nodes mode
  */
 export function chunkTree(cursor: ITreeCursorSynchronous, policy: ChunkPolicy): TreeChunk {
-	return chunkRange(cursor, policy, 1, true)[0];
+	return chunkRange(cursor, policy, 1, true)[0] ?? oob();
 }
 
 /**
@@ -182,7 +182,7 @@ export function chunkFieldSingle(
 ): TreeChunk {
 	const chunks = chunkField(cursor, policy);
 	if (chunks.length === 1) {
-		return chunks[0];
+		return chunks[0] ?? oob();
 	}
 	return new SequenceChunk(chunks);
 }
@@ -278,7 +278,7 @@ export function tryShapeFromFieldSchema(
 	if (type.types?.size !== 1) {
 		return undefined;
 	}
-	const childType = [...type.types][0];
+	const childType = [...type.types][0] ?? oob();
 	const childShape = tryShapeFromSchema(schema, policy, childType, shapes);
 	if (childShape instanceof Polymorphic) {
 		return undefined;

package/src/feature-libraries/chunked-forest/chunkedForest.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import {
 	type Anchor,
@@ -105,7 +105,7 @@ export class ChunkedForest implements IEditableForest {
 			mutableChunk: this.roots as BasicChunk | undefined,
 			getParent(): StackNode {
 				assert(this.mutableChunkStack.length > 0, 0x532 /* invalid access to root's parent */);
-				return this.mutableChunkStack[this.mutableChunkStack.length - 1];
+				return this.mutableChunkStack[this.mutableChunkStack.length - 1] ?? oob();
 			},
 			free(): void {
 				this.mutableChunk = undefined;
@@ -204,14 +204,16 @@ export class ChunkedForest implements IEditableForest {
 					parent.mutableChunk.fields.get(parent.key) ?? fail("missing edited field");
 				let indexWithinChunk = index;
 				let indexOfChunk = 0;
-				while (indexWithinChunk >= chunks[indexOfChunk].topLevelLength) {
-					indexWithinChunk -= chunks[indexOfChunk].topLevelLength;
+				let chunk = chunks[indexOfChunk] ?? oob();
+				while (indexWithinChunk >= chunk.topLevelLength) {
+					chunk = chunks[indexOfChunk] ?? oob();
+					indexWithinChunk -= chunk.topLevelLength;
 					indexOfChunk++;
 					if (indexOfChunk === chunks.length) {
 						fail("missing edited node");
 					}
 				}
-				let found = chunks[indexOfChunk];
+				let found = chunks[indexOfChunk] ?? oob();
 				if (!(found instanceof BasicChunk)) {
 					// TODO:Perf: support in place editing of other chunk formats when possible:
 					// 1. Support updating values in uniform chunks.
@@ -226,7 +228,7 @@ export class ChunkedForest implements IEditableForest {
 					chunks.splice(indexOfChunk, 1, ...newChunks);
 					found.referenceRemoved();
 
-					found = newChunks[indexWithinChunk];
+					found = newChunks[indexWithinChunk] ?? oob();
 				}
 				assert(found instanceof BasicChunk, 0x536 /* chunk should have been normalized */);
 				if (found.isShared()) {

package/src/feature-libraries/chunked-forest/codec/chunkCodecUtilities.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
 import type { TreeValue } from "../../../core/index.js";
 import { assertValidIndex } from "../../../util/index.js";
@@ -106,7 +106,7 @@ export function jsonMinimizingFilter(s: string, value: number, count: number): b
  */
 export function getChecked<T>(data: readonly T[], index: number): T {
 	assertValidIndex(index, data);
-	return data[index];
+	return data[index] ?? oob();
 }
 
 /**

package/src/feature-libraries/chunked-forest/codec/chunkDecoding.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase, oob } from "@fluidframework/core-utils/internal";
 
 import { DiscriminatedUnionDispatcher } from "../../../codec/index.js";
 import type { FieldKey, TreeNodeSchemaIdentifier, Value } from "../../../core/index.js";
@@ -169,7 +169,7 @@ export function aggregateChunks(input: TreeChunk[]): TreeChunk {
 		case 0:
 			return emptyChunk;
 		case 1:
-			return chunks[0];
+			return chunks[0] ?? oob();
 		default:
 			return new SequenceChunk(chunks);
 	}
@@ -181,7 +181,7 @@ export function aggregateChunks(input: TreeChunk[]): TreeChunk {
 export class NestedArrayDecoder implements ChunkDecoder {
 	public constructor(private readonly shape: EncodedNestedArray) {}
 	public decode(decoders: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
-		const decoder = decoders[this.shape];
+		const decoder = decoders[this.shape] ?? oob();
 
 		// TODO: uniform chunk fast path
 		const chunks: TreeChunk[] = [];
@@ -215,7 +215,7 @@ export class InlineArrayDecoder implements ChunkDecoder {
 	public constructor(private readonly shape: EncodedInlineArray) {}
 	public decode(decoders: readonly ChunkDecoder[], stream: StreamCursor): TreeChunk {
 		const length = this.shape.length;
-		const decoder = decoders[this.shape.shape];
+		const decoder = decoders[this.shape.shape] ?? oob();
 		const chunks: TreeChunk[] = [];
 		for (let index = 0; index < length; index++) {
 			chunks.push(decoder.decode(decoders, stream));
@@ -252,7 +252,10 @@ function fieldDecoder(
 	shape: number,
 ): BasicFieldDecoder {
 	assertValidIndex(shape, cache.shapes);
-	return (decoders, stream) => [key, decoders[shape].decode(decoders, stream)];
+	return (decoders, stream) => {
+		const decoder = decoders[shape] ?? oob();
+		return [key, decoder.decode(decoders, stream)];
+	};
 }
 
 /**
@@ -299,7 +302,7 @@ export class TreeDecoder implements ChunkDecoder {
 		}
 
 		if (this.shape.extraFields !== undefined) {
-			const decoder = decoders[this.shape.extraFields];
+			const decoder = decoders[this.shape.extraFields] ?? oob();
 			const inner = readStreamStream(stream);
 			while (inner.offset !== inner.data.length) {
 				const key: FieldKey = readStreamIdentifier(inner, this.cache);

package/src/feature-libraries/chunked-forest/uniformChunk.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, compareArrays } from "@fluidframework/core-utils/internal";
+import { assert, compareArrays, oob } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -339,7 +339,8 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 		this.indexOfField++;
 		const fields = this.nodeInfo(CursorLocationType.Fields).shape.fieldsArray;
 		if (this.indexOfField < fields.length) {
-			this.fieldKey = fields[this.indexOfField][0];
+			const fieldArr = fields[this.indexOfField] ?? oob();
+			this.fieldKey = fieldArr[0];
 			return true;
 		}
 		this.exitField();
@@ -415,7 +416,7 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 		if (this.indexOfField >= fields.length) {
 			return false; // Handle empty field (indexed by key into empty field)
 		}
-		const f = shape.fieldsOffsetArray[this.indexOfField];
+		const f = shape.fieldsOffsetArray[this.indexOfField] ?? oob();
 		if (childIndex >= f.topLevelLength) {
 			return false;
 		}
@@ -497,7 +498,8 @@ class Cursor extends SynchronousCursor implements ChunkedCursor {
 		}
 		this.indexOfField = 0;
 		this.mode = CursorLocationType.Fields;
-		this.fieldKey = fieldsArray[0][0];
+		const fields = fieldsArray[0] ?? oob();
+		this.fieldKey = fields[0];
 		return true;
 	}
 

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { ICodecFamily } from "../../codec/index.js";
@@ -112,8 +113,6 @@ export function relevantRemovedRoots(change: ModularChangeset): Iterable<DeltaDe
  * At some point it will likely be worth supporting at least some of these, possibly using a mechanism that could support all of them if desired.
  * If/when such a mechanism becomes available, an evaluation should be done to determine if any existing editing operations should be changed to leverage it
  * (Possibly by adding opt ins at the view schema layer).
- *
- * @internal
  */
 export interface IDefaultEditBuilder {
 	/**
@@ -122,7 +121,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	valueField(field: FieldUpPath): ValueFieldEditBuilder;
+	valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * @param field - the optional field which is being edited under the parent node
@@ -130,7 +129,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	optionalField(field: FieldUpPath): OptionalFieldEditBuilder;
+	optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * @param field - the sequence field which is being edited under the parent node
@@ -139,7 +138,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	sequenceField(field: FieldUpPath): SequenceFieldEditBuilder;
+	sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous>;
 
 	/**
 	 * Moves a subsequence from one sequence field to another sequence field.
@@ -184,7 +183,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		this.modularBuilder.addNodeExistsConstraint(path);
 	}
 
-	public valueField(field: FieldUpPath): ValueFieldEditBuilder {
+	public valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			set: (newContent: ITreeCursorSynchronous): void => {
 				const fillId = this.modularBuilder.generateId();
@@ -208,7 +207,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		};
 	}
 
-	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder {
+	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			set: (newContent: ITreeCursorSynchronous | undefined, wasEmpty: boolean): void => {
 				const detachId = this.modularBuilder.generateId();
@@ -286,14 +285,15 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 						// in the composition performed by `submitChanges`.
 						attachAncestorIndex -= count;
 						let parent: UpPath | undefined = attachPath[sharedDepth - 1];
+						const parentField = attachPath[sharedDepth] ?? oob();
 						parent = {
 							parent,
 							parentIndex: attachAncestorIndex,
-							parentField: attachPath[sharedDepth].parentField,
+							parentField: parentField.parentField,
 						};
 						for (let i = sharedDepth + 1; i < attachPath.length; i += 1) {
 							parent = {
-								...attachPath[i],
+								...(attachPath[i] ?? oob()),
 								parent,
 							};
 						}
@@ -329,7 +329,7 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		}
 	}
 
-	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder {
+	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
 		return {
 			insert: (index: number, content: ITreeCursorSynchronous): void => {
 				const length =
@@ -363,62 +363,42 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 				);
 				this.modularBuilder.submitChange(field, sequence.identifier, change);
 			},
-			move: (sourceIndex: number, count: number, destIndex: number): void => {
-				if (count === 0) {
-					return;
-				} else if (count < 0 || !Number.isSafeInteger(count)) {
-					throw new UsageError(`Expected non-negative integer count, got ${count}.`);
-				}
-				const detachId = this.modularBuilder.generateId(count);
-				const attachId = this.modularBuilder.generateId(count);
-				const change = sequence.changeHandler.editor.move(
-					sourceIndex,
-					count,
-					destIndex,
-					detachId,
-					attachId,
-				);
-				this.modularBuilder.submitChange(field, sequence.identifier, brand(change));
-			},
 		};
 	}
 }
 
 /**
- * @internal
  */
-export interface ValueFieldEditBuilder {
+export interface ValueFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`.
 	 * @param newContent - the new content for the field.
 	 * The cursor can be in either Field or Node mode and must represent exactly one node.
 	 */
-	set(newContent: ITreeCursorSynchronous): void;
+	set(newContent: TContent): void;
 }
 
 /**
- * @internal
  */
-export interface OptionalFieldEditBuilder {
+export interface OptionalFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`
 	 * @param newContent - the new content for the field.
 	 * If provided, the cursor can be in either Field or Node mode and must represent exactly one node.
 	 * @param wasEmpty - whether the field is empty when creating this change
 	 */
-	set(newContent: ITreeCursorSynchronous | undefined, wasEmpty: boolean): void;
+	set(newContent: TContent | undefined, wasEmpty: boolean): void;
 }
 
 /**
- * @internal
  */
-export interface SequenceFieldEditBuilder {
+export interface SequenceFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which inserts the `newContent` at the given `index`.
 	 * @param index - the index at which to insert the `newContent`.
 	 * @param newContent - the new content to be inserted in the field. Cursor can be in either Field or Node mode.
 	 */
-	insert(index: number, newContent: ITreeCursorSynchronous): void;
+	insert(index: number, newContent: TContent): void;
 
 	/**
 	 * Issues a change which removes `count` elements starting at the given `index`.
@@ -426,14 +406,6 @@ export interface SequenceFieldEditBuilder {
 	 * @param count - The number of elements to remove.
 	 */
 	remove(index: number, count: number): void;
-
-	/**
-	 * Issues a change which moves `count` elements starting at `sourceIndex` to `destIndex`.
-	 * @param sourceIndex - the index of the first moved element.
-	 * @param count - the number of elements to move.
-	 * @param destIndex - the index the elements are moved to, interpreted before detaching the moved elements.
-	 */
-	move(sourceIndex: number, count: number, destIndex: number): void;
 }
 
 /**
@@ -443,8 +415,8 @@ function getSharedPrefixLength(pathA: readonly UpPath[], pathB: readonly UpPath[
 	const minDepth = Math.min(pathA.length, pathB.length);
 	let sharedDepth = 0;
 	while (sharedDepth < minDepth) {
-		const detachStep = pathA[sharedDepth];
-		const attachStep = pathB[sharedDepth];
+		const detachStep = pathA[sharedDepth] ?? oob();
+		const attachStep = pathB[sharedDepth] ?? oob();
 		if (detachStep !== attachStep) {
 			if (
 				detachStep.parentField !== attachStep.parentField ||

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -227,6 +227,17 @@ export const fieldKindConfigurations: ReadonlyMap<number, FieldKindConfiguration
 			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
 		]),
 	],
+	[
+		4,
+		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
+			[nodeKey.identifier, { kind: nodeKey, formatVersion: 1 }],
+			[required.identifier, { kind: required, formatVersion: 2 }],
+			[optional.identifier, { kind: optional, formatVersion: 2 }],
+			[sequence.identifier, { kind: sequence, formatVersion: 3 }],
+			[forbidden.identifier, { kind: forbidden, formatVersion: 1 }],
+			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
+		]),
+	],
 ]);
 
 /**
@@ -246,30 +257,24 @@ export const fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor> =
 // TODO: ensure thy work in generated docs.
 // TODO: add these comments to the rest of the cases below.
 /**
- * @internal
  */
 export interface Required extends FlexFieldKind<"Value", Multiplicity.Single> {}
 /**
- * @internal
  */
 export interface Optional extends FlexFieldKind<"Optional", Multiplicity.Optional> {}
 /**
- * @internal
  */
 export interface Sequence extends FlexFieldKind<"Sequence", Multiplicity.Sequence> {}
 /**
- * @internal
  */
 export interface Identifier extends FlexFieldKind<"Identifier", Multiplicity.Single> {}
 /**
- * @internal
  */
 export interface Forbidden
 	extends FlexFieldKind<typeof forbiddenFieldKindIdentifier, Multiplicity.Forbidden> {}
 
 /**
  * Default FieldKinds with their editor types erased.
- * @internal
  */
 export const FieldKinds: {
 	// TODO: inheritDoc for these somehow

package/src/feature-libraries/default-schema/defaultSchema.ts

@@ -9,7 +9,6 @@ import { fieldKinds } from "./defaultFieldKinds.js";
 
 /**
  * FullSchemaPolicy with the default field kinds.
- * @internal
  */
 export const defaultSchemaPolicy: FullSchemaPolicy = {
 	fieldKinds,

package/src/feature-libraries/default-schema/index.ts

@@ -26,6 +26,6 @@ export {
 	relevantRemovedRoots,
 } from "./defaultEditBuilder.js";
 
-export { SchemaValidationErrors, isNodeInSchema } from "./schemaChecker.js";
+export { SchemaValidationErrors, isNodeInSchema, isFieldInSchema } from "./schemaChecker.js";
 
 export { defaultSchemaPolicy } from "./defaultSchema.js";

package/src/feature-libraries/default-schema/schemaChecker.ts

@@ -29,6 +29,9 @@ export const enum SchemaValidationErrors {
 	UnknownError,
 }
 
+/**
+ * Deeply checks that the provided node complies with the schema based on its identifier.
+ */
 export function isNodeInSchema(
 	node: MapTree,
 	schemaAndPolicy: SchemaAndPolicy,
@@ -90,6 +93,9 @@ export function isNodeInSchema(
 	return SchemaValidationErrors.NoError;
 }
 
+/**
+ * Deeply checks that the nodes comply with the field schema and included schema.
+ */
 export function isFieldInSchema(
 	childNodes: readonly MapTree[],
 	schema: TreeFieldStoredSchema,