@fluidframework/tree 2.1.0-276985 → 2.1.0

package/src/simple-tree/types.ts

@@ -9,6 +9,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import {
 	NodeKind,
 	type TreeNodeSchema,
+	type TreeNodeSchemaClass,
 	type WithType,
 	typeNameSymbol,
 } from "./schemaTypes.js";
@@ -23,7 +24,7 @@ import { isTreeNode } from "./proxies.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { fail } from "../util/index.js";
-import { setFlexNode } from "./proxyBinding.js";
+import { getFlexNode, createKernel, setFlexNode } from "./proxyBinding.js";
 import { tryGetSchema } from "./treeNodeApi.js";
 
 /**
@@ -37,6 +38,81 @@ import { tryGetSchema } from "./treeNodeApi.js";
  */
 export type Unhydrated<T> = T;
 
+/**
+ * A collection of events that can be emitted by a {@link TreeNode}.
+ *
+ * @privateRemarks
+ * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
+ * Probably have object node and map node specific APIs for this.
+ *
+ * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
+ *
+ * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
+ * Some ideas:
+ *
+ * - treeChanged, but with some subtrees/fields/paths excluded
+ * - helper to batch several nodeChanged calls to a treeChanged scope
+ * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
+ * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
+ * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
+ * to allow efficiently searching for new content (and initial content) of a given type.
+ *
+ * @sealed @public
+ */
+export interface TreeChangeEvents {
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
+	 * change is:
+	 *
+	 * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
+	 * to something else, including `undefined`).
+	 *
+	 * - For an array node, when an element is added, removed, or moved.
+	 *
+	 * - For a map node, when an entry is added, updated, or removed.
+	 *
+	 * @remarks
+	 * This event is not emitted when:
+	 *
+	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
+	 * array/map node as one of its properties.
+	 *
+	 * - The node is moved to a different location in the tree or removed from the tree.
+	 * In this case the event is emitted on the _parent_ node, not the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 *
+	 * @privateRemarks
+	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+	 * node, or when the node has to be updated due to resolution of a merge conflict
+	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+	 */
+	nodeChanged(): void;
+
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
+	 * subtree rooted at it.
+	 *
+	 * @remarks
+	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
+	 * In that case it is emitted on the _parent_ node, not the node itself.
+	 *
+	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
+	 * of the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 */
+	treeChanged(): void;
+}
+
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *
@@ -208,51 +284,65 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	 * Also used to detect if oneTimeSetup has run.
 	 *
 	 * @privateRemarks
-	 * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.
+	 * This defaults to "default", which is used to trigger an error if not overridden in the derived class.
 	 *
 	 * The value of this on TreeNodeValid must only be overridden by base classes and never modified.
 	 * Ways to enforce this immutability prevent it from being overridden,
 	 * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.
 	 */
