@fluidframework/tree 2.3.0-288113 → 2.4.0-294316

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.3.0-288113",
+  "version": "2.4.0-294316",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -23,6 +23,16 @@
         "default": "./dist/index.js"
       }
     },
+    "./alpha": {
+      "import": {
+        "types": "./lib/alpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/alpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
     "./beta": {
       "import": {
         "types": "./lib/beta.d.ts",
@@ -42,6 +52,16 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./legacy": {
+      "import": {
+        "types": "./lib/legacy.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/legacy.d.ts",
+        "default": "./dist/index.js"
+      }
     }
   },
   "main": "lib/index.js",
@@ -67,17 +87,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.3.0-288113",
-    "@fluidframework/container-runtime": "2.3.0-288113",
-    "@fluidframework/core-interfaces": "2.3.0-288113",
-    "@fluidframework/core-utils": "2.3.0-288113",
-    "@fluidframework/datastore-definitions": "2.3.0-288113",
-    "@fluidframework/driver-definitions": "2.3.0-288113",
-    "@fluidframework/id-compressor": "2.3.0-288113",
-    "@fluidframework/runtime-definitions": "2.3.0-288113",
-    "@fluidframework/runtime-utils": "2.3.0-288113",
-    "@fluidframework/shared-object-base": "2.3.0-288113",
-    "@fluidframework/telemetry-utils": "2.3.0-288113",
+    "@fluid-internal/client-utils": "2.4.0-294316",
+    "@fluidframework/container-runtime": "2.4.0-294316",
+    "@fluidframework/core-interfaces": "2.4.0-294316",
+    "@fluidframework/core-utils": "2.4.0-294316",
+    "@fluidframework/datastore-definitions": "2.4.0-294316",
+    "@fluidframework/driver-definitions": "2.4.0-294316",
+    "@fluidframework/id-compressor": "2.4.0-294316",
+    "@fluidframework/runtime-definitions": "2.4.0-294316",
+    "@fluidframework/runtime-utils": "2.4.0-294316",
+    "@fluidframework/shared-object-base": "2.4.0-294316",
+    "@fluidframework/telemetry-utils": "2.4.0-294316",
     "@sinclair/typebox": "^0.32.29",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@ungap/structured-clone": "^1.2.0",
@@ -86,21 +106,21 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.2",
     "@biomejs/biome": "~1.8.3",
-    "@fluid-internal/mocha-test-setup": "2.3.0-288113",
-    "@fluid-private/stochastic-test-utils": "2.3.0-288113",
-    "@fluid-private/test-dds-utils": "2.3.0-288113",
-    "@fluid-private/test-drivers": "2.3.0-288113",
+    "@fluid-internal/mocha-test-setup": "2.4.0-294316",
+    "@fluid-private/stochastic-test-utils": "2.4.0-294316",
+    "@fluid-private/test-dds-utils": "2.4.0-294316",
+    "@fluid-private/test-drivers": "2.4.0-294316",
     "@fluid-tools/benchmark": "^0.50.0",
-    "@fluid-tools/build-cli": "^0.43.0",
+    "@fluid-tools/build-cli": "^0.46.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.43.0",
-    "@fluidframework/container-definitions": "2.3.0-288113",
-    "@fluidframework/container-loader": "2.3.0-288113",
-    "@fluidframework/eslint-config-fluid": "^5.3.0",
-    "@fluidframework/test-runtime-utils": "2.3.0-288113",
-    "@fluidframework/test-utils": "2.3.0-288113",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.2.0",
-    "@microsoft/api-extractor": "^7.45.1",
+    "@fluidframework/build-tools": "^0.46.0",
+    "@fluidframework/container-definitions": "2.4.0-294316",
+    "@fluidframework/container-loader": "2.4.0-294316",
+    "@fluidframework/eslint-config-fluid": "^5.4.0",
+    "@fluidframework/test-runtime-utils": "2.4.0-294316",
+    "@fluidframework/test-utils": "2.4.0-294316",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.3.0",
+    "@microsoft/api-extractor": "7.47.8",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^9.1.1",
@@ -142,7 +162,18 @@
     }
   },
   "typeValidation": {
-    "broken": {}
+    "broken": {
+      "Interface_FieldSchemaUnsafe": {
+        "forwardCompat": false
+      },
+      "Interface_ITreeViewConfiguration": {
+        "forwardCompat": false
+      },
+      "TypeAlias_ImplicitFieldSchema": {
+        "forwardCompat": false
+      }
+    },
+    "entrypoint": "internal"
   },
   "scripts": {
     "api": "fluid-build . --task api",
@@ -151,6 +182,9 @@
     "bench": "mocha --timeout 999999 --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js",
     "bench:profile": "mocha --v8-prof --v8-logfile=profile.log --v8-no-logfile-per-isolate --timeout 999999 --perfMode --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js && node --prof-process profile.log > profile.txt && rimraf profile.log && echo See results in profile.txt",
     "build": "fluid-build . --task build",
+    "build:api-reports": "concurrently \"npm:build:api-reports:*\"",
+    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor.current.json",
+    "build:api-reports:legacy": "api-extractor run --local --config api-extractor/api-extractor.legacy.json",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
     "build:docs": "api-extractor run --local",
@@ -163,12 +197,19 @@
     "check:biome": "biome check .",
     "check:exports": "concurrently \"npm:check:exports:*\"",
     "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
+    "check:exports:cjs:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.cjs.json",
     "check:exports:cjs:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.cjs.json",
+    "check:exports:cjs:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.cjs.json",
     "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
+    "check:exports:esm:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.esm.json",
     "check:exports:esm:beta": "api-extractor run --config api-extractor/api-extractor-lint-beta.esm.json",
+    "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json",
     "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
     "check:format": "npm run check:biome",
     "check:prettier": "prettier --check . --cache --ignore-path ../../../.prettierignore",
+    "ci:build:api-reports": "concurrently \"npm:ci:build:api-reports:*\"",
+    "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
+    "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
     "ci:build:docs": "api-extractor run",
     "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "depcruise": "depcruise src/ --ignore-known",
@@ -184,6 +225,7 @@
     "test:benchmark:report": "mocha --exit --perfMode --parentProcess --fgrep @Benchmark --reporter @fluid-tools/benchmark/dist/MochaReporter.js --timeout 60000",
     "test:coverage": "c8 npm test",
     "test:customBenchmarks": "mocha --config ./.mocharc.customBenchmarks.cjs",
+    "test:customBenchmarks:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:customBenchmarks",
     "test:memory": "mocha --config ./src/test/memory/.mocharc.cjs",
     "test:memory-profiling:report": "mocha --config ./src/test/memory/.mocharc.cjs",
     "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",

package/src/core/index.ts

@@ -158,6 +158,7 @@ export {
 
 export {
 	areEqualChangeAtomIds,
+	areEqualChangeAtomIdOpts,
 	makeChangeAtomId,
 	asChangeAtomId,
 	type ChangeRebaser,
@@ -205,4 +206,4 @@ export {
 	AllowedUpdateType,
 } from "./schema-view/index.js";
 
-export { type Revertible, RevertibleStatus } from "./revertible/index.js";
+export { type Revertible, RevertibleStatus, type RevertibleFactory } from "./revertible.js";

package/src/core/rebase/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	areEqualChangeAtomIds,
+	areEqualChangeAtomIdOpts,
 	makeChangeAtomId,
 	asChangeAtomId,
 	mintCommit,

package/src/core/rebase/types.ts

@@ -81,6 +81,17 @@ export function areEqualChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): boolean
 	return a.localId === b.localId && a.revision === b.revision;
 }
 
+export function areEqualChangeAtomIdOpts(
+	a: ChangeAtomId | undefined,
+	b: ChangeAtomId | undefined,
+): boolean {
+	if (a === undefined || b === undefined) {
+		return a === b;
+	}
+
+	return areEqualChangeAtomIds(a, b);
+}
+
 /**
  * @returns a ChangeAtomId with the given revision and local ID.
  */

package/src/core/{revertible/revertible.ts → revertible.ts}

@@ -47,3 +47,18 @@ export enum RevertibleStatus {
 	/** The revertible has been disposed. Reverting it will have no effect. */
 	Disposed,
 }
+
+/**
+ * Factory for creating a {@link Revertible}.
+ * Will error if invoked outside the scope of the `commitApplied` event that provides it, or if invoked multiple times.
+ *
+ * @param onRevertibleDisposed - A callback that will be invoked when the `Revertible` generated by this factory is disposed.
+ * This happens when the `Revertible` is disposed manually, or when the `TreeView` that the `Revertible` belongs to is disposed,
+ * whichever happens first.
+ * This is typically used to clean up any resources associated with the `Revertible` in the host application.
+ *
+ * @sealed @public
+ */
+export type RevertibleFactory = (
+	onRevertibleDisposed?: (revertible: Revertible) => void,
+) => Revertible;

package/src/core/schema-stored/format.ts

@@ -52,7 +52,7 @@ export const TreeNodeSchemaIdentifierSchema = brandedStringType<TreeNodeSchemaId
 
 const FieldSchemaFormatBase = Type.Object({
 	kind: FieldKindIdentifierSchema,
-	types: Type.Optional(Type.Array(TreeNodeSchemaIdentifierSchema)),
+	types: Type.Array(TreeNodeSchemaIdentifierSchema),
 });
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };

