@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/core/tree/mapTree.ts

@@ -8,14 +8,55 @@ import type { FieldKey } from "../schema-stored/index.js";
 import type { NodeData } from "./types.js";
 
 /**
- * This modules provides a simple in memory tree format.
+ * This module provides a simple in-memory tree format.
  */
 
 /**
- * Simple in memory tree representation based on Maps.
- * MapTrees should not store empty fields.
- * @internal
+ * Simple in-memory tree representation based on Maps.
+ * @remarks MapTrees should not store empty fields.
  */
 export interface MapTree extends NodeData {
 	readonly fields: ReadonlyMap<FieldKey, readonly MapTree[]>;
 }
+
+/**
+ * A {@link MapTree} which is owned by a single reference, and therefore allowed to be mutated.
+ *
+ * @remarks
+ * To ensure unexpected mutations, this object should have a single owner/context.
+ * Though this type does implement MapTree, it should not be used as a MapTree while it can possibly be mutated.
+ * If it is shared to other contexts, it should first be upcast to a {@link MapTree} and further mutations should be avoided.
+ */
+export interface ExclusiveMapTree extends NodeData, MapTree {
+	fields: Map<FieldKey, ExclusiveMapTree[]>;
+}
+
+/**
+ * Returns a deep copy of the given {@link MapTree}.
+ * @privateRemarks This is implemented iteratively (rather than recursively, which is much simpler)
+ * to avoid the possibility of a stack overflow for very deep trees.
+ */
+export function deepCopyMapTree(mapTree: MapTree): ExclusiveMapTree {
+	type Next = [fields: ExclusiveMapTree["fields"], sourceFields: MapTree["fields"]];
+	const rootFields: ExclusiveMapTree["fields"] = new Map();
+	const nexts: Next[] = [[rootFields, mapTree.fields]];
+	for (let next = nexts.pop(); next !== undefined; next = nexts.pop()) {
+		const [fields, sourceFields] = next;
+		for (const [key, field] of sourceFields) {
+			if (field.length > 0) {
+				const newField: ExclusiveMapTree[] = [];
+				for (const child of field) {
+					const childClone: ExclusiveMapTree = { ...child, fields: new Map() };
+					newField.push(childClone);
+					nexts.push([childClone.fields, child.fields]);
+				}
+				fields.set(key, newField);
+			}
+		}
+	}
+
+	return {
+		...mapTree,
+		fields: rootFields,
+	};
+}

package/src/core/tree/pathTree.ts

@@ -11,8 +11,6 @@ import { type DetachedField, keyAsDetachedField } from "./types.js";
 /**
  * Identical to {@link UpPath}, but a duplicate declaration is needed to make
  * the default type parameter compile.
- *
- * @internal
  */
 export type UpPathDefault = UpPath;
 
@@ -27,7 +25,6 @@ export type UpPathDefault = UpPath;
  *
  * UpPaths can be mutated over time and should be considered to be invalidated when any edits occurs:
  * Use of an UpPath that was acquired before the most recent edit is undefined behavior.