-	protected static constructorCached: typeof TreeNodeValid | undefined = TreeNodeValid;
+	protected static constructorCached: MostDerivedData | "default" | undefined = "default";
+
+	/**
+	 * Indicate that `this` is the most derived version of a schema, and thus the only one allowed to be used (other than by being subclassed a single time).
+	 */
+	public static markMostDerived(this: typeof TreeNodeValid & TreeNodeSchema): MostDerivedData {
+		assert(this.constructorCached !== "default", 0x95f /* invalid schema class */);
+
+		if (this.constructorCached === undefined) {
+			// Set the constructorCached on the layer of the prototype chain that declared it.
+			// This is necessary to ensure there is only one subclass of that type used:
+			// if constructorCached was simply set on `schema`,
+			// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them
+			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
+
+			// This is not just an alias of `this`, but a reference to the item in the prototype chain being walked, which happens to start at `this`.
+			// eslint-disable-next-line @typescript-eslint/no-this-alias
+			let schemaBase: typeof TreeNodeValid = this;
+			while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
+				schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
+			}
+			assert(schemaBase.constructorCached === undefined, 0x962 /* overwriting wrong cache */);
+			schemaBase.constructorCached = { constructor: this, oneTimeInitialized: false };
+			assert(
+				this.constructorCached === schemaBase.constructorCached,
+				0x9b5 /* Inheritance should work */,
+			);
+			return this.constructorCached;
+		} else if (this.constructorCached.constructor === this) {
+			return this.constructorCached;
+		}
+
+		throw new UsageError(
+			`Two schema classes were used (${this.name} and ${
+				this.constructorCached.constructor.name
+			}) which derived from the same SchemaFactory generated class (${JSON.stringify(
+				this.identifier,
+			)}). This is invalid.`,
+		);
+	}
 
 	public constructor(input: TInput | InternalTreeNode) {
 		super();
 		const schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;
-		assert("constructorCached" in schema, 0x95f /* invalid schema class */);
-		if (schema.constructorCached !== schema) {
-			if (schema.constructorCached !== undefined) {
-				assert(
-					schema.constructorCached !== TreeNodeValid,
-					0x960 /* Schema class schema must override static constructorCached member */,
-				);
-				throw new UsageError(
-					`Two schema classes were instantiated (${schema.name} and ${schema.constructorCached.name}) which derived from the same SchemaFactory generated class. This is invalid`,
-				);
-			}
-
+		const cache = schema.markMostDerived();
+		if (!cache.oneTimeInitialized) {
 			const flexSchema = getFlexSchema(schema);
 			assert(
 				tryGetSimpleNodeSchema(flexSchema) === schema,
 				0x961 /* Schema class not properly configured */,
 			);
 			schema.oneTimeSetup();
-			// Set the constructorCached on the layer of the prototype chain that declared it.
-			// This is necessary to ensure there is only one subclass of that type used:
-			// if constructorCached was simply set on `schema`,
-			// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them
-			// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.
-			{
-				let schemaBase: typeof TreeNodeValid = schema;
-				while (!Object.prototype.hasOwnProperty.call(schemaBase, "constructorCached")) {
-					schemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;
-				}
-				assert(
-					schemaBase.constructorCached === undefined,
-					0x962 /* overwriting wrong cache */,
-				);
-				schemaBase.constructorCached = schema;
-			}
+			cache.oneTimeInitialized = true;
 		}
 
 		if (isTreeNode(input)) {
@@ -271,6 +361,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		);
 
 		const result = schema.prepareInstance(this, node);
+		createKernel(result);
 		setFlexNode(result, node);
 		return result;
 	}
@@ -278,6 +369,22 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 // Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
 markEager(TreeNodeValid);
 
+/**
+ * Data cached about the most derived type in a schema's class hierarchy.
+ * @remarks
+ * The most derived type is the only one allowed to be referenced by other schema or constructed as a node.
+ * It has to be discovered lazily (when a node is constructed or when a {@link TreeViewConfiguration} is made),
+ * since JavaScript provides no way to find derived classes, or inject static class initialization time logic into base classes.
+ * Additionally since schema can reference other schema through lazy references which might be forward or recursive references,
+ * this can not be evaluated for one schema when referenced by another schema.
+ *
+ * See {@link TreeNodeValid.constructorCached} and {@link TreeNodeValid.markMostDerived}.
+ */
+export interface MostDerivedData {
+	readonly constructor: typeof TreeNodeValid & TreeNodeSchema;
+	oneTimeInitialized: boolean;
+}
+
 /**
  * A node type internal to `@fluidframework/tree`.
  * @remarks
@@ -293,3 +400,157 @@ export function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {
 	assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
 	return node;
 }
+
+// #region NodeJS custom inspect for TreeNodes.
+
+/**
+ * Used to customize "inspect" behavior in NodeJS.
+ * See https://nodejs.org/api/util.html#utilinspectcustom for details.
+ *
+ * VS-Code's debugger also uses this to inspect objects,
+ * see https://github.com/microsoft/vscode-js-debug/blob/64df2686c92bac402909dee5c3c389bbb7a81f6d/src/adapter/templates/getStringyProps.ts#L11 for details.
+ */
+const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+
+/**
+ * Node inspecting function for use with {@link customInspectSymbol}.
+ */
+function inspectNodeFunction(
+	this: TreeNodeValid<unknown>,
+	depth: number,
+	options?: unknown,
+	inspect?: unknown,
+): unknown {
+	// TODO: replicated from tryGetSchema to avoid cycle.
+	// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
+	const schema = tryGetSimpleNodeSchema(getFlexNode(this).schema) as TreeNodeSchemaClass;
+	const title = `${schema.name}: ${NodeKind[schema.kind]} Node (${schema.identifier})`;
+
+	if (depth < 2) {
+		const short = shortContent(this);
+		if (short !== undefined) {
+			return `${title} ${short}`;
+		}
+		return title;
+	}
+	const content = `${title} ${JSON.stringify(this)}`;
+	return content;
+}
+
+/**
+ * If the node has no items, a short JSON string for it.
+ */
+function shortContent(node: TreeNodeValid<unknown>): string | undefined {
+	if (Object.values(node).length === 0) {
+		return JSON.stringify(node);
+	}
+	return undefined;
+}
+
+/**
+ * Add inherited non-enumerable symbol for NodeJS inspection to all nodes.
+ *
+ * See {@link customInspectSymbol}.
+ */
+Object.defineProperty(TreeNodeValid.prototype, customInspectSymbol, {
+	value: inspectNodeFunction,
+	enumerable: false,
+});
+
+// #endregion
+
+// #region Browser custom debug format for TreeNodes
+
+// This section has side-effects, so including it in this file ensures its loaded whenever TreeNodes could exist.
+// Supported in at least Chrome and FireFox, more details at https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters/index.html
+// For this to work the browser's dev tools generally have to "Enable custom formatters".
+
+// This formatter is inspired by https://github.com/andrewdavey/immutable-devtools/blob/master/src/createFormatters.js which provides a similar formatter for the immutable.js library.
+
+const globals = typeof window === "undefined" ? globalThis : window;
+const formatters = ((
+	globals as { devtoolsFormatters?: DevtoolsFormatter.DevtoolsFormatter[] }
+).devtoolsFormatters ??= []);
+
+const nodeFormatter: DevtoolsFormatter.DevtoolsFormatter = {
+	header(object, config) {
+		if (isTreeNode(object)) {
+			return ["span", `${inspectNodeFunction.call(object, 1)}`];
+		}
+		return null;
+	},
+	body(object, config): DevtoolsFormatter.Item {
+		const children: DevtoolsFormatter.Item[] = [];
+		for (const [key, value] of Object.entries(object as TreeNode)) {
+			children.push(["li", ["span", `${key}: `], formattedReference(value)]);
+		}
+
+		// TODO:
+		// for array nodes, this isn't great since (at least in FireFox) the list items show up with a prefixed number starting from 1.
+		// This looks messy when followed by the array index.
+		// Find a way to hide the list index.
+		// { style: 'list-style-type: none` } did not seem to work.
+
+		return ["ol", ...children];
+	},
+	hasBody(object, config) {
+		return shortContent(object as TreeNodeValid<undefined>) === undefined;
+	},
+};
+
+function formattedReference(
+	object: unknown,
+	config?: DevtoolsFormatter.ObjectConfig,
+): DevtoolsFormatter.Item {
+	if (typeof object === "undefined") {
+		return ["span", "undefined"];
+	} else if (object === "null") {
+		return ["span", "null"];
+	}
+
+	return ["object", { object, config }];
+}
+
+formatters.push(nodeFormatter);
+
+// #endregion
+
+// These types are based on https://github.com/BenjaminAster/Better-TypeScript/blob/main/types/devtools-formatters.d.ts
+// however the original package causes multiple compile errors due to some of its other types it used, so the relevant part has been extracted and adjusted to better match our conventions.
+declare namespace DevtoolsFormatter {
+	type ObjectConfig = Record<string | symbol, unknown>;
+
+	type ElementTagName = "div" | "span" | "ol" | "li" | "table" | "tr" | "td";
+
+	type ElementTemplate = StyledElementTemplate | UnstyledElementTemplate;
+
+	type StyledElementTemplate = readonly [
+		ElementTagName,
+		{
+			style?: string;
+		},
+		...Item[],
+	];
+
+	type UnstyledElementTemplate = readonly [ElementTagName, ...Item[]];
+
+	type ObjectReference = readonly [
+		"object",
+		{
+			object: unknown;
+			config?: ObjectConfig;
+		},
+	];
+
+	type Item = string | ElementTemplate | ObjectReference;
+
+	interface DevtoolsFormatter {
+		header(
+			object?: unknown,
+			config?: ObjectConfig,
+			// eslint-disable-next-line @rushstack/no-new-null
+		): Item | null;
+		hasBody(object?: unknown, config?: ObjectConfig): boolean;
+		body(object?: unknown, config?: ObjectConfig): Item;
+	}
+}

package/src/util/breakable.ts

@@ -0,0 +1,214 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+/**
+ * An object which can enter a "broken" state where trying to use it is a UsageError.
+ */
+export class Breakable {
+	private brokenBy?: Error;
+
+	public constructor(private readonly name: string) {}
+
+	/**
+	 * Throws if the object is in the broken state.
+	 * @remarks
+	 * Can use {@link throwIfBroken} to apply this to a method.
+	 */
+	public use(): void {
+		if (this.brokenBy !== undefined) {
+			throw new UsageError(
+				`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${this.brokenBy}`,
+			);
+		}
+	}
+
+	/**
+	 * Puts this object into the broken state, and throws an error.
+	 *
+	 * @throws If already broken by a different error, throws a UsageError, otherwise throws `brokenBy`.
+	 */
+	public break(brokenBy: Error): never {
+		// If already broken by this error, let it bubble up without rethrowing a modified version.
+		// This prevents internal errors like asserts getting rethrown as different errors when wrapped with multiple call to `{@link Breakable.run}` or `{@link breakingMethod}`.
+		if (this.brokenBy !== brokenBy) {
+			this.use();
+			this.brokenBy = brokenBy;
+		}
+		throw brokenBy;
+	}
+
+	/**
+	 * {@link Breakable.break}, except tolerates `unknown` to be more easily used by catch blocks.
+	 * @privateRemarks
+	 * If there is a use-case, this should be made public.
+	 */
+	private rethrowCaught(brokenBy: unknown): never {
+		if (brokenBy instanceof Error) {
+			this.break(brokenBy);
+		}
+		this.break(
+			new Error(`Non-error thrown breaking ${this.name}. Thrown value: "${brokenBy}"`),
+		);
+	}
+
+	/**
+	 * Runs code which should break the object if it throws.
+	 * @remarks
+	 * This also throws if already broken like {@link Breakable.use}.
+	 * Any exceptions this catches are re-thrown.
+	 * Can use {@link breakingMethod} to apply this to a method.
+	 */
+	public run<TResult>(breaker: () => TResult): TResult {
+		this.use();
+		try {
+			return breaker();
+		} catch (error: unknown) {
+			this.rethrowCaught(error);
+		}
+	}
+
+	/**
+	 * Clears the existing broken state.
+	 * @remarks
+	 * This is rarely safe to to: it is only ok when all objects using this breaker are known to not have been left in an invalid state.
+	 * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.
+	 */
+	public clearError(): void {
+		assert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);
+		this.brokenBy = undefined;
+	}
+}
+
+/**
+ * Marks an object as being able to be in a broken state (unknown/unspecified/broken state due to unhandled exception).
+ * @remarks
+ * See decorators {@link breakingMethod} and {@link throwIfBroken} for ease of use.
+ */
+export interface WithBreakable {
+	readonly breaker: Breakable;
+}
+
+/**
+ * Decorator for methods which should break the object when they throw.
+ * @remarks
+ * This also throws if already broken like {@link throwIfBroken}.
+ * See {@link Breakable.run} for details.
+ *
+ * This should be used on methods which modify data that could result in an unsupported/broken state if an exception is thrown while modifying.
+ * It is ok for breakingMethods to call each-other.
+ * @privateRemarks
+ * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.
+ */
+export function breakingMethod<
+	Target extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),
+	This extends WithBreakable,
+	Args extends never[],
+	Return,
+>(target: Target, context?: ClassMethodDecoratorContext<This, Target>): Target {
+	function replacementMethod(this: This, ...args: Args): Return {
+		if (this.breaker === undefined) {
+			// This case is necessary for when wrapping methods which are invoked inside the constructor of the base class before `breaker` is set.
+			// Since the constructor throwing does not return an object, failing to put it into a broken state is not too bad.
+			// However when more than just the constructed object should be broken, this can result in missing a break.
+			return target.call(this, ...args);
+		}
+		return this.breaker.run(() => {
+			return target.call(this, ...args);
+		});
+	}
+	markBreaker(replacementMethod);
+	nameFunctionFrom(replacementMethod, target);
+	return replacementMethod as Target;
+}
+
+/**
+ * Decorator for methods which should throw if the object is in a broken state.
+ * @remarks
+ * This should be used on methods which read data that could be invalid when the object is broken.
+ * @privateRemarks
+ * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.
+ */
+export function throwIfBroken<
+	Target extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),
+	This extends WithBreakable,
+	Args extends never[],
+	Return,
+>(target: Target, context: ClassMethodDecoratorContext<This, Target>): Target {
+	function replacementMethod(this: This, ...args: Args): Return {
+		this.breaker.use();
+		return target.call(this, ...args);
+	}
+	markBreaker(replacementMethod);
+	nameFunctionFrom(replacementMethod, target);
+	return replacementMethod as Target;
+}
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+type PossiblyNamedFunction = Function & { displayName?: undefined | string };
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+function nameFunctionFrom(toName: Function, nameFrom: Function): void {
+	(toName as PossiblyNamedFunction).displayName =
+		(nameFrom as PossiblyNamedFunction).displayName ?? nameFrom.name;
+}
+
+const isBreakerSymbol: unique symbol = Symbol("isBreaker");
+
+// Accepting any function like value is desired and safe here as this does not call the provided function.
+// eslint-disable-next-line @typescript-eslint/ban-types
+function markBreaker(f: Function): void {
+	(f as unknown as Record<typeof isBreakerSymbol, true>)[isBreakerSymbol] = true;
+}
+
+// Accepting any function like value is desired and safe here as this does not call the provided function.
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isBreaker(f: Function): boolean {
+	return isBreakerSymbol in (f as unknown as Record<typeof isBreakerSymbol, true>);
+}
+
+/**
+ * Decorator for classes which should break when their methods throw.
+ * @remarks
+ * Applies {@link breakingMethod} to all methods declared directly by class or its base classes.
+ * Does not include those on derived classes.
+ * Does not include getters or setters, or value properties.
+ * Methods already marked as {@link breakingMethod} or {@link throwIfBroken} are unaffected.
+ */
+export function breakingClass<Target extends abstract new (...args: any[]) => WithBreakable>(
+	target: Target,
+	context: ClassDecoratorContext<Target>,
+): Target {
+	abstract class DecoratedBreakable extends target {}
+
+	// Keep track of what keys we have seen,
+	// since we visit most derived properties first and need to avoid wrapping base properties overriding more derived ones.
+	const overriddenKeys: Set<string | symbol> = new Set();
+
+	let prototype: object | null = target.prototype;
+	while (prototype !== null) {
+		for (const key of Reflect.ownKeys(prototype)) {
+			if (!overriddenKeys.has(key)) {
+				overriddenKeys.add(key);
+				const descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);
+				if (descriptor !== undefined) {
+					// Method
+					if (typeof descriptor.value === "function") {
+						if (!isBreaker(descriptor.value)) {
+							// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor
+							descriptor.value = breakingMethod(descriptor.value);
+							Object.defineProperty(DecoratedBreakable.prototype, key, descriptor);
+						}
+					}
+				}
+			}
+		}
+		prototype = Reflect.getPrototypeOf(prototype);
+	}
+
+	return DecoratedBreakable;
+}

package/src/util/index.ts

@@ -24,11 +24,13 @@ export {
 	getOrDefaultInNestedMap,
 	forEachInNestedMap,
 	type NestedMap,
+	type ReadonlyNestedMap,
 	SizedNestedMap,
 	populateNestedMap,
 	setInNestedMap,
 	tryAddToNestedMap,
 	tryGetFromNestedMap,
+	mapNestedMap,
 	nestedMapToFlatList,
 	nestedMapFromFlatList,
 } from "./nestedMap.js";
@@ -67,6 +69,7 @@ export {
 	JsonCompatibleReadOnlySchema,
 	makeArray,
 	mapIterable,
+	filterIterable,
 	type Mutable,
 	type Populated,
 	type RecursiveReadonly,
@@ -125,3 +128,11 @@ export {
 	type IdAllocationState,
 	fakeIdAllocator,
 } from "./idAllocator.js";
+
+export {
+	Breakable,
+	type WithBreakable,
+	breakingMethod,
+	throwIfBroken,
+	breakingClass,
+} from "./breakable.js";