package/src/core/schema-stored/schema.ts

@@ -32,11 +32,6 @@ export enum ValueSchema {
  * Set of allowed tree types.
  * Providing multiple values here allows polymorphism, tagged union style.
  *
- * If not specified, types are unconstrained
- * (equivalent to the set containing every TreeNodeSchemaIdentifier defined in the document).
- *
- * Note that even when unconstrained, children must still be in-schema for their own type.
- *
  * In the future, this could be extended to allow inlining a TreeNodeStoredSchema here
  * (or some similar structural schema system).
  * For structural types which could go here, there are a few interesting options:
@@ -58,7 +53,7 @@ export enum ValueSchema {
  * Care would need to be taken to make sure this is sound for the schema updating mechanisms.
  * @internal
  */
-export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier> | undefined;
+export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier>;
 
 /**
  * Declarative portion of a Field Kind.
@@ -105,11 +100,12 @@ export interface SchemaPolicy {
  */
 export interface TreeFieldStoredSchema {
 	readonly kind: FieldKindIdentifier;
+
 	/**
 	 * The set of allowed child types.
 	 * If not specified, types are unconstrained.
 	 */
-	readonly types?: TreeTypeSet;
+	readonly types: TreeTypeSet;
 }
 
 /**
@@ -295,20 +291,18 @@ function decodeValueSchema(inMemory: PersistedValueSchema): ValueSchema {
 }
 
 export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFormat {
-	const out: FieldSchemaFormat = {
+	return {
 		kind: schema.kind,
+		// Types are sorted by identifier to improve stability of persisted data to increase chance of schema blob reuse.
+		types: [...schema.types].sort(),
 	};
-	if (schema.types !== undefined) {
-		out.types = [...schema.types];
-	}
-	return out;
 }
 
 export function decodeFieldSchema(schema: FieldSchemaFormat): TreeFieldStoredSchema {
 	const out: TreeFieldStoredSchema = {
 		// TODO: maybe provide actual FieldKind objects here, error on unrecognized kinds.
 		kind: schema.kind,
-		types: schema.types === undefined ? undefined : new Set(schema.types),
+		types: new Set(schema.types),
 	};
 	return out;
 }

package/src/core/tree/anchorSet.ts

@@ -713,9 +713,17 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			pathVisitors: new Map<PathNode, Set<PathVisitor>>(),
 			parentField: undefined as FieldKey | undefined,
 			parent: undefined as UpPath | undefined,
+
+			/**
+			 * Events collected during the visit which get sent as a batch during "free".
+			 */
 			bufferedEvents: [] as {
 				node: PathNode;
 				event: keyof AnchorEvents;
+				/**
+				 * The key for the impacted field, if the event is associated with a key.
+				 * Some events, such as afterDestroy, do not involve a key, and thus leave this undefined.
+				 */
 				changedField?: FieldKey;
 			}[],
 
@@ -760,9 +768,13 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 					}
 					emittedEvents?.push(event);
 					if (event === "childrenChangedAfterBatch") {
-						const fieldKeys = this.bufferedEvents
+						const fieldKeys: FieldKey[] = this.bufferedEvents
 							.filter((e) => e.node === node && e.event === event)
-							.map((e) => e.changedField as FieldKey);
+							.map(
+								(e) =>
+									e.changedField ??
+									fail("childrenChangedAfterBatch events should have a changedField"),
+							);
 						node.events.emit(event, { anchor: node, changedFields: new Set(fieldKeys) });
 					} else {
 						node.events.emit(event, node);
@@ -778,7 +790,10 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			notifyChildrenChanged(): void {
 				this.maybeWithNode(
 					(p) => {
-						assert(this.parentField !== undefined, "Must be in a field");
+						assert(
+							this.parentField !== undefined,
+							0xa24 /* Must be in a field to modify its contents */,
+						);
 						p.events.emit("childrenChanged", p);
 						this.bufferedEvents.push({
 							node: p,

package/src/core/tree/detachedFieldIndex.ts

@@ -99,11 +99,11 @@ export class DetachedFieldIndex {
 		return clone;
 	}
 
-	public *entries(): Generator<
-		{ root: ForestRootId; latestRelevantRevision?: RevisionTag } & {
-			id: Delta.DetachedNodeId;
-		}
-	> {
+	public *entries(): Generator<{
+		root: ForestRootId;
+		latestRelevantRevision?: RevisionTag;
+		id: Delta.DetachedNodeId;
+	}> {
 		for (const [major, innerMap] of this.detachedNodeToField) {
 			if (major !== undefined) {
 				for (const [minor, { root, latestRelevantRevision }] of innerMap) {
@@ -331,6 +331,7 @@ export class DetachedFieldIndex {
 		this.isFullyLoaded = false;
 		const rootMap = new Map<ForestRootId, Delta.DetachedNodeId>();
 		forEachInNestedMap(detachedFieldIndex.data, ({ root }, major, minor) => {
+			setInNestedMap(this.detachedNodeToField, major, minor, { root });
 			rootMap.set(root, { major, minor });
 		});
 

package/src/core/tree/visitDelta.ts

@@ -249,8 +249,13 @@ function transferRoots(
  */
 export interface DeltaVisitor {
 	/**
-	 * Frees/releases the visitor. Must be called once the visitor is no longer needed, since trying to acquire
-	 * a new one before freeing an existing one is invalid.
+	 * Frees/releases the visitor.
+	 *
+	 * Must be called once the visitor finished traversing the delta for a couple of reasons:
+	 *
+	 * 1. Some visitors, such as those from forests, are put into a special mode while they have a visitor, forbidding some actions (like making more visitors).
+	 *
+	 * 2. Some visitors, such as those from an anchorSet, defer some events for batching purposes until the visitor is freed.
 	 */
 	free(): void;
 	/**

package/src/events/{events.ts → emitter.ts}

@@ -3,116 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import type { IEvent } from "@fluidframework/core-interfaces";
-import { getOrCreate } from "../util/index.js";
-
-/**
- * Convert a union of types to an intersection of those types. Useful for `TransformEvents`.
- * @privateRemarks
- * First an always true extends clause is used (T extends T) to distribute T into to a union of types contravariant over each member of the T union.
- * Then the constraint on the type parameter in this new context is inferred, giving the intersection.
- */
-export type UnionToIntersection<T> = (T extends T ? (k: T) => unknown : never) extends (
-	k: infer U,
-) => unknown
-	? U
-	: never;
-
-/**
- * `true` iff the given type is an acceptable shape for a {@link Listeners | event} listener
- * @public
- */
-export type IsListener<TListener> = TListener extends (...args: any[]) => void ? true : false;
-
-/**
- * Used to specify the kinds of events emitted by a {@link Listenable}.
- *
- * @remarks
- * Any object type is a valid {@link Listeners}, but only the {@link IsListener | event-like} properties of that
- * type will be included.
- *
- * @example
- * ```typescript
- * interface MyEvents {
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }
- * ```
- *
- * @public
- */
-export type Listeners<T extends object> = {
-	[P in (string | symbol) & keyof T as IsListener<T[P]> extends true ? P : never]: T[P];
-};
-
-/**
- * Converts a {@link Listeners} type (i.e. the event registry for a {@link Listenable}) into a type consumable
- * by an IEventProvider from `@fluidframework/core-interfaces`.
- * @param E - the `Events` type to transform
- * @param Target - an optional `IEvent` type that will be merged into the result along with the transformed `E`
- *
- * @example
- *
- * ```typescript
- * interface MyEvents {
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }
- *
- * class MySharedObject extends SharedObject<TransformEvents<MyEvents, ISharedObjectEvents>> {
- *    // ...
- * }
- * ```
- */
-export type TransformListeners<
-	TListeners extends Listeners<TListeners>,
-	TTarget extends IEvent = IEvent,
-> = {
-	[P in keyof Listeners<TListeners>]: (event: P, listener: TListeners[P]) => void;
-} extends Record<string | number | symbol, infer Z>
-	? UnionToIntersection<Z> & TTarget
-	: never;
-
-/**
- * An object which allows the registration of listeners so that subscribers can be notified when an event happens.
- * @param TListeners - All the {@link Listeners | events} that this subscribable supports
- *
- * @privateRemarks
- * `EventEmitter` can be used as a base class to implement this via extension.
- * ```ts
- * type MyEventEmitter = IEventEmitter<{
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }>
- * ```
- * {@link createEmitter} can help implement this interface via delegation.
- *
- * @sealed @public
- */
-export interface Listenable<TListeners extends object> {
-	/**
-	 * Register an event listener.
-	 * @param eventName - the name of the event
-	 * @param listener - the handler to run when the event is fired by the emitter
-	 * @returns a {@link Off | function} which will deregister the listener when called.
-	 * This deregistration function is idempotent and therefore may be safely called more than once with no effect.
-	 * @remarks Do not register the exact same `listener` object for the same event more than once.
-	 * Doing so will result in undefined behavior, and is not guaranteed to behave the same in future versions of this library.
-	 */
-	on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
-}
-
-/**
- * A function that, when called, will deregister an event listener subscription that was previously registered.
- * @remarks
- * It is returned by the {@link Listenable.on | event registration function} when event registration occurs.
- * @public
- */
-export type Off = () => void;
+import { setInNestedMap } from "../util/index.js";
+import type { Listenable, Listeners, Off } from "./listeners.js";
 
 /**
  * Interface for an event emitter that can emit typed events to subscribed listeners.
- * @sealed @alpha
  */
 export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	/**
@@ -141,23 +36,9 @@ export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	): ReturnType<TListeners[K]>[];
 }
 
-/**
- * Create a {@link Listenable} that can be instructed to emit events via the {@link IEmitter} interface.
- *
- * 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.
- * @alpha
- */
-export function createEmitter<TListeners extends object>(
-	noListeners?: NoListenersCallback<TListeners>,
-): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners> {
-	return new ComposableEventEmitter<TListeners>(noListeners);
-}
-
 /**
  * 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.
- * @alpha
  */
 export type NoListenersCallback<TListeners extends object> = (
 	eventName: keyof Listeners<TListeners>,
@@ -165,7 +46,7 @@ export type NoListenersCallback<TListeners extends object> = (
 
 /**
  * Allows querying if an object has listeners.
- * @sealed @alpha
+ * @sealed
  */
 export interface HasListeners<TListeners extends Listeners<TListeners>> {
 	/**
@@ -188,32 +69,34 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
  *
  * ```typescript
  * interface MyEvents {
- *   "loaded": () => void;
+ * 	loaded: () => void;
+ * 	computed: () => number;
  * }
  *
- * class MyClass extends EventEmitter<MyEvents> {
- *   private load() {
- *     this.emit("loaded");
- *   }
+ * class MyInheritanceClass extends EventEmitter<MyEvents> {
+ * 	private load() {
+ * 		this.emit("loaded");
+ * 		const results: number[] = this.emitAndCollect("computed");
+ * 	}
  * }
  * ```
  *
  * @example Composing over this class
  *
  * ```typescript
- * class MyClass implements ISubscribable<MyEvents> {
- *   private readonly events = createEmitter<MyEvents>();
+ * class MyCompositionClass implements Listenable<MyEvents> {
+ * 	private readonly events = createEmitter<MyEvents>();
  *
- *   private load() {
- *     this.events.emit("loaded");
- *   }
+ * 	private load() {
+ * 		this.events.emit("loaded");
+ * 		const results: number[] = this.events.emitAndCollect("computed");
+ * 	}
  *
- *   public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {
- *     return this.events.on(eventName, listener);
- *   }
+ * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
+ * 		return this.events.on(eventName, listener);
+ * 	}
  * }
  * ```
- * @alpha
  */
 export class EventEmitter<TListeners extends Listeners<TListeners>>
 	implements Listenable<TListeners>, HasListeners<TListeners>
@@ -233,7 +116,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 	): void {
 		const listeners = this.listeners.get(eventName);
 		if (listeners !== undefined) {
-			// Current TS (5.4.5) cannot spread `args` into `listener()`, but assigning to an array first makes it work.
+			// Current tsc (5.4.5) cannot spread `args` into `listener()`.
 			const argArray: unknown[] = args;
 
 			// This explicitly copies listeners so that new listeners added during this call to emit will not receive this event.
@@ -283,7 +166,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 			}
 		};
 
-		getOrCreate(this.listeners, eventName, () => new Map()).set(off, listener);
+		setInNestedMap(this.listeners, eventName, off, listener);
 		return off;
 	}
 
@@ -298,7 +181,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 /**
  * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public
  */
-export class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
+class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
 	extends EventEmitter<TListeners>
 	implements IEmitter<TListeners>
 {
@@ -320,3 +203,33 @@ export class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
 		return super.emitAndCollect(eventName, ...args);
 	}
 }
+
+/**
+ * Create a {@link Listenable} that can be instructed to emit events via the {@link IEmitter} interface.
+ *
+ * A class can delegate handling {@link Listenable} to the returned value while using it to emit the events.
+ * See also {@link EventEmitter} which be used as a base class to implement {@link Listenable} via extension.
+ * @example Forwarding events to the emitter
+ * ```typescript
+ * interface MyEvents {
+ * 	loaded(): void;
+ * }
+ *
+ * class MyClass implements Listenable<MyEvents> {
+ * 	private readonly events = createEmitterMinimal<MyEvents>();
+ *
+ * 	private load(): void {
+ * 		this.events.emit("loaded");
+ * 	}
+ *
+ * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {
+ * 		return this.events.on(eventName, listener);
+ * 	}
+ * }
+ * ```
+ */
+export function createEmitter<TListeners extends object>(
+	noListeners?: NoListenersCallback<TListeners>,
+): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners> {
+	return new ComposableEventEmitter<TListeners>(noListeners);
+}

package/src/events/index.ts

@@ -6,14 +6,14 @@
 export {
 	createEmitter,
 	EventEmitter,
-	ComposableEventEmitter,
+	type IEmitter,
+	type NoListenersCallback,
+	type HasListeners,
+} from "./emitter.js";
+
+export {
 	type Listeners,
 	type Listenable,
 	type Off,
 	type IsListener,
-	type TransformListeners,
-	type UnionToIntersection,
-	type IEmitter,
-	type NoListenersCallback,
-	type HasListeners,
-} from "./events.js";
+} from "./listeners.js";