@fluidframework/tree 2.10.0 → 2.12.0

package/src/simple-tree/toStoredSchema.ts

@@ -20,7 +20,7 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-import { brand, fail, isReadonlyArray } from "../util/index.js";
+import { brand, fail, getOrCreate, isReadonlyArray } from "../util/index.js";
 import { NodeKind, type TreeNodeSchema } from "./core/index.js";
 import {
 	FieldKind,
@@ -33,29 +33,35 @@ import { LeafNodeSchema } from "./leafNodeSchema.js";
 import { isObjectNodeSchema } from "./objectNodeTypes.js";
 import { normalizeFlexListEager } from "./flexList.js";
 
+const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
+
 /**
  * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
  */
 export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
-	walkFieldSchema(root, {
-		node(schema) {
-			if (nodeSchema.has(brand(schema.identifier))) {
-				// Use JSON.stringify to quote and escape identifier string.
-				throw new UsageError(
-					`Multiple schema encountered with the identifier ${JSON.stringify(
-						schema.identifier,
-					)}. Remove or rename them to avoid the collision.`,
-				);
-			}
-			nodeSchema.set(brand(schema.identifier), getStoredSchema(schema));
-		},
-	});
+	return getOrCreate(viewToStoredCache, root, () => {
+		const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
+		walkFieldSchema(root, {
+			node(schema) {
+				if (nodeSchema.has(brand(schema.identifier))) {
+					// Use JSON.stringify to quote and escape identifier string.
+					throw new UsageError(
+						`Multiple schema encountered with the identifier ${JSON.stringify(
+							schema.identifier,
+						)}. Remove or rename them to avoid the collision.`,
+					);
+				}
+				nodeSchema.set(brand(schema.identifier), getStoredSchema(schema));
+			},
+		});
 
-	return {
-		nodeSchema,
-		rootFieldSchema: convertField(root),
-	};
+		const result: TreeStoredSchema = {
+			nodeSchema,
+			rootFieldSchema: convertField(root),
+		};
+		viewToStoredCache.set(root, result);
+		return result;
+	});
 }
 
 /**

package/src/util/brand.ts

@@ -18,7 +18,6 @@ import type { Covariant } from "./typeCheck.js";
  * `Type 'Name1' is not assignable to type 'Name2'.`
  *
  * These branded types are not opaque: A `Brand<A, B>` can still be used as a `B`.
- * @internal
  */
 export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;
 
@@ -42,7 +41,6 @@ export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;
  * - get nominal typing (so types produced without using this class can never be assignable to it).
  *
  * @sealed