- * @internal
  */
 export interface UpPath<TParent = UpPathDefault> {
 	/**
@@ -49,7 +46,6 @@ export interface UpPath<TParent = UpPathDefault> {
  * Path from a field in the tree upward.
  *
  * See {@link UpPath}.
- * @internal
  */
 export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
 	/**
@@ -68,13 +64,11 @@ export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
  * A range of nodes in a detached field.
  * Unlike RangeUpPath, such ranges are generated by create and detach operations,
  * as well as consumed by destroy and attach operations.
- * @internal
  */
 export type DetachedRangeUpPath = Brand<Omit<RangeUpPath, "parent">, "DetachedRangeUpPath">;
 
 /**
  * Delimits the extend of a range.
- * @internal
  */
 export interface Range {
 	/**
@@ -92,7 +86,6 @@ export interface Range {
 /**
  * A possibly empty range of nodes in a field.
  * This object only characterizes the location of the range, it does not own/contain the nodes in the range.
- * @internal
  */
 export interface RangeUpPath<TUpPath extends UpPath = UpPath>
 	extends FieldUpPath<TUpPath>,
@@ -100,7 +93,6 @@ export interface RangeUpPath<TUpPath extends UpPath = UpPath>
 
 /**
  * A place in a field.
- * @internal
  */
 export interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPath<TUpPath> {
 	/**
@@ -111,21 +103,18 @@ export interface PlaceUpPath<TUpPath extends UpPath = UpPath> extends FieldUpPat
 
 /**
  * A place in a detached field.
- * @internal
  */
 export type DetachedPlaceUpPath = Brand<Omit<PlaceUpPath, "parent">, "DetachedRangeUpPath">;
 
 /**
  * Indicates the index of a node in a field.
  * Zero indicates the first node in a field.
- * @internal
  */
 export type NodeIndex = number;
 
 /**
  * Indicates a place between nodes in a field or at the extremity of a field.
  * Zero indicates the place at the start of the field (before the first node if any).
- * @internal
  */
 export type PlaceIndex = number;
 

package/src/core/tree/treeTextFormat.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { fail } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { NodeData } from "./types.js";
@@ -94,7 +95,7 @@ export function getGenericTreeField<T>(
 
 	// Do not just read field and check for undefined: see warning on FieldMapObject.
 	if (Object.prototype.hasOwnProperty.call(children, key)) {
-		return children[key];
+		return children[key] ?? fail("This wont be undefined due to the check above");
 	}
 	// Handle missing field:
 	if (createIfMissing === false) {
@@ -169,7 +170,7 @@ export function genericTreeDeleteIfEmpty<T>(
 ): void {
 	const children = getGenericTreeFieldMap(node, false);
 	if (Object.prototype.hasOwnProperty.call(children, key)) {
-		if (children[key].length === 0) {
+		if (children[key]?.length === 0) {
 			// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
 			delete children[key];
 			if (removeMapObject) {

package/src/core/tree/types.ts

@@ -19,7 +19,6 @@ import type {
 } from "../schema-stored/index.js";
 
 /**
- * @internal
  */
 export type TreeType = TreeNodeSchemaIdentifier;
 
@@ -42,19 +41,15 @@ export const EmptyKey: FieldKey = brand("");
  * FieldKey to use for the root of documents in places that need to refer to detached sequences or the root.
  * TODO: if we do want to standardize on a single value for this,
  * it likely should be namespaced or a UUID to avoid risk of collisions.
- * @internal
  */
 export const rootFieldKey: FieldKey = brand("rootFieldKey");
 
 /**
- * @internal
  */
 export const rootField = keyAsDetachedField(rootFieldKey);
 
 /**
  * Location of a tree relative to is parent container (which can be a tree or forest).
- *
- * @internal
  */
 export interface ChildLocation {
 	readonly container: ChildCollection;
@@ -63,7 +58,6 @@ export interface ChildLocation {
 
 /**
  * Wrapper around DetachedField that can be detected at runtime.
- * @internal
  */
 export interface RootField {
 	readonly key: DetachedField;
@@ -71,7 +65,6 @@ export interface RootField {
 
 /**
  * Identifier for a child collection, either on a node/tree or at the root of a forest.
- * @internal
  */
 export type ChildCollection = FieldKey | RootField;
 
@@ -87,7 +80,6 @@ export type ChildCollection = FieldKey | RootField;
  *
  * In some APIs DetachedFields are used as FieldKeys on a special implicit root node
  * to simplify the APIs and implementation.
- * @internal
  */
 export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField">> {}
 
@@ -96,7 +88,6 @@ export interface DetachedField extends Opaque<Brand<string, "tree.DetachedField"
  * This maps detached field to field keys for thus use.
  *
  * @returns `field` as a {@link FieldKey} usable on a special root node serving as a parent of detached fields.
- * @internal
  */
 export function detachedFieldAsKey(field: DetachedField): FieldKey {
 	return brand(extractFromOpaque(field));
@@ -106,7 +97,6 @@ export function detachedFieldAsKey(field: DetachedField): FieldKey {
  * The inverse of {@link detachedFieldAsKey}.
  * Thus must only be used on {@link FieldKey}s which were produced via {@link detachedFieldAsKey},
  * and with the same scope (ex: forest) as the detachedFieldAsKey was originally from.
- * @internal
  */
 export function keyAsDetachedField(key: FieldKey): DetachedField {
 	return brand(key);
@@ -116,7 +106,6 @@ export function keyAsDetachedField(key: FieldKey): DetachedField {
  * TODO: integrate this into Schema. Decide how to persist them (need stable Id?). Maybe allow updating field kinds?.
  * TODO: make families of changes per field kind. Build editing APIs from that.
  * TODO: factor ChangeRebaser implementations to support adding new field kinds.
- * @internal
  */
 export interface FieldKind {
 	readonly name: string;

package/src/core/tree/visitDelta.ts

@@ -246,7 +246,6 @@ function transferRoots(
 /**
  * Visitor for changes in a delta.
  * Must be freed after use.
- * @internal
  */
 export interface DeltaVisitor {
 	/**
@@ -473,13 +472,13 @@ function buildTrees(
 	latestRevision: RevisionTag | undefined,
 	visitor: DeltaVisitor,
 ): void {
-	for (let i = 0; i < trees.length; i += 1) {
+	for (const [i, tree] of trees.entries()) {
 		const offsettedId = offsetDetachId(id, i);
 		let root = detachedFieldIndex.tryGetEntry(offsettedId);
 		assert(root === undefined, 0x929 /* Unable to build tree that already exists */);
 		root = detachedFieldIndex.createEntry(offsettedId, latestRevision);
 		const field = detachedFieldIndex.toFieldKey(root);
-		visitor.create([trees[i]], field);
+		visitor.create([tree], field);
 	}
 }
 

package/src/core/tree/visitPath.ts

@@ -17,8 +17,6 @@ import type {
  *
  * For any of these events, the paths are guaranteed to be valid at the time of the event,
  * and it is valid to read from the Forest at that path.
- *
- * @internal
  */
 export interface PathVisitor {
 	/**

package/src/core/tree/visitorUtils.ts

@@ -115,7 +115,6 @@ export function combineVisitors(
 /**
  * Visitor that is notified of changes before, after, and when changes are made.
  * Must be freed after use.
- * @internal
  */
 export interface AnnouncedVisitor extends DeltaVisitor {
 	/**

package/src/domains/index.ts

@@ -11,6 +11,9 @@ export {
 	jsonRoot,
 	jsonSchema,
 	singleJsonCursor,
+	typedJsonCursor,
+	type TypedJsonCompatible,
+	type TypedJsonCompatibleObject,
 } from "./json/index.js";
 
 export { leaf } from "./leafDomain.js";

package/src/domains/json/index.ts

@@ -3,5 +3,11 @@
  * Licensed under the MIT License.
  */
 
-export { singleJsonCursor, cursorToJsonObject } from "./jsonCursor.js";
+export {
+	singleJsonCursor,
+	cursorToJsonObject,
+	typedJsonCursor,
+	type TypedJsonCompatible,
+	type TypedJsonCompatibleObject,
+} from "./jsonCursor.js";
 export { jsonSchema, jsonObject, jsonArray, jsonRoot } from "./jsonDomainSchema.js";

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,7 @@ export type Off = () => void;
 
 /**
  * Interface for an event emitter that can emit typed events to subscribed listeners.
- * @internal
+ * @sealed @alpha
  */
 export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	/**
@@ -146,7 +146,7 @@ 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
+ * @alpha
  */
 export function createEmitter<TListeners extends object>(
 	noListeners?: NoListenersCallback<TListeners>,
@@ -157,14 +157,15 @@ 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
+ * @alpha
  */
 export type NoListenersCallback<TListeners extends object> = (
 	eventName: keyof Listeners<TListeners>,
 ) => void;
 
 /**
- * @internal
+ * Allows querying if an object has listeners.
+ * @sealed @alpha
  */
 export interface HasListeners<TListeners extends Listeners<TListeners>> {
 	/**
@@ -201,7 +202,7 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
  *
  * ```typescript
  * class MyClass implements ISubscribable<MyEvents> {
- *   private readonly events = EventEmitter.create<MyEvents>();
+ *   private readonly events = createEmitter<MyEvents>();
  *
  *   private load() {
  *     this.events.emit("loaded");
@@ -212,6 +213,7 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
  *   }
  * }
  * ```
+ * @alpha
  */
 export class EventEmitter<TListeners extends Listeners<TListeners>>
 	implements Listenable<TListeners>, HasListeners<TListeners>
@@ -231,7 +233,9 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 	): void {
 		const listeners = this.listeners.get(eventName);
 		if (listeners !== undefined) {
-			const argArray: unknown[] = args; // TODO: Current TS (4.5.5) cannot spread `args` into `listener()`, but future versions (e.g. 4.8.4) can.
+			// Current TS (5.4.5) cannot spread `args` into `listener()`, but assigning to an array first makes it work.
+			const argArray: unknown[] = args;
+
 			// This explicitly copies listeners so that new listeners added during this call to emit will not receive this event.
 			for (const [off, listener] of [...listeners]) {
 				// If listener has been unsubscribed while invoking other listeners, skip it.

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