@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/domains/json/jsonCursor.ts

@@ -13,12 +13,17 @@ import {
 	mapCursorField,
 	mapCursorFields,
 } from "../../core/index.js";
-import { type CursorAdapter, stackTreeNodeCursor } from "../../feature-libraries/index.js";
-import type { JsonCompatible } from "../../util/index.js";
+import {
+	type CursorAdapter,
+	stackTreeNodeCursor,
+	TreeNodeSchemaBase,
+} from "../../feature-libraries/index.js";
+import { brand, isReadonlyArray, type JsonCompatible } from "../../util/index.js";
 import { leaf } from "../leafDomain.js";
 
 import { jsonArray, jsonObject } from "./jsonDomainSchema.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import type { IFluidHandle } from "@fluidframework/core-interfaces/internal";
 
 const adapter: CursorAdapter<JsonCompatible> = {
 	value: (node: JsonCompatible) =>
@@ -38,7 +43,7 @@ const adapter: CursorAdapter<JsonCompatible> = {
 			default:
 				if (node === null) {
 					return leaf.null.name;
-				} else if (Array.isArray(node)) {
+				} else if (isReadonlyArray(node)) {
 					return jsonArray.name;
 				} else {
 					return jsonObject.name;
@@ -50,7 +55,7 @@ const adapter: CursorAdapter<JsonCompatible> = {
 			case "object":
 				if (node === null) {
 					return [];
-				} else if (Array.isArray(node)) {
+				} else if (isReadonlyArray(node)) {
 					return node.length === 0 ? [] : [EmptyKey];
 				} else {
 					return Object.keys(node) as FieldKey[];
@@ -70,7 +75,7 @@ const adapter: CursorAdapter<JsonCompatible> = {
 			return [];
 		}
 
-		if (Array.isArray(node)) {
+		if (isReadonlyArray(node)) {
 			return key === EmptyKey ? node : [];
 		}
 
@@ -88,7 +93,8 @@ const adapter: CursorAdapter<JsonCompatible> = {
 };
 
 /**
- * Used to read a Jsonable tree for testing and benchmarking.
+ * Used to read generic json compatible data as a tree in the JSON domain.
+ * The returned tree will have a schema in the json domain as defined by {@link jsonRoot}.
  *
  * @returns an {@link ITreeCursorSynchronous} for a single {@link JsonCompatible}.
  */
@@ -138,3 +144,104 @@ export function cursorToJsonObject(reader: ITreeCursor): JsonCompatible {
 		}
 	}
 }
+
+// #region TypedJsonCursor
+
+/** Used to construct a {@link TypedJsonCursor} */
+export interface TypedJsonCompatibleObject {
+	[key: string]: TypedJsonCompatible;
+	[typedJsonSymbol]: string | TreeNodeSchemaBase;
+}
+
+/** Used to construct a {@link TypedJsonCursor} */
+export type TypedJsonCompatible =
+	| JsonCompatible
+	| TypedJsonCompatibleObject
+	| TypedJsonCompatible[]
+	| IFluidHandle
+	| JsonCompatible;
+
+const typedJsonSymbol = Symbol("JSON Cursor Type");
+
+function isObject(json: TypedJsonCompatible): json is TypedJsonCompatibleObject {
+	if (typeof json === "object" && json !== null) {
+		const typed = json as Partial<TypedJsonCompatibleObject>;
+		return typed[typedJsonSymbol] !== undefined;
+	}
+
+	return false;
+}
+
+const typedAdapter: CursorAdapter<TypedJsonCompatible> = {
+	value: (node: TypedJsonCompatible) => {
+		if (isFluidHandle(node)) {
+			return node;
+		}
+
+		// TODO: Get rid of this cast by combining TypedJsonCompatible and JsonCompatible into a single cursor with flags to configure behavior.
+		// This cast is necessary because TypedJsonCompatible can have Fluid handles underneath it, however, `adapter` only cares if `node` itself is a FluidHandle, which it is not.
+		return adapter.value(node as JsonCompatible);
+	},
+	type: (node: TypedJsonCompatible) => {
+		if (isFluidHandle(node)) {
+			return leaf.handle.name;
+		}
+
+		if (isObject(node)) {
+			const type = node[typedJsonSymbol];
+			return type instanceof TreeNodeSchemaBase ? type.name : brand(type);
+		}
+
+		return adapter.type(node as JsonCompatible);
+	},
+	keysFromNode: (node: TypedJsonCompatible): readonly FieldKey[] => {
+		if (isFluidHandle(node)) {
+			return [];
+		}
+		return adapter.keysFromNode(node as JsonCompatible);
+	},
+	getFieldFromNode: (
+		node: TypedJsonCompatible,
+		key: FieldKey,
+	): readonly TypedJsonCompatible[] => {
+		if (isFluidHandle(node)) {
+			return [];
+		}
+
+		const field = adapter.getFieldFromNode(node as JsonCompatible, key);
+		if (isReadonlyArray(field) && field.length === 1 && isReadonlyArray(field[0])) {
+			// If the field is an array wrapping another array, then unbox to the inner array
+			return field[0];
+		}
+
+		return field;
+	},
+};
+
+/**
+ * A variant of {@link singleJsonCursor} which allows types to be provided for nodes.
+ *
+ * @remarks Types are optional, but if present will be used to derive the type of the node when the cursor is read.
+ *
+ * This cursor differs from singleJsonCursor in that it inlines arrays, (arrays are not boxed into an "array node" but are directly interpreted as sequence fields).
+ *
+ * It also allows Fluid handles as input.
+ *
+ * @example
+ * ```ts
+ * const cursor = typedJsonCursor({
+ *   [typedJsonCursor.type]: Point,
+ *   x: 3,
+ *   y: 42
+ * });
+ * ```
+ */
+const singleTypedJsonCursor = function (root: TypedJsonCompatible): ITreeCursorSynchronous {
+	return stackTreeNodeCursor(typedAdapter, root);
+};
+
+singleTypedJsonCursor.type = typedJsonSymbol;
+
+export { singleTypedJsonCursor as typedJsonCursor };
+
+// #endregion TypedJsonCursor

package/src/domains/json/jsonDomainSchema.ts

@@ -8,7 +8,7 @@
 // which API-Extractor leaves as is when generating the rollup, leaving them pointing at the wrong directory.
 // API-Extractor issue: https://github.com/microsoft/rushstack/issues/4507
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
-import { ValueSchema } from "../../core/index.js";
+import { EmptyKey, ValueSchema } from "../../core/index.js";
 import {
 	FieldKinds,
 	type FlexAllowedTypes,
@@ -40,9 +40,8 @@ export const jsonObject = builder.mapRecursive(
 	FlexFieldSchema.createUnsafe(FieldKinds.optional, jsonRoot),
 );
 
-export const jsonArray = builder.fieldNodeRecursive(
-	"array",
-	FlexFieldSchema.createUnsafe(FieldKinds.sequence, jsonRoot),
-);
+export const jsonArray = builder.objectRecursive("array", {
+	[EmptyKey]: FlexFieldSchema.createUnsafe(FieldKinds.sequence, jsonRoot),
+});
 
 export const jsonSchema = builder.intoLibrary();

package/src/domains/leafDomain.ts

@@ -24,7 +24,6 @@ const library = builder.intoLibrary();
 
 /**
  * Built-in {@link LeafNodeSchema}.
- * @internal
  */
 export const leaf = {
 	/**

package/src/domains/schemaBuilder.ts

@@ -6,7 +6,6 @@
 import {
 	FieldKinds,
 	type FlexFieldKind,
-	FlexFieldNodeSchema,
 	type FlexFieldSchema,
 	type FlexImplicitAllowedTypes,
 	type FlexImplicitFieldSchema,
@@ -64,27 +63,6 @@ export class SchemaBuilder<
 		) as unknown as FlexObjectNodeSchema<`${TScope}.${Name}`, T>;
 	}
 
-	/**
-	 * Define (and add to this library) a {@link FlexFieldNodeSchema} for a {@link Sequence}.
-	 *
-	 * The name must be unique among all TreeNodeSchema in the the document schema.
-	 */
-	public list<Name extends TName, const T extends FlexImplicitAllowedTypes>(
-		name: Name,
-		allowedTypes: T,
-	): FlexFieldNodeSchema<
-		`${TScope}.${Name}`,
-		FlexFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>
-	> {
-		const schema = FlexFieldNodeSchema.create(
-			this,
-			this.scoped(name as TName & Name),
-			this.sequence(allowedTypes),
-		);
-		this.addNodeSchema(schema);
-		return schema;
-	}
-
 	/**
 	 * Define a schema for an {@link FieldKinds.optional|optional field}.
 	 * @remarks

package/src/events/events.ts

@@ -112,7 +112,6 @@ export type Off = () => void;
 
 /**
  * Interface for an event emitter that can emit typed events to subscribed listeners.
- * @internal
  */
 export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	/**
@@ -146,7 +145,6 @@ export interface IEmitter<TListeners extends Listeners<TListeners>> {
  *
  * A class can delegate handling {@link Listenable} to the returned value while using it to emit the events.
  * See also `EventEmitter` which be used as a base class to implement {@link Listenable} via extension.
- * @internal
  */
 export function createEmitter<TListeners extends object>(
 	noListeners?: NoListenersCallback<TListeners>,
@@ -157,14 +155,12 @@ export function createEmitter<TListeners extends object>(
 /**
  * Called when the last listener for `eventName` is removed.
  * Useful for determining when to clean up resources related to detecting when the event might occurs.
- * @internal
  */
 export type NoListenersCallback<TListeners extends object> = (
 	eventName: keyof Listeners<TListeners>,
 ) => void;
 
 /**
- * @internal
  */
 export interface HasListeners<TListeners extends Listeners<TListeners>> {
 	/**

package/src/feature-libraries/chunked-forest/README.md

@@ -10,4 +10,12 @@ This allows for efficient cloning of forests, without major performance overhead
 
 ## Status
 
-In progress: not ready for use.
+Working, but not fully optimized.
+Might not provide a faster experience than the reference implementation.
+
+Currently unconditionally splits chunks when editing.
+To actually deliver on the performance goals of this design,
+it will need to keep data in uniform chunks in more cases:
+this mainly requires avoiding splitting them into basic chunks when editing (ex: updating a leaf number) by supporting in-place updates via replace operations (which `DeltaVisitor` currently does not expose) instead of delete and inserts which forces the data to be re-encoded as the intermediate form violates the shape requires of the uniform chunk.
+
+SequenceChunks also aren't well optimized in the cursor, since each one traversed adds another level of wrappers on the cursor.

package/src/feature-libraries/chunked-forest/basicChunk.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,
@@ -183,13 +183,14 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 
 	private getStackedFieldKey(height: number): FieldKey {
 		assert(height % 2 === 0, 0x51f /* must field height */);
-		return this.siblingStack[height][this.indexStack[height]] as FieldKey;
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return this.siblingStack[height]![this.indexStack[height]!] as FieldKey;
 	}
 
 	private getStackedNodeIndex(height: number): number {
 		assert(height % 2 === 1, 0x520 /* must be node height */);
 		assert(height >= 0, 0x521 /* must not be above root */);
-		return this.indexStack[height];
+		return this.indexStack[height] ?? oob();
 	}
 
 	private getStackedNode(height: number): BasicChunk {
@@ -368,9 +369,11 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 
 		this.indexWithinChunk += offset;
 		if (offset >= 0) {
-			const chunks = this.siblings as TreeChunk[];
-			while (this.indexWithinChunk >= chunks[this.indexOfChunk].topLevelLength) {
-				this.indexWithinChunk -= chunks[this.indexOfChunk].topLevelLength;
+			const chunks = (this.siblings as TreeChunk[]) ?? oob();
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			while (this.indexWithinChunk >= chunks[this.indexOfChunk]!.topLevelLength) {
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				this.indexWithinChunk -= chunks[this.indexOfChunk]!.topLevelLength;
 				this.indexOfChunk++;
 				if (this.indexOfChunk === chunks.length) {
 					this.exitNode();
@@ -389,7 +392,8 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 					return false;
 				}
 				this.indexOfChunk--;
-				this.indexWithinChunk += chunks[this.indexOfChunk].topLevelLength;
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				this.indexWithinChunk += chunks[this.indexOfChunk]!.topLevelLength;
 			}
 		}
 
@@ -436,7 +440,8 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 		this.indexWithinChunk++;
 		if (
 			this.indexWithinChunk ===
-			(this.siblings as TreeChunk[])[this.indexOfChunk].topLevelLength
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			(this.siblings as TreeChunk[])[this.indexOfChunk]!.topLevelLength
 		) {
 			this.indexOfChunk++;
 			if (this.indexOfChunk === (this.siblings as TreeChunk[]).length) {
@@ -455,7 +460,7 @@ export class BasicChunkCursor extends SynchronousCursor implements ChunkedCursor
 			this.mode === CursorLocationType.Nodes,
 			0x55d /* can only initNestedCursor when in Nodes */,
 		);
-		const chunk = (this.siblings as TreeChunk[])[this.indexOfChunk];
+		const chunk = (this.siblings as TreeChunk[])[this.indexOfChunk] ?? oob();
 		this.nestedCursor = !(chunk instanceof BasicChunk) ? chunk.cursor() : undefined;
 		this.nestedCursor?.enterNode(this.indexWithinChunk);
 	}

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;
 	}