- * @internal
  */
 export abstract class BrandedType<out ValueType, Name> {
 	protected _typeCheck?: Covariant<ValueType>;

package/src/util/index.ts

@@ -37,7 +37,6 @@ export {
 } from "./nestedMap.js";
 export { addToNestedSet, type NestedSet, nestedSetContains } from "./nestedSet.js";
 export { type OffsetList, OffsetListFactory } from "./offsetList.js";
-export { TransactionResult } from "./transactionResult.js";
 export type {
 	areSafelyAssignable,
 	Contravariant,
@@ -91,6 +90,10 @@ export {
 	compareStrings,
 	find,
 	count,
+	getLast,
+	hasSome,
+	hasSingle,
+	defineLazyCachedProperty,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 

package/src/util/typeCheck.ts

@@ -107,8 +107,6 @@ export interface Contravariant<in T> {
  * ```typescript
  * protected _typeCheck?: Covariant<T>;
  * ```
- *
- * @internal
  */
 export interface Covariant<out T> {
 	_removeContravariance?: T;
@@ -193,6 +191,11 @@ export type requireAssignableTo<_A extends B, B> = true;
 
 /**
  * Returns a type parameter that is true iff the `Keys` union includes all the keys of `T`.
+ *
+ * @remarks
+ * This does not handle when the T has an index signature permitting keys like `string` which
+ * TypeScript cannot omit members from.
+ *
  * @example
  * ```ts
  * type _check = requireTrue<areOnlyKeys<{a: number, b: number}, 'a' | 'b'>> // true`
@@ -201,5 +204,5 @@ export type requireAssignableTo<_A extends B, B> = true;
  */
 export type areOnlyKeys<T, Keys extends keyof T> = isAssignableTo<
 	Record<string, never>,
-	Omit<T, Keys>
+	Omit<Required<T>, Keys>
 >;

package/src/util/typeCheckTests.ts

@@ -15,6 +15,7 @@ import type {
 	Covariant,
 	Invariant,
 	MakeNominal,
+	areOnlyKeys,
 	areSafelyAssignable,
 	eitherIsAny,
 	isAny,
@@ -221,10 +222,19 @@ export type EnforceTypeCheckTests =
 	| requireTrue<isStrictSubset<[1, true], [1 | 2, true | false]>>
 	| requireTrue<isStrictSubset<[1, true], [1, true | false]>>
 	| requireTrue<isStrictSubset<[1, true], [1, true] | [1 | false]>>
+	| requireTrue<isStrictSubset<1, number>>
 	| requireFalse<isStrictSubset<1, 1>>
 	| requireFalse<isStrictSubset<1, 2>>
 	| requireFalse<isStrictSubset<[1, true], [1, true]>>
-	| requireFalse<isStrictSubset<1 | 2, 1>>;
+	| requireFalse<isStrictSubset<1 | 2, 1>>
+
+	// areOnlyKeys
+	| requireTrue<areOnlyKeys<{ a: number; b: number }, "a" | "b">>
+	| requireTrue<areOnlyKeys<{ a?: number; b: number }, "a" | "b">>
+	| requireFalse<areOnlyKeys<{ a?: number; b: number }, "b">>
+	| requireFalse<areOnlyKeys<{ a: number; b: number }, "a">>;
+// This case is explicitly documented as unsupported.
+// | requireFalse<areOnlyKeys<Record<string, unknown>, "a">>;
 
 // negative tests (should not build)
 // @ts-expect-error negative test

package/src/util/utils.ts

@@ -79,6 +79,44 @@ export function makeArray<T>(size: number, filler: (index: number) => T): T[] {
 	return array;
 }
 
+/**
+ * Returns the last element of an array, or `undefined` if the array has no elements.
+ * @param array - The array to get the last element from.
+ * @remarks
+ * If the type of the array has been narrowed by e.g. {@link hasSome | hasSome(array)} or {@link hasSingle | hasOne(array)} then the return type will be `T` rather than `T | undefined`.
+ */
+export function getLast<T>(array: readonly [T, ...T[]]): T;
+export function getLast<T>(array: { [index: number]: T; length: number }): T | undefined;
+export function getLast<T>(array: { [index: number]: T; length: number }): T | undefined {
+	return array[array.length - 1];
+}
+
+/**
+ * Returns true if and only if the given array has at least one element.
+ * @param array - The array to check.
+ * @remarks
+ * If `array` contains at least one element, its type will be narrowed and can benefit from improved typing from e.g. `array[0]` and {@link getLast | getLast(array)}.
+ * This is especially useful when "noUncheckedIndexedAccess" is enabled in the TypeScript compiler options, since the return type of `array[0]` will be `T` rather than `T | undefined`.
+ */
+export function hasSome<T>(array: T[]): array is [T, ...T[]];
+export function hasSome<T>(array: readonly T[]): array is readonly [T, ...T[]];
+export function hasSome<T>(array: readonly T[]): array is [T, ...T[]] {
+	return array.length > 0;
+}
+
+/**
+ * Returns true if and only if the given array has exactly one element.
+ * @param array - The array to check.
+ * @remarks
+ * If `array` contains exactly one element, its type will be narrowed and can benefit from improved typing from e.g. `array[0]` and {@link getLast | getLast(array)}.
+ * This is especially useful when "noUncheckedIndexedAccess" is enabled in the TypeScript compiler options, since the return type of `array[0]` will be `T` rather than `T | undefined`.
+ */
+export function hasSingle<T>(array: T[]): array is [T];
+export function hasSingle<T>(array: readonly T[]): array is readonly [T];
+export function hasSingle<T>(array: readonly T[]): array is [T] {
+	return array.length === 1;
+}
+
 /**
  * Compares two sets using callbacks.
  * Early returns on first false comparison.
@@ -499,3 +537,29 @@ export function capitalize<S extends string>(s: S): Capitalize<S> {
 export function compareStrings<T extends string>(a: T, b: T): number {
 	return a > b ? 1 : a === b ? 0 : -1;
 }
+
+/**
+ * Defines a property on an object that is lazily initialized and cached.
+ * @remarks This is useful for properties that are expensive to compute and it is not guaranteed that they will be accessed.
+ * This function initially defines a getter on the object, but after first read it replaces the getter with a value property.
+ * @param obj - The object on which to define the property.
+ * @param key - The key of the property to define.
+ * @param get - The function (called either once or not at all) to compute the value of the property.
+ * @returns `obj`, typed such that it has the new property.
+ * This allows for the new property to be read off of `obj` in a type-safe manner after calling this function.
+ */
+export function defineLazyCachedProperty<
+	T extends object,
+	K extends string | number | symbol,
+	V,
+>(obj: T, key: K, get: () => V): typeof obj & { [P in K]: V } {
+	Reflect.defineProperty(obj, key, {
+		get() {
+			const value = get();
+			Reflect.defineProperty(obj, key, { value });
+			return value;
+		},
+		configurable: true,
+	});
+	return obj as typeof obj & { [P in K]: V };
+}

package/dist/events/emitter.d.ts

@@ -1,139 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { Listenable, Listeners, Off } from "./listeners.js";
-/**
- * Interface for an event emitter that can emit typed events to subscribed listeners.
- */
-export interface IEmitter<TListeners extends Listeners<TListeners>> {
-    /**
-     * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.
-     * @param eventName - the name of the event to fire
-     * @param args - the arguments passed to the event listener functions
-     */
-    emit<K extends keyof Listeners<TListeners>>(eventName: K, ...args: Parameters<TListeners[K]>): void;
-    /**
-     * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.
-     * It also collects the return values of all listeners into an array.
-     *
-     * Warning: This method should be used with caution. It deviates from the standard event-based integration pattern as creates substantial coupling between the emitter and its listeners.
-     * For the majority of use-cases it is recommended to use the standard {@link IEmitter.emit} functionality.
-     * @param eventName - the name of the event to fire
-     * @param args - the arguments passed to the event listener functions
-     * @returns An array of the return values of each listener, preserving the order listeners were called.
-     */
-    emitAndCollect<K extends keyof Listeners<TListeners>>(eventName: K, ...args: Parameters<TListeners[K]>): ReturnType<TListeners[K]>[];
-}
-/**
- * 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.
- */
-export type NoListenersCallback<TListeners extends object> = (eventName: keyof Listeners<TListeners>) => void;
-/**
- * Allows querying if an object has listeners.
- * @sealed
- */
-export interface HasListeners<TListeners extends Listeners<TListeners>> {
-    /**
-     * When no `eventName` is provided, returns true iff there are any listeners.
-     *
-     * When `eventName` is provided, returns true iff there are listeners for that event.
-     *
-     * @remarks
-     * This can be used to know when its safe to cleanup data-structures which only exist to fire events for their listeners.
-     */
-    hasListeners(eventName?: keyof Listeners<TListeners>): boolean;
-}
-/**
- * Provides an API for subscribing to and listening to events.
- *
- * @remarks Classes wishing to emit events may either extend this class, compose over it, or expose it as a property of type {@link Listenable}.
- *
- * @example Extending this class
- *
- * ```typescript
- * interface MyEvents {
- * 	loaded: () => void;
- * 	computed: () => number;
- * }
- *
- * class MyInheritanceClass extends EventEmitter<MyEvents> {
- * 	private load() {
- * 		this.emit("loaded");
- * 		const results: number[] = this.emitAndCollect("computed");
- * 	}
- * }
- * ```
- *
- * @example Composing over this class
- *
- * ```typescript
- * class MyCompositionClass implements Listenable<MyEvents> {
- * 	private readonly events = createEmitter<MyEvents>();
- *
- * 	private load() {
- * 		this.events.emit("loaded");
- * 		const results: number[] = this.events.emitAndCollect("computed");
- * 	}
- *
- * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
- * 		return this.events.on(eventName, listener);
- * 	}
- * }
- * ```
- *
- * @example Exposing this class as a property
- *
- * ```typescript
- * class MyExposingClass {
- * 	private readonly _events = createEmitter<MyEvents>();
- * 	public readonly events: Listenable<MyEvents> = this._events;
- *
- * 	private load() {
- * 		this._events.emit("loaded");
- * 		const results: number[] = this._events.emitAndCollect("computed");
- * 	}
- * }
- * ```
- */
-export declare class EventEmitter<TListeners extends Listeners<TListeners>> implements Listenable<TListeners>, HasListeners<TListeners> {
-    private readonly noListeners?;
-    protected readonly listeners: Map<keyof TListeners, Set<(...args: any[]) => TListeners[keyof TListeners]>>;
-    protected constructor(noListeners?: NoListenersCallback<TListeners> | undefined);
-    protected emit<K extends keyof TListeners>(eventName: K, ...args: Parameters<TListeners[K]>): void;
-    protected emitAndCollect<K extends keyof TListeners>(eventName: K, ...args: Parameters<TListeners[K]>): ReturnType<TListeners[K]>[];
-    on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
-    off<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): void;
-    hasListeners(eventName?: keyof TListeners): boolean;
-}
-/**
- * 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);
- * 	}
- *
- * 	public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
- * 		return this.events.off(eventName, listener);
- * 	}
- * }
- * ```
- */
-export declare function createEmitter<TListeners extends object>(noListeners?: NoListenersCallback<TListeners>): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners>;
-//# sourceMappingURL=emitter.d.ts.map

package/dist/events/emitter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../src/events/emitter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,UAAU,SAAS,SAAS,CAAC,UAAU,CAAC;IACjE;;;;OAIG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EACzC,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAChC,IAAI,CAAC;IAER;;;;;;;;;OASG;IACH,cAAc,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EACnD,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAChC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,UAAU,SAAS,MAAM,IAAI,CAC5D,SAAS,EAAE,MAAM,SAAS,CAAC,UAAU,CAAC,KAClC,IAAI,CAAC;AAEV;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,SAAS,SAAS,CAAC,UAAU,CAAC;IACrE;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,SAAS,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,YAAY,CAAC,UAAU,SAAS,SAAS,CAAC,UAAU,CAAC,CACjE,YAAW,UAAU,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC;IASrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAPnD,SAAS,CAAC,QAAQ,CAAC,SAAS,sCAEb,GAAG,EAAE,KAAK,UAAU,CAAC,MAAM,UAAU,CAAC,GACjD;IAIJ,SAAS,aAA8B,WAAW,CAAC,6CAAiC;IAEpF,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,UAAU,EACxC,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAChC,IAAI;IAeP,SAAS,CAAC,cAAc,CAAC,CAAC,SAAS,MAAM,UAAU,EAClD,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAChC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE;IAavB,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EAC9C,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,GAAG;IAcC,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EAC/C,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,IAAI;IAQA,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,UAAU,GAAG,OAAO;CAM1D;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,UAAU,SAAS,MAAM,EACtD,WAAW,CAAC,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAC3C,UAAU,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,CAE1E"}

package/dist/events/emitter.js

@@ -1,165 +0,0 @@
-"use strict";
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEmitter = exports.EventEmitter = void 0;
-const internal_1 = require("@fluidframework/telemetry-utils/internal");
-const index_js_1 = require("../util/index.js");
-/**
- * Provides an API for subscribing to and listening to events.
- *
- * @remarks Classes wishing to emit events may either extend this class, compose over it, or expose it as a property of type {@link Listenable}.
- *
- * @example Extending this class
- *
- * ```typescript
- * interface MyEvents {
- * 	loaded: () => void;
- * 	computed: () => number;
- * }
- *
- * class MyInheritanceClass extends EventEmitter<MyEvents> {
- * 	private load() {
- * 		this.emit("loaded");
- * 		const results: number[] = this.emitAndCollect("computed");
- * 	}
- * }
- * ```
- *
- * @example Composing over this class
- *
- * ```typescript
- * class MyCompositionClass implements Listenable<MyEvents> {
- * 	private readonly events = createEmitter<MyEvents>();
- *
- * 	private load() {
- * 		this.events.emit("loaded");
- * 		const results: number[] = this.events.emitAndCollect("computed");
- * 	}
- *
- * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
- * 		return this.events.on(eventName, listener);
- * 	}
- * }
- * ```
- *
- * @example Exposing this class as a property
- *
- * ```typescript
- * class MyExposingClass {
- * 	private readonly _events = createEmitter<MyEvents>();
- * 	public readonly events: Listenable<MyEvents> = this._events;
- *
- * 	private load() {
- * 		this._events.emit("loaded");
- * 		const results: number[] = this._events.emitAndCollect("computed");
- * 	}
- * }
- * ```
- */
-class EventEmitter {
-    // Because this is protected and not public, calling this externally (not from a subclass) makes sending events to the constructed instance impossible.
-    // Instead, use the static `create` function to get an instance which allows emitting events.
-    constructor(noListeners) {
-        this.noListeners = noListeners;
-        this.listeners = new Map();
-    }
-    emit(eventName, ...args) {
-        const listeners = this.listeners.get(eventName);
-        if (listeners !== undefined) {
-            // Current tsc (5.4.5) cannot spread `args` into `listener()`.
-            const argArray = args;
-            // This explicitly copies listeners so that new listeners added during this call to emit will not receive this event.
-            for (const listener of [...listeners]) {
-                // If listener has been unsubscribed while invoking other listeners, skip it.
-                if (listeners.has(listener)) {
-                    listener(...argArray);
-                }
-            }
-        }
-    }
-    emitAndCollect(eventName, ...args) {
-        const listeners = this.listeners.get(eventName);
-        if (listeners !== undefined) {
-            const argArray = args;
-            const resultArray = [];
-            for (const listener of [...listeners.values()]) {
-                resultArray.push(listener(...argArray));
-            }
-            return resultArray;
-        }
-        return [];
-    }
-    on(eventName, listener) {
-        const listeners = (0, index_js_1.getOrCreate)(this.listeners, eventName, () => new Set());
-        if (listeners.has(listener)) {
-            const eventDescription = typeof eventName === "symbol" ? eventName.description : String(eventName.toString());
-            throw new internal_1.UsageError(`Attempted to register the same listener object twice for event ${eventDescription}`);
-        }
-        listeners.add(listener);
-        return () => this.off(eventName, listener);
-    }
-    off(eventName, listener) {
-        const listeners = this.listeners.get(eventName);
-        if (listeners?.delete(listener) === true && listeners.size === 0) {
-            this.listeners.delete(eventName);
-            this.noListeners?.(eventName);
-        }
-    }
-    hasListeners(eventName) {
-        if (eventName === undefined) {
-            return this.listeners.size !== 0;
-        }
-        return this.listeners.has(eventName);
-    }
-}
-exports.EventEmitter = EventEmitter;
-/**
- * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public
- */
-class ComposableEventEmitter extends EventEmitter {
-    constructor(noListeners) {
-        super(noListeners);
-    }
-    emit(eventName, ...args) {
-        return super.emit(eventName, ...args);
-    }
-    emitAndCollect(eventName, ...args) {
-        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);
- * 	}
- *
- * 	public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
- * 		return this.events.off(eventName, listener);
- * 	}
- * }
- * ```
- */
-function createEmitter(noListeners) {
-    return new ComposableEventEmitter(noListeners);
-}
-exports.createEmitter = createEmitter;
-//# sourceMappingURL=emitter.js.map

package/dist/events/emitter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/events/emitter.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { getOrCreate } from \"../util/index.js\";\nimport type { Listenable, Listeners, Off } from \"./listeners.js\";\n\n/**\n * Interface for an event emitter that can emit typed events to subscribed listeners.\n */\nexport interface IEmitter<TListeners extends Listeners<TListeners>> {\n\t/**\n\t * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.\n\t * @param eventName - the name of the event to fire\n\t * @param args - the arguments passed to the event listener functions\n\t */\n\temit<K extends keyof Listeners<TListeners>>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): void;\n\n\t/**\n\t * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.\n\t * It also collects the return values of all listeners into an array.\n\t *\n\t * Warning: This method should be used with caution. It deviates from the standard event-based integration pattern as creates substantial coupling between the emitter and its listeners.\n\t * For the majority of use-cases it is recommended to use the standard {@link IEmitter.emit} functionality.\n\t * @param eventName - the name of the event to fire\n\t * @param args - the arguments passed to the event listener functions\n\t * @returns An array of the return values of each listener, preserving the order listeners were called.\n\t */\n\temitAndCollect<K extends keyof Listeners<TListeners>>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): ReturnType<TListeners[K]>[];\n}\n\n/**\n * Called when the last listener for `eventName` is removed.\n * Useful for determining when to clean up resources related to detecting when the event might occurs.\n */\nexport type NoListenersCallback<TListeners extends object> = (\n\teventName: keyof Listeners<TListeners>,\n) => void;\n\n/**\n * Allows querying if an object has listeners.\n * @sealed\n */\nexport interface HasListeners<TListeners extends Listeners<TListeners>> {\n\t/**\n\t * When no `eventName` is provided, returns true iff there are any listeners.\n\t *\n\t * When `eventName` is provided, returns true iff there are listeners for that event.\n\t *\n\t * @remarks\n\t * This can be used to know when its safe to cleanup data-structures which only exist to fire events for their listeners.\n\t */\n\thasListeners(eventName?: keyof Listeners<TListeners>): boolean;\n}\n\n/**\n * Provides an API for subscribing to and listening to events.\n *\n * @remarks Classes wishing to emit events may either extend this class, compose over it, or expose it as a property of type {@link Listenable}.\n *\n * @example Extending this class\n *\n * ```typescript\n * interface MyEvents {\n * \tloaded: () => void;\n * \tcomputed: () => number;\n * }\n *\n * class MyInheritanceClass extends EventEmitter<MyEvents> {\n * \tprivate load() {\n * \t\tthis.emit(\"loaded\");\n * \t\tconst results: number[] = this.emitAndCollect(\"computed\");\n * \t}\n * }\n * ```\n *\n * @example Composing over this class\n *\n * ```typescript\n * class MyCompositionClass implements Listenable<MyEvents> {\n * \tprivate readonly events = createEmitter<MyEvents>();\n *\n * \tprivate load() {\n * \t\tthis.events.emit(\"loaded\");\n * \t\tconst results: number[] = this.events.emitAndCollect(\"computed\");\n * \t}\n *\n * \tpublic on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {\n * \t\treturn this.events.on(eventName, listener);\n * \t}\n * }\n * ```\n *\n * @example Exposing this class as a property\n *\n * ```typescript\n * class MyExposingClass {\n * \tprivate readonly _events = createEmitter<MyEvents>();\n * \tpublic readonly events: Listenable<MyEvents> = this._events;\n *\n * \tprivate load() {\n * \t\tthis._events.emit(\"loaded\");\n * \t\tconst results: number[] = this._events.emitAndCollect(\"computed\");\n * \t}\n * }\n * ```\n */\nexport class EventEmitter<TListeners extends Listeners<TListeners>>\n\timplements Listenable<TListeners>, HasListeners<TListeners>\n{\n\tprotected readonly listeners = new Map<\n\t\tkeyof TListeners,\n\t\tSet<(...args: any[]) => TListeners[keyof TListeners]>\n\t>();\n\n\t// Because this is protected and not public, calling this externally (not from a subclass) makes sending events to the constructed instance impossible.\n\t// Instead, use the static `create` function to get an instance which allows emitting events.\n\tprotected constructor(private readonly noListeners?: NoListenersCallback<TListeners>) {}\n\n\tprotected emit<K extends keyof TListeners>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): void {\n\t\tconst listeners = this.listeners.get(eventName);\n\t\tif (listeners !== undefined) {\n\t\t\t// Current tsc (5.4.5) cannot spread `args` into `listener()`.\n\t\t\tconst argArray: unknown[] = args;\n\t\t\t// This explicitly copies listeners so that new listeners added during this call to emit will not receive this event.\n\t\t\tfor (const listener of [...listeners]) {\n\t\t\t\t// If listener has been unsubscribed while invoking other listeners, skip it.\n\t\t\t\tif (listeners.has(listener)) {\n\t\t\t\t\tlistener(...argArray);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprotected emitAndCollect<K extends keyof TListeners>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): ReturnType<TListeners[K]>[] {\n\t\tconst listeners = this.listeners.get(eventName);\n\t\tif (listeners !== undefined) {\n\t\t\tconst argArray: unknown[] = args;\n\t\t\tconst resultArray: ReturnType<TListeners[K]>[] = [];\n\t\t\tfor (const listener of [...listeners.values()]) {\n\t\t\t\tresultArray.push(listener(...argArray));\n\t\t\t}\n\t\t\treturn resultArray;\n\t\t}\n\t\treturn [];\n\t}\n\n\tpublic on<K extends keyof Listeners<TListeners>>(\n\t\teventName: K,\n\t\tlistener: TListeners[K],\n\t): Off {\n\t\tconst listeners = getOrCreate(this.listeners, eventName, () => new Set());\n\t\tif (listeners.has(listener)) {\n\t\t\tconst eventDescription =\n\t\t\t\ttypeof eventName === \"symbol\" ? eventName.description : String(eventName.toString());\n\n\t\t\tthrow new UsageError(\n\t\t\t\t`Attempted to register the same listener object twice for event ${eventDescription}`,\n\t\t\t);\n\t\t}\n\t\tlisteners.add(listener);\n\t\treturn () => this.off(eventName, listener);\n\t}\n\n\tpublic off<K extends keyof Listeners<TListeners>>(\n\t\teventName: K,\n\t\tlistener: TListeners[K],\n\t): void {\n\t\tconst listeners = this.listeners.get(eventName);\n\t\tif (listeners?.delete(listener) === true && listeners.size === 0) {\n\t\t\tthis.listeners.delete(eventName);\n\t\t\tthis.noListeners?.(eventName);\n\t\t}\n\t}\n\n\tpublic hasListeners(eventName?: keyof TListeners): boolean {\n\t\tif (eventName === undefined) {\n\t\t\treturn this.listeners.size !== 0;\n\t\t}\n\t\treturn this.listeners.has(eventName);\n\t}\n}\n\n/**\n * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public\n */\nclass ComposableEventEmitter<TListeners extends Listeners<TListeners>>\n\textends EventEmitter<TListeners>\n\timplements IEmitter<TListeners>\n{\n\tpublic constructor(noListeners?: NoListenersCallback<TListeners>) {\n\t\tsuper(noListeners);\n\t}\n\n\tpublic override emit<K extends keyof TListeners>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): void {\n\t\treturn super.emit(eventName, ...args);\n\t}\n\n\tpublic override emitAndCollect<K extends keyof TListeners>(\n\t\teventName: K,\n\t\t...args: Parameters<TListeners[K]>\n\t): ReturnType<TListeners[K]>[] {\n\t\treturn super.emitAndCollect(eventName, ...args);\n\t}\n}\n\n/**\n * Create a {@link Listenable} that can be instructed to emit events via the {@link IEmitter} interface.\n *\n * A class can delegate handling {@link Listenable} to the returned value while using it to emit the events.\n * See also {@link EventEmitter} which be used as a base class to implement {@link Listenable} via extension.\n * @example Forwarding events to the emitter\n * ```typescript\n * interface MyEvents {\n * \tloaded(): void;\n * }\n *\n * class MyClass implements Listenable<MyEvents> {\n * \tprivate readonly events = createEmitterMinimal<MyEvents>();\n *\n * \tprivate load(): void {\n * \t\tthis.events.emit(\"loaded\");\n * \t}\n *\n * \tpublic on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {\n * \t\treturn this.events.on(eventName, listener);\n * \t}\n *\n * \tpublic off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {\n * \t\treturn this.events.off(eventName, listener);\n * \t}\n * }\n * ```\n */\nexport function createEmitter<TListeners extends object>(\n\tnoListeners?: NoListenersCallback<TListeners>,\n): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners> {\n\treturn new ComposableEventEmitter<TListeners>(noListeners);\n}\n"]}

package/dist/events/index.d.ts

@@ -1,7 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-export { createEmitter, EventEmitter, type IEmitter, type NoListenersCallback, type HasListeners, } from "./emitter.js";
-export { type Listeners, type Listenable, type Off, type IsListener, } from "./listeners.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,aAAa,EACb,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,YAAY,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,GAAG,EACR,KAAK,UAAU,GACf,MAAM,gBAAgB,CAAC"}

package/dist/events/index.js

@@ -1,11 +0,0 @@
-"use strict";
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventEmitter = exports.createEmitter = void 0;
-var emitter_js_1 = require("./emitter.js");
-Object.defineProperty(exports, "createEmitter", { enumerable: true, get: function () { return emitter_js_1.createEmitter; } });
-Object.defineProperty(exports, "EventEmitter", { enumerable: true, get: function () { return emitter_js_1.EventEmitter; } });
-//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,2CAMsB;AALrB,2GAAA,aAAa,OAAA;AACb,0GAAA,YAAY,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tcreateEmitter,\n\tEventEmitter,\n\ttype IEmitter,\n\ttype NoListenersCallback,\n\ttype HasListeners,\n} from \"./emitter.js\";\n\nexport {\n\ttype Listeners,\n\ttype Listenable,\n\ttype Off,\n\ttype IsListener,\n} from \"./listeners.js\";\n"]}

package/dist/events/interop.d.ts

@@ -1,30 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { IEvent } from "@fluidframework/core-interfaces";
-import type { Listeners } from "./listeners.js";
-import type { UnionToIntersection } from "../util/index.js";
-/**
- * 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;
-//# sourceMappingURL=interop.d.ts.map

package/dist/events/interop.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interop.d.ts","sourceRoot":"","sources":["../../src/events/interop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAI5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,kBAAkB,CAC7B,UAAU,SAAS,SAAS,CAAC,UAAU,CAAC,EACxC,OAAO,SAAS,MAAM,GAAG,MAAM,IAC5B;KACF,CAAC,IAAI,MAAM,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI;CAC/E,SAAS,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,GAChD,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,GAChC,KAAK,CAAC"}

package/dist/events/interop.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"interop.js","sourceRoot":"","sources":["../../src/events/interop.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IEvent } from \"@fluidframework/core-interfaces\";\nimport type { Listeners } from \"./listeners.js\";\nimport type { UnionToIntersection } from \"../util/index.js\";\n\n// TODO: this file is currently unused. Use it or remove it.\n\n/**\n * Converts a {@link Listeners} type (i.e. the event registry for a {@link Listenable}) into a type consumable\n * by an IEventProvider from `@fluidframework/core-interfaces`.\n * @param E - the `Events` type to transform\n * @param Target - an optional `IEvent` type that will be merged into the result along with the transformed `E`\n *\n * @example\n *\n * ```typescript\n * interface MyEvents {\n *   load: (user: string, data: IUserData) => void;\n *   error: (errorCode: number) => void;\n * }\n *\n * class MySharedObject extends SharedObject<TransformEvents<MyEvents, ISharedObjectEvents>> {\n *    // ...\n * }\n * ```\n */\nexport type TransformListeners<\n\tTListeners extends Listeners<TListeners>,\n\tTTarget extends IEvent = IEvent,\n> = {\n\t[P in keyof Listeners<TListeners>]: (event: P, listener: TListeners[P]) => void;\n} extends Record<string | number | symbol, infer Z>\n\t? UnionToIntersection<Z> & TTarget\n\t: never;\n"]}